> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Auth service

> Issue and validate OAuth2/OIDC tokens, enforce permissions, and cache credentials with the centralized Auth service across Lerian apps.

Auth is a centralized service that provides authentication and authorization capabilities for Lerian Studio's applications. Built on top of an Identity Provider (IdP), this service offers:

* **OAuth2/OIDC-compliant authentication flows**.
* **Token issuance, validation, and refresh capabilities**.
* **User information retrieval according to OIDC standards**.
* **Permission enforcement for resources**.
* **Performance optimization through caching mechanisms**.

**Auth** serves as a middleware between Lerian’s applications and the underlying authorization server, providing a unified interface for all authentication and authorization needs while adding caching capabilities to improve performance.

## Authentication and authorization flow

***

**Auth** implements several key authentication and authorization flows:

<Frame caption="Figure 1. Authentication and Authorization Flow">
  <img src="https://mintcdn.com/lerian-49cb71fc/BCres49JP2Vepzou/images/en/docs/am-auth_flow.jpg?fit=max&auto=format&n=BCres49JP2Vepzou&q=85&s=7515306f6e79f51081d0a7ba19a17bdc" alt="" width="2044" height="764" data-path="images/en/docs/am-auth_flow.jpg" />
</Frame>

### Authentication flow

1. **Token request**
   * Client applications request access tokens using either:
     * Password grant (username/password for interactive users).
     * Client credentials grant (for service-to-service authentication).
   * The request is forwarded to the Identity Provider.
   * Access token, refresh token, and optional ID token are returned.
2. **Token refresh**
   * Client applications use refresh tokens to obtain new access tokens.
   * The refresh token is validated via the Identity Provider.
   * A new access token is issued.
3. **Token validation**
   * The access tokens are validated on protected resource access.
   * The results are cached for performance optimization.
   * Token claims are extracted to identify the subject.

<Note>
  **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](/en/multi-tenancy).
</Note>

### Authorization flow

1. **Enforce access**
   * Client requests access to a resource with an action.
   * The subject ID is extracted from the token.
   * The policy engine determines if the subject has permission.
   * The result is cached for performance.
   * The authorization decision is returned.
2. **Retrieve policies**
   * The client requests all policies for the authenticated user.
   * The policy engine is queried for all permitted resources and actions.
   * Policies are returned as a map of resources to the allowed actions.

### User information flow

1. **Profile request**
   * The client requests user profile information.
   * The access token is validated.
   * User details are retrieved from the Identity Provider.
   * OIDC-compliant user information is returned.

### Logout flow

1. **User logout**
   * Client sends logout request with ID token hint.
   * The tokens are invalidated in the Identity Provider.
   * Cache entries are invalidated.

## API overview

***

**Auth** provides secure identity management and access control for Lerian applications. APIs support:

* **Authentication and token lifecycle management**.
* **Authorization and permission enforcement**.
* **User information retrieval**.

Access to the Auth APIs is secured by strict permission controls. For technical details on endpoints and usage, check the [Auth APIs](/en/reference/access-manager/am-api-introduction) documentation.

## Policy structure

***

The policy tables store permissions using the following pattern:

### Policy rule (ptype='p'):

```
p, <role>, <resource>, <action>, allow, <note>
```

**Example:**

```
p, lerian/identity-editor-role, users, get, allow, lerian/identity-editor-permission
```

This grants the `identity-editor-role` permission to perform the `GET` action on the `users` resource.

### Group assignment (ptype='g'):

```
g, <user_id>, <role>
```

**Example:**

```
g, user123, lerian/identity-editor-role
```

This assigns the user with ID `user123` to the `identity-editor-role` role.

## Data storage and caching

***

**Auth** optimizes performance and security by leveraging a structured storage system and caching mechanisms:

* **Policy management**: Stores access control policies for users and services.
* **Token introspection cache**: Caches token validation results to reduce redundant checks.
* **Permission cache**: Stores authorization decisions to improve response time.
* **User policies cache**: Maintains a map of resources and actions for efficient access control.

## Testing & reliability

***

**Auth** undergoes continuous testing to maintain reliability and security. Tests cover:

* **Authentication and token validation flows**.
* **Access control enforcement**.
* **Performance and caching efficiency**.

Security assessments and monitoring ensure compliance with best practices and evolving security standards.