OAuth 2.0 support

TBMQ allows you to provide Single Sign-On (SSO) functionality for your users and automatically create Administrators or Viewers using external user management platforms that support the OAuth 2.0 protocol. Examples of platforms that support OAuth 2.0 include: Google, Auth0, Keycloak, Okta, Azure, etc.

TBMQ supports the Authorization Code grant type to exchange an authorization code for an access token. Once the user is redirected back to the TBMQ client, the platform retrieves the authorization code from the URL and uses it to request an access token from the external user management platform. Using the basic mapper or custom mapper, the external user info object is converted from the external platform into a TBMQ internal OAuth 2.0 user. After this, the regular TBMQ authorization flow takes place.

OAuth 2.0 clients are configured separately from domains, allowing reuse of the configured client and making the settings clearer. To use authentication through an external provider, first configure an OAuth 2.0 client with the necessary credentials. Then, either add a new domain or use an existing one, and update the OAuth 2.0 client list with the new client.

Adding a domain

1. On the Domains tab of the OAuth 2.0 page, click the plus icon.
2. Provide your domain name and OAuth 2.0 client.
3. Click Add to finalize.

On the "Domains" tab of the "OAuth 2.0" page, click the "plus" icon to add a new domain. Provide your domain name and OAuth 2.0 client. Then, click "Add". Domain added.

Editing a domain

1. Click on the domain to view its details.
2. Switch to editing mode by clicking the large orange button.
3. Make the required modifications.
4. Save your changes by clicking Apply changes.

Click on the domain to view its details. Switch to editing mode by clicking the large orange button. Make the required modifications. Then confirm and save the changes by clicking the "Apply changes" button.

Deleting a domain

1. Click the trash icon in the row of the domain you wish to remove.
2. Confirm the deletion by clicking Yes.

Click the "trash" icon in the domain's row you wish to remove. Confirm the deletion by clicking "Yes".

Adding an OAuth 2.0 client

1. Navigate to the OAuth 2.0 clients tab on the OAuth 2.0 page, and click the plus icon.
2. Enter a descriptive title for the client.
3. Select the authentication provider from the dropdown menu.
4. Provide the Client ID and Client Secret obtained from your authentication provider.
5. Configure advanced settings as necessary.
6. Click Add to finalize.

Navigate to the "OAuth 2.0 clients" tab on the "OAuth 2.0" page. Click the "plus" icon to add a new OAuth 2.0 client. Enter a descriptive title for the client, and select the provider from the dropdown menu. Provide the Client ID and Client Secret. Configure advanced settings as necessary. Then, click "Add". New OAuth 2.0 client added.

Editing an OAuth 2.0 client

1. Click on the client to view its details.
2. Switch to editing mode by clicking the large orange button.
3. Make the required modifications.
4. Save your changes by clicking Apply changes.

Click on the OAuth 2.0 client to view its details. Switch to editing mode by clicking the large orange button. Make the required modifications. Then confirm and save the changes by clicking the "Apply changes" button.

Deleting an OAuth 2.0 client

1. Click the trash icon in the row of the client you wish to remove.
2. Confirm the deletion by clicking Yes.

Click the "trash" icon in the client's row you wish to remove. Confirm the deletion by clicking "Yes".

This example uses Google for authentication.

To map external user information from Google to TBMQ, use the built-in basic mapper. If the basic mapper does not fit your business needs, you can configure a custom mapper for more flexibility.

To use Google OAuth 2.0 authentication, you must set up a project in the Google API Console to obtain OAuth 2.0 credentials.

1. Go to the Credentials page in the left menu and select OAuth client ID from the Create credentials dropdown.

2. Enter an OAuth client name and add the TBMQ redirect URI in the Authorized Redirect URIs section using the format:

   http(s)://domain:port/login/oauth2/code/

   Replace domain with your TBMQ domain and specify the port used for HTTP access. For example:

   https://my.tbmq.org/login/oauth2/code/

