Configure OIDC-Based SSO

This page explains how to configure and use Single Sign-On (SSO) based on the OpenID Connect (OIDC) protocol.

Prerequisite

Be familiar with the basic concepts of Single Sign-On (SSO).

Supported OIDC provider

The EMQX Dashboard can integrate with identity services that support the OIDC protocol to enable OIDC-based SSO, such as:

• Microsoft Entra ID
• Okta

Configure SSO by Integrating with Microsoft Entra ID

This section guides you on how to use Microsoft Entra ID as an Identity Provider (IdP) and configure SSO. You need to complete configurations on both the Microsoft and EMQX Dashboard sides.

Step 1: Enable OIDC in the EMQX Dashboard

1. In the EMQX Dashboard, navigate to System -> SSO.
2. Click the Enable button on the OIDC card.

Step 2: Register an Application to Integrate with Microsoft Entra ID

1. Log in to the MS Azure Portal as an administrator.

2. Go to Microsoft Entra ID -> Enterprise Applications -> New Application and click Create your own application.

   

3. Enter the application name, for example, EMQX Dashboard, select Register an application to integrate with Microsoft Entra ID (App you're developing), and click Create.

   

4. On the Register an application page, select which account types you want to be supported, and configure Redirect URL using the information provided by the EMQX Dashboard in Step 1:

   • Redirect URL: Select Web and enter the Sign-in Redirect URI provided in the Dashboard, such as http://localhost:18083/api/v5/sso/oidc/callback.

5. Go to Certificates and Secrets -> Client secrets tab, click New client secret, enter a description, select an expiration period, and click Add. Copy the generated secret value, as you will need it in Step 3.

Step 3: Complete the EMQX Dashboard Configuration

1. On the configuration page, enter the following information:

   • Provider: Leave Generic.

   • Issuer URL: This corresponds to OpenID Connect metadata document, which you can find in the Endpoints tab of application overview page in Step 2, but without /.well-known/openid-configuration part because EMQX adds this automatically, e.g.https://login.microsoftonline.com/<tenant_id>/v2.0, where <tenant_id> is your Directory (tenant) ID.

   • Client ID: This corresponds to Application (client) ID found on the application overview page in Step 2.

     

   • Client Secret: Use the secret value generated in Step 2.

   • Dashboard Address: Enter the base URL where users can access the Dashboard, such as http://localhost:18083. This address will be automatically combined to generate the SSO Address and Metadata Address for configuration on the IdP side.

     

2. Click Update to finish the configuration.

Configure SSO by Integrating with Okta

This section guides you on how to use Okta as an Identity Provider (IdP) and configure SSO. You need to complete configurations on both the Okta and EMQX Dashboard sides.

Step 1: Enable OIDC in the EMQX Dashboard

1. In the EMQX Dashboard, navigate to System -> SSO.
2. Click the Enable button on the OIDC card.

Step 2: Add an OIDC Application to Okta's Application Catalog

1. Log in to Okta as an administrator and go to the Okta Admin Console.

2. Go to the Applications -> Applications page, click the Create App integration button, and select OIDC - OpenID Connect as the sign-in method in the pop-up dialog.

3. Select the Web Application as the Application type and click Next.

4. On the General Settings tab, enter your application name, for example, EMQX Dashboard. Click Next.

5. On the LOGIN tab, configure the settings using the information provided by the EMQX Dashboard in Step 1:

   • Sign-in redirect URIs: Enter the Sign-in Redirect URI provided in the Dashboard, such as http://localhost:18083/api/v5/sso/oidc/callback.
   • Additional settings are optional and can be configured according to your specific requirements.

6. Review the settings and click Save.

For more detailed instructions, refer to the Okta documentation.

Step 3: Complete the EMQX Dashboard Configuration

1. On the configuration page, enter the following information:
   • Provider: Choose Okta or select Generic for other providers.
   • Issuer URL: This is the URL of your Okta authorization server, e.g., https://example-org.okta.com.
   • Client ID: Copy it from the application created in Step 2.
   • Client Secret: Copy it from the application created in Step 2.
   • Dashboard Address: Enter the base URL where users can access the Dashboard, such as http://localhost:18083. This address will be automatically combined to generate the SSO Address and Metadata Address for configuration on the IdP side.
2. Click Update to finish the configuration.

Login and User Management

After enabling OIDC SSO, the EMQX Dashboard will display the SSO option on the login page. Click the OIDC button to go to the OIDC provider preset login page, where you can enter the credentials assigned to the user for login.

After successful authentication, EMQX will automatically add a Dashboard user, which you can manage in Users, such as assigning roles and permissions.

Logout

Users can click their username in the top navigation bar of the Dashboard and then click the Logout button in the dropdown menu to log out. Please note that this only logs you out of the Dashboard.