SSO

This guide is for the IdP engineer configuring trust with this broker.

Scope

• Protocol supported: OIDC only (Authorization Code flow).

• Client auth methods supported at token endpoint:

• client_secret_post

• private_key_jwt (RS256 only)

Not supported:

• SAML

• OIDC implicit flow

• client_secret_basic

• private_key_jwt algorithms other than RS256

What You Configure on Your IdP

For all IdPs (Entra ID, Okta, Auth0, Keycloak, etc):

• Create an OIDC confidential client / app registration.

• Add redirect URI: https://sso.conducttr.app/api/sso/callback

• Ensure Authorization Code flow is enabled.

• Ensure PKCE (S256) is allowed.

• Ensure ID token contains:

• nonce (required)

• one stable user ID claim: sub (or oid for Entra)

• an email-like login claim: email preferred, preferred_username fallback

• Configure token endpoint auth method as one of:

• client_secret_post

• private_key_jwt

Integration Handoff by Auth Method

Option A: client_secret_post

What we need from you:

• issuer

• discovery_url

• client_id

• client_secret

• optional requested scopes beyond default

What you need from us:

• Redirect URI to register (https://sso.conducttr.app/api/sso/callback)

• Any agreed scope/profile requirements from relying apps

Option B: private_key_jwt (RS256)

What we need from you:

• issuer

• discovery_url

• client_id

• whether kid is required/enforced by your IdP

• optional requested scopes beyond default

What you need from us:

• Redirect URI to register (https://sso.conducttr.app/api/sso/callback)

• Client public key/certificate (or JWK) and kid for registration in your IdP app

Constraints:

• Signing algorithm must be RS256.

• Broker builds client_assertion with iss=sub=client_id, aud=<token_endpoint>, short expiry, unique jti.

Discovery

Please provide the Conducttr broker team with your discovery URL.

During the discovery phase, this is how the process proceeds:

1. Obtain the OpenID Connect configuration URL of your Identity Provider (IdP).

2. Verify the JSON Web Key Set (JWKS) endpoint to fetch public keys for signature validation.

3. Ensure the token endpoint and authorisation endpoint URLs are correct and accessible.

4. Confirm the issuer in metadata corresponds to the expected URL of your IdP.

5. Validate the supported signing algorithms, ensuring they include RS256.

6. Check for any custom claims that may need to be handled during token validation.

Ensure all discovery information aligns with the specifications for smooth integration and function of the SSO process.

Validation Checklist

• IdP has exact redirect URI match.

• Token endpoint auth method matches agreed method.

• First login reaches /api/sso/callback successfully.

• Token exchange succeeds at IdP token endpoint.

• ID token validates and contains required claims (nonce, user ID, email-like login).

• Browser returns to relying app with ticket=....

Notes for Entra ID

• oid is accepted as stable user identifier.

• preferred_username is accepted if email is absent.

• Coordinate issuer policy with the Conducttr broker team before launching multi-tenant/family issuer behavior.