OIDC Authentication and Role Mapping

note

Identity provider role mapping is available only for on-premise deployments.

info

For the legacy single-provider OIDC integration, see OIDC Authentication/SSO.

OpenID Connect single sign-on

Mosquitto Platform can use one or more OpenID Connect (OIDC) providers for single sign-on (SSO). Each provider has its own login option and can map claims from the identity provider to project roles in Mosquitto Platform.

Terminology

• Single sign-on (SSO) lets users access multiple applications with one identity provider account.
• OpenID Connect (OIDC) is an identity layer based on OAuth 2.0.
• Relying party (RP) is the application that delegates authentication to an identity provider. Mosquitto Platform is the relying party.
• OpenID Provider (OP) authenticates users and returns identity claims.
• Claim is an attribute in an OIDC profile or token, such as an email address, group, or role.

Configure Mosquitto Platform

Complete these steps to enable OIDC login:

1. Enable one or more providers with AUTH_OIDC_PROVIDERS.
2. Set the required environment variables for each provider.
3. Register the redirect URI at each identity provider.
4. Start or restart Mosquitto Platform.
5. Optionally, map identity-provider claims to project roles in the Platform UI.

Enable providers

Set AUTH_OIDC_PROVIDERS to a comma-separated list of provider IDs:

AUTH_OIDC_PROVIDERS=keycloak,entra

Do not add these providers to AUTH_PROVIDERS. The oidc entry in AUTH_PROVIDERS configures the separate, legacy single-provider integration.

Mosquitto Platform forms each provider's environment-variable prefix as AUTH_OIDC_<ID>_. <ID> is the original provider ID, trimmed and uppercased, with each sequence of non-alphanumeric characters replaced by _. The callback URL still uses the original provider ID. Examples:

Provider ID	Resulting env-variable prefix	Callback path
keycloak	AUTH_OIDC_KEYCLOAK_	/keycloak
oidc-main	AUTH_OIDC_OIDC_MAIN_	/oidc-main

Required environment variables

Mosquitto Platform does not use OIDC discovery. Set the issuer, authorization, token, and userinfo endpoints explicitly.

Each provider also needs a client secret and a user profile source. If any required value is absent, Mosquitto Platform does not register that provider.

Replace <ID> in the variable names below with that uppercase form. For example, the keycloak issuer URL is AUTH_OIDC_KEYCLOAK_ISSUER.

Variable	Description
AUTH_OIDC_<ID>_ISSUER	Issuer URL.
AUTH_OIDC_<ID>_CLIENT_ID	Client ID assigned to Mosquitto Platform.
AUTH_OIDC_<ID>_AUTHORIZATION_URL	Authorization endpoint to which users are redirected.
AUTH_OIDC_<ID>_TOKEN_URL	Token endpoint used to exchange the authorization code.

Client secret. Set one of:

• AUTH_OIDC_<ID>_CLIENT_SECRET: the client secret itself.
• AUTH_OIDC_<ID>_CLIENT_SECRET_FILE_PATH: full path to a file containing the client secret. Surrounding whitespace in the file is removed.

If both are set, the inline client secret takes precedence.

User profile. Set one of:

• AUTH_OIDC_<ID>_USERINFO_URL: userinfo endpoint.
• AUTH_OIDC_<ID>_ID_TOKEN=1: read the profile from ID token claims instead of calling a userinfo endpoint.

If both are set and AUTH_OIDC_<ID>_ID_TOKEN is 1, the ID token is used.

Optional environment variables

Variable	Description
AUTH_OIDC_<ID>_NAME	Provider name shown on the login option. Defaults to the provider ID.
AUTH_OIDC_<ID>_LOGO_URL	Provider logo shown on the login option. Defaults to /auth.svg.
AUTH_OIDC_<ID>_DISABLE_PKCE_CHECK	When set to a non-empty value, disables the PKCE check and retains only the state check. When unset, both PKCE and state checks are enabled.
AUTH_OIDC_<ID>_DEFAULT_CLAIM_PATH	Default claim path for this provider's role mapping rules. Defaults to groups.

User provisioning

AUTH_CUSTOM_ALLOWED_SIGNUP_EMAILS can be used as a comma-separated allowlist when a user who does not yet have an account signs in through an enabled OIDC provider. If this variable is not set, the user can be provisioned automatically. An existing local account with the same email address cannot be linked implicitly during a separate signup flow.

Example

AUTH_OIDC_PROVIDERS=keycloak

