SAML Authentication/SSO

note

This feature is only available in the enterprise version.

SAML SSO (Single Sign-On)

Mosquitto Platform can use an identity provider that supports SAML 2.0 for single sign-on.

Configure this feature with environment variables before starting Mosquitto Platform.

Terminology

• Single Sign-On (SSO) - The process of using a single account to log in across many applications.

• Single Logout (SLO, sometimes also called Single Sign-Out) - The process of terminating all active sessions associated with the same user across connected applications when the user logs out from one application.

• SAML - XML-based communication protocol used for the SSO and SLO processes when exchanging messages between SP and IdP.

• Service Provider (SP) - Application that acts as a client in the SSO process and communicates with Identity Provider to authenticate users. In simple terms, it is an application that users sign into using SSO.

• Identity Provider (IdP) - A centralized entity facilitating SSO process that users authenticate into. After successful authentication it securely communicates user identity data with SPs allowing users to access them.

SP endpoints

Configure the following Assertion Consumer Service (ACS) URL in the identity provider:

<platform_host_url>/api/oauth/saml

The endpoint accepts an HTTP POST containing the SAML response after successful authentication at the identity provider.

info

SAML is a distinct protocol different from OAuth 2.0, so the two should not be mixed up. The reason for naming the callback endpoint api/oauth/saml is due to internal implementation trying to transform standard SAML flow to mimic the OAuth 2.0 flow for consistency with other authentication methods. This does not require any configuration changes and is being mentioned to avoid confusion.

The non-standard <platform_host_url>/auth/error endpoint is available as a convenience error redirect. An error can be supplied as a query parameter, for example <platform_host_url>/auth/error?error=someError. Most identity providers do not need this endpoint.

Configuration

To enable SAML:

1. Set NEXTAUTH_URL to the externally accessible Platform URL, or set BASE_URL if the same URL is used for internal routing.
2. Add saml to the comma-separated AUTH_PROVIDERS list. Add credentials as well if users should also be able to log in with email and password.
3. Configure IdP metadata using one of the methods below.
4. Configure the Mosquitto Platform entity ID at the identity provider. Set the same value in AUTH_SAML_SP_ENTITY_ID. If the variable is omitted, Mosquitto Platform uses https://mosquitto-platform-enterprise.
5. Restart Mosquitto Platform.

Configure IdP metadata with one of these variables. If more than one is set, Mosquitto Platform uses the first available source in this order:

1. AUTH_SAML_METADATA_URL: an HTTP or HTTPS metadata URL.
2. AUTH_SAML_RAW_METADATA_FILE_PATH: the full path to a metadata XML file.
3. AUTH_SAML_RAW_METADATA: raw or base64-encoded metadata XML.

If the identity provider does not expose metadata, Mosquitto Platform can generate it from all of the following:

• AUTH_SAML_IDP_ENTITY_ID: the identity provider entity ID.
• AUTH_SAML_IDP_CERTIFICATE or AUTH_SAML_IDP_CERTIFICATE_FILE_PATH: the identity provider certificate as a string or full file path. The file takes precedence when both are set.
• AUTH_SAML_IDP_URL: the identity provider sign-in URL.
• AUTH_SAML_IDP_BINDINGS: optional comma-separated bindings. Supported values are httpRedirect and httpPost; the default enables both.

To enable Platform-initiated single logout, set AUTH_SAML_SLO_URL to the identity provider's SLO endpoint. When Mosquitto Platform generates metadata, it includes this endpoint in that metadata.

After SAML is enabled:

• On a fresh installation, choose SSO on the setup screen. The first user becomes the root administrator.
• On an existing installation, an administrator can create users with the SSO user type under Admin board > User management and assign administrators under Administrators.
• Set AUTH_SAML_JIT=1 to create users automatically on their first successful SAML login. See Automatic user creation.

An existing credentials user with the same email is not linked by default. See Link existing credentials users.

You can optionally specify the following variables:

