Configure Microsoft Azure OAuth

This requires an app registration in your school’s Microsoft Entra ID (Azure AD) tenant. You’ll likely need IT involvement for that part.

1. Install the authenticator

   sudo /opt/tljh/hub/bin/pip install oauthenticator

2. Register an app in Azure AD

   Either you or IT needs to do this at https://portal.azure.com > Entra ID > App registrations > New registration:

   • Name: JupyterHub
   • Supported account types: “Accounts in this organizational directory only” (single tenant)
   • Redirect URI: http://<your-ip>/hub/oauth_callback (type: Web)

   After creation, note down:

   • Application (client) ID
   • Directory (tenant) ID
   • Under Certificates & secrets, create a new client secret and copy the value

3. Configure TLJH

   sudo tljh-config set auth.type oauthenticator.azuread.AzureAdOAuthenticator
   sudo tljh-config set auth.AzureAdOAuthenticator.client_id '<client-id>'
   sudo tljh-config set auth.AzureAdOAuthenticator.client_secret '<client-secret>'
   sudo tljh-config set auth.AzureAdOAuthenticator.tenant_id '<tenant-id>'
   sudo tljh-config set auth.AzureAdOAuthenticator.oauth_callback_url 'http://<your-ip>/hub/oauth_callback'
   
   # Use the user principal name as the JupyterHub username
   sudo tljh-config set auth.AzureAdOAuthenticator.username_claim upn
   
   # Allow any user in the tenant to log in (simplest for classroom use)
   sudo tljh-config set auth.AzureAdOAuthenticator.allow_all true
   
   # Set yourself as admin using your Microsoft email
   sudo tljh-config set auth.AzureAdOAuthenticator.admin_users '["leo@yourschool.org.uk"]'
   
   sudo tljh-config reload hub

   Replace the email with whatever your actual school Microsoft account is.

   Why `username_claim upn`?

   The default email claim isn’t always present in tokens issued by school tenants — Entra ID often only includes upn (User Principal Name) and unique_name. Setting username_claim upn is the most reliable choice: every Entra user has one, and it’s stable across renames.

   `allowed_organizations` was removed

   Older guides recommend allowed_organizations. That trait was dropped in oauthenticator 17.3.0+. Use allow_all true for classroom-wide access, or allowed_groups (with Entra group object IDs) for finer control — see step 4 below.

4. Restrict to specific groups (optional)

   If you want only your CS class rather than the entire school:

   • In Azure AD, create a security group (e.g. “CS JupyterHub Users”)
   • In the app registration, go to Token configuration > Add groups claim > Security groups
   • Then configure:

   sudo tljh-config set auth.AzureAdOAuthenticator.manage_groups true
   sudo tljh-config set auth.AzureAdOAuthenticator.allowed_groups '["<group-object-id>"]'

   This way only students in that group can log in.

What to ask IT for:

• An app registration in the school’s Azure AD tenant
• The tenant ID
• If restricting by group, the object ID of the relevant security group