Skip to main content

GitHub SSO Setup (OAuth/OIDC-style configuration)

This guide explains how to create and configure a GitHub OAuth App for CodeTogether SSO.

Audience​

SSO/IdP Administrator​

Create the GitHub OAuth application and provide required values.

CodeTogether System Administrator​

Apply values in cthq.properties, restart services, and validate login.

Prerequisites​

  • Access to a GitHub organization/account with permission to create OAuth Apps
  • Access to your CodeTogether environment configuration (QA/Staging/Prod)

1) Create OAuth App in GitHub​

  1. Go to GitHub Settings → Developer settings → OAuth Apps
  2. Click New OAuth App
  3. Configure:
    • Application name: e.g. CodeTogether SSO
    • Homepage URL: https://<your-domain>
    • Authorization callback URL:
      https://<your-domain>/api/v1/auth/sso/success/insights
  4. Click Register application

2) Collect required values​

From the app page, copy:

  • Client ID → hq.sso.client.id

Then generate and copy:

  • Client Secret → hq.sso.client.secret
danger

Copy the Client Secret when generated and store it securely. If lost, generate a new one.

3) Confirm callback URL​

In GitHub OAuth App settings, verify callback URL is exactly:

https://<your-domain>/api/v1/auth/sso/success/insights

Must match exactly (scheme, host, and path).

4) Configure CodeTogether (cthq.properties)​

hq.sso.provider=github
hq.sso.label=GitHub
hq.sso.client.id=<GITHUB_CLIENT_ID>
hq.sso.client.secret=<GITHUB_CLIENT_SECRET>
hq.sso.redirect.uri=https://<your-domain>/api/v1/auth/sso/success/insights
hq.sso.auth.uri=https://github.com/login/oauth/authorize
hq.sso.token.uri=https://github.com/login/oauth/access_token
hq.sso.info.uri=https://api.github.com/user
hq.sso.logout.uri=https://github.com/logout
hq.sso.jwt.set.uri=https://token.actions.githubusercontent.com/.well-known/jwks

5) Deploy and restart​

  • Apply configuration changes
  • Restart backend services so SSO settings are reloaded

6) Validation checklist​

  • OAuth App exists in GitHub
  • Callback URL matches exactly in GitHub and CodeTogether
  • client.id and client.secret are valid
  • Login flow redirects to GitHub and returns successfully to: /api/v1/auth/sso/success/insights