Google specific configs

Google specific configs#

This guide covers optional, advanced configurations for Google OAuthenticator.

Access via Google Groups#

You can use Google Groups to manage user access and admin authorization for JupyterHub. To do this you must use a Service Account with domain-wide delegation to read group and user information.

The instructions below are to be performed after finishing setting up Google.

Note

The Google Cloud and Workspace UIs change frequently. For the most up-to-date instructions:

Install the googlegroups extra_requires#

Install the following in your hub environment:

pip install oauthenticator[googlegroups]

Creating a Service Account and Credentials#

  1. Open the Service accounts page. If prompted, select a project.

  2. Click add (+) Create Service Account and enter a name and description for the Service Account. The Permissions (optional) and Principals with access (optional) sections that follow are not required. When done select Done.

  3. Once created, select your Service Account and go to Keys. Select Add key and Create new key. Select the JSON format for your key and select Create. See Best practices for managing Service Account keys for storing and using this key securely.

  4. Return to your Service Account and copy the OAuth 2 Client ID (sometimes called Unique ID or just Client ID). You will need this for configuring domain-wide delegation.

Delegating Domain-Wide Authority#

Note

This step may require a Google Workspace administrator.

  1. Go to your Google Workspace domain’s Admin console.

  2. Select Security -> Access and data control -> API controls.

  3. Select MANAGE DOMAIN WIDE DELEGATION.

  4. Select Add new.

  5. In the Client ID field, enter the Client ID obtained from the Service Account creation steps above.

  6. In the OAuth scopes field enter the scopes:

    • https://www.googleapis.com/auth/admin.directory.user.readonly

    • https://www.googleapis.com/auth/admin.directory.group.readonly

  7. Select Authorize.

Enable the Admin SDK API#

  1. Go to the Google Cloud console API Library.

  2. Select your project from the project list.

  3. Search for the Admin SDK API. This is a Google Enterprise API with the service name admin.googleapis.com.

  4. Select Enable.

Configure a Google Admin Account to Impersonate#

Note

This step may require a Google Workspace administrator.

The Service Account you created will retrieve Google Group membership by impersonating an admin account with those privileges.

  1. Go to your Google Workspace domain’s Admin console.

  2. Go to Directory -> Users.

  3. Create the new user.

  4. Select the user and then Admin roles and privileges.

  5. Create a custom role that includes the Groups.Read and Users.Read Admin API privileges permissions.

  6. Assign the role to the account.

Configuring jupyterhub_config.py#

Add the relevant lines below to your jupyterhub_config.py.

# Email of the Google Workspace admin user that the Service Account will impersonate.
# This user must have read-only access to users and groups
c.GoogleOAuthenticator.gsuite_administrator = {'example.com': 'admin-for-jupyter@example.com'}

# Path to the JSON key file for your Service Account
c.GoogleOAuthenticator.google_service_account_keys = {'example.com': '/etc/jupyterhub/service_account.json'}

# List of Google Groups whose members should get admin rights on JupyterHub
c.GoogleOAuthenticator.admin_google_groups = {'example.com': ['jupyterhub-admins']}

# List of Google Groups whose members are allowed to log in to JupyterHub
c.GoogleOAuthenticator.allowed_google_groups = {'example.com': ['jupyterhub-users']}

Retrieving access_token and refresh_token#

In your jupyterhub_config.py do the following:

c.OAuthenticator.extra_authorize_params = {'access_type': 'offline', 'approval_prompt': 'force'}

For more parameters see the Google OAuth 2.0 documentation.

Contents