Identity provider configuration
Private cloud only.
This page is the reference for every setting involved in identity provider (IdP) login, including the group mapping. For what the feature does and how to set it up, see Identity provider login.
IdP login is configured in the mcp.idp block of the Helm chart, which has two sub-blocks: env for the identity provider variables, and mapping for the group-to-credential mapping.
mcp:
idp:
enabled: true
env:
- name: IDP_ISSUER
value: "https://your-idp.example.com"
- name: IDP_CLIENT_ID
value: "your-idp-client-id"
- name: IDP_CLIENT_SECRET
value: "your-idp-client-secret"
mapping: |
profiles:
- name: platform-admins
client_id: svc-platform-admin
client_secret: <deeploy-client-secret>
groups: [deeploy-admins]
- name: default
match_all: true
client_id: svc-shared
client_secret: <deeploy-client-secret>
allow_tools: [list_agents, register_agent, send_trace]
The chart refuses to render if mcp.idp.enabled is true and mcp.idp.mapping is empty, so a deployment cannot be created without one. This is deliberate: without a mapping there is no credential to resolve, and every IdP user would be denied.
The reverse is not true — setting mcp.idp.env without enabled: true has no effect, and the variables are not passed to the container at all.
Required variables
| Variable | Required | Description |
|---|---|---|
IDP_ISSUER | Yes | Base issuer URL of your identity provider. The server appends /.well-known/openid-configuration itself — do not include that path. See Provider notes for the exact form per provider. |
IDP_CLIENT_ID | Yes | Client ID of the confidential OAuth application you registered with the IdP. |
IDP_CLIENT_SECRET | Yes | Client secret for that application. Use the secret value, not its ID. |
All three must be set for IdP login to engage. A missing one leaves the server on the Deeploy credential flow.
Claims and scopes
| Variable | Required | Description |
|---|---|---|
IDP_SCOPES | No | Scopes requested from the IdP. Defaults to openid,profile,email. Must include openid, and email so that an unmatched user can be identified in logs and on the error page. Add whatever scope yields the groups claim — Okta needs groups here. |
IDP_GROUPS_CLAIM | No | Claim holding the user's group or role list. Defaults to groups. The mapping matches against these values. |
IDP_EMAIL_CLAIM | No | Claim holding the user's email. Defaults to email. Used for explicit per-user rules and for identifying the user in logs. |
IDP_NAME_CLAIM | No | Claim holding the user's display name. Defaults to name. |
These three fall back to their defaults only when unset. Setting one to an empty string replaces the default with nothing, so the claim is never found — users then appear to have no groups and everyone is denied. Leave the variable out rather than setting it to "".
IDP_SCOPES behaves differently: an empty value yields an empty scope set, which also breaks login.
Endpoint overrides
The server reads the authorization, token, and JWKS endpoints from the IdP's discovery document. Override them for an IdP that has no discovery document.
| Variable | Required | Description |
|---|---|---|
IDP_AUTHORIZATION_ENDPOINT | No | Authorization endpoint override. Taken from the IdP's discovery document when unset. |
IDP_TOKEN_ENDPOINT | No | Token endpoint override. Taken from the IdP's discovery document when unset. |
IDP_JWKS_URI | No | JWKS endpoint override, used to verify token signatures. Taken from the IdP's discovery document when unset. |
Set all three to skip the discovery request entirely. A partial set still makes the request, because the endpoints you did not set have to come from somewhere — the values you do set win over the discovered ones.
Issuer validation
| Variable | Required | Description |
|---|---|---|
IDP_ACCEPTED_ISSUERS | No | Comma-separated list of additional iss values to accept. Needed for Entra's common and organizations endpoints, which issue a per-tenant iss that does not equal the discovery issuer. |
Token exchange
| Variable | Required | Description |
|---|---|---|
IDP_TOKEN_AUTH_METHOD | No | How the client secret is sent at the token endpoint. Defaults to client_secret_post. Options: client_secret_post or client_secret_basic. Should match how the application is registered with the IdP. |
Timeouts and caching
| Variable | Required | Description |
|---|---|---|
IDP_DISCOVERY_TIMEOUT_SECONDS | No | Timeout for the discovery request. Defaults to 5 seconds. |
IDP_REQUEST_TIMEOUT_SECONDS | No | Timeout for requests to the IdP, including the token exchange. Defaults to 10 seconds. |
IDP_JWKS_CACHE_TTL_SECONDS | No | How long the IdP's signing keys are cached before being fetched again. Defaults to 3600 seconds. |
IDP_STATE_TTL_SECONDS | No | How long a signed login state stays valid. Defaults to 600 seconds. This only bridges the redirect out to the IdP and back, so it is deliberately short. A non-positive or non-numeric value falls back to the default. |
Login behaviour
| Variable | Required | Description |
|---|---|---|
IDP_ALLOW_CREDENTIAL_LOGIN | No | Defaults to off, which redirects straight to the IdP. 1 instead shows a combined page with both an SSO button and the Deeploy credential fields. See Offering both login methods. |
Profile mapping
The profile mapping is what connects an identity provider to Deeploy. SSO proves who a user is; the profile mapping decides which Deeploy credential their session runs as. It is a YAML (or JSON) document with a single profiles list:
profiles:
- name: platform-admins
client_id: svc-platform-admin
client_secret: <deeploy-client-secret>
groups: [deeploy-admins]
- name: ml-engineers
client_id: svc-ml-engineer
client_secret: <deeploy-client-secret>
groups: [ml-platform, data-science]
allow_tools: [list_agents, list_use_cases, get_use_case, add_control_evidence]
allow_skills: [deeploy-use-case-controls]
workspace_id: ws-ml
- name: default
match_all: true
client_id: svc-shared
client_secret: <deeploy-client-secret>
allow_tools: [list_agents, send_trace]
Profile fields
| Field | Required | Description |
|---|---|---|
name | Yes | Identifies the profile, and appears in the session token. |
client_id | Yes | Deeploy credential client id the session runs as. |
client_secret | Yes | Deeploy credential client secret. |
groups | No | IdP group values that select this profile. |
users | No | Email addresses that select this profile. |
match_all | No | Makes this the catch-all profile. At most one profile may set it. |
allow_tools | No | Only these tools are offered. Omit for unrestricted. |
allow_skills | No | Only these skills are offered. Omit for unrestricted. |
workspace_id | No | Overrides the deployment-wide workspace for sessions using this profile. |
A profile with none of groups, users, or match_all matches nothing — so a typo in a group name denies access rather than silently granting it.
Matching rules
Rules are evaluated in this order:
users— explicit email addresses. These win outright, before any group is considered.groups— the user's IdP groups. Profiles are checked in file order, and the first match wins.match_all— the single catch-all fallback, checked last.
If nothing matches, the user is denied.
Group matching is case-sensitive; email matching is not. Using the wrong casing for a group name is the most common cause of a user being denied with no obvious reason.
Limits per profile
allow_tools and allow_skills restrict which tools and skills a session is offered, and workspace_id scopes a profile to a different workspace than the deployment default.
allow_tools, allow_skills, and workspace_id decide what the server offers a session. They do not reduce what the underlying Deeploy credential is permitted to do — a user who obtains that credential by another route is limited only by the credential itself. Shape the Deeploy credential's own permissions if you need a hard boundary. See Limitations.
match_all: true hands its shared credential to any identity the IdP issues a token for. The server never sees whether the user was assigned to the application, so this is often much broader than intended. Leave it out if unmatched users should be denied. See IdP-side assignment is not enforced by the token.
Applying mapping changes
Editing mcp.idp.mapping changes the generated secret and triggers a rolling restart, so the new mapping takes effect without any further action. A mapping that fails to parse is refused and the previous mapping stays in effect, so a malformed edit cannot lock everyone out — but it also means the change silently does not apply. Check the MCP server logs to confirm.