Identity service

Identity is the management service for Access Manager. It’s where administrators define who can access Lerian products: which groups and roles people belong to, which applications can authenticate with machine-to-machine credentials, and which communication or OAuth providers are available. Identity does not issue access tokens or make runtime authorization decisions. Auth uses the identity data managed here to authenticate subjects and evaluate permissions. Use Identity when you need to:

• create, update, list, or delete users.
• assign users to product groups or direct permissions.
• create, update, list, or delete groups and inspect their permissions.
• create, update, list, or delete tenant-scoped custom roles and assign their permissions, users, and groups.
• create, list, retrieve, or delete machine-to-machine applications.
• create, update, list, retrieve, or delete communication providers.
• link providers to applications and select the default provider.
• configure the tenant’s SSO policy and active OAuth provider.
• turn passkey sign-in on or off, and add or remove passkeys.
• initiate, verify, enable, disable, review, or change MFA settings for users.
• reset or update user passwords.

​

Users and groups

---

Identity manages human access through users, groups, and direct user permissions. A group represents a permission set for a product or Access Manager area. For example, you can assign a user to a Midaz viewer group to inspect ledger data without changing it. You can also assign that user to a Reporter contributor group to create report templates. A user can also receive a direct permission without belonging to a group for that product. Identity exposes user endpoints to list users, create users, retrieve a user, update user information, manage group assignments and direct permissions, delete users, update passwords, and reset passwords. User and group list endpoints use page and limit for pagination. On Lerian Cloud, the service returns only the users and groups that belong to your tenant. When you create or update a user, send the group IDs returned by List Groups. The API handles the internal organization prefixing. Clients should not build organization/group values manually.

​

Roles

Access Manager uses role levels as a common convention across products. The effective actions for each role come from the product or application permission set. Identity also supports custom roles scoped to the tenant. Access Manager supplies the platform permission catalog. You can create, update, and delete tenant-scoped groups, then use List Groups and Retrieve Group Details to inspect the groups available in your environment. Identity deletes a group only when it has no members and no subgroups. Otherwise it returns 409 with code IDE-1058 or IDE-1059. Group assignments are one way to grant access. Identity also supports direct user-permission assignment. You can create custom roles and assign permissions, users, and groups to them. Built-in system roles are immutable: Identity rejects attempts to create, update, or delete them. Use custom roles when the standard role levels do not express the access model you need. A Lerian product can declare its own permissions and roles. Only the product decides which roles hold a permission that it declares, and which groups hold a role that it declares for people. Identity refuses with 422 to add or remove a role on such a permission, or a group on such a role. To change who has that access, add or remove people on the product’s role, or in a group that holds the role. For the resource-action model, the action vocabularies used by each product, and how routes are protected at runtime, see Product-level enforcement. For the API workflow that ties users, groups, and tokens together, see Using Access Manager.

​

Applications

---

Applications represent machine-to-machine clients for the client_credentials grant. Use them when a service, job, or integration needs to authenticate without a human user. An application stores the clientId and clientSecret used by Auth during the client_credentials flow. Identity returns the clientSecret only in the response to the create request. If you lose the secret, delete the application and create a new one. After creating an application, the integration can request an access token from Auth and call protected Lerian APIs according to its configured permissions. Identity supports:

• listing applications.
• creating applications.
• retrieving application details.
• deleting applications.
• issuing service credentials, in a single-tenant deployment.

For example, a reconciliation job can use a Bank Transfer application to request a token and call only the endpoints needed for its workflow. Identity accepts only application names from its catalog when it creates or deletes applications. Application names are product identifiers, such as midaz or reporter, not UI display labels. List Available Applications returns the catalog. A service credential is the application that a Lerian service signs in with. A person issues it with Issue a Service Credential, with source, the service that signs in, and target, the service that it calls. Both must be in the catalog. With the target plugin-identity, the credential only authenticates the service’s own permission declaration. Any other target must have published a declaration with service roles, or the route answers 422. Identity refuses an application token on this route. In a multi-tenant deployment, the route answers 501. Create an Application refuses source with 400.

​

Tenant scoping

On Lerian Cloud, Identity uses the authenticated context as the tenant boundary for management operations:

• user operations apply to the caller’s tenant organization.
• group lists include only permission groups available in that tenant.
• application lists include only machine-to-machine applications bound to that tenant.
• application credentials created for an integration belong to the tenant that created them.

This keeps operational access local to the tenant. An administrator token from one tenant cannot list or mutate another tenant’s users, groups, or applications through the public Identity APIs.

​

Communication providers

---

Communication providers define delivery services available to applications. Email providers can deliver MFA challenges. Identity manages providers separately from applications so you can reuse and control the same provider consistently. Identity supports:

• listing providers.
• creating providers.
• retrieving provider details.
• updating providers.
• deleting providers.

Identity also supports application-provider links:

• list providers linked to an application.
• link a provider to an application.
• update a provider link.
• unlink a provider from an application.
• set the default provider for an application.

Use a default provider when an application has more than one linked provider and needs a preferred one. For SSO, Identity manages one active OAuth provider per tenant. Supported provider types are Google, AzureAD (Microsoft Entra ID), Okta, and Custom. The Auth SSO callback URL must be an absolute URL and appear in the application’s redirect-URI allowlist, or the authorization-code relay will fail. Before saving a candidate SSO provider, run its preflight validation. It checks the configuration, OIDC endpoint discovery, client credentials, and the callback redirect URI without creating or changing a provider, application-provider link, or application. The validation result reports a failed check. A malformed or unauthorized request returns an HTTP error. For a BYOC deployment with one fixed Caradhras organization, set PLUGIN_AUTH_SSO_STATIC_ORGANIZATION in Auth. Pre-login SSO then resolves every request to that organization instead of looking up an organization from the user’s email.

​

MFA management

---

Identity manages MFA configuration for users. Auth uses that configuration during login when MFA is required. Identity supports:

• initiating MFA setup.
• verifying an MFA passcode during setup.
• enabling MFA after verification.
• disabling MFA.
• retrieving the current MFA status.
• setting the preferred MFA method.

MFA supports an authenticator app or email. Email MFA requires an email provider and a saved email address for the user. The standard MFA setup and management operations are self-service: the caller’s token subject must match the target user. Administrative MFA operations are separate and apply only to the methods supported by those operations.

​

Architecture and identity flow

---

1. Management request
   • An administrator or authorized client calls an Identity API.
   • When Identity’s Auth client is enabled and configured, the request is authenticated and checked against Access Manager permissions. Set AUTH_REQUIRED=true when the deployment must refuse management requests if that client is disabled or misconfigured.
2. Request processing
   • Identity validates the payload and applies the requested operation.
   • The service updates users, groups, roles, applications, providers, provider links, SSO configuration, or MFA configuration in the configured identity system.
3. Runtime use
   • Auth reads the resulting identity data during token, permission, and MFA flows.
   • Protected Lerian products rely on Auth decisions before processing product operations.

​

API overview

---

Identity exposes APIs for:

• users.
• groups.
• custom roles and their assignments.
• applications.
• providers.
• application-provider links.
• SSO policy and OAuth-provider configuration.
• passkey policy and passkey management.
• MFA setup and management.
• tenant IP allowlist configuration.
• self-service profile and phone management.
• password reset and password update flows.

When its Auth client is enabled and configured, Identity protects management access through Access Manager permissions. For technical details, check the Identity APIs documentation.