Skip to main content

Microsoft Entra ID SSO Setup (OIDC)

This guide explains how to create and configure a Microsoft Entra application for CodeTogether SSO.

Audience​

SSO/IdP Administrator​

Create the Entra app and provide required values.

CodeTogether System Administrator​

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

Prerequisites​

  • Access to Microsoft Entra admin center
  • Permission to create app registrations
  • Access to your CodeTogether environment configuration (QA/Staging/Prod)

1) Create app registration​

  1. Go to Microsoft Entra admin center
  2. Navigate to Microsoft Entra ID → App registrations
  3. Click New registration
  1. Set:
    • Name: e.g. CodeTogether QA SSO
    • Supported account types: typically single tenant
    • Redirect URI:
      • Platform: Web
      • Value: https://<your-domain>/api/v1/auth/sso/success/insights
  2. Click Register

2) Collect required values​

From Overview, copy:

  • Application (client) ID → hq.sso.client.id
  • Directory (tenant) ID → used in issuer URL:
    https://login.microsoftonline.com/<TENANT_ID>/v2.0

3) Create client secret​

  1. Open Certificates & secrets
  2. Click New client secret
  3. Add description/expiration and create
IMPORTANT: Use Secret Value, not Secret ID

Use the Client Secret Value for hq.sso.client.secret.

  • The secret Value is shown only once at creation time.
  • After that, it is masked and cannot be copied again.
  • If lost, generate a new client secret.

4) Confirm redirect URI​

In Authentication, verify Web redirect URI is exactly:

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

Must match exactly.

5) Configure CodeTogether (cthq.properties)​

hq.sso.provider=azure
hq.sso.label=Microsoft Entra ID
hq.sso.client.id=<APPLICATION_CLIENT_ID>
hq.sso.client.secret=<CLIENT_SECRET_VALUE>
hq.sso.client.issuer.url=https://login.microsoftonline.com/<TENANT_ID>/v2.0
hq.sso.redirect.uri=https://<your-domain>/api/v1/auth/sso/success/insights

6) Deploy and restart​

Apply configuration changes

  • Restart backend services so SSO settings are reloaded

7) Validation checklist​

  • App exists in Entra app registrations
  • client.id matches Application ID
  • client.issuer.url contains correct tenant and ends with /v2.0
  • Redirect URI matches exactly in Entra and CodeTogether
  • Client secret value is valid and unexpired
  • Login flow returns successfully to /api/v1/auth/sso/success/insights