OAuth 2.0

ThingsBoard supports OAuth 2.0 authentication for Single Sign-On (SSO), allowing users to log in using external identity providers such as Google, Auth0, Keycloak, and others. Administrators can configure multiple providers per domain and control how external accounts are mapped to ThingsBoard tenants, customers, and user groups.

ThingsBoard uses the Authorization Code grant type. The flow works as follows:

1. The user selects an external provider on the ThingsBoard login page.
2. The browser redirects to the provider’s authentication page.
3. After successful authentication, the provider redirects back to ThingsBoard with an authorization code.
4. ThingsBoard exchanges the code for an access token.
5. The access token is used to retrieve user information from the provider.
6. The user information is mapped to a ThingsBoard account via a configured mapper.
7. Standard ThingsBoard authorization applies and the user is logged in.

Two components are required to enable OAuth 2.0 login: an OAuth 2.0 client that stores provider credentials and mapping rules, and a domain that ties one or more clients to a specific ThingsBoard URL.

Navigate to Security → OAuth 2.0 → Clients and click + to create a new client.

Navigate to Security → OAuth 2.0 → Domains and click + to add a domain.

Each OAuth 2.0 client includes a mapper that defines how provider user attributes are translated into ThingsBoard account properties. Two mapper types are available.

The Basic mapper handles standard OpenID Connect providers that return email, given_name, and family_name attributes.

The Custom mapper delegates all mapping logic to an external HTTP service. ThingsBoard sends user attribute data to the configured endpoint, and the service returns the ThingsBoard account details. Use this type when you need complex logic such as role mapping based on IdP groups, custom tenant or customer creation rules, or attribute validation.

This example creates a ThingsBoard tenant user from a Google account. Each user is placed under a tenant whose name matches the user’s email address.

1. Open the Google Cloud Console and create or select a project.

2. Navigate to APIs & Services → Credentials and click Create credentials → OAuth client ID.

   

3. Select Web application as the application type, enter a name, and add your ThingsBoard redirect URI under Authorized redirect URIs:

   http(s)://$DOMAIN:$PORT/login/oauth2/code/

   

4. Click Create. Copy the generated Client ID and Client Secret.

   

1. In ThingsBoard, navigate to Security → OAuth 2.0 → Domains and click + to add a domain. Enter your domain name.

2. In the OAuth 2.0 Clients section of the domain form, click + to create a new client. Set:

   • Title: Google
   • Provider: Google
   • Client ID and Client Secret: paste the values from Google Console.

3. Open Advanced Settings → General and configure:

   • Client Authentication Method: POST
   • Allow User Creation: enabled
   • Activate User: enabled
   • Scope: email openid profile

4. Open the Mapper tab and configure:

   • Mapper Type: BASIC
   • Tenant Name Strategy: CUSTOM
   • Tenant Name Pattern: %{email}

5. Save the client, then save the domain.

Navigate to Security → OAuth 2.0 → Domains and click + to add a domain. Enter your domain name and open the OAuth 2.0 Clients section. Set the title to Google, select Google as the provider, and paste the Client ID and Secret. In Advanced Settings → General, set the authentication method to POST and configure scopes. In the Mapper tab, set strategy to CUSTOM and enter %{email} as the Tenant Name Pattern. Optionally set User Groups Name Pattern. The Google OAuth client is added to the domain. The domain is saved with the Google OAuth client attached.

Navigate to your ThingsBoard login page. A Login with Google button should appear. Click it to authenticate with your Google account.

The Login with Google button appears on the ThingsBoard login page. Select the Google account to authenticate with. After successful authentication, the user is logged in as a tenant administrator. The authenticated user is visible in the Tenant Administrators user group.

This example creates a ThingsBoard customer user from an Auth0 account. The tenant is determined from the email domain, and the user is placed under a customer whose name matches the full email address.

1. Log in to the Auth0 Management Console and navigate to Applications → Applications. Click Create Application.

   

2. Select Regular Web Applications as the application type.

   

3. Choose a technology (e.g. Java Spring Boot) and proceed.

   

4. Open the application Settings tab. Copy the Client ID and Client Secret.

   

5. Scroll to Allowed Callback URLs and add your ThingsBoard redirect URI:

   http(s)://$DOMAIN:$PORT/login/oauth2/code/

   

6. Open Advanced Settings → Endpoints to find the OpenID Connect endpoint URLs you will need for ThingsBoard configuration.

   

1. In ThingsBoard, open the domain created in the Google example (or create a new one). In the OAuth 2.0 Clients section, click + to add a new client. Set:

   • Title: Auth0
   • Provider: Custom
   • Client ID and Client Secret: paste the values from Auth0.
   • Fill in Access Token URI, Authorization URI, JSON Web Key URI, and User Info URI from Auth0 endpoint settings.
   • Client Authentication Method: POST
   • Scope: openid email profile

2. Open the Mapper tab and configure:

   • Mapper Type: BASIC
   • Tenant Name Strategy: DOMAIN
   • Customer Name Pattern: %{email}