AUTH_OIDC_KEYCLOAK_ISSUER=https://id.example.com/realms/company
AUTH_OIDC_KEYCLOAK_CLIENT_ID=cedalo-platform
AUTH_OIDC_KEYCLOAK_CLIENT_SECRET_FILE_PATH=/run/secrets/oidc-client-secret
AUTH_OIDC_KEYCLOAK_AUTHORIZATION_URL=https://id.example.com/realms/company/protocol/openid-connect/auth
AUTH_OIDC_KEYCLOAK_TOKEN_URL=https://id.example.com/realms/company/protocol/openid-connect/token
AUTH_OIDC_KEYCLOAK_USERINFO_URL=https://id.example.com/realms/company/protocol/openid-connect/userinfo
AUTH_OIDC_KEYCLOAK_NAME=Company SSO
AUTH_OIDC_KEYCLOAK_LOGO_URL=https://id.example.com/assets/company-logo.svg
AUTH_OIDC_KEYCLOAK_DEFAULT_CLAIM_PATH=groups

Restart Mosquitto Platform after changing the provider environment variables.

Configure the identity provider

Redirect URI

Register the following redirect URI with the identity provider:

<platform_host_url>/api/auth/callback/<provider_id>

Replace platform_host_url with the Mosquitto Platform URL and use the provider ID from AUTH_OIDC_PROVIDERS, not the normalized environment-variable form.

For example, a provider whose ID is keycloak uses:

https://platform.example.com/api/auth/callback/keycloak

A wildcard such as <platform_host_url>/* is often enough if the provider does not require the full path.

Profile claims

The OIDC profile must contain:

• a user ID in the sub or id claim
• an email address in the email claim

Login fails if either value is missing.

Mosquitto Platform also maps these optional standard profile claims:

• profile image: picture
• first name: given_name, first_name, or firstname
• last name: family_name, last_name, or lastname

Map claims to project roles

Project owners and project administrators can manage mappings in the Platform UI under Project settings > IdP Mapping. The page is shown on on-premise deployments when at least one OIDC provider ID is configured.

OIDC providers themselves cannot be configured on this page; their settings come from environment variables.

Mappings are project-specific:

1. Select a provider.
2. Add one or more rules. Each rule contains:
   • Claim value regex: a regular expression matched against claim values.
   • Role: the project role granted by a match: Viewer, Editor, or Admin.
   • Claim path override: an optional path used instead of the provider's default claim path.

The default claim path is displayed above the rule list. Leave the override empty to use that default. Dot-separated paths address nested claims; for example, realm_access.roles.

Rules for a provider that is no longer enabled remain visible. This allows them to be edited or removed, but they cannot take effect until users can sign in through that provider again.

Claim values and regular expressions

A claim can be either a string or an array of non-empty strings. Other value types do not match. A rule matches when its regular expression matches at least one value.

Regular expressions always match the complete claim value. For example:

• engineering matches only engineering.
• engineering-.* matches values such as engineering-eu.
• team-(reader|writer) matches either team-reader or team-writer.

The expression must not be empty or longer than 250 characters. Expressions that are excessively broad, susceptible to catastrophic backtracking, or use lookahead, lookbehind, or backreferences are rejected.

Rules with the same provider, project, claim path, and regular expression are duplicates and cannot be added, even if they specify different roles.

How roles are synchronized

Role mappings are evaluated after every successful sign-in through an enabled OIDC provider:

1. Mosquitto Platform combines claims from the returned profile and decodable ID and access tokens. ID token claims override profile claims, and access token claims override both when names overlap. Opaque or invalid tokens do not contribute claims.
2. It evaluates all rules for that provider across all projects.
3. A matching rule adds a provider-managed project membership.
4. If several rules match the same project, the highest role wins: Admin, then Editor, then Viewer.
5. A changed match updates the provider-managed role. If no rule matches anymore, the provider-managed membership is removed.

Manually assigned project memberships are never changed or removed by OIDC mapping. Consequently, a mapping does not replace a manual role, even when the mapping would grant a higher role.

Rule changes are applied when the affected user next signs in. Saving or deleting a rule does not immediately recalculate memberships for users who are already signed in. The mapping page does not provide a rule preview or test action.

Limitations

Mosquitto Platform uses OIDC access and ID tokens to authenticate the user and evaluate role mappings during sign-in. It then maintains its own application session. Access-token expiration and refresh tokens do not control an existing Platform session.

Single logout is not supported. Logging out of Mosquitto Platform does not end the session at the OpenID Provider. If that provider session is still active, starting OIDC login again can immediately authenticate the same account.