the-littlest-jupyterhub/docs/howto/auth/awscognito.md

(howto-auth-awscognito)=

# 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](https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-with-cognito-user-pools.html).

   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 {ref}`topic/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 {ref}`howto/auth/firstuse`.