Skip to main content

Configuring Single Sign-On (SSO) for CodeTogether

To integrate CodeTogether with your organization's identity provider, configure the SSO settings in the cthq.properties file. This setup supports providers compatible with the OpenID Connect (OIDC) protocol, such as GitHub, GitLab, Keycloak, Azure AD, and others.

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.

General SSO Configuration​

INTEL_FQDN Configuration​

INTEL_FQDN is defined in your .env file and represents the public hostname(FQDN) of the Intel service (e.g. intel.example.com).

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:

provider: The name of the SSO provider (e.g., keycloak, github, google). client.id: The client/application ID issued by the SSO provider. .secret: The secret key provided by the SSO provider. client.issuer.url: The issuer or discovery URL of the provider. .uri: The URI to which the provider should redirect after authentication. Additional optional values: auth.uri, token.uri, info.uri, logout.uri, 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

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.

Additional Notes​

  • Ensure that the hq.sso.redirect.uri matches the redirect URI configured in your SSO provider.
  • The hq.sso.jwt.set.uri is used to retrieve the JSON Web Key Set (JWKS) for validating tokens.
  • For providers like Keycloak, the hq.sso.client.issuer.url may be required instead of individual endpoint URLs.
  • If your deployment is single-tenant, the hq.sso.tenants property is not necessary.
  • For detailed instructions on configuring specific SSO providers, refer to the respective provider's documentation. If you need assistance tailoring the configuration to your specific SSO provider, please contact your CodeTogether technical support representative for expert guidance.
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: