How to Setup GitHub OAuth for JupyterHub

This guide will walk you through the process of setting up GitHub OAuth for your JupyterHub deployment.

Prerequisites

1. A GitHub account

2. Administrative access to your JupyterHub deployment

3. Your JupyterHub domain/URL

Step 1: Create a New GitHub Organization

1. Go to github.com and click on + icon in the top right

2. Click New Organization from the dropdown menu

   

3. Fill in the organization details:

   • Enter your Organization name (e.g., “AUP-INT-TEST”)

   • Provide a Contact email

   • Select whether this organization belongs to “My personal account” or “A business or institution”

   • Complete the verification puzzle

   • Accept the Terms of Service

   • Click Next to create the organization

   

Step 2: Create Teams to Assign Different Permissions

Teams allow you to organize members and control access to different resources in your JupyterHub deployment.

1. Navigate to your organization’s Teams page

2. Click the New team button in the top right

   

3. Fill in the team creation form:

   • Team name: Use the same name as the key in your jupyterhub_config.py (e.g., “cpu”, “gpu”, “npu”, “official”)

   • Description: Add a description of what this team is for

   • Team visibility: Select Visible (recommended) - this allows all organization members to see the team

   • Team notifications: Choose whether to enable notifications

   • Click Create team

   

4. Repeat this process to create all the teams you need for your resource mapping (e.g., cpu, gpu, npu, official, public, test)

Step 3: Add Members to the Organization

1. Go to the People tab in your organization

2. Click the Invite member button in the top right

   

3. In the invitation dialog:

   • Enter the member’s email address or GitHub username

   • Click Invite

   

4. Assign the member to appropriate teams and roles:

   • Role in the organization:

     • Select Member for normal users (can see all members and be granted access to repositories)

     • Select Owner for admin users (full administrative rights to the organization)

   • Teams: Select the teams this member should belong to (e.g., cpu, gpu, official)

   • Click Send invitation

   

5. Repeat this process for all members you want to add to your organization

Step 4: Create a GitHub OAuth App

1. Go to your organization settings: github.com/<your-organization>/settings

2. In the left sidebar, scroll down to Developer settings

3. Click OAuth Apps

4. Click New OAuth App

   

5. Fill in the OAuth application registration form:

   • Application name: Your domain name (e.g., “openhw.io domain”)

   • Homepage URL: Your JupyterHub homepage URL (e.g., https://www.openhw.io/)

     • Important: Must use HTTPS protocol

   • Application description: Brief description of your application (optional)

   • Authorization callback URL: Your OAuth callback URL

     • Format: https://<your-domain>/hub/oauth_callback

     • Example: https://www.openhw.io/hub/oauth_callback

     • Important: Must use HTTPS protocol

     • Note: The “/github” part in the URL is only needed for Multi-OAuth setups. For simple GitHub OAuth, use the format shown above.

   • Enable Device Flow: Leave unchecked (not needed for JupyterHub)

   • Click Register application

   

6. After registration, you will see your Client ID and Client secrets:

   • Copy the Client ID - you’ll need this for your JupyterHub configuration

   • Click Generate a new client secret

   • Important: Copy the client secret immediately - it will only be shown once!

   • Store both the Client ID and Client secret securely

   

Step 5: Configure JupyterHub for GitHub OAuth

1. Open your JupyterHub configuration file (typically jupyterhub_config.py or values.yaml for Helm deployments)

2. Add the GitHub OAuth configuration:

   # ---- GitHub OAuth ----
   # If you are only using GitHub OAuth, not Multi-Auth, the link should be:
   # https://<Your.domain>/hub/oauth_callback
   GitHubOAuthenticator:
     oauth_callback_url: "https://<Your.domain>/hub/oauth_callback"
     client_id: "YOUR_CLIENT_ID"
     client_secret: "YOUR_CLIENT_SECRET"
     allowed_organizations:
       - <YOUR-ORG-NAME>
     scope:
       - read:user
       - read:org
   

   

3. Configure team-to-resource mapping on jupyterhub_config.py:

   # TEAM RESOURCE MAPPING
   # left side is team_name, right side is resource_name
   # the resource_name should be the same as the key in RESOURCE_IMAGES
   TEAM_RESOURCE_MAPPING = {
       "cpu": ["cpu"],
       "gpu": ["Course-CV", "Course-DL", "Course-LLM"],
       "official": ["cpu", "Course-CV", "Course-DL", "Course-LLM"],
       "AUP-IT": ["Course-CV", "Course-DL", "Course-LLM"]
   }
   

   

4. Update the organization in jupyterhub_config.py file

Search for the following line and update the name of your GitHub organization

team["organization"]["login"] == 

5. Save the configuration file and restart JupyterHub for the changes to take effect

Verification

1. Navigate to your JupyterHub URL

2. You should see a “Sign in with GitHub” button

3. Click it and authorize the application

4. You should be redirected back to JupyterHub and logged in

5. Verify that users can only access resources based on their team membership

Troubleshooting

• OAuth callback error: Ensure your callback URL exactly matches what you configured in GitHub (including HTTPS)

• Organization not found: Verify the organization name in your configuration matches your GitHub organization exactly

• Users can’t access resources: Check that users are added to the correct teams in GitHub

• Authentication fails: Verify your Client ID and Client Secret are correct and the secret hasn’t expired

Security Best Practices

1. Always use HTTPS for your JupyterHub deployment

2. Keep your Client Secret secure and never commit it to version control

3. Regularly review organization members and their team assignments

4. Use environment variables or secret management systems for storing OAuth credentials

5. Limit OAuth scopes to only what’s necessary (read:user and read:org)

Additional Resources

• JupyterHub Documentation

• GitHub OAuth Documentation

• OAuthenticator Documentation