Skip to main content

Configuring Single Sign-On (SSO) for CodeTogether

To integrate CodeTogether with your organization's identity provider (IdP), configure SSO settings in the Intel container via cthq.properties. CodeTogether uses OpenID Connect (OIDC) (OAuth 2.0 Authorization Code flow) for user authentication. Any standards-compliant OIDC provider can work as long as the required redirect URLs and claims are configured.

note

CodeTogether requires Single Sign-On (SSO) for user authentication. All deployments must be integrated with an SSO provider. If your organization does not currently have an SSO provider, please contact your CodeTogether technical support representative for guidance on configuration of your specific SSO connection.

Supported IdPs & flows​

CodeTogether supports OIDC IdPs. Commonly used providers include:

  • Keycloak
  • Microsoft Entra ID (Azure AD)
  • Okta
  • GitHub
  • GitLab
  • Google
  • Ping Identity

If your IdP is not listed, use the OIDC discovery/issuer URL approach and provide the required redirect URL + claims (see below).

Who does what (2-team model)​

Team A: SSO/IdP Administrator​

Responsible for:

  • Creating the SSO app in the identity provider
  • Configuring redirect URI(s)
  • Generating client credentials
  • Sharing required values securely with the system administrator

Team B: CodeTogether System Administrator​

Responsible for:

  • Updating cthq.properties
  • Applying config and restarting backend services
  • Validating login flow end to end

What the IdP admin needs to configure (checklist)​

In your IdP, create an OIDC Web Application (confidential client) and collect:

  1. Issuer / Discovery URL
    • Example formats:
      • Keycloak: https://<keycloak-host>/realms/<realm>
      • Entra ID: https://login.microsoftonline.com/<tenant-id>/v2.0
      • Okta (default custom auth server): https://<yourOktaDomain>/oauth2/default
  2. Client ID
  3. Client Secret Value
  4. Redirect (callback) URL (exact match required)
  5. Scopes: at minimum openid. Recommended: openid,profile,email
  6. Claim mapping: ensure the ID token includes a stable user identifier + a display name + (recommended) email

