Identity provider login
Private cloud only.
By default, users authenticate to the MCP server with a Deeploy oauth credential — a client_id and client_secret. This page covers the alternative: letting users log in with your corporate identity provider (IdP) over OpenID Connect, so they authenticate with the account they already have.
Everything on this page is configured by an administrator in the Helm chart. Users do not configure any of it.
Deeploy's own interface has a separate SSO configuration — see Configure SSO with OIDC. That governs logging into Deeploy. The setup below governs logging into the MCP server, which is configured independently.
Why use it
Enabling IdP login opens the MCP server to people who have no Deeploy account of their own, thus allowing governance on their agentic actions in Deeploy. An analyst, contractor, or vendor can connect an agent and register their sessions and traces in Deeploy — so their work is governed centrally by the same workspaces, use cases, and controls as everyone else's, instead of happening off to the side. Deeploy's identity system and your IdP stay separate, and a profile is what bridges them: it maps an IdP group onto a Deeploy credential, so someone who has never signed in to Deeploy can still use an agent against Deeploy data.
Alongside it, IdP login also removes the need to hand out Deeploy credentials:
- Distribution. Credentials must be created and given to each person, and re-issued when someone leaves or loses theirs.
- Exposure. A credential pasted into a client has no expiry and can be copied anywhere. It is a long-lived secret sitting in a configuration field.
- No control over what a session can do. A Deeploy credential carries the permissions of its Deeploy account, so the server cannot narrow what an individual's MCP session reaches.
IdP login addresses these too. Users sign in with the account they already have, so there is nothing to distribute and nothing to rotate. Access follows the groups your identity provider already maintains — when someone changes team or leaves, you update it in one place and their next sign-in reflects it. And because the server never hands the Deeploy credential to the user, it can attach restrictions to each group's session instead.
The usual setup is the corporate IdP you already use for everything else, with groups that
already describe who should reach what — an ml-platform group for engineers, a compliance
group for the officers who use the use case controls workflow. Okta and Microsoft Entra ID
both serve the groups claim with a little configuration; Google Workspace does not, so there
the mapping falls back to explicit per-user rules or a single catch-all profile. See
Provider notes.
A profile maps a group to one shared Deeploy credential, so registrations and traces made through it appear in Deeploy's audit trail as coming from that credential's owner — not from the individual behind them. The verified identity (email, name) is logged by the MCP server, so server-side logs do record who did what, but Deeploy's own audit trail does not.
Give groups that need per-person attribution their own profile and credential. See No per-user Deeploy identity.
How it works
- The user opens the MCP server and is redirected to your IdP to sign in.
- The IdP returns a signed token containing the user's identity and their groups.
- The server looks the user's groups/email in a mapping file, which assign a mapped Deeploy credential to the user. It is also possible to configure a fallback profile for all users that do not fall under the other profiles with limited access to tools and skills.
- The session proceeds using that credential.
The mapping file is the bridge. The IdP proves who the user is; the mapping decides which Deeploy credential they run as.
Configuration
IdP login is enabled in the mcp.idp block of the Helm chart. It takes two things: the
provider variables in mcp.idp.env, and a mcp.idp.mapping that assigns Deeploy
credentials to groups.
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:
# ...
| Setting | Description |
|---|---|
mcp.idp.enabled | Turns IdP login on. While false, none of the variables below reach the container. |
mcp.idp.env | The identity provider variables, as Kubernetes name/value pairs. IDP_ISSUER, IDP_CLIENT_ID, and IDP_CLIENT_SECRET are required. |
mcp.idp.mapping | The group → Deeploy credential mapping. Required whenever enabled is true — the chart will not render without it. |
IDP_ISSUER is the base URL of your provider, without /.well-known/openid-configuration,
which the server appends itself. IDP_SCOPES must include openid, plus whatever scope
yields the groups claim (Okta: groups). Use the client secret's value, not its ID.
See Identity provider configuration for every variable, its default, and the full mapping reference. For the general installation procedure, see Install and upgrade with Helm.
Registering the application with your IdP
Create a confidential web application at your IdP and allow this redirect URI:
https://mcp.<base_url>/oauth/callback
Replace <base_url> with your own Deeploy host, matching the private cloud MCP server URL.
Then ensure the groups claim is actually present in the ID token — this is the step most often missed. See Provider notes.
The mapping
The mapping is what connects your identity provider to Deeploy. SSO proves who a user is; the mapping decides which Deeploy credential their session runs as, based on their groups. Without it, every IdP user is denied.
It is set with mcp.idp.mapping, alongside the IdP variables:
mcp:
idp:
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, send_trace]
Each profile pairs a Deeploy credential with the rules that select it. Rules are
matched in order — explicit users first, then groups in file order, then a single
match_all catch-all — and a user matching nothing is denied.
For every profile field, the full matching order, per-profile tool and skill limits, and how to apply changes, see Profile mapping.
match_all: true grants its shared credential to any identity the IdP issues a token
to. Because IdP-side assignment is not visible to the server, this can be much broader
than it looks — see IdP-side assignment is not enforced by the
token. Leave it out if you want
unmatched users denied.
Provider notes
The groups claim is not present by default on most providers. If it is missing, users appear to have no groups, nothing matches, and everyone is denied.
Okta
Two things are required, and omitting either fails silently:
- Add
groupstoIDP_SCOPES(inmcp.idp.env). - Add the claim to the app: Applications → your app → Sign On → Group Claims → Edit. Set Groups claim type to Filter and Claim name to
groups, with a filter such as Matches regex.*.
Note that this lives in Group Claims, not under OpenID Connect ID Token. Also assign users to the application — group membership alone does not put a user in the app.
Prefer a scoped filter (e.g. Starts with deeploy-) over .*. A token carrying every group in a large org can exceed size limits, and when that happens the provider drops the claim — which looks identical to never having configured it. Note Okta's match is unanchored unless you add ^/$.
Microsoft Entra ID
The claim must be added in the app registration: Token configuration → Add optional claim → ID → Groups. Assigning the group to the app is not enough on its own.
Entra then sends group object IDs (GUIDs), not names, so your mapping must use GUIDs. Matching on names requires Graph Group.Read.All. Two further details:
- If you use Entra's
commonororganizationsendpoints, setIDP_ACCEPTED_ISSUERS, because the advertised issuer differs from the token's. - With many group memberships Entra replaces the claim with an overage indirection, which yields no groups. See Entra group overage.
Google
Google's ID token has no groups claim. Group membership requires a separate Directory API call with domain-wide delegation, which is not implemented. Use users rules for specific accounts, or a match_all profile to cover the Workspace domain.
Offering both login methods
By default, once SSO is enabled the login page becomes a redirect to your IdP — the Deeploy credential form is not shown at all.
Setting IDP_ALLOW_CREDENTIAL_LOGIN: "1" (in mcp.idp.env) presents a single page offering both: a Sign in with SSO button and the credential fields below it. This is intended as a way in when the SSO path cannot complete — an unmapped group, group overage, or a rotated IdP secret that only an out-of-band login can fix.
Direct Deeploy credential logins carry no profile, so group-based filtering does not apply to them. A user who logs in this way is not restricted by allow_tools or allow_skills. They are only restricted by the scope of oauth credentials they have on Deeploy.
Revocation and access changes
Because the mapping is read on every request, most changes take effect immediately, without restarting anything:
| Change | Effect |
|---|---|
| Remove or rename a profile in the mapping | Immediate. Sessions naming it stop resolving and are refused. |
| Rotate a Deeploy secret in the mapping | Immediate. The next request uses the new secret. |
| Remove a user from an IdP group | Only at next login. See below. |
The one exception is IdP group membership. Groups are resolved once, at login, and stored in the session token; the server does not call the IdP on each request. So removing someone from a group does not end their current session — it takes effect the next time they log in.
If you need to cut off access immediately, use one of the mapping levers: remove the profile, or rotate the Deeploy credential behind it. Both work regardless of the user's current session.
Limitations
No per-user Deeploy identity
A profile maps a group to one Deeploy credential, shared by everyone in that group. Deeploy's internal audit trail therefore attributes actions to the owner of that credential — not to the individual who triggered them, who may have no Deeploy account at all.
This is inherent to the design rather than a shortcut — a Deeploy principal may not exist for an IdP user, and creating one automatically would mean the MCP server provisioning Deeploy identities from an external IdP. The verified identity (email, name) is logged by the server, so server-side logs do attribute actions to people.
Tool and skill limits are not a security boundary
allow_tools and allow_skills control what the agent is offered. They are defence in depth, not authorization — a hostile client can attempt any tool name directly.
The Deeploy credential behind each profile is authoritative. Scope each one to the minimum permissions it needs, and treat the tool limits as a usability feature rather than a security control.
IdP-side assignment is not enforced by the token
A valid signed token proves only that the IdP issued it. It does not prove the user was entitled to one — app assignment is enforced by the IdP before the token exists, so the server cannot see it.
Many providers (Entra among them) issue tokens to unassigned users by default. Combined with a match_all profile, that means everyone with a valid IdP account can get access.
If you rely on assignment to restrict access, enable enforcement at the IdP:
- Entra ID — Enterprise Applications → your app → Properties → Assignment required? = Yes. It defaults to No. This is on the enterprise application, not the app registration.
- Okta — ensure the app's sign-on policy actually requires assignment, and test with a user who is in no group.
- Google — the consent screen's test-user list applies only while the app is in Testing status.
Entra group overage
With many group memberships, Entra omits the groups claim and emits an overage indirection pointing at Graph instead. The claim resolves to nothing, no group rule matches, and the user is denied. The server log shows groups=[].
Mitigations: keep the group count under the threshold, use explicit users rules for affected accounts, or add a match_all fallback profile.
Google groups are unavailable
Google requires a separate Directory API call with domain-wide delegation to read group membership — a significant privilege to grant for a login feature. Not implemented. See Provider notes.
No SAML
The client is OIDC only. SAML-only IdPs need an OIDC bridge in front (such as Keycloak or Dex).
Sessions cannot be revoked individually
Once issued, a session token cannot be cancelled out-of-band — there is no revocation list. It expires on its own instead.
In practice this is mild, because the Deeploy credential behind it is re-resolved on every request: removing the profile makes the token useless immediately, even though the token itself stays technically valid. What is not possible is revoking one user's token while others on the same profile keep working.
A failed mapping change keeps the old mapping
If the mapping file is malformed on reload — a half-written secret mount, for example — the server keeps the previous good mapping rather than dropping to "no profiles". A truncated write therefore does not lock everyone out.
Troubleshooting
Users hitting "not authorized" is almost always one of these:
| Symptom | Likely cause |
|---|---|
| Everyone denied | The groups claim is not configured at the IdP, so no user has any groups. |
| One user denied | Their group name does not match the mapping, including casing. |
| A group stops working | The group name changed at the IdP, or the profile was removed from the mapping. |
| Users denied after many groups | Entra group overage. See above. |
Denied with groups=[] | The claim exists but resolved to nothing — overage, or the user is in no matching group. |
| Login succeeds but tools are missing | allow_tools / allow_skills on the matched profile. |
| Access persists after removal from a group | Expected — groups apply at next login. Use the mapping levers above. |
The server log records the identity and the groups considered when a user is denied, which is usually enough to identify a missing or misspelled rule.