Authenticate using Google#
The Google Authenticator 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.
See Google’s documentation
on how to create OAUth 2.0 client credentials.
Note
You’ll need a Google account in order to complete these steps.
Step 1: Create a Google project#
Go to Google Developers Console and create a new project:
Step 2: Set up a Google OAuth client ID and secret#
After creating and selecting the project:
Go to the credentials menu:
![]()
Click “Create credentials” and from the dropdown menu select “OAuth client ID”:
![]()
- You will have to fill a form with:
Application type: Choose Web application
Name: A descriptive name for your OAuth client ID (e.g.
tljh-client
)Authorized JavaScript origins: Use the IP address or URL of your JupyterHub. e.g.
http(s)://<my-tljh-url>
.Authorized redirect URIs: Insert text with the following form:
http(s)://<my-tljh-ip-address>/hub/oauth_callbackWhen you’re done filling in the page, it should look something like this (ideally without the red warnings):
![]()
Click “Create”. You’ll be taken to a page with the registered application details.
Copy the Client ID and Client Secret from the application details page. You will use these later to configure your JupyterHub authenticator.
Important
If you are using a virtual machine from a cloud provider and stop the VM, then when you re-start the VM, the provider will likely assign a new public IP address to it. In this case, you must update your Google application information with the new IP address.
Configure your JupyterHub to use the Google Oauthenticator#
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.
Log in as an administrator account to your JupyterHub.
Open a terminal window.
Configure the Google OAuthenticator to use your client ID, client secret and callback URL with the following commands:
sudo tljh-config set auth.GoogleOAuthenticator.client_id '<my-tljh-client-id>'
sudo tljh-config set auth.GoogleOAuthenticator.client_secret '<my-tljh-client-secret>'
sudo tljh-config set auth.GoogleOAuthenticator.oauth_callback_url 'http(s)://<my-tljh-ip-address>/hub/oauth_callback'
Tell your JupyterHub to use the Google OAuthenticator for authentication:
sudo tljh-config set auth.type oauthenticator.google.GoogleOAuthenticator
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 a Google login button like below:
After you log in with your Google credentials, 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 Let users choose a password when they first log in.