Skip to content

SSO#

Lens Agents authenticates users over OIDC. Out of the box it uses Lens ID; 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#

Two Helm values do it:

helm upgrade lens-agents oci://ghcr.io/lensapp/lens-agents --reuse-values \
  --set oidc.issuer="https://your-org.okta.com" \
  --set oidc.jwksUri="https://your-org.okta.com/oauth2/v1/keys"
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) Leave empty for self-activation. Set only for a pre-provisioned deployment that should skip activation.

Both 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 Lens Agents 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.

Changing config.publicUrl later changes the redirect URI. Update the IdP registration at the same time, or logins will fail with a redirect mismatch.

Authentication flow#

  1. A user opens the platform.
  2. The platform redirects to your identity provider over OIDC.
  3. The user authenticates, including MFA if your IdP requires it.
  4. The IdP returns a signed JWT.
  5. The platform verifies the token against oidc.jwksUri and creates or updates the session.
  6. The user is signed in with their organization role and team memberships.

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 team membership and project roles inside the platform, and from policy bindings. A user who authenticates successfully but belongs to no team can sign in and reach nothing.

Group claims from your IdP are not mapped to teams automatically. Manage team membership 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.

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.