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.
In LavinMQ 2.7, OAuth 2.0 authentication applies to:
The LavinMQ management UI continues to use basic authentication and does not support OAuth 2.0 / SSO login in this release.
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.
|
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
Assign these scopes to the users, clients, or roles that should connect to LavinMQ over AMQP, MQTT, or 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.