From 8ecb158bc9a7d487e7796015fbf7c06905e4025a Mon Sep 17 00:00:00 2001 From: Jordan Bradford <36420801+jrdnbradford@users.noreply.github.com> Date: Wed, 17 May 2023 22:58:07 -0400 Subject: [PATCH 1/3] Update Google auth docs --- docs/howto/auth/google.md | 85 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 81 insertions(+), 4 deletions(-) diff --git a/docs/howto/auth/google.md b/docs/howto/auth/google.md index 1557a4c..b8c4a34 100644 --- a/docs/howto/auth/google.md +++ b/docs/howto/auth/google.md @@ -2,7 +2,7 @@ # Authenticate using Google -The **Google Authenticator** lets users log into your JupyterHub using their +The **Google OAuthenticator** lets users log into your JupyterHub using their Google user ID / password. To do so, you'll first need to register an application with Google, and then provide information about this application to your `tljh` configuration. @@ -74,11 +74,18 @@ IP address** to it. In this case, **you must update your Google application info with the new IP address. ::: -## Configure your JupyterHub to use the Google Oauthenticator +## Step 3: Configure your JupyterHub to use the Google OAuthenticator -We'll use the `tljh-config` tool to configure your JupyterHub's authentication. +### Configuration with `tljh-config` + +In this section we'll use the `tljh-config` tool to configure your JupyterHub's authentication. For more information on `tljh-config`, see [](/topic/tljh-config). +:::{important} +By default, the following allows *anyone* with a Google account to login. +You can set specific allowed users and admins using [](#tljh-set-user-lists). +::: + 1. Log in as an administrator account to your JupyterHub. 2. Open a terminal window. @@ -113,7 +120,77 @@ For more information on `tljh-config`, see [](/topic/tljh-config). sudo tljh-config reload ``` -## Confirm that the new authenticator works +### Advanced Configuration with Google Groups + +Administrative and regular users of your TLJH can also be easily managed with Google Groups. +This requires a service account and a Workspace admin account that can be impersonated by the +service account to read groups in your domain. You may need to contact your Google Workspace +administrator for help performing these steps. + +1. [Create a service account](https://cloud.google.com/iam/docs/service-accounts-create). + +1. [Create a service account key](https://developers.google.com/workspace/guides/create-credentials#create_credentials_for_a_service_account). Keep this key in a safe space, you will need to add it to your instance later. + +1. Setup [domain-wide delegation](https://developers.google.com/workspace/guides/create-credentials#optional_set_up_domain-wide_delegation_for_a_service_account) for the service account that includes the following scopes: + ``` + https://www.googleapis.com/auth/admin.directory.user.readonly + https://www.googleapis.com/auth/admin.directory.group.readonly + ``` +1. Add the service account key to your instance and ensure it is _not_ readable by non-admin users of the hub. + :::{important} + The service account key is a secret. Anyone for whom you configure admin privileges on your TLJH instance will be able to access it. + ::: + +1. Log in as an administrator account to your JupyterHub. + +1. Open a terminal window. + + ```{image} ../../images/notebook/new-terminal-button.png + :alt: New terminal button. + ``` + +1. Install the extra requirements within the hub environment. + + ``` + source /opt/tljh/hub/bin/activate + pip3 install oauthenticator[googlegroups] + deactivate + ``` + +1. Create a configuration directory `jupyterhub_config.d` within `/opt/tljh/config/`. + Any `.py` files within this directory will be sourced for configuration. + + ``` + sudo mkdir /opt/tljh/config/jupyterhub_config.d + ``` + +1. Configure your hub for Google Groups-based authentication by adding the following to a `.py` file within `/opt/tljh/config/jupyterhub_config.d`. + + ```python + from oauthenticator.google import GoogleOAuthenticator + c.JupyterHub.authenticator_class = GoogleOAuthenticator + + c.GoogleOAuthenticator.google_service_account_keys = {'': ''} + c.GoogleOAuthenticator.gsuite_administrator = {'': ''} + c.GoogleOAuthenticator.allowed_google_groups = {'': ['example-group', 'another-example-group']} + c.GoogleOAuthenticator.admin_google_groups = {'': ['example-admin-group', 'another-example-admin-group']} + c.GoogleOAuthenticator.client_id = '' + c.GoogleOAuthenticator.client_secret = '' + c.GoogleOAuthenticator.hosted_domain = '' + c.GoogleOAuthenticator.login_service = '' + c.GoogleOAuthenticator.oauth_callback_url = 'http(s):///hub/oauth_callback' + ``` + + See the [Google OAuthenticator documentation](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.google.html) + for more information on these and other configuration options. + + +1. Reload your configuration for the changes to take effect: + ``` + sudo tljh-config reload + ``` + +## Step 4: 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!) From be4580c21eb56e88b077605edc89510816bc13cd Mon Sep 17 00:00:00 2001 From: Jordan Bradford <36420801+jrdnbradford@users.noreply.github.com> Date: Wed, 17 May 2023 23:01:01 -0400 Subject: [PATCH 2/3] Update user config language --- docs/topic/tljh-config.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/topic/tljh-config.md b/docs/topic/tljh-config.md index f994213..561e4b9 100644 --- a/docs/topic/tljh-config.md +++ b/docs/topic/tljh-config.md @@ -89,9 +89,9 @@ sudo tljh-config reload proxy ### User Lists -- `users.allowed` takes in usernames to whitelist +- `users.allowed` takes in usernames to allow -- `users.banned` takes in usernames to blacklist +- `users.banned` takes in usernames to ban - `users.admin` takes in usernames to designate as admins From eeb76c0894d71a3c4ae3ee1f80cf2c5b67b5912c Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 18 May 2023 14:08:34 +0000 Subject: [PATCH 3/3] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/howto/auth/google.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/howto/auth/google.md b/docs/howto/auth/google.md index b8c4a34..bba1f0c 100644 --- a/docs/howto/auth/google.md +++ b/docs/howto/auth/google.md @@ -82,7 +82,7 @@ In this section we'll use the `tljh-config` tool to configure your JupyterHub's For more information on `tljh-config`, see [](/topic/tljh-config). :::{important} -By default, the following allows *anyone* with a Google account to login. +By default, the following allows _anyone_ with a Google account to login. You can set specific allowed users and admins using [](#tljh-set-user-lists). ::: @@ -124,7 +124,7 @@ You can set specific allowed users and admins using [](#tljh-set-user-lists). Administrative and regular users of your TLJH can also be easily managed with Google Groups. This requires a service account and a Workspace admin account that can be impersonated by the -service account to read groups in your domain. You may need to contact your Google Workspace +service account to read groups in your domain. You may need to contact your Google Workspace administrator for help performing these steps. 1. [Create a service account](https://cloud.google.com/iam/docs/service-accounts-create). @@ -150,16 +150,16 @@ administrator for help performing these steps. ``` 1. Install the extra requirements within the hub environment. - + ``` source /opt/tljh/hub/bin/activate pip3 install oauthenticator[googlegroups] deactivate ``` -1. Create a configuration directory `jupyterhub_config.d` within `/opt/tljh/config/`. +1. Create a configuration directory `jupyterhub_config.d` within `/opt/tljh/config/`. Any `.py` files within this directory will be sourced for configuration. - + ``` sudo mkdir /opt/tljh/config/jupyterhub_config.d ``` @@ -170,9 +170,9 @@ administrator for help performing these steps. from oauthenticator.google import GoogleOAuthenticator c.JupyterHub.authenticator_class = GoogleOAuthenticator - c.GoogleOAuthenticator.google_service_account_keys = {'': ''} - c.GoogleOAuthenticator.gsuite_administrator = {'': ''} - c.GoogleOAuthenticator.allowed_google_groups = {'': ['example-group', 'another-example-group']} + c.GoogleOAuthenticator.google_service_account_keys = {'': ''} + c.GoogleOAuthenticator.gsuite_administrator = {'': ''} + c.GoogleOAuthenticator.allowed_google_groups = {'': ['example-group', 'another-example-group']} c.GoogleOAuthenticator.admin_google_groups = {'': ['example-admin-group', 'another-example-admin-group']} c.GoogleOAuthenticator.client_id = '' c.GoogleOAuthenticator.client_secret = '' @@ -181,10 +181,9 @@ administrator for help performing these steps. c.GoogleOAuthenticator.oauth_callback_url = 'http(s):///hub/oauth_callback' ``` - See the [Google OAuthenticator documentation](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.google.html) + See the [Google OAuthenticator documentation](https://oauthenticator.readthedocs.io/en/latest/reference/api/gen/oauthenticator.google.html) for more information on these and other configuration options. - 1. Reload your configuration for the changes to take effect: ``` sudo tljh-config reload