Documentation base URLs use placeholder https://{your-tenant}.sso.id. Log in to show your tenant or custom domain.
Log in for Your Tenant URL
Chapter 3B — Enterprise OIDC Federation

OpenID Connect (OIDC) Enterprise Connections

Federate with enterprise workforce directories — including Microsoft Entra ID (Azure AD), Okta, Auth0, Keycloak, PingFederate, and OneLogin — using automatic .well-known/openid-configuration discovery, JWKS cryptographic validation, group-to-role mapping, and SCIM 2.0 provisioning.

The Enterprise OIDC Story 1. Auto-Discovery Setup 2. Entra ID & Okta Guide 3. Group & Role Mapping 4. API & AI Prompt
Enterprise Story: Onboarding a 5,000-Seat Microsoft Entra ID Customer

Why Modern Enterprises Prefer OIDC Federation + SCIM 2.0

When Apex Healthcare subscribed to CloudPulse, their IT team used Microsoft Entra ID (Azure AD). Instead of manually exchanging X.509 certificates, Apex gave CloudPulse their Entra Tenant ID (contoso.onmicrosoft.com), Client ID, and Client Secret.

In /connections, CloudPulse pasted the Entra OIDC Discovery URL (https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration), clicked Fetch Discovery Metadata, verified the connection live with Test Connection, and mapped Entra Security Groups directly to CloudPulse RBAC Roles.

1. Automatic OIDC Discovery & Endpoint Population

When creating an OIDC Connection in /connections, you can either use a provider template (GET /api/connections/defaults) or paste the external IdP's Issuer / Discovery URL:

Flow Diagram Enterprise OIDC Auto-Discovery & Federation Sequence
sequenceDiagram autonumber participant User as End User participant SSO as SSO.ID Broker (/connections) participant Entra as Microsoft Entra / Okta OIDC User->>SSO: Selects Enterprise OIDC Connection SSO->>Entra: GET /authorize (PKCE S256, openid, profile, groups) Entra->>User: Corporate Login & MFA Challenge Entra-->>SSO: 302 Callback with code SSO->>Entra: POST /token (code + secret/PKCE) Entra-->>SSO: Upstream id_token + access_token SSO->>SSO: Validate JWKS signature & Map Claims to Roles SSO-->>User: Issue SSO.ID Session Token
SSO.ID fetches the upstream IdP metadata, brokers the OAuth code exchange with PKCE, maps claims, and JIT-provisions the user into the tenant.
1

Provide Issuer & Discovery URL

Enter the external IdP's .well-known/openid-configuration URL. SSO.ID automatically resolves the authorization_endpoint, token_endpoint, userinfo_endpoint, end_session_endpoint, and jwks_uri.

2

Configure Scopes, Response Type & PKCE

Default scopes include openid profile email groups offline_access. SSO.ID supports both confidential back-channel code exchange (response_type=code) with PKCE (S256) and id_token validation against the upstream IdP's JWKS keys.

2. Common Enterprise OIDC Provider Settings

Enterprise IdP Discovery Endpoint Pattern Redirect URI to Register in Customer's IdP
Microsoft Entra ID (Azure AD) https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration https://{your-tenant}.sso.id/auth/oidc/callback (or custom domain)
Okta Workforce Identity https://{your-okta-domain}/oauth2/default/.well-known/openid-configuration https://{your-tenant}.sso.id/auth/oidc/callback
Keycloak https://{keycloak-host}/realms/{realm}/.well-known/openid-configuration https://{your-tenant}.sso.id/auth/oidc/callback
Auth0 / Ping / OneLogin https://{domain}/.well-known/openid-configuration https://{your-tenant}.sso.id/auth/oidc/callback

3. Mapping OIDC groups & roles Claims to SSO.ID RBAC

Enterprise OIDC providers emit a groups or roles array inside the id_token or userinfo response. In the Mappings tab of the Connection dialog:

  • Map the incoming claim name (e.g., groups or roles) to SSO.ID's Role/Group resolver.
  • Define explicit mappings (e.g., External Group a1b2c3d4-entra-group-id → SSO.ID Role Billing Administrator).
  • Pair with SCIM 2.0 (https://{your-tenant}.sso.id/api/scim/v2/connections/{connectionId}) so group changes and deactivations happen even when the user is offline.

4. AI Agent Prompt for Enterprise OIDC Onboarding

AI Agent Prompt Automate Enterprise Customer OIDC Connection Onboarding via SSO.ID API 
You are an enterprise SaaS platform engineer. Build a self-service **"Configure Enterprise OIDC SSO"** wizard inside our B2B customer admin portal that calls **SSO.ID v2** (`https://{your-tenant}.sso.id/api`).

### Workflow to Implement
1. Collect from the customer IT admin:
   - `providerName` (e.g. `Microsoft Entra ID`, `Okta`, `Keycloak`)
   - `discoveryUrl` (`https://.../.well-known/openid-configuration`)
   - `clientId` and `clientSecret`
   - `scopes` (default `openid profile email groups`)
2. Call `POST https://{your-tenant}.sso.id/api/connections/test` with their OIDC configuration to validate their Discovery URL and credentials before saving.
3. Call `POST https://{your-tenant}.sso.id/api/connections` with `assignToOrganizationOnly: true` and `organizationId: `, enabling `autoProvisionUsers: true`.
4. Link the newly created `connectionId` to the customer's Organization via `POST https://{your-tenant}.sso.id/api/organizations//connections` and display their dedicated SCIM 2.0 endpoint (`https://{your-tenant}.sso.id/api/scim/v2/connections/${connectionId}`).