• AUTH_CUSTOM_NAME to display a different provider name on the SSO button on login and signup pages. Default name is SAML SSO.
• AUTH_CUSTOM_PROFILE_IMAGE_CLAIM to specify a claim of the user object returned by your identity provider where user profile image is stored.
• AUTH_CUSTOM_PROFILE_IMAGE_URL to set a default image for your users. Example: https://my-org.org/media/profile-image.png.
• AUTH_CUSTOM_LOGO_URL to set a default logo for the SSO button. Example: https://my-org.org/media/logo.png.
• AUTH_CUSTOM_PROFILE_EMAIL_CLAIM to specify a non-standard claim of the user object returned by your identity provider where email is stored. If a standard claim is used, i.e. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, there is no need to specify this variable.
• AUTH_CUSTOM_PROFILE_FIRSTNAME_CLAIM to specify a non-standard claim of the user object returned by your identity provider that stores first name. If a standard claim is used, i.e. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname, there is no need to specify this variable.
• AUTH_CUSTOM_PROFILE_LASTNAME_CLAIM to specify a non-standard claim of the user object returned by your identity provider that stores last name. If a standard claim is used, i.e. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname, there is no need to specify this variable.
• AUTH_CUSTOM_PROFILE_NAME_CLAIM to specify a non-standard claim of the user object returned by your identity provider that stores both first name and last name separated by a space. This variable doesn't need to be specified if there are separate claims for the first name and last name in your user object. When this claim is specified you also have to specify AUTH_CUSTOM_INFER_NAME and set it to 1.
• AUTH_CUSTOM_INFER_NAME - whether to try to extract the user's first and last names from the name or email claims if they were not found. This extraction removes everything after the @ symbol and looks for a separator such as ., -, , or _. If a separator is found, the first part becomes the first name and the second part becomes the last name. Set this variable to 1 to enable inference. If it is not set, or the names cannot be extracted, the user can set them in account settings after login.
• AUTH_SAML_DEFAULT_CLAIM_PATH to set the default attribute path used by identity-mapping rules that do not override the claim path. Default: groups. See Map attributes to project roles.
• AUTH_SAML_JIT to automatically create a Platform user on first SAML login. Set to 1 to enable. Default is off. See Automatic user creation.
• AUTH_SSO_LINK_CREDENTIALS to let a successful SAML or OIDC login use an existing credentials account with the same email. Set to 1 to enable. Default is off. See Link existing credentials users.
• AUTH_CUSTOM_ALLOWED_SIGNUP_EMAILS to optionally restrict which emails may be created (signup or JIT) or linked. Unset means no extra email filter. An empty value means nobody. See Automatic user creation.

To log detailed SSO diagnostics to the server console, set AUTH_CUSTOM_DEBUG=1. Debug output can contain identity-provider data; enable it only while troubleshooting.

info

Sometimes entity id fields can be called "issuer" or "audience" on the side of the identity provider. Issuer is typically used for IdP entity ID, while audience often represent's SP's entity ID.

SAML-specific variables use the AUTH_SAML_ prefix (same pattern as AUTH_LDAP_ and AUTH_OIDC_). The previous AUTH_CUSTOM_SAML_* names still work as a fallback and log a deprecation warning.

Automatic user creation

By default, SAML login does not create users. Existing users (created by an admin, or via the setup/signup flow) can sign in; unknown users are rejected.

Set AUTH_SAML_JIT=1 to create a Platform user on the first successful SAML login. This matches the always-on just-in-time creation used for providers listed in AUTH_OIDC_PROVIDERS. Google and GitHub stay opt-in via signup.

JIT does not look up users in the identity provider directory. The identity provider is already the gate: Mosquitto Platform only continues after a valid SAML assertion. Anyone the IdP rejects never reaches user creation. Anyone the IdP accepts is treated as a known SAML user.

AUTH_CUSTOM_ALLOWED_SIGNUP_EMAILS is an optional extra filter on top of that, not the main guard:

• Unset — no Platform email filter. Every identity that completes SAML login may be created.
• Set to one or more emails — only those emails may be created. Others are rejected as not allowed.
• Set but empty — nobody may be created.

You do not need to remove the allowlist for JIT to work. You only unset it if the IdP should be the only who-may-join decision.

Also when JIT is enabled:

• If the email already belongs to another user, login is rejected, unless that user is a credentials account and AUTH_SSO_LINK_CREDENTIALS=1 (see Link existing credentials users).
• On a fresh on-premise install with no users, the first SAML login still becomes the root admin, same as other SSO setup flows.

Link existing credentials users

By default, a SAML (or OIDC) login cannot take over a Platform user that was created with email and password. That collision is rejected.