Recommended IdP settings:

  • PKCE: not required (server-side flow)
  • Client authentication method: default is usually client_secret_basic (some IdPs require client_secret_post)
  • Allowed CORS / Web origins: your Intel base URL (e.g., https://intel.example.com)
  • Post-logout redirect (optional): https://<INTEL_FQDN>/*
Microsoft Entra secret requirement

Use Client Secret Value in hq.sso.client.secret — not Secret ID.

The secret value is shown only once when created, then masked. If the value is lost, create a new client secret.

Required callback URL​

Use the Intel public hostname (FQDN) as seen by end-users.

  • Sign-in redirect / callback URL
    • https://<INTEL_FQDN>/api/v1/auth/sso/success/insights
note

Your IdP redirect URI must match exactly (scheme, host, path, trailing slashes).

Required claims (attributes) and example mappings​

CodeTogether expects standard OIDC identity information. Ensure your IdP issues these in the ID token:

  • Stable user identifier: sub (required by OIDC)
  • Display name claim (choose one): preferred_username or name
  • Email (recommended): email

If your IdP does not provide the claim you want for display names, set:

hq.sso.name.attr=preferred_username

Or:

hq.sso.name.attr=name

General SSO Configuration​

INTEL_FQDN Configuration​

INTEL_FQDN represents the public hostname (FQDN) of the Intel service (for example: intel.example.com).

Where you set this depends on how you deploy:

  • Docker Compose: .env
  • Kubernetes/Helm: set codetogether.url in values.yaml and use the same public FQDN in cthq.properties

For example:

INTEL_FQDN=intel.example.com

Base URLs​

When running with docker compose these values are configured in the .env file. If you are running the server without docker compose, you will need to set these values in the cthq.properties file.

hq.base.url=https://${INTEL_FQDN}
hq.collab.url=https://${COLLAB_FQDN}
hq.collab.secret=${INTEL_SECRET}

SSO Provider Configuration​

You can configure SSO providers using the following common properties:

  • hq.sso.provider: Provider name (e.g., keycloak, azure, okta, github, gitlab, google, ping)
  • hq.sso.label: Display name shown to users on the login screen
  • hq.sso.client.id: OIDC client/application ID
  • hq.sso.client.secret: OIDC client secret
  • hq.sso.client.issuer.url: OIDC issuer URL
  • hq.sso.redirect.uri: Redirect/callback URL after successful login
  • Optional (provider-specific):
    • hq.sso.scope
    • hq.sso.name.attr
    • hq.sso.client.authentication.method
    • hq.sso.auth.uri, hq.sso.token.uri, hq.sso.info.uri, hq.sso.logout.uri, hq.sso.jwt.set.uri
hq.sso.tenants=github,gitlab
hq.sso.provider=<provider_name>  # e.g. github, gitlab, keycloak
hq.sso.label=<Provider Label>    # Display name for the SSO option
hq.sso.client.id=<client_id>
hq.sso.client.secret=<client_secret>
hq.sso.redirect.uri=https://<server-fqdn>/api/v1/auth/sso/success/insights

Single-Tenant SSO Configuration​

Use this if your deployment is configured to use only one SSO provider.

hq.sso.provider=github
hq.sso.label=GitHub
hq.sso.client.id=<github_client_id> ## Replace with your GitHub client ID
hq.sso.client.secret=<github_client_secret> ## Replace with your GitHub client secret
hq.sso.redirect.uri=https://${INTEL_FQDN}/api/v1/auth/sso/success/insights ## configure with .env with docker compose
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.jwt.set.uri=https://token.actions.githubusercontent.com/.well-known/jwks
hq.sso.logout.uri=https://github.com/logout

Multi-Tenant SSO Configuration​

Use this if you support multiple SSO providers. Each provider must be listed under hq.sso.tenants, and each configuration block must be prefixed accordingly.

hq.sso.tenants=github,gitlab

# GitHub Configuration
hq.sso.github.provider=github
hq.sso.github.label=GitHub
hq.sso.github.client.id=<github_client_id>
hq.sso.github.client.secret=<github_client_secret>
hq.sso.github.redirect.uri=https://${INTEL_FQDN}/api/v1/auth/sso/success/insights ## configure with .env with docker compose
hq.sso.github.auth.uri=https://github.com/login/oauth/authorize
hq.sso.github.token.uri=https://github.com/login/oauth/access_token
hq.sso.github.info.uri=https://api.github.com/user
hq.sso.github.jwt.set.uri=https://token.actions.githubusercontent.com/.well-known/jwks
hq.sso.github.logout.uri=https://github.com/logout

# GitLab Configuration
hq.sso.gitlab.provider=gitlab
hq.sso.gitlab.label=GitLab
hq.sso.gitlab.client.id=<gitlab_client_id>
hq.sso.gitlab.client.secret=<gitlab_client_secret>
hq.sso.gitlab.redirect.uri=https://${INTEL_FQDN}/api/v1/auth/sso/success/insights ## configure with .env with docker compose

Example: Single SSO Configurations​

Keycloak​

hq.sso.provider=keycloak
hq.sso.label=Keycloak
hq.sso.client.id=codetogether
hq.sso.client.secret=***
hq.sso.client.issuer.url=https://auth.edge.codetogether.com/realms/codetogether
hq.sso.redirect.uri=https://${INTEL_FQDN}/api/v1/auth/sso/success/insights

Azure​

hq.sso.provider=azure
hq.sso.client.id=***
hq.sso.client.secret=***
hq.sso.client.issuer.url=https://login.microsoftonline.com/<tenant-id>/v2.0
hq.sso.redirect.uri=https://${INTEL_FQDN}/api/v1/auth/sso/success/insights

GitHub​

hq.sso.provider=github
hq.sso.label=GitHub
hq.sso.client.id=***
hq.sso.client.secret=***
hq.sso.redirect.uri=https://${INTEL_FQDN}/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

Google​

hq.sso.provider=google
hq.sso.label=Google
hq.sso.client.id=***
hq.sso.client.secret=***
hq.sso.client.issuer.url=https://accounts.google.com
hq.sso.redirect.uri=https://${INTEL_FQDN}/api/v1/auth/sso/success/insights

Okta​

Use your Okta authorization server issuer URL. Most organizations use the default custom authorization server:

hq.sso.provider=okta
hq.sso.label=Okta
hq.sso.client.id=***
hq.sso.client.secret=***
hq.sso.client.issuer.url=https://<yourOktaDomain>/oauth2/default
hq.sso.redirect.uri=https://${INTEL_FQDN}/api/v1/auth/sso/success/insights
hq.sso.scope=openid,profile,email
# Optional (if you prefer a specific display name claim)
# hq.sso.name.attr=preferred_username
note

If your Okta org uses a different authorization server, the issuer will be https://<yourOktaDomain>/oauth2/<authorizationServerId>.

Ping Identity​

hq.sso.provider=ping
hq.sso.label=Ping Identity
hq.sso.client.id=***
hq.sso.client.secret=***
hq.sso.scope=openid,profile,email
hq.sso.client.issuer.url=https://auth.pingone.com/***
hq.sso.redirect.uri=https://${INTEL_FQDN}/api/v1/auth/sso/success/insights
hq.sso.name.attr=sub
hq.sso.client.authentication.method=client_secret_post
note

If you're unsure which authentication method to use, check your Ping Identity admin console or refer to the official Ping documentation. Using an incorrect method may cause token endpoint authentication to fail.

Handoff from IdP Admin to System Admin​

Once app setup is complete, the IdP admin should securely share:

  • provider
  • client ID
  • client secret value
  • issuer URL
  • redirect URI

The system admin then updates cthq.properties, deploys changes, restarts backend services, and validates login.

Provider-specific setup guides​

Validation checklist​

  • Redirect URI matches exactly in IdP and CodeTogether
  • Issuer URL is correct for the tenant/auth server
  • Client secret value is valid and not expired
  • User is redirected to IdP and returns successfully to: /api/v1/auth/sso/success/insights
Optional Configuration Steps Available

Looking to configure a provider like Keycloak from scratch or need to set up a custom Java truststore for secure certificate handling?

These steps are optional and only needed if: