Enabling Access Manager

Activate Access Manager across Lerian products — set the Auth environment variables in each .env so your services start enforcing access.

Installing Access Manager isn’t enough on its own. To start enforcing access, you turn it on in each product by setting the Auth variables in the .env file of any Lerian product or plugin where you want it active.

Enabling Access Manager only turns on authorization enforcement in a product or plugin. Access data such as users, groups, applications, providers, roles, and permissions is managed separately through Access Manager.

Every protected product must enable enforcement and point to Auth. The address variable is not the same in every repository, so use the variable expected by the product you are configuring:

Text

# Most products and plugins
PLUGIN_AUTH_ENABLED=true
PLUGIN_AUTH_ADDRESS=http://plugin-auth:4000

For a product that supports BYOC multi-tenancy, configure the complete product-specific set of variables. For Midaz Ledger, enabling multi-tenancy also requires the URL of its Tenant Manager Service and a Valkey host. Tenant Manager listens on port 4026 by default:

Text

# Midaz Ledger multi-tenant configuration
MULTI_TENANT_ENABLED=true
MULTI_TENANT_URL=https://tenant-manager.<your-domain>
MULTI_TENANT_REDIS_HOST=valkey

Point MULTI_TENANT_URL at an HTTPS endpoint so MULTI_TENANT_SERVICE_API_KEY does not travel over cleartext HTTP. In-cluster HTTP (http://tenant-manager.<namespace>.svc.cluster.local:4026) is for local, non-production clusters only and requires the explicit opt-in MULTI_TENANT_ALLOW_INSECURE_HTTP=true.

In Helm deployments, Midaz also needs MULTI_TENANT_SERVICE_API_KEY, normally supplied through a Secret or an existing Secret. The flag alone is not a complete multi-tenant configuration; follow the deployment documentation for the product you are configuring. If your Tenant Manager SERVER_ADDRESS or Kubernetes Service overrides the default port, use that deployed address instead.

Once Access Manager is enabled, protected API requests must include an Authorization header with a valid Bearer access token.

Without this header, protected requests will be rejected, even for endpoints that were previously accessible without authentication.

Learn how to generate and use access tokens.

Where to update

---

You’ll find the relevant .env files in these locations:

• Midaz
  • /midaz/components/ledger uses PLUGIN_AUTH_HOST. The CRM component uses PLUGIN_AUTH_ADDRESS in its own configuration.
  • /midaz/components/tracer uses PLUGIN_AUTH_ADDRESS
• Other products and plugins
  • Use the .env file in the product or plugin root, or in the component directory when the repository is split into components.
  • Reporter, Flowker, Bank Transfer, and Fetcher use PLUGIN_AUTH_ADDRESS.
  • Pix Indirect BTG uses PLUGIN_AUTH_ADDRESS in its pix service and PLUGIN_AUTH_HOST in its inbound and outbound workers.
  • Pix Direct JD uses PLUGIN_AUTH_HOST.

If you can’t see the files, adjust your system settings to show hidden files. .env files are often hidden by default.

Rebuild after changes

---

After updating a .env file, rebuild and restart from the root of the repository that owns that file. Lifecycle commands differ by repository: in the Midaz repository root, run make rebuild-up, because its make up target starts services without rebuilding them. For other products and plugins, use the lifecycle command documented in that repository. The Access Manager source uses the following commands:

1. In your terminal, go to the Access Manager repository root.

2. If Docker is running, stop it:

   Bash

   make down
   
3. Then build and start the stack:

   Bash

   make up
   

Deployment lifecycle

---

Access Manager setup has two phases, and bootstrap differs by deployment mode:

• Single-tenant bootstrap seeds a new environment with the base organization, roles, groups, applications, and permission sets required by the platform.
• Multi-tenant bootstrap prepares shared certificate material only. It does not seed tenant organizations, users, groups, applications, or permission sets; create and manage tenant access data after the tenant exists.
• Operation starts after the environment is running. From that point on, manage access through the Identity APIs or Lerian Console.

Use the operational APIs for user access, group assignment, application credentials, providers, and MFA. Don’t change a running environment by editing bootstrap seed files.

Bootstrap seed data is only applied 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.