Single Sign-On (SSO) Support

SSO integration was introduced in CodeTogether 4.0 and is currently available only for On-Premises installations.

Scope of SSO Integration

CodeTogether integrates with SSO providers that support the OpenID Connect protocol—this includes providers like Okta, Azure AD, Microsoft AD FS and Auth0 among others.

SSO support in CodeTogether is straightforward—once configured on your on-premises install, users will be allowed CodeTogether access only if they’ve been authorized by your provider. If they are unauthorized, they will neither be able to host, nor join any sessions running on your server.

At this time, the only SSO integration we support is the ability to log in and log out. SSO groups and other similar constructs are not synchronized with CodeTogether teams, or any other CodeTogether functionality.

Configuration

Setting Up Your SSO Provider

When integrating CodeTogether as a new application in your SSO provider you will need to configure the following common OIDC properties:

Property Value
Login redirect URI CT_SERVER_URL/sso/authorization-code/callback
Logout redirect URI CT_SERVER_URL/sso/logout
Allowed Grant Types  
– Client Credentials enabled
– Authorization Code enabled
– Refresh Token enabled

CT_SERVER_URL must be the externally visible name of your on-premises server, using the HTTPS protocol. e.g. https://codetogether.acme.com
You will already have configured this variable while setting up your container.

Setting Up Your CodeTogether Server

To have CodeTogether integrate with the SSO application you created in the step above, you need to configure the following environment variables. These are in addition to the standard environment variables defined in our on-premises installation guide.

Environment Variable Description
CT_SSO_SYSTEM_BASE_URL
(since CodeTogether 4.1.2)

The base URL for your identity system, aka, Domain, Realm, etc.

Example: https://{OKTA_DOMAIN}/oauth2/default

The presence of this variable signals to CodeTogether that SSO is enabled. If not defined, all variables below are ignored.

CT_SSO_TOKEN_ENDPT Optional: URL to the authorization server endpoint that provides refresh tokens.
Use this environment variable for non-standard OIDC systems.

Example: https://{OKTA_DOMAIN}/oauth2/default/v1/token

CT_SSO_CLIENT_ID Unique ID assigned by the SSO provider to the CodeTogether SSO application.
CT_SSO_CLIENT_SECRET Private key assigned by the SSO provider to the CodeTogether SSO application.
CT_SSO_PROVIDER

Optional: Can be OKTA, MICROSOFT or IDCS.

If you’re using another provider, please omit this variable.

CT_SSO_SECURE_JWKS_ENDPT_ENABLE

Optional: Can be “true” or “false”.

When true, it informs CT_SSO that the authorization server URL used by the OpenID middleware for access to public keys is protected and can only be accessed by an authenticated user.

An example is the Oracle IDCS, which does not provide anonymous access to its jwks_uri endpoint. For such systems, either include this environment variable with a value of “true”, or enable your IDCS default settings to allow access to the public signing keys. You can make this change in the IDCS Dashboard – go to Settings > Default Settings and enable Access Signing Certificate.

Note: In CodeTogether 4.1.2, CT_SSO_SYSTEM_BASE_URL replaces the CT_SSO_AUTHORIZATION_ENDPT, as this new name better reflects the purpose of this variable. The older variable will continue to function as an alias.

Please see Appendix A: Configuring an Okta Application for CodeTogether Authorization, for additional details. The configuration process will be similar in all SSO providers.

Example Identity Provider Configurations

Okata OpenID Connect

ENV CT_SSO_PROVIDER "OKTA"
ENV CT_SSO_CLIENT_ID "0oa5vFs2yPWSiq..."
ENV CT_SSO_CLIENT_SECRET "bI96uXez4QBb3ZxIY7eO4GCr..."
ENV CT_SSO_SYSTEM_BASE_URL "https://YOURDOMAIN.okta.com/oauth2/default"

Oracle IDCS OpenID Connect

ENV CT_SSO_PROVIDER "IDCS"
ENV CT_SSO_CLIENT_ID "357c9f87e5de442..."
ENV CT_SSO_CLIENT_SECRET "ab358ae8-4729-4f08-bc74-..."
ENV CT_SSO_SYSTEM_BASE_URL "https://idcs-YOURTENANCY.identity.oraclecloud.com"
ENV CT_SSO_SECURE_JWKS_ENDPT_ENABLE "true"

Keycloak OpenID Connect

ENV CT_SSO_PROVIDER "KEYCLOAK"
ENV CT_SSO_CLIENT_ID "code-together"
ENV CT_SSO_CLIENT_SECRET "924ec27b-670e-4e18-8b97-..."
ENV CT_SSO_SYSTEM_BASE_URL "https://HOSTNAME/auth/realms/YOURREALM"

Azure OpenID Connect

ENV CT_SSO_PROVIDER "MICROSOFT"
ENV CT_SSO_CLIENT_ID "ab55a5a3-498b-479b-..."
ENV CT_SSO_CLIENT_SECRET "_ZcjuPg_TNh_g~hld..."
ENV CT_SSO_SYSTEM_BASE_URL "https://login.microsoftonline.com/89abea56-e91d-41f7-a8.../v2.0"

Using CodeTogether with SSO

The first time you use CodeTogether, you will be asked to authenticate with your organization’s single sign-on service.

Click connect to be taken to your provider’s login page, where you can authenticate as required.


CodeTogether view after logging in

SSO FAQ

  1. How long will a user stay logged in?
    CodeTogether will authenticate the user each IDE session. Refresh tokens, if available, will be used to refresh auth data, and keep the user logged in without having to sign in again. Of course, this depends upon how an SSO Administrator configures the lifetime of refresh tokens.
  2. What info does CodeTogether SSO Integration access?
    CodeTogether accesses minimal information, as defined by the following OIDC scopes: openid, profile, off_line
  3. How do I find the Token endpoint URL (CT_SSO_TOKEN_ENDPT)?
    As of CodeTogether 4.1.2, this variable is optional and we will fetch it from the well known configuration. However, you may specify it if you have a non-standard OIDC system or wish to override the value.
    For this URL and other configuration details, look for the token_endpoint property in the provider’s discovery document: CT_SSO_SYSTEM_BASE_URL/.well-known/openid-configuration
    Following are examples of discovery document paths:
    https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration
    https://dev-83772425.okta.com/oauth2/default/.well-known/openid-configuration
    https://login.microsoftonline.com/9e67eb9a-b109-4066-a505-bf770af1bdb0/v2.0/.well-known/openid-configuration

Appendix A: Configuring an Okta Application for CodeTogether Authorization

This section will walk you through the creation of an SSO application in Okta – where you specify CodeTogether URLs to configure the application, and pick up endpoint URLs and properties to plug back into your CodeTogether container configuration.

Even as we step through this process with Okta, the process and properties will be quite similar for other SSO providers as well.

  1. Add and then Create a new Okta Application
  2. Give your application a suitable name, select Web as the platform and OpenID Connect as the sign on method.
  3. Specify the Login and Logout redirect URI as described in the configuration section and click Save.
  4. Your application will now be created, and you can copy the Client ID and Client Secret from the Client Credentials section.
  5. Edit the General Settings and ensure you set the required Application grant types and Save these changes. Your SSO application is now ready for CodeTogether integration.