From f0fbf6cf0947b7a57eb59951f7a1fd137c30bf17 Mon Sep 17 00:00:00 2001 From: Martin Stevens Date: Wed, 4 Dec 2019 21:01:11 +0000 Subject: [PATCH 1/8] Added AWS Cognito docs --- docs/howto/auth/awscognito.rst | 124 +++++++++++++++++++++++++++++++++ docs/howto/index.rst | 3 +- 2 files changed, 126 insertions(+), 1 deletion(-) create mode 100644 docs/howto/auth/awscognito.rst diff --git a/docs/howto/auth/awscognito.rst b/docs/howto/auth/awscognito.rst new file mode 100644 index 0000000..dfa68aa --- /dev/null +++ b/docs/howto/auth/awscognito.rst @@ -0,0 +1,124 @@ +.. _howto/auth/awscognito: + +============================== +Authenticate using AWS Cognito +============================== + +The **AWS Cognitor Authenticator** lets users log into your JupyterHub using +a cognito user pools. To do so, you'll first need to register configure a +cognito user pool and app, and then provide information about this +application to your ``tljh`` configuration. + + +Create an AWS Cognito application +========================================= + +#. 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 avaialable 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):///hub/oauth_callback + + * **Signout URL** This s the landing page for a user when they are no logged on:: + + http(s):// + + * **Auth Domain** Create an auth domain and e.g. .:: + + https://<.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 config variables:: + + #!/bin/bash + ############################################## + # Setup systemd environment variable overrides + ############################################## + mkdir /etc/systemd/system/jupyterhub.service.d + + echo "[Service] + Environment=AWSCOGNITO_DOMAIN=${awscognito_domain}" >> /etc/systemd/system/jupyterhub.service.d/jupyterhub.conf + + ############################################## + # Need to ensure oauthenticator is bumped to 0.10.0 + ############################################## + curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \ + | sudo python3 - \ + --admin insightadmin + + ############################################## + # Setup aws Cognito Authenticator + ############################################## + echo "c.AWSCognitoAuthenticator.client_id='${client_id}' + c.AWSCognitoAuthenticator.client_secret='${client_secret}' + c.AWSCognitoAuthenticator.oauth_callback_url='${callback_url}' + c.AWSCognitoAuthenticator.username_key='username' + c.AWSCognitoAuthenticator.oauth_logout_redirect_url='${logout_url}'" >> /opt/tljh/config/jupyterhub_config.d/awscognito.py + + + tljh-config set auth.type oauthenticator.awscognito.AWSCognitoAuthenticator + + tljh-config reload + +Manual configuration to use the AWS Cognito Oauthenticator +============================================================ + +Assuming tljh has already been installed, we need to make sure the oautheneticator module is at 0.10.0 and if not +do a pip install oauthenticator>=0.10.0 + +Because the AWS Congito authenticator uses environment variables and the systemd script we need to pass the +the AWS Cognito domain in via systemd we can do this by creating a systemd service overide file:: + + /etc/systemd/system/jupyterhub.service.d/jupyterhub.conf with the contents + +Add the following contents:: + + [Service] + Environment=AWSCOGNITO_DOMAIN=https://<.auth.eu-west-1.amazoncognito.com + +Using your prefered editor create the config file:: + + /opt/tljh/config/jupyterhub_config.d/awscognito.py + +subsituting the relevant variables:: + + c.AWSCognitoAuthenticator.client_id='${client_id}' + c.AWSCognitoAuthenticator.client_secret='${client_secret}' + c.AWSCognitoAuthenticator.oauth_callback_url='${callback_url}' + c.AWSCognitoAuthenticator.username_key='username' + c.AWSCognitoAuthenticator.oauth_logout_redirect_url='${logout_url}' + +We'll use the ``tljh-config`` tool to configure your JupyterHub's authentication. +For more information on ``tljh-config``, see :ref:`topic/tljh-config`. + +#. Tell your JupyterHub to *use* the AWS Cognito OAuthenticator for authentication:: + + tljh-config set auth.type oauthenticator.awscognito.AWSCognitoAuthenticator + +#. Restart your JupyterHub so that new users see these changes:: + + sudo tljh-config reload + +Confirm that the new authenticator works +======================================== + +#. **Open an incognito window** in your browser (do not log out until you confirm + that the new authentication method works!) + +#. Go to your JupyterHub URL. + +#. You should see an AWS Cognito login button: + +#. 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. + +#. **If this does not work** you can revert back to the default + JupyterHub authenticator by following the steps in :ref:`howto/auth/firstuse`. diff --git a/docs/howto/index.rst b/docs/howto/index.rst index c17303e..3102742 100644 --- a/docs/howto/index.rst +++ b/docs/howto/index.rst @@ -36,6 +36,7 @@ with your JupyterHub. For more information on Authentication, see auth/dummy auth/github auth/google + auth/awscognito auth/firstuse auth/nativeauth @@ -59,4 +60,4 @@ Cloud provider configuration :titlesonly: providers/digitalocean - providers/azure \ No newline at end of file + providers/azure From 22545901fe47fd4d9c0cc5be76d30397a273bbb6 Mon Sep 17 00:00:00 2001 From: Martin Stevens Date: Thu, 5 Dec 2019 16:07:33 +0000 Subject: [PATCH 2/8] Update docs/howto/auth/awscognito.rst Co-Authored-By: Georgiana Elena --- docs/howto/auth/awscognito.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howto/auth/awscognito.rst b/docs/howto/auth/awscognito.rst index dfa68aa..535ef8c 100644 --- a/docs/howto/auth/awscognito.rst +++ b/docs/howto/auth/awscognito.rst @@ -79,7 +79,7 @@ the AWS Cognito domain in via systemd we can do this by creating a systemd servi /etc/systemd/system/jupyterhub.service.d/jupyterhub.conf with the contents -Add the following contents:: +and add the following:: [Service] Environment=AWSCOGNITO_DOMAIN=https://<.auth.eu-west-1.amazoncognito.com From 6419fb1e907d42ed597d6239437fcee30fc33c3a Mon Sep 17 00:00:00 2001 From: Martin Stevens Date: Thu, 5 Dec 2019 16:07:44 +0000 Subject: [PATCH 3/8] Update docs/howto/auth/awscognito.rst Co-Authored-By: Georgiana Elena --- docs/howto/auth/awscognito.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howto/auth/awscognito.rst b/docs/howto/auth/awscognito.rst index 535ef8c..e4b6dff 100644 --- a/docs/howto/auth/awscognito.rst +++ b/docs/howto/auth/awscognito.rst @@ -77,7 +77,7 @@ do a pip install oauthenticator>=0.10.0 Because the AWS Congito authenticator uses environment variables and the systemd script we need to pass the the AWS Cognito domain in via systemd we can do this by creating a systemd service overide file:: - /etc/systemd/system/jupyterhub.service.d/jupyterhub.conf with the contents + /etc/systemd/system/jupyterhub.service.d/jupyterhub.conf and add the following:: From 0a618d710371d805615e467af3c2f29c8a307d65 Mon Sep 17 00:00:00 2001 From: Martin Stevens Date: Thu, 5 Dec 2019 16:07:51 +0000 Subject: [PATCH 4/8] Update docs/howto/auth/awscognito.rst Co-Authored-By: Georgiana Elena --- docs/howto/auth/awscognito.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howto/auth/awscognito.rst b/docs/howto/auth/awscognito.rst index e4b6dff..ac23456 100644 --- a/docs/howto/auth/awscognito.rst +++ b/docs/howto/auth/awscognito.rst @@ -27,7 +27,7 @@ Create an AWS Cognito application http(s):// - * **Auth Domain** Create an auth domain and e.g. .:: + * **Auth Domain** Create an auth domain e.g. :: https://<.auth.eu-west-1.amazoncognito.com From 534a8099ddee3893b1e998bef3c727cb1e7450b3 Mon Sep 17 00:00:00 2001 From: Martin Stevens Date: Thu, 5 Dec 2019 16:07:58 +0000 Subject: [PATCH 5/8] Update docs/howto/auth/awscognito.rst Co-Authored-By: Georgiana Elena --- docs/howto/auth/awscognito.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howto/auth/awscognito.rst b/docs/howto/auth/awscognito.rst index ac23456..e63a660 100644 --- a/docs/howto/auth/awscognito.rst +++ b/docs/howto/auth/awscognito.rst @@ -23,7 +23,7 @@ Create an AWS Cognito application http(s):///hub/oauth_callback - * **Signout URL** This s the landing page for a user when they are no logged on:: + * **Signout URL**: This is the landing page for a user when they are not logged on:: http(s):// From 8d9ea5d47125fbb498c29370958e023d350760f8 Mon Sep 17 00:00:00 2001 From: Martin Stevens Date: Thu, 5 Dec 2019 16:08:16 +0000 Subject: [PATCH 6/8] Update docs/howto/auth/awscognito.rst Co-Authored-By: Georgiana Elena --- docs/howto/auth/awscognito.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howto/auth/awscognito.rst b/docs/howto/auth/awscognito.rst index e63a660..8d8d286 100644 --- a/docs/howto/auth/awscognito.rst +++ b/docs/howto/auth/awscognito.rst @@ -15,7 +15,7 @@ Create an AWS Cognito application #. 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 avaialable to you. + 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 From 3cf977988ef7f69633ec4d6bf88e751a5714a4fd Mon Sep 17 00:00:00 2001 From: Martin Stevens Date: Thu, 5 Dec 2019 16:08:32 +0000 Subject: [PATCH 7/8] Update docs/howto/auth/awscognito.rst Co-Authored-By: Georgiana Elena --- docs/howto/auth/awscognito.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howto/auth/awscognito.rst b/docs/howto/auth/awscognito.rst index 8d8d286..5b26052 100644 --- a/docs/howto/auth/awscognito.rst +++ b/docs/howto/auth/awscognito.rst @@ -5,7 +5,7 @@ Authenticate using AWS Cognito ============================== The **AWS Cognitor Authenticator** lets users log into your JupyterHub using -a cognito user pools. To do so, you'll first need to register configure a +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. From 30dad022128ceec4645d7ffb963e8178480d3b7a Mon Sep 17 00:00:00 2001 From: Martin Stevens Date: Thu, 5 Dec 2019 16:08:37 +0000 Subject: [PATCH 8/8] Update docs/howto/auth/awscognito.rst Co-Authored-By: Georgiana Elena --- docs/howto/auth/awscognito.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howto/auth/awscognito.rst b/docs/howto/auth/awscognito.rst index 5b26052..a4bb805 100644 --- a/docs/howto/auth/awscognito.rst +++ b/docs/howto/auth/awscognito.rst @@ -4,7 +4,7 @@ Authenticate using AWS Cognito ============================== -The **AWS Cognitor Authenticator** lets users log into your JupyterHub using +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.