How to Enable OAuth2 Login in ThingsBoard 4.0.1 Community Edition Using Keycloak and HAProxy

ThingsBoard is a powerful open-source IoT platform supporting device management, telemetry, dashboards, and multi-tenancy. In this guide, I’ll show you how to enable OAuth2 login using Keycloak in ThingsBoard 4.0.1 Community Edition (CE), with HAProxy managing SSL termination and routing for multiple domains.

Login Architecture

We’ll have two domains:

Domain	Purpose	Login Options
`thingsboard.maksonlee.com`	Primary server domain for internal access	Local login only
`iot.maksonlee.com`	Customer-facing portal for end users	Local + OAuth2 login visible

Prerequisites

ThingsBoard 4.0.1 Community Edition installed (running on port 8080)
HAProxy installed and running on port 443
Keycloak available at https://keycloak.maksonlee.com
TLS certificates for:
- thingsboard.maksonlee.com
- iot.maksonlee.com

Configure HAProxy with SSL and SNI

HAProxy terminates SSL and routes traffic based on domain via SNI.

Place your certs

/etc/haproxy/certs/
├── thingsboard.maksonlee.com.pem
├── iot.maksonlee.com.pem

Each .pem must include both private key and full certificate chain.

HAProxy Configuration

frontend https-in
    bind *:443 ssl crt /etc/haproxy/certs/ alpn h2,http/1.1
    mode http
    option forwardfor
    http-request set-header X-Forwarded-Proto https

    acl host_tb hdr(host) -i thingsboard.maksonlee.com
    acl host_iot hdr(host) -i iot.maksonlee.com

    use_backend tb-backend if host_tb
    use_backend tb-backend if host_iot

backend tb-backend
    mode http
    server tb1 127.0.0.1:8080

This HAProxy setup:

Terminates TLS
Uses the correct cert for each domain
Routes all requests to ThingsBoard on localhost

Configure Keycloak

Create a new client in your Keycloak realm.

Setting	Value
Client ID	`iot`
Root URL	`https://iot.maksonlee.com`
Valid Redirect URIs	`https://iot.maksonlee.com/login/oauth2/code/`
Post Logout Redirect URIs	`https://iot.maksonlee.com`
Web Origins	`https://iot.maksonlee.com`
Access Type	confidential
Standard Flow	Enabled
Direct Access Grants	Enabled
Consent Required	Disabled

Copy the Client Secret from the Credentials tab after saving.

Configure OAuth2 in ThingsBoard

Add OAuth2 Client
Navigate to: Security → OAuth 2.0 → OAuth 2.0 clients → Add OAuth 2.0 client

Field	Value
Client ID	`iot`
Client Secret	(from Keycloak)
Provider	`Custom`
Authorization URI	`https://keycloak.maksonlee.com/realms/maksonlee.com/protocol/openid-connect/auth`
Access Token URI	`https://keycloak.maksonlee.com/realms/maksonlee.com/protocol/openid-connect/token`
User Info URI	`https://keycloak.maksonlee.com/realms/maksonlee.com/protocol/openid-connect/userinfo`
JWKS URI	`https://keycloak.maksonlee.com/realms/maksonlee.com/protocol/openid-connect/certs`
Scope	`openid profile email`
Allow user creation	Enabled
Provider label	`Keycloak`

Mapper:

Field	Value
Mapper type	BASIC
Username attribute key	`email`
Email attribute key	`email`
Tenant name strategy	CUSTOM
Tenant name pattern	`Tenant`
Customer name pattern	`Customer %{email}`

Add OAuth2 Domain
Navigate to: Security → OAuth 2.0 → Domains → Add domain

Field	Value
Domain name	`iot.maksonlee.com`
Redirect URI template	`https://iot.maksonlee.com/login/oauth2/code/`
Enable OAuth 2.0 settings	Enabled
OAuth2 Client	`Keycloak Login` (select the one you just created)

Test the Login Behavior

https://iot.maksonlee.com
- Login page shows both local login and OAuth2 login (CE default)
- Clicking Keycloak logs the user in via OAuth
- User is automatically provisioned in ThingsBoard under a tenant/customer
https://thingsboard.maksonlee.com
- No OAuth2 configured
- Only local login is shown (e.g. for sysadmin@thingsboard.com)

Leave a Comment Cancel Reply