Skip to main content
Version: Mosquitto 3.0

SAML Authentication/SSO

note

This feature is only available in the enterprise version.

SAML SSO (Single Sign-On)​

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

This feature can be configured by specifying several environment variables for 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 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​

You will 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.

info

SAML is a distinct protocol different from OAuth 2.0, so the two should not be mixed up. The reason for naming > 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 changes > configuration changes and is being mentioned to avoid confusion.

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​

It's recommended (but not required) to start with a clean Platform that doesn't have any users. You can delete mosquitto-enterprise.sqlite3 file to achieve this and restart the platform. The file is stored in the data directory which depends on your installation, but in Docker environments it's usually called data, while for an RPM-package it's located under var/opt/cedalo/mosquitto-platform. You can also manually delete your users as an administrator or by signing in one user at a time and navigating to Settings -> Delete account. A crucial point is to make sure you don't have any existing Platform users that use the same email as SSO users you want to add.

In order to enable the feature you have to:

  • Set BASE_URL environment variable to point to an internal URL of your Mosquitto Platform. Alternatively, set NEXTAUTH_URL to point to an external URL.

  • 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 environement variable.

  • Specify AUTH_CUSTOM_SP_ENTITY_ID which represents Mosquitto Platform's entity ID configured in your identity provider such as Azure AD (now Microsoft Entra ID), 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 environemnt varaible.

  • 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 signle logout (SLO), specify AUTH_CUSTOM_SLO_URL environment varaible which should point to your identity provider's SLO endpoint.

  • After specifying all the required environment variables, you can start Mosquitto Platform and open it in your browser. If you don't have any users you will be greeted with a Setup screen where you can choose SSO option to create an admin user and sign in. In case you already have users in the platform, you will have to login using an admin account.

  • After you are signed in as an admin, you can click on the top-right menu and choose "Admin board".

  • Navigate to "User management" and create new users specifying SSO as a user type.

  • You can also choose to make some users admins in "Administrators" section on the left-hand side.

  • After users were created, they can be used to login to the Platform by choosing the SSO option on the login page.

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_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 varaible.
  • 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 varaible.
  • 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 user's first name and last name from the name or email claims if they were not found. This extraction will try to remove everything after the @ symbol in the email or name fields and look for a seperator such as ., -, , or _. If a separator is found, the first part of the string before it becomes user's first name and second part - their last name. You can set this varaible to 1 to enbale the inference. If this variable is not set or first and last name could not be extracted, you will be able to set manually them in user's account settings after login.

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 signin URL.
  • AUTH_CUSTOM_IDP_BINDINGS to optionally specify a comma separated list of HTTP bindings (Redirect or POST) which can typically be safely ommited. 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 environement variable to 1
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.

Limitations​

Currently, Mosquitto MQTT Platform doesn't supports IdP initiated SLO. This means that if a user initates 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.