Skip to main content
Auth is the runtime access service for Access Manager. It sits between your protected Lerian products and the configured identity provider, giving products a single interface for token lifecycle, user information, permission checks, logout, and MFA login verification. Use Auth when you need to:
  • request access tokens for human users or machine-to-machine applications;
  • refresh an expired access token;
  • retrieve OIDC-compatible user information;
  • validate whether a subject can perform an action on a resource;
  • retrieve the permissions available to the authenticated user;
  • end a user session;
  • initiate and verify MFA challenges during login.
Auth delegates identity data to the identity provider and caches token, permission, and MFA-related data with Valkey to reduce repeated calls during normal operation.

​
Main flows

Auth supports the access flows used by Lerian products and integrations.
Conceptual authentication and authorization flow through the Auth plugin, including token issuance and permission checks

Figure 1. Authentication and Authorization Flow

​
Authentication flow

  1. Token request
    • Human users authenticate with the password grant.
    • Service integrations authenticate with the client_credentials grant.
    • Auth forwards the request to the identity provider and returns the access token, refresh token, and ID token when applicable.
  2. Token refresh
    • Clients exchange a refresh token for a new access token.
    • Auth validates the refresh token with the identity provider before issuing the new token.
  3. Token validation
    • Protected products validate bearer tokens before accepting a request.
    • Auth extracts trusted token claims to identify the subject and tenant context.
    • Validation results can be cached to reduce repeated identity-provider calls.

​
Organization context

For authorization, Auth uses the JWT owner claim when it is present and otherwise the configured organization. The product that receives an authorized request owns its own tenant data context and data-plane isolation. Do not infer a cross-product tenant-resolution flow from Auth alone. For multi-tenant deployment configuration, follow the relevant product and multi-tenancy documentation.

​
Browser SSO flow

  1. Start the flow
    • The browser starts SSO through Auth with an email address, an eligible provider, and an S256 PKCE code_challenge. Auth resolves the tenant server-side from the email domain and redirects the browser to the upstream identity provider.
  2. Handle the callback
    • The identity provider redirects the browser to PLUGIN_AUTH_SSO_CALLBACK_URL. This absolute callback URL must be registered in the identity provider application’s redirect-URI allowlist.
    • The Console submits the provider authorization code, the Auth state, and the matching PKCE codeVerifier through Auth’s sso_code grant. Auth consumes the flow once, relays the code to the identity provider, and returns the token envelope.
Configure the tenant’s OAuth provider and SSO policy through Identity. The Auth callback URL must match the application’s allowed redirect URI.

​
MFA login flow

  1. Challenge required
    • When MFA is required, Auth returns an MFA challenge state instead of completing the login immediately.
  2. Start challenge delivery
    • For email or SMS MFA, the client submits the returned MFA token and the selected method to request challenge delivery, and Auth sends the challenge code through that method.
    • A TOTP application generates its passcode locally, without a delivery request.
  3. Challenge verification
    • The user submits the MFA token and either a passcode or a recovery code, not both.
    • Auth verifies the challenge and returns access tokens when the verification succeeds.
  4. Session controls
    • MFA challenges expire after the configured TTL.
    • Failed attempts are limited to protect the account from repeated guessing.

​
Authorization flow

  1. Enforce access
    • A protected product asks whether the authenticated subject can perform a specific action on a specific resource.
    • Auth evaluates the request against the configured Access Manager permissions.
    • Successful authorization decisions can be cached for performance.
  2. Retrieve permissions
    • A client can retrieve the permissions available to the authenticated user.
    • Auth returns permissions as a map of resources to allowed actions.

​
User information flow

  1. Profile request
    • The client requests user profile information with a bearer token.
    • Auth validates the token and retrieves user details from the identity provider.
    • Auth returns OIDC-compatible user information.

​
Logout flow

  1. User logout
    • The client sends a logout request with the ID token hint.
    • Auth invalidates the session in the identity provider.
    • Related cache entries are cleared.

​
API overview

Auth exposes APIs for:
  • requesting access tokens with password or client_credentials;
  • refreshing access tokens;
  • ending user sessions;
  • validating user permissions;
  • retrieving user information;
  • retrieving user permissions;
  • starting, completing, and discovering browser SSO flows;
  • initiating an MFA challenge;
  • verifying an MFA login challenge.
Auth exposes both credential-bearing entry points and protected operations. Follow the security requirements documented for each endpoint. For technical details on endpoints and usage, check the Auth APIs documentation.

​
Permission decisions

When a protected product asks Auth whether a subject can perform an action on a resource, Auth resolves the subject (a human user or a machine-to-machine application), looks up the permissions associated with it, and returns an authorized or denied decision. For human users, Auth evaluates permissions embedded in their identity data, including direct user permissions and applicable roles. For machine-to-machine applications, permissions come from the application’s configured permission set. Auth does not invent permissions; it evaluates the data Identity manages. For the full subject/resource/action model, examples, and how routes are protected, see Product-level enforcement. To inspect what the authenticated subject can reach, use Retrieve User Permissions.

​
Data storage and caching

Auth uses structured policy data and cache entries to reduce repeated work:
  • Policy data stores access-control rules for users, groups, and applications.
  • Token cache stores token validation results.
  • Permission cache stores successful authorization decisions.
  • User permissions cache stores the map of resources and actions available to a user.
  • MFA cache stores temporary challenge state, attempt counters, and remember-device state when configured.

​
Testing and reliability

Auth undergoes continuous testing to maintain reliability and security. Tests cover:
  • Authentication and token validation flows.
  • Access control enforcement.
  • Performance and caching efficiency.
Auth also runs ongoing security assessments and monitoring across these flows.