Handle key exception and beef up docs

Author: jessebrennan

README.md

@@ -1,7 +1,7 @@
 [![Build Status](https://travis-ci.org/ucsc-cgp/bouncer.svg?branch=master)](https://travis-ci.org/ucsc-cgp/bouncer)
 
 # bouncer
-The whitelist checker for authentication with CGP HCA Data Store
+Simple email whitelist checker backed by the AWS Secrets Manager
 
 ## setup
 
@@ -23,27 +23,43 @@ To test, run
 python -m unittest -v test.py
 ```
 ## how to use
+
+### setting up the whitelist
+1. Go to the AWS Console and find the **Secrets Manager** service.
+1. Select **Store a new secret**.
+1. For secret type select **Other type of secrets**.
+1. Under the **Secret key/value** tab enter `email` as the key and a
+   comma separated (no spaces) list of whitelisted emails as the
+   value. Select **Next**.
+1. Name your secret something descriptive, such as 
+   `commons/dev/whitelist` and give it a description. Select **Next**.
+1. Make sure **Disable automatic rotation** is selected. Then select
+   **Next**.
+1. Review your configuration and select **Store**.
+
+### adding someone to the whitelist
+1. Go to the AWS Console and find the **Secrets Manager** service.
+1. Find the secret to which you want to add. For example, one might
+   search for `commons/dev/whitelist`.
+1. Under **Secret value**, select **Retrieve secret value**. Then
+   select **Edit**. 
+1. Add your email with **NO WHITESPACE** to the comma separated list
+   under the key `email` and select **Save**.
+
+### using bouncer to check the whitelist
 Using is simple!
 
 Here's an example
 
 ```python
 >>> from bouncer import Bouncer
 >>> b = Bouncer('commons/dev/whitelist')
->>> b.is_authorized('jrbrenna@ucsc.edu')
+>>> b.is_authorized('valid.email@example.com')
 True
->>> b.is_authorized('evil.gnomes@ucsc.edu')
+>>> b.is_authorized('evil.gnomes@example.com')
 False
 ```
 
 This checks the AWS Secret Keeper called `commons/dev/whitelist` to see
-if the users `jrbrenna@ucsc.edu` and `evil.gnomes@ucsc.edu` are in the
-whitelist.
-
-## adding users to the whitelist
-1. Go to the AWS Console and find the **AWS Secrets Manager** service.
-1. Find the secret to which you want to add. For example, one might
-   search for `commons/dev/whitelist`.
-1. Under **Secret value** select **Edit**.
-1. Add your email with **NO WHITESPACE** to the comma separated list
-   under the key `email`.
+if the users `valid.email@example.com` and `evil.gnomes@example.com`
+are in the whitelist.

bouncer/bouncer.py

@@ -33,7 +33,7 @@ def is_authorized(self, email: str) -> bool:
 
         :param email: Google email address for which authorization is to be determined
         :return: True if the email address is authorized, False if not authorized
-        :exception: <TBD> If an error occurs.
+        :exception SecretManagerException: If an error occurs.
         """
         return email in self.whitelist()
 
@@ -50,4 +50,8 @@ def whitelist(self):
         else:
             secret_string = get_secret_value_response['SecretString']
             secret_dict = json.loads(secret_string)
-            return secret_dict[SECRET_KEY].split(',')
+            try:
+                return secret_dict[SECRET_KEY].split(',')
+            except KeyError as e:
+                raise SecretManagerException(f"Your secret is misformatted. Expected key: {SECRET_KEY}, "
+                                             f"actually found: {list(secret_dict.keys())}")

setup.py

@@ -16,7 +16,7 @@ def read(fname):
 
 setup(
     name="cgp-bouncer",
-    description="The whitelist checker for authentication with CGP HCA Data Store",
+    description="Simple email whitelist checker backed by the AWS Secrets Manager",
     packages=find_packages(),  # include all packages
     url="https://github.com/ucsc-cgp/bouncer",
     long_description=read('README.md'),