3. Click Create. You now have a Client ID and a Client Secret.

Go to the "Credentials" page in the left menu and select "OAuth client ID" from the "Create credentials" dropdown menu. Enter a OAuth client name, and add the TBMQ redirect URI, to the "Authorized Redirect URIs" section. Then, click "Create". OAuth client created. You now have credentials consisting of a Client ID and a Client secret.

1. Log in to your TBMQ instance. Go to the OAuth 2.0 page in the Security section. On the Domains tab, click the plus icon. Enter your domain name or IP address and click Create new in the OAuth 2.0 clients section.

   Log in to your TBMQ instance. Go to the "OAuth 2.0" page of the "Security" section. While on the "Domains" tab, click the "plus" icon. Enter your domain name or IP address of your TBMQ instance. Click "Create new" in the "OAuth 2.0 clients" section to add a new one.

2. Configure the new OAuth 2.0 client: enter Google as the title, set the provider to Google, and enter the Client ID and Client Secret from the Google API Console.

   Then expand Advanced settings → General:

   • Refer to Google’s OpenID Connect discovery for the latest Access Token URI and Authorization URI.
   • Select POST as the client authentication method.
   • Enable Allow user creation.
   • Add the following scopes: email, openid, profile.
   Enter "Google" as the title. The provider should be set to "Google". Enter the Client ID and Client secret. Expand Advanced settings and configure the General block. Select "POST" as the client authentication method. Turn on the "Allow user creation" option. Add to the scope field: "email", "openid", and "profile".

3. Go to the Mapper block. Keep the mapper type as BASIC. Configure the role assignment settings, then click Add.

   

4. The OAuth client has been added successfully. Click Add again to confirm the domain.

   The OAuth client is added successfully. Click "Add" again to confirm the addition of the domain. A new domain has been added.

Go to the TBMQ login screen. You will see a new Login with Google option. Select one of your Google accounts — you will be logged into TBMQ using your Google email.

Go to the Users page to find the newly created user.

This example configures OAuth authentication using Auth0 as an external provider.

1. Go to the Auth0 management console. Open the Applications page, and click + Create Application. Name your application TBMQ and choose the type Regular Web Applications. Next, choose Java Spring Boot as the technology.

2. Once your application is created, navigate to the Settings tab to find the Client ID and Client Secret.

3. In the Allowed Callback URLs field, add the redirect URI using the format:

   http(s)://domain:port/login/oauth2/code/

   For example, if your domain is my.tbmq.org:

   https://my.tbmq.org/login/oauth2/code/

4. In the Advanced Settings section, find all the necessary endpoint URLs required for OAuth 2.0 configuration. Click Save Changes.

Go to the Auth0 Management Console. Open the "Applications" page, and click "+ Create Application" button. Name your application "TBMQ", and choose the application type - "Regular Web Applications". Choose the "Java Spring Boot" technology. Navigate to the "Settings" tab to find the Client ID and Client Secret. Update your allowed Callback URLs. In the "Advanced Settings" section you will find all the required URLs for OAuth 2.0 configuration. Click "Save Changes".

1. Log in to your TBMQ instance. Go to the OAuth 2.0 page in the Security section. On the Domains tab, click the plus icon. Enter your domain name or IP address and click Create new.

   Log in to your TBMQ instance. Go to the "OAuth 2.0" page of the "Security" section. While on the "Domains" tab, click the "plus" icon. Enter your domain name. Click "Create new" in the "OAuth 2.0 clients" section to add a new one.

2. Configure the new OAuth 2.0 client: enter Auth0 as the title, select Custom as the provider, and enter the Client ID and Client Secret from Auth0.

   In Advanced settings → General: fill in all required URLs from Auth0, select POST as the authentication method, enter Auth0 as the provider label, and add scopes: openid, email, profile.

   