Set AUTH_SSO_LINK_CREDENTIALS=1 to attach the SAML/OIDC account to that existing credentials user when the emails match. This is account linking, not JIT:

• JIT creates a new user when none exists.
• Linking reuses the existing credentials user. The password stays; the user can still sign in with credentials.
• LDAP users, admin-precreated SSO users, and users that already have another federated provider are not linked this way.

The identity provider is still the identity check. Linking only runs after a valid SAML/OIDC login. AUTH_CUSTOM_ALLOWED_SIGNUP_EMAILS still applies when set.

This is off by default on purpose. Anyone who can get an IdP identity with the same email can sign in as that Platform user. Enable it only when you trust IdP emails (typically a company IdP).

JIT and linking are independent:

• JIT off, link on — unknown SAML emails are rejected; matching credentials emails are linked.
• JIT on, link off — unknown emails are created; credentials emails are still rejected.
• both on — unknown emails are created; credentials emails are linked.

Map attributes to project roles

Project owners and project administrators can map SAML assertion attributes (typically groups) to project roles. Mappings are managed in the Platform UI under Project settings > IdP Mapping. The page is shown on on-premise deployments when saml is listed in AUTH_PROVIDERS (or when another identity-mapping provider such as OIDC or LDAP is configured).

The SAML provider ID is saml. Identity provider connection settings cannot be configured on this page; they come from the SAML environment variables above.

Mappings are project-specific:

1. Select the SAML 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 SAML default claim path.

The default claim path is displayed above the rule list. Leave the override empty to use that default.

The identity provider must include the mapped attributes in the SAML assertion (for example a groups attribute, or the Azure AD groups claim). Attributes that are not sent cannot be mapped.

This is the same mapping page used for OIDC role mapping.

SAML claims

After a successful SAML sign-in, Mosquitto Platform builds claims from the SAML user profile returned by its SAML bridge:

• Wrapper fields such as id, email, firstName, and lastName become claims of the same name.
• Assertion attributes from the profile's raw object become claims of the same name. Raw assertion values override wrapper fields when both are present.
• Values are strings or arrays of strings. Empty values are ignored.
• HTTP(S) attribute URIs are also available under their last path segment. For example, http://schemas.microsoft.com/ws/2008/06/identity/claims/groups is also available as groups.

If multiple attribute URIs end in the same segment, only the first URI in the assertion receives that short-name alias. Configure unique attribute names at the identity provider so that rules match the intended attribute.

The default claim path is groups. Set AUTH_SAML_DEFAULT_CLAIM_PATH if rules should match a different attribute by default (for example memberOf or Group).

Do not use a full attribute URI as the claim path in a rule. Claim paths are looked up with dotted-path syntax, so a URI containing . will not match. Use the last path segment instead (groups).

Examples:

Goal	Claim path	Example regex
Match a groups attribute	groups (or empty)	^Platform Admins$
Match Azure AD groups via the short name	groups (or empty)	^Platform Admins$
Match another assertion attribute	department	^engineering$
Match memberOf as sent by the IdP	memberOf	CN=Platform Admins,.*

Azure AD often emits group object IDs rather than display names. In that case the regular expression must match the ID the IdP sends, or the IdP must be configured to emit group names.

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 SAML sign-in:

1. Mosquitto Platform reads the SAML user profile and builds claims as described above.
2. It evaluates all SAML rules across all projects.
3. A matching rule adds a provider-managed project membership whose mapping provider is saml.
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 SAML mapping. A mapping does not replace a manual role, even when the mapping would grant a higher role.

Projects the user owns are not affected.

If group attributes are missing from the assertion, the user can still sign in. Provider-managed SAML memberships are then removed, so the user only keeps owned projects and manual memberships until a later login includes those attributes.

A mapping failure does not block sign-in. If synchronization fails, Mosquitto Platform removes the user's existing SAML-managed memberships to avoid retaining stale access. Manual memberships and owned projects remain unchanged. Invalid rules are skipped; valid rules are still evaluated, and the Platform displays the mapping error status to the affected user.

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 does not support IdP-initiated SLO. If a user starts SLO from another application, the identity provider cannot relay that request to Mosquitto Platform to terminate its session. Mosquitto Platform supports only SP-initiated SLO.

Identity mapping is available on on-premise deployments only. The identity provider must emit the attributes used by mapping rules in the SAML assertion.