Further clarifications in external-oauth example

examples/external-oauth/README.md

@@ -11,8 +11,8 @@ This is an implementation of OAuth 2.0 provided by the jupyterhub package,
 which configures all of the necessary URLs from environment variables.
 
 The second is `whoami-oauth-basic`, which implements the full OAuth process
-without any inheritance, so it can be used as a reference for other OAuth
-implementations.
+without any inheritance, so it can be used as a reference for OAuth
+implementations in other web servers or languages.
 
 ## Run the example
 
@@ -20,10 +20,13 @@ implementations.
 
         export JUPYTERHUB_API_TOKEN=`openssl rand -hex 32`
 
-2. launch the whoami service:
+2. launch a version of the the whoami service.
+   For `whoami-oauth`:
 
         bash launch-service.sh &
-        # or
+
+    or for `whoami-oauth-basic`:
+
         bash launch-service-basic.sh &
 
 3. Launch JupyterHub:
@@ -73,7 +76,7 @@ The essential pieces for using JupyterHub as an OAuth provider are:
 
 2. Telling your service how to authenticate with JupyterHub.
 
-The relevant OAuth URLs for working with JupyterHub are:
+The relevant OAuth URLs and keys for using JupyterHub as an OAuth provider are:
 
 1. the client_id, used in oauth requests
 2. the api token registered with jupyterhub is the client_secret for oauth requests

examples/external-oauth/launch-service-basic.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# script to launch whoami-oauth-basic service
 set -euo pipefail
 
 # the service needs to know:

examples/external-oauth/launch-service.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# script to launch whoami-oauth service
 set -euo pipefail
 
 # the service needs to know:

examples/external-oauth/whoami-oauth-basic.py

@@ -1,7 +1,7 @@
 """Basic implementation of OAuth without any inheritance
 
-Implements OAuth handshake directly
-so all URLs and requests should be in one place
+Implements OAuth handshake manually
+so all URLs and requests necessary for OAuth with JupyterHub should be in one place
 """
 
 import json
@@ -69,13 +69,17 @@ class WhoAmIHandler(web.RequestHandler):
     """Serve the JSON model for the authenticated user"""
 
     def get_current_user(self):
-        """The login handler stored a jupyterhub API token
+        """The login handler stored a JupyterHub API token in a cookie
 
-        in a cookie
+        @web.authenticated calls this method.
+        If a Falsy value is returned, the request is redirected to `login_url`.
+        If a Truthy value is returned, the request is allowed to proceed.
         """
-        btoken = self.get_secure_cookie('whoami-oauth-token')
-        if btoken:
-            return btoken.decode('ascii')
+        token = self.get_secure_cookie('whoami-oauth-token')
+
+        if token:
+            # secure cookies are bytes, decode to str
+            return token.decode('ascii', 'replace')
 
     async def user_for_token(self, token):
         """Retrieve the user for a given token, via /hub/api/user"""