3. Go to the Mapper block. Leave the mapper type as BASIC. Configure the role assignment settings. Click Add.

   

4. The Auth0 client has been successfully added. Click Add again to confirm the domain.

   The Auth0 client has been successfully added. Click "Add" again to confirm the addition of the domain. A new domain has been added.

Navigate to the login screen. You will find the Login with Auth0 option. Click it and use your Auth0 credentials to log in.

Navigate to the login screen. You will find Auth0 login method. Click on the "Login with Auth0" button and use your Auth0 credentials to log in. Go to the "Users" page. There you should find the new user that logged in.

This example uses Keycloak for authentication.

Start Keycloak

Make sure you have Docker installed, then run:

docker run -p 8081:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.0.5 start-dev

Run this command to start Keycloak on local port 8081 and create an initial admin user.

Log in to the admin console

Log in to the Keycloak Admin Console using admin as both username and password.

Create a realm

1. Click Keycloak next to the master realm, then click Create realm.
2. Enter ThingsBoard in the realm name field, and click Create.

Click "Keycloak" next to the master realm, then click "Create realm" button. Enter "ThingsBoard" in the realm name field, and click "Create" button. The new realm has been created.

Create a new client

1. Go to the Clients page in the left-hand menu, and click Create client.

2. Enter thingsboard as the client ID. Leave the type as OpenID Connect. Click Next.

3. Enable Client authentication. Confirm that Standard flow is enabled. Click Next.

4. In the Login settings section, add the TBMQ redirect URI to Authorized Redirect URIs:

   http(s)://domain:port/login/oauth2/code/

   For example: https://my.thingsboard.instance/login/oauth2/code/

5. Click Save.

Go to the "Clients" page in the left-hand menu, and click the "Create client" button. Enter "thingsboard" as the client ID. Leave the client type as "OpenID Connect". Click "Next". Turn on "Client authentication" option. Confirm that "Standard flow" is enabled. Click "Next". Add the TBMQ redirect URI to the "Authorized Redirect URIs" section. Then, click "Save". Client created successfully.

The Client ID is on the Settings tab; the Client Secret is on the Credentials tab.

You can find the "Client ID" on the "Settings" tab. The "Client Secret" is located on the "Credentials" tab.

Get endpoint URLs

Go to the Realm settings page, scroll down to locate the OpenID Endpoint Configuration link, and click it. A new window will open with the configuration — check Pretty-print for easier reading. Here you can find the Access Token URI, Authorization URI, JSON Web Key URI, and User Info URI. A description of all available endpoints is provided in the Keycloak OIDC layers documentation.

Go to the "Realm settings" page. Scroll down and locate the link to "OpenID Endpoint Configuration", then click on it. A new window with OpenID Endpoint Configuration will open. Check "Pretty-print" option. Here you find Access token URI, Authorization URI, JSON Web Key URI, and User info URI.

Create a user

Only users added to Keycloak will be able to authenticate via Keycloak.

1. Go to the Users page in the left-hand menu. Click Create new user.
2. Enter the username and email address. Click Create.
3. Navigate to the Credentials tab and click Set password. Fill in the password form. Toggle Temporary to Off. Click Save password.

Go to the "Users" page in the left-hand menu. Click "Create new user". Enter the username and email address in the form. First name and last name are optional. Then, click "Create". The user has been created. Navigate to the "Credentials" tab. Click "Set password". Fill in the "Set password" form with a password. Toggle "Temporary" to "Off". Click "Save". Confirm the set password by clicking "Save password". The password has been set successfully.

1. Log in to your TBMQ instance. Go to the OAuth 2.0 page in the Security section. Navigate to the OAuth 2.0 clients tab, and click the plus icon.

   Enter Keycloak as the title. Select Custom as the provider. Enter the Client ID and Client Secret from Keycloak.

   In Advanced settings → General: fill in the endpoint URLs, set authentication method to POST, enter Keycloak as the provider label, and add scopes: email, openid, profile.

   Log in to your TBMQ instance. Navigate to the "OAuth 2.0" in the "Security" menu section, open "OAuth 2.0 clients" tab, and click "plus" icon. Enter "Keycloak" as the title. Select "Custom" as the provider. Enter the Client ID and Client secret. Fill in all necessary URLs. Set authentication method to POST. Add scopes: "email", "openid", "profile".

