# 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](https://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//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:///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: ```yaml # ---- GitHub OAuth ---- # If you are only using GitHub OAuth, not Multi-Auth, the link should be: # https:///hub/oauth_callback GitHubOAuthenticator: oauth_callback_url: "https:///hub/oauth_callback" client_id: "YOUR_CLIENT_ID" client_secret: "YOUR_CLIENT_SECRET" allowed_organizations: - scope: - read:user - read:org ```  3. Configure team-to-resource mapping on `jupyterhub_config.py`: ```python # 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 ```python 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](https://jupyterhub.readthedocs.io/) - [GitHub OAuth Documentation](https://docs.github.com/en/developers/apps/building-oauth-apps) - [OAuthenticator Documentation](https://oauthenticator.readthedocs.io/)