> For the complete documentation index, see [llms.txt](https://helpdocs.conducttr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdocs.conducttr.com/concepts/security/sso.md).

# 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://helpdocs.conducttr.com/concepts/security/sso.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.