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.

Field	Description
Title	Display name for the client, shown as a button label on the login page.
Provider	Predefined provider (Apple, Facebook, GitHub, Google) or Custom for any OpenID Connect-compatible provider. Select Custom if your provider is not listed (for example, Keycloak, Okta, Azure AD, Auth0).
Allowed platforms	Restricts the client to Web UI only, Mobile app only, or All platforms.
Client ID	OAuth client identifier obtained from the identity provider.
Client Secret	OAuth client secret obtained from the identity provider.

Field	Description
Access Token URI	Provider endpoint used to exchange the authorization code for an access token.
Authorization URI	Provider endpoint where the user authenticates and grants access.
JSON Web Key URI	Provider JWKS endpoint supplying public keys for JWT validation.
User Info URI	Provider endpoint for retrieving user profile attributes.
Client Authentication Method	How the client authenticates with the provider: BASIC (recommended), POST, or NONE. If authentication fails during token exchange (e.g. invalid_client error), verify that the selected method matches the identity provider configuration.
Allow User Creation	When enabled, ThingsBoard automatically creates a new account on first login if no matching user exists.
Activate User	When enabled, newly created accounts are activated immediately without requiring email confirmation.
Scope	Space-separated list of OAuth scopes to request. Typical value: email openid profile.

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

Field	Description
Domain Name	The domain users access ThingsBoard from (e.g. my.thingsboard.instance). Must match the actual DNS-configured domain.
Redirect URI Template	Auto-generated callback URL to register with your OAuth provider. Format: http(s)://$DOMAIN:$PORT/login/oauth2/code/.
OAuth 2.0 Clients	Select one or more existing clients to make available for this domain.
Enable OAuth 2.0	Toggles OAuth login availability for the 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.

Field	Description
Email Attribute Key	Provider attribute containing the user’s email address. Default: email.
First Name Attribute Key	Provider attribute for the user’s first name.
Last Name Attribute Key	Provider attribute for the user’s last name.
User Name Attribute Key	Provider attribute used as the username. Most OAuth providers return the email address as the most stable identifier; the recommended value is email.
Tenant Name Strategy	How the tenant is determined for the authenticated user: DOMAIN (derives tenant name from the email domain), EMAIL (uses the full email address), or CUSTOM (uses the pattern defined in Tenant Name Pattern).
Tenant Name Pattern	Custom pattern used when strategy is CUSTOM. Supports %{attribute_key} placeholders. Examples: Demo Tenant (hard-coded), %{email} (full email), %{givenName} (first name).
Customer Name Pattern	If set, the user is created under a customer matching this pattern. Supports %{attribute_key} placeholders. Examples: Demo Customer (hard-coded), %{email} (full email), %{city} (city from profile).
Default Dashboard	Dashboard opened automatically after login.
Always Full Screen	Opens the default dashboard in full-screen mode.
User Groups Name Pattern	Comma-separated list of user group name patterns. The user is added to matching groups on each login. Supports %{attribute_key} placeholders. PE / Cloud only
Parent Customer Name Pattern	Pattern for an optional parent customer. Creates a customer hierarchy automatically. PE / Cloud only

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 your ThingsBoard login page. A Login with Google button should appear. Click it to authenticate with your Google account.

---

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.

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

---

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 your ThingsBoard login page. A Login with Keycloak button should appear. Click it and authenticate with 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.

---