This feature is available on dedicated LavinMQ instances running LavinMQ 2.7 or later.
LavinMQ supports OAuth 2.0 as an authorization backend. Clients authenticate using JWT access tokens issued by an OpenID Connect (OIDC) compliant identity provider such as UAA, Keycloak, Auth0, Azure, or Okta. You can configure OAuth 2.0 in the CloudAMQP console under the OAuth 2.0 Configuration tab, or through the CloudAMQP API.
From LavinMQ 2.7, OAuth 2.0 authentication applies to:
From LavinMQ 2.9, the management UI also supports single sign-on (SSO) login through your identity provider. See Management UI SSO login below. On earlier versions the management UI uses basic authentication only.
The following configuration options can be set through the CloudAMQP console or API.
| Option | Description |
|---|---|
issuer
(Required) |
The URL of the OAuth 2.0 authorization server that issues the JWT tokens. The server must be OpenID Connect (OIDC) compliant. The URL must start with
https://.
|
resource_server_id
|
The identifier that represents this LavinMQ instance as an OAuth 2.0 resource server. Used as the default prefix for permission scopes. |
audience
|
Some identity providers (e.g. Auth0) mandate this parameter. Should not be set if you are using Azure/Entra v2 endpoints. |
preferred_username_claims
|
A list of JWT token claims that LavinMQ will search to extract a user-friendly username. |
additional_scopes_keys
|
A list of alternative JWT claim keys to extract scopes from, in addition to the standard
scope
claim.
|
scope_prefix
|
Custom prefix for OAuth 2.0 scopes, used to avoid scope collisions or unintended overlap. By default,
resource_server_id
followed by a dot (.) character is used as the prefix.
|
verify_aud
(Default: true) |
Controls whether LavinMQ validates the "aud" (audience) claim in JWT tokens against the configured
resource_server_id
(or
audience
if set). Leave enabled for production instances.
|
jwks_cache_ttl
|
How long JWKS signing keys are cached before being re-fetched from the identity provider, in seconds (0–86400).
Lower values respond faster to key rotation; higher values reduce load on the identity provider.
The
Cache-Control max-age
header from the identity provider takes precedence when present.
|
client_id
(LavinMQ 2.9+) |
The OAuth 2.0 client ID registered with your identity provider for the LavinMQ management UI. Setting this enables SSO login on the management UI. |
mgmt_scopes
(LavinMQ 2.9.1+) |
Space-separated OAuth 2.0 scopes requested during management UI SSO login. Defaults to
openid profile.
Override when your identity provider requires specific scopes to issue a JWT access token for LavinMQ (e.g. Azure/Entra).
|
Configure scopes at your identity provider that map to LavinMQ's permission model. The prefix is
resource_server_id
by default, or the value of
scope_prefix
if set.
{prefix}.configure:{vhost}/{resource}
- Configure permissions
{prefix}.read:{vhost}/{resource}
- Read permissions
{prefix}.write:{vhost}/{resource}
- Write permissions
{prefix}.tag:{tag}
- User tag, where
{tag}
is one of
administrator,
monitoring,
management
or
policymaker.
Assign these scopes to the users, clients, or roles that should connect to LavinMQ over AMQP, MQTT, or the HTTP API.
On instances running LavinMQ 2.9 or later, users can log in to the management UI through your identity provider instead of with username and password. To enable it:
https://{your-instance-hostname}/oauth/callback
as an allowed redirect URI for the application. The hostname is shown on the instance details page in the CloudAMQP console.
client_id
in the OAuth 2.0 configuration to the client ID of the registered application.
mgmt_scopes
accordingly (requires LavinMQ 2.9.1).
To be able to log in, a user's access token must grant at least one user tag, e.g.
{prefix}.tag:administrator.
The token's permission scopes control what the user can see and do in the management UI, just as for the HTTP API.
Saving an OAuth 2.0 configuration requires a broker restart before the change takes effect. The console will indicate when a restart is pending.