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.

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.