Azure AD (OIDC) Setup
Step-by-step guide to configure Single Sign-On with Microsoft Entra ID (Azure AD) using OpenID Connect.
Prerequisites
- Azure AD tenant with admin access
- SecureCodingHub org admin account
- Organization domain verified in SecureCodingHub
Step 1 — Register an Application in Azure AD
Go to Azure Portal → Microsoft Entra ID → App registrations → New registration
Name: SecureCodingHub SSO
Supported account types: Accounts in this organizational directory only
Redirect URI: Web → https://api.securecodinghub.com/api/sch/auth/sso/callback/oidc
Click Register
Step 2 — Create a Client Secret
Go to Certificates & secrets → New client secret
Description: SecureCodingHub
Expiry: Choose your policy (recommended: 24 months)
Copy the secret value immediately — it is shown only once
Step 3 — Note Your IDs
Collect the following values from your Azure AD application. You will need them in the next step.
| Setting | Where to Find |
|---|---|
| Application (Client) ID | Overview page |
| Directory (Tenant) ID | Overview page |
| Client Secret | Certificates & secrets |
| Discovery URL | https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration |
Step 4 — Configure SSO in SecureCodingHub
Log in as Org Admin → SSO Settings
Protocol: OIDC
Entity ID / Client ID: paste your Application ID
Discovery / Metadata URL: paste your OpenID configuration URL
Client Secret: paste the secret
Enable SSO
Click Save
Step 5 — Test
Open an incognito/private browser window
Go to SecureCodingHub login
Enter an email address with your organization's domain
You should be redirected to Microsoft login
After authentication, you should be logged into SecureCodingHub
Common Azure AD SAML pitfalls
When SAML is used with Azure AD instead of OIDC, three failure modes account for most production incidents. The first is a mismatched entity ID. Azure AD will accept any string in the Identifier field of the SSO blade, but if it does not exactly match the SP Entity ID configured in SecureCodingHub, the SAML response is rejected with an audience restriction error. Copy the identifier from the SecureCodingHub SSO settings page directly, do not type it. Trailing slashes and protocol mismatches (http versus https) are common silent failures.
The second pitfall is a claim issuer URI mismatch. Azure AD signs assertions with the federation metadata URL it publishes, and SecureCodingHub validates that the issuer in the SAML response matches the issuer in the metadata. If you swap tenants, regenerate certificates, or copy a metadata URL from a different application, the issuer will diverge and every login will fail with an invalid signature error. The third pitfall is group claim sizing. Azure AD truncates group claims when the assertion exceeds the maximum payload, replacing groups with a graph endpoint reference. If you rely on group claims for downstream role mapping, configure Azure AD to emit only the groups assigned to the application rather than all groups the user belongs to.
How to verify SSO is working end-to-end
End-to-end verification has three stages. First, open an incognito window and start the login from the SecureCodingHub login page using a corporate email address. The browser should redirect to login.microsoftonline.com, present the Microsoft login experience, and then redirect back to SecureCodingHub. If the redirect back fails, capture the URL bar at the moment of failure. The error code in the query string is the most useful piece of evidence.
Second, confirm that the user lands at the correct organization and dashboard. A successful login with an empty home page or a wrong-org redirect usually points to a missing organization-domain mapping. Third, sign out, sign in again, and verify the second login is silent or near-silent. The Microsoft session cookie should make the second flow nearly invisible. If both logins require full re-authentication, your IdP application is using a session policy that prevents single sign-on cookie reuse. For shared troubleshooting steps, see the SAML setup guide.