3. Save the client, then save the domain.

Configure the Auth0 client with title, Custom provider, credentials, and endpoint URLs. Set Mapper Type to BASIC, Tenant Name Strategy to DOMAIN, and Customer Name Pattern to %{email}. The Auth0 OAuth client is added to the domain. The domain now has both Google and Auth0 clients available.

Navigate to your ThingsBoard login page. Both Login with Google and Login with Auth0 buttons should now appear.

Both providers appear on the login page. After successful Auth0 authentication, the user is logged into ThingsBoard as a customer user. The Auth0-authenticated user is visible in the Customer Users group.

This example uses a self-hosted Keycloak instance as an identity provider.

1. Start Keycloak using Docker:

   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 the Docker command to start a Keycloak instance in development mode. Keycloak initialises and starts listening on port 8080.

1. Open http://localhost:8081/admin and log in with admin / admin.

   Navigate to the Keycloak admin console and log in. Keycloak admin console home screen.

1. In the top-left dropdown, click Create realm.

   

2. Enter ThingsBoard as the realm name and click Create.

   Enter ThingsBoard as the realm name. The ThingsBoard realm is created and selected.

1. Navigate to Clients and click Create client.

   

2. Set Client type to OpenID Connect and enter thingsboard as the Client ID. Click Next.

   

3. Enable Client authentication and ensure Standard flow is checked. Click Next.

   

4. Under Login settings, add your ThingsBoard redirect URI to Valid redirect URIs:

   http(s)://$DOMAIN:$PORT/login/oauth2/code/

   Click Save.

   Add the ThingsBoard redirect URI to Valid redirect URIs. The thingsboard client is created successfully.

1. Open the client’s Settings tab and copy the Client ID.

   

2. Open the Credentials tab and copy the Client Secret.

   

1. Navigate to Realm settings and click the OpenID Endpoint Configuration link.

   

2. Enable the Pretty-print toggle for better readability, then note the values for token_endpoint, authorization_endpoint, jwks_uri, and userinfo_endpoint.

   

1. Navigate to Users and click Create new user.

   

2. Enter a Username and Email for the test user. Click Create.

   Enter the username and email for the test user. The test user is created and listed in the Users table.

3. Open the user’s Credentials tab and click Set password.

   

4. Enter a password, disable the Temporary toggle, and click Save → Save password.

   Enter a password and disable Temporary so the user is not prompted to change it on first login. Confirm the password save in the confirmation dialog. The password is set and the user is ready for login.

1. In ThingsBoard, navigate to Security → OAuth 2.0 → Clients and click + to create a new client. Set:

   • Title: Keycloak
   • Provider: Custom
   • Client ID and Client Secret: paste the values from Keycloak.
   • Fill in the endpoint URLs from the OpenID endpoint configuration JSON.
   • Client Authentication Method: POST
   • Scope: openid email profile

2. Open the Mapper tab and configure:

   • Mapper Type: BASIC
   • Tenant Name Strategy: CUSTOM
   • Tenant Name Pattern: %{email}

3. Navigate to Security → OAuth 2.0 → Domains, open your domain, and add the Keycloak client. Save the domain.

Navigate to Security → OAuth 2.0 → Clients and click + to create the Keycloak client. Enter the Keycloak Client ID, Secret, and all endpoint URLs. Configure the mapper settings for the Keycloak client. The Keycloak client is saved successfully. Open the domain and add the Keycloak client. The domain is updated with the Keycloak client.

Navigate to your ThingsBoard login page. A Login with Keycloak button should appear. Click it and authenticate with the test user credentials.

The Login with Keycloak button appears on the ThingsBoard login page. The Keycloak login page. Enter the test user credentials.

This example configures ThingsBoard to authenticate users via their Okta account. After authentication, the user is logged in as a Tenant Administrator. The tenant name equals the user’s email address, and is automatically created if it does not already exist.

1. Open the Okta Developer Console and navigate to Applications → Applications. Click + Create Application.

2. Enter an application name (e.g. ThingsBoard) and choose the Regular Web Application type. Click Create.

3. In the Application Login URIs settings, add the ThingsBoard redirect URI:

   http(s)://$DOMAIN:$PORT/login/oauth2/code/

   Click Save.

