SSO#
Mirantis Agent Platform authenticates users over OIDC. A new install offers Lens ID as a built-in sign-in for evaluation (Activation and license); point it at your own identity provider and users sign in with their corporate credentials, with every action attributed to that identity in the audit trail.
OIDC is the only user authentication protocol. SAML and SCIM are not supported.
Point the install at your provider#
Three Helm values do it, with the client you register in your provider:
helm upgrade lens-agents oci://ghcr.io/lensapp/lens-agents --reset-then-reuse-values \
--set oidc.issuer="https://your-org.okta.com" \
--set oidc.jwksUri="https://your-org.okta.com/oauth2/v1/keys" \
--set oidc.clientId="<client-id>"
| Value | Default | Purpose |
|---|---|---|
oidc.issuer |
Lens Cloud realm | Issuer URL of your OIDC provider. |
oidc.jwksUri |
Lens Cloud realm | JWKS endpoint used to verify signed tokens. |
oidc.clientId |
(empty) | The client people sign in through. Empty offers a choice on the setup screen, including the Lens ID client Lens Cloud registers for the install. See Activation and license. |
oidc.issuer and oidc.jwksUri default to the Lens Cloud realm, which is what makes Lens ID login work on a fresh install. Override them together — an issuer whose JWKS endpoint does not match cannot verify a token.
Issuer URLs by provider:
| Provider | Issuer |
|---|---|
| Okta | https://your-org.okta.com |
| Microsoft Entra ID | https://login.microsoftonline.com/<tenant-id>/v2.0 |
| JumpCloud | https://oauth.id.jumpcloud.com/ |
Any standards-compliant OIDC provider works. Those three are validated.
Register the application#
In your identity provider, register Mirantis Agent Platform as a web application. The admin UI builds its redirect URI from the address it is served on:
<config.publicUrl>/auth/callback
So an install with config.publicUrl=https://agents.example.com uses https://agents.example.com/auth/callback, and the post-logout redirect is config.publicUrl itself.
Clients that sign in on a loopback redirect — http://localhost, 127.0.0.1, or [::1] on any port, as Claude Code and Codex do — come back through the platform rather than straight to the client. Where you set oidc.clientId yourself, allow this redirect URI on that client as well:
<config.publicUrl>/oauth/callback
Without it, those sign-ins fail with a redirect mismatch. The platform requires PKCE with S256 on them.
Changing config.publicUrl later changes both redirect URIs. Update the IdP registration at the same time, or logins will fail with a redirect mismatch.
Authentication flow#
- A user opens the platform.
- The platform redirects to your identity provider over OIDC.
- The user authenticates, including MFA if your IdP requires it.
- The IdP returns a signed JWT.
- The platform verifies the token against
oidc.jwksUriand creates or updates the session. - The user is signed in with their organization and project roles.
Desktop AI tools connecting to the MCP endpoint trigger the same flow on first connection, then hold a refresh token for later sessions. That is why an interactive sign-in needs no token to create or store.
What SSO does and does not decide#
SSO decides who a user is. It does not decide what they may do.
Permissions come from organization and project roles inside the platform, and from policy bindings. A user who authenticates successfully but holds no project role can sign in and reach no project.
Group claims from your IdP are not mapped to project roles automatically. Manage project members in the platform.
Who gets an account#
A corporate IdP authenticates every employee, so on a default install every employee can sign in and collect an account. Installation owners is the control for that: name your owners with config.ownerEmails and a signed-in person is admitted only if they belong to an organization, may create one, or hold a pending invitation. Everybody else is refused with 403 and no account is stored.
Set it as part of pointing the install at your provider rather than afterwards — it is the same decision.
The email claim must be in the access token, and verified
Owner matching reads the email from the access token, not the id_token. Microsoft Entra ID in particular omits email from access tokens until you configure it, and an install that names owners whose email never arrives refuses everyone who belongs to no organization — owners included. Confirm the claim before you name owners.
The claim must be verified by the IdP as well. Where a user can set their own email without proof, that user can claim an owner address.
Direct API access#
Signing in and using the API directly are separate decisions. When an application of yours calls Mirantis Agent Platform on behalf of people and enforces its own limits on them, those people should not be able to take their own token to the REST API, /mcp, or the web UI and skip those limits. The direct-access gate closes that path with a realm role from your IdP.
| Value | Default | Purpose |
|---|---|---|
oidc.directAccessRole |
(empty) | The realm role a person needs to use the API directly — web UI, nexusctl, and MCP clients. Read from the access token's realm_access.roles. Empty turns the gate off. |
oidc.delegatedClients |
[] |
OAuth clients admitted without the role, because they call on behalf of people and gate them themselves. |
oidc.sandboxIngressClients |
{} |
Client-to-role map for bearer tokens that open a sandbox's private port, each with the role it needs instead of directAccessRole. |
oidc.sandboxIngressClientsWithoutRole |
[] |
Clients whose bearer tokens open a sandbox's private port with no role, for a person who already belongs to an organization. |
oidc.directAccessReportOnly |
false |
Log every request the gate would refuse, and let it through. |
With oidc.directAccessRole set, an OIDC token is accepted on REST, /mcp, and WebSockets only if it is an access token and either was issued to this installation's own client to a person who holds the role or is a named installation owner with a verified email, or was issued to a client in oidc.delegatedClients. A person without the role gets 403, whatever organizations or invitations they have. An ID token, or a token from any other client, gets 401. API tokens are not OIDC tokens and are not affected.
The browser login to a sandbox's private port signs in through oidc.clientId, so with the gate on it needs the role too. A person without it reaches a private port only with a bearer token from a client in oidc.sandboxIngressClients or oidc.sandboxIngressClientsWithoutRole. An ingress session already open is not re-checked, so removing the role does not end it.
A client that decides itself who may use it, such as a product with its own access list, goes in oidc.sandboxIngressClientsWithoutRole. Its tokens need no role on a private port, but the person must already belong to an organization; anyone else gets 403 and no account is created, in report-only mode too. A pending invitation does not count. Either way, the person reaches only sandboxes in projects they have access to, and, with either gate on, the client's tokens stay refused on the API. The chart refuses an oidc.sandboxIngressClients entry with no role, and an empty item in oidc.sandboxIngressClientsWithoutRole, so a role left out by mistake does not turn the check off.
The gate is off when the role is empty, so an install behaves as before until you set it. The install refuses to start on a combination that looks gated but is not:
- delegated or ingress clients, or report-only mode, with neither a role nor the client gate,
- the installation's own client listed in
oidc.delegatedClients, - an ingress client whose role is
oidc.directAccessRole, - an ingress client that is the installation's own client or is in
oidc.delegatedClients.
Confirm the role is in the access token
Decode a real access token issued to oidc.clientId and check realm_access.roles before you enforce. An IdP client that does not map realm roles into its tokens leaves the role out, and every direct user is refused.
Roll it out in report-only mode#
- Grant the role, through a group, to everyone who uses the web UI,
nexusctl, or an MCP client. - Deploy with
oidc.directAccessReportOnly: true. Each refusal the gate would make is logged with the person's subject and client, at most once an hour for each person, client, and reason, and the install warns hourly that the gate is not enforcing. - Grant the role to anyone in the log who should keep direct access. They sign out and back in.
- Set
oidc.directAccessReportOnly: false.
Token clients without a role#
The platform also checks which client a token was issued to when oidc.directAccessRole is empty. oidc.clientGate decides when:
oidc.clientGate |
The check is on |
|---|---|
auto (default) |
When oidc.clientId is empty — the install signs in through the Lens ID client Lens Cloud registered for it. With your own client it stays off. |
always |
For whichever client is in effect. |
never |
Never without the role, as before 0.32.0. |
Quote the value in YAML ("never"): an unquoted on, off, yes, or no reads as a boolean, and the install fails on it.
With the check on, an OIDC token is accepted only when it is an access token issued to the installation's own client or to a client in oidc.delegatedClients. A token from any other client in the realm — one a person got for another Lens app, or for another installation — gets 401. Until the install has its own client, only delegated clients and oidc.sandboxIngressClients get through. Who is admitted is then decided as usual, by org membership, a pending invitation, or installation owners; nobody needs a role. A client in oidc.sandboxIngressClientsWithoutRole admits org members only.
nexusctl and MCP clients such as Claude Code sign in through the platform, which asks for the installation's own client, so they keep working.
List every client that calls the platform on people's behalf in oidc.delegatedClients. oidc.delegatedClients, oidc.sandboxIngressClients, oidc.sandboxIngressClientsWithoutRole, and oidc.directAccessReportOnly apply here as they do to the direct-access gate.
Each refusal is logged with the person's subject, the token's client, and the reason, at most once an hour for each.
The token endpoint relays sign-in grants only#
The install's /oauth/token endpoint, which browsers and MCP clients use to complete sign-in, relays only the authorization_code, refresh_token, and device-code (urn:ietf:params:oauth:grant-type:device_code) grants. Any other grant type, client_credentials included, is refused with 400 unsupported_grant_type, so the endpoint cannot be used to mint a token for the installation's own client.
Non-interactive access#
Machines cannot complete a browser flow. CI jobs, scripts, and external agents use API tokens, which are separate principals with their own bindings and their own audit attribution. A CI run or another workload with an OIDC token of its own can use workload identity federation instead, and store no secret.
Service account#
A backend that acts on every organization when nobody is signed in, such as a billing service that sets each organization's monthly spending limit or stops its sandboxes when a subscription ends, can use the installation's service account. It is off by default.
Give the backend a confidential client of its own in your IdP and list it in oidc.serviceClients:
| Value | Default | Purpose |
|---|---|---|
oidc.serviceClients |
[] |
Clients whose client-credentials token is the installation's service account (OIDC_SERVICE_CLIENTS). |
The client must be dedicated to the service account: service accounts on, and every other flow off — standard flow, direct access grants, device authorization, and token exchange — so no person can get a token issued to it. A token the client gets with the client-credentials grant from your IdP is then the service account:
- It is an org admin in every organization, including ones created later, and project
ADMINin every project, without a membership. It can do what an org admin can, members, API tokens, and spending limits included. - It is refused by the LLM proxy and realtime sessions, so it never spends, and it cannot mint sandbox tokens or open a sandbox's private port.
- The audit trail names it by its client, in
metadata.serviceClient.
The install's own /oauth/token endpoint still refuses client_credentials, so the backend asks your IdP for its token directly. The service account works with the direct-access gate and the client gate on or off. The server refuses to start when oidc.serviceClients names oidc.clientId, a delegated client, or a sandbox-ingress client, because people sign in through those.
To revoke it, take the client off the list, or disable the client or its secret in your IdP. Tokens already issued stay valid until they expire, so keep the client's access-token lifespan short.
Related#
- Activation and license — the sign-in choice a fresh install offers
- Organizations and projects — where permissions actually come from
- Identity — users, API tokens, and sandboxes as principals
- API tokens — authenticating without a browser