Authentication and authorization are foundational to protecting your system. While authentication confirms who the user is, authorization controls what that user can access or do. Both are essential to keep your applications secure and your data safe.

In the case of Midaz, since it’s open source and distributed on-premise—along with its plugins—there’s no need for a built-in multi-tenancy layer. Most clients already have their own authentication mechanisms, and we respect that. Still, we know that implementing fine-grained security controls isn't always straightforward, especially when you’re dealing with critical applications like the ledger.

That’s why we’ve developed the Access Manager plugin: an optional component designed to handle user access and identity management when you need more control at the application level.

👍

Test the Access Manager Plugin locally

Run Lerian’s plugins without deploying to Kubernetes using our plugins-docker-compose repository.

Keep in mind that these services require a valid license to run. Without it, the application will not start. For license details, check our License documentation.

Why use the Access Manager plugin?

When your security strategy requires native, fine-tuned access control across Midaz and its plugins, Access Manager is your go-to. It helps you manage users, credentials, and application access with performance and flexibility in mind.

👍

Tip

Access Manager is available as a part of the Enterprise model. If you'd like to learn more or evaluate it for your use case, get in touch with our team.

Components

The Access Manager plugin is made up of two independent services that work together:

• Auth: Acts as the bridge between your applications and your authentication/authorization layer. It handles:
  • Access token generation (OAuth2).
  • Token refresh.
  • Credential validation.
• Identity: Provides a clear interface—via REST API or the Console—for managing users and access controls. It covers:
  • User Management.
  • Machine-to-Machine (M2M) Credentials.

Everything is built for performance, simplicity, and extensibility.

🚧

Attention

Although Access Manager is split into two independent services, they don’t work in isolation. Each service depends on the other to function properly. Make sure both are up and running before diving in.

Technical specs

• RESTful APIs and Console interface available.
• Midaz and its plugins include the lib-auth library, ready to enforce authorization checks.
• Feature flag available via environment variable PLUGIN_AUTH_ENABLED to toggle validation.
• OAuth2-based token management and credential flow.
• Integration-ready with third-party authentication and authorization platforms.
• Valkey caching to boost performance.
• Role-based access control (RBAC) aligned with Midaz resource structure.

Use cases

Access Manager is ideal for:

• Clients looking for built-in authentication and authorization at the application layer.
• Organizations without a pre-existing IAM solution.
• Scenarios where secure M2M integrations are needed.
• Teams that want unified access control across Midaz and all its plugins.

Best practices

Access Manager is powerful — it handles identity, authorization, and credentials at the heart of your Midaz stack. That power comes with responsibility. Here’s how to use it securely and efficiently.

Credentials

Create credentials on both ends

If two plugins need to talk to each other, both must have the necessary M2M credentials created. Don’t assume symmetry — define explicitly on both sides.

Lock down the physical environment

Access Manager store credentials locally. That means anyone with access to the hardware could potentially extract them. Make sure the physical or virtual machine hosting the plugin is tightly secured — this is your first line of defense.

Avoid exposing endpoints that retrieve the credentials.

Admins in Access Manager (via Identity) can retrieve credentials — which is exactly why these endpoints should not be integrated into any back-office system. Keep sensitive operations isolated to reduce the chance of accidental exposure.

Security recommendations

Use Application-to-Application flows for sensitive endpoints

For critical accesses like the Ledger, we recommend interacting through Applications. This ensures you have full control over each credential. If something leaks, you can revoke or delete the Application without bringing down your entire system.

Manual actions? Use user-based credentials

When human access is required (for debugging, operations, or support), always create user credentials using the password grant — not client_credentials. This approach allows you to easily manage access, revoke permissions, and trigger forced logouts when needed via the appropriate endpoint.

We strongly recommend implementing a credentials rotation policy and performing regular access reviews to minimize exposure and ensure only authorized users retain access.

Always enforce the principle of least privilege, granting only the exact permissions needed — nothing more, nothing less — for both users and applications.

👍

Tip

Looking to strengthen your infrastructure? Check out our Security Recommendations for best practices and actionable guidance.

Enabling Access Manager

After installing the Access Manager plugin, you must enable it for it to function properly. This means updating the Auth variables in the .env files of Midaz Ledger, Midaz Console, or any plugin where you want to use Access Manager.

Your configuration should look like this:

# AUTH CONFIGS 
PLUGIN_AUTH_ENABLED=true
PLUGIN_AUTH_HOST=http://plugin-auth:4000

❗️

Important

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

Without this header, your requests will be rejected, even for public or previously accessible endpoints.

Learn how to generate and use access tokens.

Where to update

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

• Midaz Ledger and Midaz Console

  • /midaz/components/onboarding
  • /midaz/components/transaction
  • /midaz/components/console

• Other plugins

  • The .env file should be in the root directory of the plugin.

👍

Tip

Can’t see the files? Try adjusting your system settings to show hidden files since.env files are often hidden by default.

Rebuild after changes

After updating the environment, rebuild your Docker images to apply the changes:

1. In your terminal, go to the root of your Midaz project.
2. If Docker is running, stop it:

make down

3. Then rebuild everything:

make rebuild-up