Authenticate Using GitHub Usernames - The Littlest JupyterHub

Skip to main content Back to top Ctrl+K

• Installing
• How-To Guides
• Topic Guides
• Reference
• Troubleshooting
• Contributing

• GitHub
• Discourse

Section Navigation

Content and data

• Distributing materials to users with nbgitpuller
• Adding data to the JupyterHub
• Share data with your users

The user environment

• Install conda, pip or apt packages
• Change default user interface
• Configure resources available to users
• Setting New Default JupyterLab Settings

Authentication

• Authenticate any user with a single shared password
• Authenticate using GitHub Usernames
• Authenticate using Google
• Authenticate using AWS Cognito
• Let users choose a password when they first log in
• Let users sign up with a username and password

Administration and security

• Add / Remove admin users
• Estimate Memory / CPU / Disk needed
• Resize the resources available to your JupyterHub
• Check your memory usage
• Enable HTTPS
• Enabling Jupyter Notebook extensions
• Customizing systemd services
• Upgrade TLJH

Cloud provider configuration

• Perform common Digital Ocean configuration tasks
• Perform common Microsoft Azure configuration tasks
• Perform common Google Cloud configuration tasks

• How-To Guides
• Authenticate...

Authenticate using GitHub Usernames#

Warning

This documentation has not been updated recently, and a major version of OAuthenticator has been released since it was. Due to that, please only use this as a complement to the official OAuthenticator documentation.

Going onwards, the goal is to ensure we have good documentation in the OAuthenticator project and reference that instead of maintaining similar documentation in this project also.

The GitHub Authenticator lets users log into your JupyterHub using their GitHub user ID / password. To do so, you’ll first need to register an application with GitHub, and then provide information about this application to your tljh configuration.

Note

You’ll need a GitHub account in order to complete these steps.

Step 1: Create a GitHub application#

1. Go to the GitHub OAuth app creation page.

   • Application name: Choose a descriptive application name (e.g. tljh)

   • Homepage URL: Use the IP address or URL of your JupyterHub. e.g. http(s)://<my-tljh-url>`.

   • Application description: Use any description that you like.

   • Authorization callback URL: Insert text with the following form:

     http(s)://<my-tljh-ip-address>/hub/oauth_callback

   • When you’re done filling in the page, it should look something like this:

     

2. Click “Register application”. You’ll be taken to a page with the registered application details.

3. 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 GitHub application information with the new IP address.

Configure your JupyterHub to use the GitHub 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.

1. Log in as an administrator account to your JupyterHub.

2. Open a terminal window.

   

3. Configure the GitHub OAuthenticator to use your client ID, client secret and callback URL with the following commands:

   sudo tljh-config set auth.GitHubOAuthenticator.client_id '<my-tljh-client-id>' sudo tljh-config set auth.GitHubOAuthenticator.client_secret '<my-tljh-client-secret>' sudo tljh-config set auth.GitHubOAuthenticator.oauth_callback_url 'http(s)://<my-tljh-ip-address>/hub/oauth_callback'

4. Tell your JupyterHub to use the GitHub OAuthenticator for authentication:

   sudo tljh-config set auth.type github

5. Tell JupyterHub which users to allow, if you haven’t already:

   sudo tljh-config add-item users.allowed good-user_1

6. 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 a GitHub login button like below:

   

4. After you log in with your GitHub credentials, 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 Let users choose a password when they first log in.

On this page

• Step 1: Create a GitHub application
• Configure your JupyterHub to use the GitHub Oauthenticator
• Confirm that the new authenticator works

Edit on GitHub Show Source