Authenticate using AWS Cognito

The AWS Cognito Authenticator lets users log into your JupyterHub using cognito user pools. To do so, you’ll first need to register and configure a cognito user pool and app, and then provide information about this application to your tljh configuration.

Create an AWS Cognito application

  1. Create a user pool Getting Started with User Pool.

    When you have completed creating a user pool, app, and domain you should have the following settings available to you:

    • App client id: From the App client page

    • App client secret From the App client page

    • Callback URL This should be the domain you are hosting you server on:

      http(s)://<my-tljh-ip-address>/hub/oauth_callback
      
    • Signout URL: This is the landing page for a user when they are not logged on:

      http(s)://<my-tljh-ip-address>
      
    • Auth Domain Create an auth domain e.g. <my_jupyter_hub>:

      https://<<my_jupyter_hub>.auth.eu-west-1.amazoncognito.com
      

Install and configure an AWS EC2 Instance with userdata

By adding following script to the ec2 instance user data you should be able to configure the instance automatically, replace relevant placeholders:

#!/bin/bash
##############################################
# Ensure tljh is up to date
##############################################
curl -L https://tljh.jupyter.org/bootstrap.py \
  | sudo python3 - \
    --admin insightadmin

##############################################
# Setup AWS Cognito OAuthenticator
##############################################
echo > /opt/tljh/config/jupyterhub_config.d/awscognito.py <<EOF
c.GenericOAuthenticator.client_id = "[your app client ID]"
c.GenericOAuthenticator.client_secret = "[your app client secret]"
c.GenericOAuthenticator.oauth_callback_url = "https://[your-jupyterhub-host]/hub/oauth_callback"

c.GenericOAuthenticator.authorize_url = "https://your-AWSCognito-domain/oauth2/authorize"
c.GenericOAuthenticator.token_url = "https://your-AWSCognito-domain/oauth2/token"
c.GenericOAuthenticator.userdata_url = "https://your-AWSCognito-domain/oauth2/userInfo"
c.GenericOAuthenticator.logout_redirect_url = "https://your-AWSCognito-domain/oauth2/logout"

# these are always the same
c.GenericOAuthenticator.login_service = "AWS Cognito"
c.GenericOAuthenticator.username_key = "username"
c.GenericOAuthenticator.userdata_method = "POST"
EOF

tljh-config set auth.type oauthenticator.generic.GenericOAuthenticator

tljh-config reload

Manual configuration to use the AWS Cognito OAuthenticator

AWS Cognito is configured as a generic OAuth provider.

Using your preferred editor create the config file:

/opt/tljh/config/jupyterhub_config.d/awscognito.py

substituting the relevant variables:

c.GenericOAuthenticator.client_id = "[your app ID]"
c.GenericOAuthenticator.client_secret = "[your app Password]"
c.GenericOAuthenticator.oauth_callback_url = "https://[your-jupyterhub-host]/hub/oauth_callback"

c.GenericOAuthenticator.authorize_url = "https://your-AWSCognito-domain/oauth2/authorize"
c.GenericOAuthenticator.token_url = "https://your-AWSCognito-domain/oauth2/token"
c.GenericOAuthenticator.userdata_url = "https://your-AWSCognito-domain/oauth2/userInfo"
c.GenericOAuthenticator.logout_redirect_url = "https://your-AWSCognito-domain/oauth2/logout"

# these are always the same
c.GenericOAuthenticator.login_service = "AWS Cognito"
c.GenericOAuthenticator.username_key = "username"
c.GenericOAuthenticator.userdata_method = "POST"

We’ll use the tljh-config tool to configure your JupyterHub’s authentication. For more information on tljh-config, see Configuring TLJH with tljh-config.

  1. Tell your JupyterHub to use the GenericOAuthenticator for authentication:

    tljh-config set auth.type oauthenticator.generic.GenericOAuthenticator
    
  2. Restart your JupyterHub so that new users see these changes:

    sudo tljh-config reload
    

Confirm that the new authenticator works

  1. Open an incognito window in your browser (do not log out until you confirm that the new authentication method works!)

  2. Go to your JupyterHub URL.

  3. You should see an AWS Cognito login button:

  4. You will likely have to create a new user (sign up) and then you should be directed to the Jupyter interface used in this JupyterHub.

  5. If this does not work you can revert back to the default JupyterHub authenticator by following the steps in Let users choose a password when they first log in.