SAML Authentication

note

This feature is only available in the enterprise version.

SAML-based SSO

SAML-based SSO feature enables support for any SSO provider that supports OAuth authentication flow based on SAML 2.0 protocol.

This feature can be configured by specifying several environment variables for the Mosquitto MQTT Platform.

Terminology

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

• Single Log Out (SLO, sometimes also called Single Sign Out) - The process of terminating all active sessions associated with the same user across all 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 you use SSO to login into.

• 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

You might need to configure the Assertion Consumer Service (ACS) URL in your identity provider. The URL for Mosquitto Platform is <platform_host_url>/api/oauth/saml and it expects a POST request containing a SAML response object obtained after a successful authentication to the identity provider.

In case you need to redirect your identity provider to the application's error page, you may use <platform_host_url>/auth/error. If you need to specify a particular error then: <platform_host_url>/auth/error?error=someError. This is however a non-standard convenience redirect, so unlike ACS URL you won't need to worry about it for most Identity Providers.

Configuration

In order to enable the feature you have to:

• Make sure you don't have any existing Platform users that use the same email as SSO flow.

• Add saml to the comma separated list of authentication providers specified in AUTH_PROVIDERS environment variable.

• Specify AUTH_CUSTOM_SP_ENTITY_ID which represents Mosquitto Platform's entity ID configured in your identity provider such as AzureID, Okta, OneLogin etc.

• Specify SSO email addresses that you want to register in Mosquitto Platform as a comma separated list in the AUTH_CUSTOM_ALLOWED_SIGNUP_EMAILS environment variable.

• Specify your SAML metadata url via AUTH_CUSTOM_SAML_METADATA_URL. If instead you have a metadata file, use AUTH_CUSTOM_RAW_SAML_METADATA_FILE_PATH to specify its full path. For raw or base64 metadata, specify AUTH_CUSTOM_RAW_SAML_METADATA.

• If you want to configure single logout (SLO), specify AUTH_CUSTOM_SLO_URL environment variable which should point to your identity provider's SLO endpoint.

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 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_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.

In case your identity provider does not expose metadata, you can specify the following instead:

• AUTH_CUSTOM_IDP_ENTITY_ID to specify entity id of the identity provider.
• AUTH_CUSTOM_IDP_CERTIFICATE or AUTH_CUSTOM_IDP_CERTIFICATE_FILE_PATH to specify identity provider's certificate as a plain string or file path respectively.
• AUTH_CUSTOM_IDP_URL to specify identity provider's sign-in URL.
• AUTH_CUSTOM_IDP_BINDINGS to optionally specify a comma separated list of HTTP bindings (Redirect or POST) which can typically be safely omitted. Example: httpRedirect,httpPost. These bindings specify which request type (GET or POST) should be used to redirect to your IdP.

To debug SSO flow:

• Set AUTH_CUSTOM_DEBUG environment variable to 1

Note

Sometimes entity id fields can be called "issuer" or "audience" when looking for them in your identity provider. Issuer is typically used for IdP entity ID, while audience often represents SP's entity ID.

Limitations

Currently, Mosquitto MQTT Platform doesn't support IdP initiated SLO. This means that if a user initiates an SLO process from a different application, identity provider will not be able to relay this request to the Mosquitto MQTT Platform to terminate its user session. Platform is currently only able to initiate SLO requests but not receive them when they originate from other apps.