4. Copy the generated Client ID and Client Secret from the application page. Note your Okta domain (e.g. https://example.okta.com).

1. In ThingsBoard, navigate to Security → OAuth 2.0 → Clients and click + to create a new client. Set:

   • Title: Okta
   • Provider: Custom
   • Client ID and Client Secret: paste the values from Okta.

2. Open Advanced Settings → General and configure:

   • Access Token URI: https://<your-okta-domain>/oauth2/v1/token
   • Authorization URI: https://<your-okta-domain>/oauth2/v1/authorize
   • User Info URI: https://<your-okta-domain>/oauth2/v1/userinfo
   • JSON Web Key URI: https://<your-okta-domain>/oauth2/v1/keys
   • Client Authentication Method: BASIC
   • Allow User Creation: enabled
   • Scope: email openid profile

3. Open the Mapper tab and configure:

   • Mapper Type: BASIC
   • Tenant Name Strategy: CUSTOM
   • Tenant Name Pattern: %{email}

4. Click Add to save the client.

1. Navigate to Security → OAuth 2.0 → Domains and click + to add a domain (or open an existing one).

2. Enter your domain name and select Okta in the OAuth 2.0 Clients section.

3. Click Add.

Navigate to your ThingsBoard login page. A Login with Okta button should appear. Click it and authenticate with your Okta credentials to log in as a Tenant Administrator.

This example configures ThingsBoard to authenticate users via Microsoft Azure Active Directory (Microsoft Entra ID). After authentication, the user is logged in as a Tenant Administrator. The tenant name equals the user’s email address and is automatically created if it does not already exist.

1. Open the Azure Portal. On the home page, click View under Manage Azure Active Directory.

   

2. Navigate to App registrations in the left sidebar, then click + New registration.

   

3. Configure the application:

   • Name: ThingsBoard (or any descriptive name)
   • Redirect URI: select platform Web and enter:

   http(s)://$DOMAIN:$PORT/login/oauth2/code/

   Click Register.

   

4. On the application Overview page, copy the Application (client) ID and the Directory (tenant) ID — you will need both when configuring ThingsBoard.

   

5. Open the Authentication tab. Under Implicit grant, enable the Access tokens checkbox and click Save.

   

6. Open the Certificates & secrets tab. Click + New client secret, enter a description and expiration period, and click Add. Copy the generated Value — this is your Client Secret.

   

7. Go back to the Overview tab and click Endpoints. Follow the OpenID Connect metadata document link to find the up-to-date authorization, token, and JWKS endpoint URLs for your directory.

   

1. In ThingsBoard, navigate to Security → OAuth 2.0 → Clients and click + to create a new client. Set:

   • Title: Azure Active Directory
   • Provider: Custom
   • Client ID: the Application (client) ID from Azure.
   • Client Secret: the secret value from Azure.

2. Open Advanced Settings → General and configure (replace <directory-id> with your Azure Directory/Tenant ID):

   • Authorization URI: https://login.microsoftonline.com/<directory-id>/oauth2/v2.0/authorize
   • Access Token URI: https://login.microsoftonline.com/<directory-id>/oauth2/v2.0/token
   • JSON Web Key URI: https://login.microsoftonline.com/common/discovery/v2.0/keys
   • User Info URI: https://graph.microsoft.com/oidc/userinfo
   • Client Authentication Method: POST
   • Allow User Creation: enabled
   • Activate User: enabled
   • Scope: email openid profile

3. Open the Mapper tab and configure:

   • Mapper Type: BASIC
   • User Name Attribute Key: email
   • Tenant Name Strategy: CUSTOM
   • Tenant Name Pattern: %{email}

4. Click Add to save the client.

1. Navigate to Security → OAuth 2.0 → Domains and click + to add a domain (or open an existing one).

2. Enter your domain name and select Azure Active Directory in the OAuth 2.0 Clients section.

3. Click Add.

Navigate to your ThingsBoard login page. A Login with Azure Active Directory button should appear. Click it and authenticate with your Azure AD credentials to log in as a Tenant Administrator.

After creating OAuth 2.0 clients, you can manage them from Security → OAuth 2.0 → Clients. The clients table lists all configured clients with their title, provider, and enabled state.

To edit a client, click the pencil icon in its row to open the client form. Make your changes and click Save.

To delete a client, click the trash icon in its row and confirm the deletion. Deleting a client removes it from all domains it was assigned to.

Domains are managed from Security → OAuth 2.0 → Domains. The domains table lists all registered domains with their name and assigned clients.

To edit a domain, click the pencil icon in its row. You can update the domain name, add or remove OAuth 2.0 clients, and toggle the Enable OAuth 2.0 switch.

To delete a domain, click the trash icon in its row and confirm the deletion. Deleting a domain removes the OAuth 2.0 login option for users accessing ThingsBoard from that domain.

If you use HaProxy as a reverse proxy in front of ThingsBoard, configure it to forward the original protocol and host information so that the redirect URI generated by ThingsBoard matches what your OAuth provider expects.

Add the following configuration to your HaProxy frontend and backend sections:

frontend http-in
  bind *:80
  bind *:443 ssl crt /etc/haproxy/ssl/server.pem
  option forwardfor
  http-request set-header X-Forwarded-Proto https if { ssl_fc }
  http-request set-header X-Forwarded-Proto http if !{ ssl_fc }
  default_backend tb-backend

backend tb-backend
  option forwardfor
  http-request set-header X-Forwarded-Port %[dst_port]
  server tb1 127.0.0.1:8080 check

Ensure ThingsBoard is configured to use the forwarded headers by setting the following in thingsboard.yml:

server:
  forward_headers_strategy: NATIVE

This allows ThingsBoard to construct the correct redirect URI (https://yourdomain/login/oauth2/code/) from the forwarded headers rather than the internal HTTP address.