Auth service

Issue OAuth2/OIDC tokens, validate sessions, verify permissions, and handle MFA challenges with the Auth service.

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.

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.

Tenant context — In SaaS and multi-tenant BYOC deployments, the issued JWT contains a tenantId claim. This claim is resolved automatically by the platform on every API request — you don’t need to pass a tenant identifier in headers or request bodies. Your token establishes your scope. Learn more about multi-tenancy.

Multi-tenant token handling

When multi-tenancy is enabled, Auth keeps token and permission operations inside the tenant resolved for the authenticated subject.

For human users, the password grant resolves the user’s tenant before requesting tokens from the configured identity provider. Refresh-token flows use the tenant context carried by the existing token, so a refresh cannot move the session into another tenant.

For machine-to-machine integrations, Auth resolves the application credentials and permission set from the application organization. The resulting token is scoped to that application’s tenant.

In single-tenant deployments, Auth uses the configured default organization and does not require a tenant claim.

MFA login flow

1. Challenge required
   • When MFA is required, Auth returns an MFA challenge state instead of completing the login immediately.
   • The user receives a challenge code through the configured method.
2. Challenge verification
   • The user submits the MFA token and passcode.
   • Auth verifies the challenge and returns access tokens when the verification succeeds.
3. 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;
• initiating an MFA challenge;
• verifying an MFA login challenge.

Access to the Auth APIs is secured by strict permission controls. 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, permissions come from the groups assigned in Identity. 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.