Skip to main content
Version: Next

OIDC Authentication/SSO

note

This feature is only available in the enterprise version.

Open ID Connect SSO (Single Sign-On)​

Open ID Connect- (OIDC-) based SSO feature enables support for any SSO provider that supports Open ID Connect 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

  • Open ID Connect (OIDC) - an extension of OAuth 2.0 protocol which provides a JWT with user information. This allows it to implement authentication as opposed to the original OAuth 2.0 protocol designed for authorization.

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

  • OpenID Provider (OP) - A centralized entity facilitating SSO process that users authenticate into. After successful authentication it securely communicates user identity data with RP, allowing users to access RP.

RP Callback Endpoints​

You will need to configure the Allowed Callback URL in your OpenID Provider. The URL for Mosquitto Platform is <platform_host_url>/api/auth/callback/oidc.

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 OpenID Provider.

Configuration​

In order to enable the feature you have to:

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

  • Add oidc to the comma separated list of authentication providers specified in AUTH_PROVIDERS environement variable.

  • 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 AUTH_CUSTOM_OIDC_ISSUER to set a URL of the OpenID Provider (OP).

  • Specify AUTH_CUSTOM_OIDC_CLIENT_ID to set Platform's client ID from the OpenID Provider.

  • Either specify AUTH_CUSTOM_OIDC_CLIENT_SECRET, which is Platform's client secret from the OpenID Provider or AUTH_CUSTOM_OIDC_CLIENT_SECRET_FILE_PATH which is a full path to a file containing client secret.

  • Either specify AUTH_CUSTOM_OIDC_WELL_KNOWN_URL which is a URL of the OIDC discovery endpoint, or specify AUTH_CUSTOM_OIDC_TOKEN_URL, AUTH_CUSTOM_OIDC_AUTHORIZATION_URL, AUTH_CUSTOM_OIDC_ISSUER, and AUTH_CUSTOM_OIDC_USERINFO_URL or AUTH_CUSTOM_OIDC_ID_TOKEN.

  • If discovery endpoint was not set, specify AUTH_CUSTOM_OIDC_AUTHORIZATION_URL representing an authorization endpoint URL where users are redirected to login.

  • If discovery endpoint was not set, specify AUTH_CUSTOM_OIDC_TOKEN_URL representing a token endpoint URL where the code is exchanged for tokens.

  • If discovery endpoint was not set, specify AUTH_CUSTOM_OIDC_USERINFO_URLrepresenting a user info endpoint URL where user profile data is retrieved from. You can alternatively specify AUTH_CUSTOM_OIDC_ID_TOKEN instead.

  • If discovery endpoint and user info endpoints were not set, specify AUTH_CUSTOM_OIDC_ID_TOKEN to control whether to use ID tokens for extracting user information. If set to 1, Platform gets user info from the ID token. If not set, Platform will use userinfo endpoint which has to be specified in this case.

  • Specify AUTH_CUSTOM_OIDC_PROFILE_AUTOPARSE to automatically parse user information. You can alternatively manually specify at least email and id claims from the optional varaibles below.

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

There are also some additional mostly optional variables such as:

  • AUTH_CUSTOM_OIDC_DISABLE_PKCE_CHECK - to specify whether to use perform PKCE security check. If set to 1, Platform will only perform a state check. If not set, both PKCE and state checks will be peformed, which is a default.
  • AUTH_CUSTOM_NAME to display a different provider name on the SSO button on login and signup pages. Default name is OIDC SSO.
  • AUTH_CUSTOM_LOGO_URL to set a default logo for the SSO button. Example: https://my-org.org/media/logo.png.
  • AUTH_CUSTOM_OIDC_PROFILE_ID_CLAIM to specify a non-standard claim of the user object retreived from your OpenID Provider that stores user's unique id. By default (if autoparse is enabled) sub is being used. If not found, id claim is also tried.
  • AUTH_CUSTOM_PROFILE_EMAIL_CLAIM to specify a non-standard claim of the user object retreived from your OpenID Provider that stores user's email address. By default email claim is used.
  • AUTH_CUSTOM_PROFILE_FIRSTNAME_CLAIM to specify a non-standard claim of the user object retreived from your OpenID Provider that stores user's first name. By default given_name claim is used. Additionally firstname and first_name are also tried.
  • AUTH_CUSTOM_PROFILE_LASTNAME_CLAIM to specify a non-standard claim of the user object retreived from your OpenID Provider that stores user's last name. By default family_name claim is used. Additionally lastname and last_name are also tried.
  • AUTH_CUSTOM_PROFILE_NAME_CLAIM to specify a non-standard claim of the user object retreived from your OpenID Provider that stores both first name and last name separated by a space. This variable needs to be specified together with AUTH_CUSTOM_INFER_NAME. however variable doesn't need to be specified if there are separate claims for the first name and last name in your user object. By default name claim is used.
  • AUTH_CUSTOM_PROFILE_IMAGE_CLAIM to specify a claim of the user object retreived from your OpenID Provider where user profile image is stored. By default picture claim is used.
  • AUTH_CUSTOM_PROFILE_IMAGE_URL to set a default image for your users. Example: https://my-org.org/media/profile)image.png.
  • 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.

To debug SSO flow:

  • Set AUTH_CUSTOM_DEBUG environement variable to 1

Limitations​

Only single sign on is supported. There is currently no single log out functionality. Access tokens generated by OIDC are only used one time by the Platform to create an internal session which is managed separately thereafter. This means that expiration date of the access token will not be utilized after the first use. The same is true for any refresh token (if any) which was provided together with access token. Refresh tokens are not used by the Platform. The above also means that RP-initiated logout process is irrelevant to the Platform as it doesn't rely on refresh tokens to keep the user signed in. While a so-called back-channel logout which represents an OP-initiated logout would be more relevant to Mosquitto Platform, it is not supported, as it is not a part of the official OpenID specification but is instead detailed in the OpenID implementer's draft.