Skip to main content
Installing Access Manager means getting the Auth and Identity services running, connected to their dependencies, and ready to answer access decisions. This step has to happen before any Lerian product can enforce authentication or permissions. This guide is for operators who install Access Manager. To install or upgrade the services, see the Access Manager chart README.

Prerequisites

You can plan an installation without deep Kubernetes knowledge. Use the list below as a checklist before you start.

License

Access Manager requires a Lerian license: a global license key in LICENSE_KEY, or a signed license file that Lerian issues, mounted and set in LICENSE_FILE_PATH. Auth and Identity do not start without one. With the key, they need outbound HTTPS to https://license.lerian.io. If the license service does not answer at startup, they stay up, not ready, and keep retrying. They stop when the license is revoked or when the license they hold reaches its stop time. Read License Manager for the key. If you don’t have a license yet, get in touch with our team.

Deployment model

Decide how you’re going to run Access Manager. The choice shapes tenant resolution, Caradhras configuration, and a few operational defaults later on.
  • SaaS - Lerian runs the platform. You manage users, groups, and applications through Lerian Console or the Identity APIs.
  • BYOC - You run Access Manager against a configured default organization and Caradhras identity backend.
If you’re not sure which model applies, confirm with your Lerian contact before installing.

Auth service

Auth is the runtime side of Access Manager. It issues and refreshes tokens, validates sessions, checks permissions, handles logout and user info, and runs MFA challenges. Auth needs to be reachable from every protected Lerian product over the network.

Identity service

Identity is the data side of Access Manager: users, groups, applications, communication providers, application-provider links, and MFA configuration. Identity is the management surface. Both Identity and Auth connect to the configured Caradhras backend: Identity manages identity data through it, while Auth uses its own connection for tokens, MFA, and authorization decisions.

Identity backend

Access Manager uses a configured Caradhras backend for identity storage. Caradhras persists its identity data in the configured PostgreSQL database. PostgreSQL backs Caradhras and does not replace it. For a BYOC deployment, configure that Caradhras backend for your environment.

Data and cache services

  • A PostgreSQL instance as the backing database for Caradhras-managed identity data.
  • A Valkey cache for token, permission, and MFA-related operations.
Provision both and make them reachable before Auth and Identity start. Sizing and high-availability decisions depend on your deployment model.

Product connectivity

Plan the network paths now so you’re not debugging them later:
  • Protected products must reach Auth over the network.
  • Administrators (and any back-office tooling) must reach Identity to manage users, groups, applications, and providers.
  • Do not expose either service publicly without the appropriate ingress controls.

Environment and bootstrap data

A fresh environment seeds base access data, including its organization, built-in roles, groups, applications, and permission sets, once at startup. This is the bootstrap layer. In single-tenant mode, set ADMIN_PASSWORD on Identity to create the first Console administrator. Read First Console administrator. After the environment is up, day-to-day changes happen through the Identity APIs or Lerian Console, not by editing bootstrap data.
Bootstrap applies its seed data only during initial environment setup. Changes to built-in resources, actions, roles, groups, applications, or permission sets in an existing environment must be delivered through controlled platform updates, such as migrations or an idempotent reconciler.

Installation flow

Follow these steps in order. Each one builds on the previous one.
1

Choose your deployment model

Pick SaaS or BYOC and confirm any model-specific decisions with your Lerian contact: Caradhras configuration. Write this down because every later step refers back to it.
2

Prepare dependencies

Provision the supporting infrastructure so Auth and Identity have everything they need at startup:
  • a valid Lerian license configured for the environment.
  • a PostgreSQL instance to back Caradhras-managed identity data.
  • a Valkey cache for tokens, permissions, and MFA.
  • the configured Caradhras identity backend.
  • network paths between Access Manager, its dependencies, and the products that will eventually enforce access.
Don’t move on until each dependency is reachable from where Access Manager will run.
3

Deploy Auth and Identity

Install the Access Manager services into your environment. See the Access Manager chart README.
4

Bootstrap base access data

First startup seeds the base organization, built-in roles, groups, applications, and permission sets that the platform relies on. Let bootstrap finish before pointing any product at the services.From this point on, treat bootstrap data as read-only. Manage everyday access through the Identity APIs or Lerian Console.
5

Validate the services

Confirm that the installation is healthy before any product depends on it:
  • Auth and Identity report healthy and are reachable from the products that will use them. Set HEALTH_PORT on both: /readyz is served on that port only, and without it there is no readiness endpoint. /readyz answers 503 until a license is accepted, and the main port opens only after that. See Health and readiness.
  • PostgreSQL (Caradhras’s backing database) and Valkey are connected and responsive.
  • The Caradhras identity backend is configured and reachable.
  • A test token request succeeds against Auth, and a basic Identity call (for example, List Groups) succeeds for the selected deployment mode.
If anything in this list fails, fix it here. Don’t enable products on top of an unhealthy install.
6

Enable protected products

After you validate the installation, turn enforcement on inside each Lerian product or plugin by setting the Auth variables in its environment. The full per-product configuration lives in Enabling Access Manager.
7

Use Access Manager

With installation done and products enforcing access, move on to day-to-day operation: requesting tokens, managing users, groups, and applications, configuring MFA, and calling protected APIs. Start with Using Access Manager for the API workflow, or Access Manager via Lerian Console for the visual flow.
Auth and Identity should be deployed, healthy, and validated before you flip any product into enforcement mode.

Next steps