2. Go to the Mapper block. Leave the mapper type as BASIC. Configure the role assignment settings. Click Add to confirm.

   Go to the "Mapper" block. Leave the mapper type "BASIC". Configure role assignment settings. Click "Add" to confirm. A new OAuth 2.0 client has been added.

3. Now add a new domain: go to the Domains tab, click the plus icon, enter your domain name or IP address, specify Keycloak as the OAuth 2.0 client, and click Add.

   Navigate to the "Domains" tab, and click "plus" icon. Enter your domain name or IP address. Specify "Keycloak" as the OAuth 2.0 client. Click "Add" to confirm. A new domain has been added.

Go to the TBMQ login screen. You will see the Login with Keycloak option. Click it, enter your Keycloak credentials, and click Sign In.

Go to the TBMQ login screen. You will see an additional option, "Login with Keycloak". Click this button and login using your Keycloak credentials. Go to the "Users" page. There you should find the new user that logged in.

Mapping an external user info object into a TBMQ user can be achieved using the Basic, Custom, GitHub, and Apple mappers.

The basic mapper merges an external OAuth 2.0 user info object into the TBMQ OAuth 2.0 user with a predefined set of rules.

To use the basic mapper, set the mapper type to Basic.

Available properties:

• Allow user creation — If enabled and the user account does not exist in TBMQ, it will be created automatically. If disabled, the user will receive an access denied error if no corresponding TBMQ user exists.
• Email attribute key — The attribute key from the external OAuth 2.0 user info used for the TBMQ user email.
• First name attribute key — The attribute key used for the TBMQ user first name.
• Last name attribute key — The attribute key used for the TBMQ user last name.
• Role assignment settings — Select a fixed role or map roles dynamically from user attributes:
  • Static — This role will be assigned to all users authenticated through this provider.
  • Dynamic — Roles are assigned based on the value of a specific attribute in the user info object.
    • Role attribute key — User info attribute (e.g., roles or groups) for mapping. If both match, Administrator is granted over Viewer.
    • Administrator role values — List of attribute values that will grant the Administrator role.
    • Viewer role values — List of attribute values that will grant the Viewer role.

If the basic mapper does not meet your business needs, you can configure a custom mapper to implement logic that fits your specific goals.

A custom mapper is designed as a separate microservice running alongside the TBMQ microservice. TBMQ forwards all mapping requests to this microservice and expects a TBMQ OAuth 2.0 user object in response.

Refer to the base implementation as a starting point for your custom mapper.

To use the custom mapper, set the mapper type to Custom.

Available properties:

• URL — The URL of the custom mapper endpoint.
• username — If the custom mapper endpoint uses basic authentication, specify the username here.
• password — If the custom mapper endpoint uses basic authentication, specify the password here.

If TBMQ is running behind a load balancer such as HAProxy, configure the balancing algorithm to ensure the correct session is maintained on the TBMQ instance:

backend tbmq-api-backend
  ...
  balance source # balance must be set to 'source'
  ...

Also configure ACL mapping for HTTP and HTTPS requests to include the OAuth 2.0 paths:

frontend http-in
  ...
  acl tbmq_api_acl path_beg /api/ /swagger /webjars /v2/ /oauth2/ /login/oauth2/ # '/oauth2/ /login/oauth2/' added
  ...

frontend https_in
  ...
  acl tbmq_api_acl path_beg /api/ /swagger /webjars /v2/ /oauth2/ /login/oauth2/ # '/oauth2/ /login/oauth2/' added
  ...