ThingsBoard支持基于OAuth 2.0的认证，为客户提供单点登录(SSO)，并与外部身份提供商集成。
使用OAuth 2.0，您可以让用户使用外部平台的现有账号登录，并自动创建tenant、customer或sub-customer。
ThingsBoard兼容大多数OAuth 2.0提供商，包括Google、Facebook、Github、Auth0、Keycloak、Okta、Azure等。
OAuth 2.0认证流程
ThingsBoard支持OAuth 2.0的Authorization Code授权类型。认证流程如下：
- 用户打开ThingsBoard登录页面并选择外部提供商（例如Google或Keycloak）。
- 用户被重定向到提供商的登录页面进行身份认证。
- 登录成功后，提供商使用配置的重定向URI将用户重定向回ThingsBoard。
- ThingsBoard从重定向URL中提取授权码，并将其兑换为访问令牌。
- ThingsBoard获取外部用户信息，并使用配置的映射器（Basic 或Custom）。
- 映射步骤完成后，应用标准ThingsBoard授权流程。
该流程使ThingsBoard能够根据身份提供商属性自动确定正确的tenant、customer和用户权限。
通过外部提供商配置认证
要启用通过外部提供商的OAuth 2.0认证，您必须配置两个组件：
- OAuth 2.0客户端 – 存储提供商凭证、端点、scope和映射规则。
- 域配置 – 定义特定ThingsBoard域可用的OAuth客户端。
一般配置流程包括：
- 在外部提供商创建OAuth 2.0客户端并获取 Client ID 和 Client Secret。
- 在ThingsBoard中添加对应的OAuth 2.0客户端，并配置所有必需的端点、scope和mapper设置。
- 在ThingsBoard中将OAuth 2.0客户端分配给域。
- 使用ThingsBoard登录页面上的新 使用 …登录 选项验证登录流程。
添加OAuth 2.0客户端
ThingsBoard允许您配置OAuth 2.0客户端，用于通过Google、GitHub、Apple、Facebook、Keycloak、Auth0、Okta、Azure AD等外部身份提供商对用户进行认证。
OAuth 2.0客户端存储认证所需的全部信息，包括：
- 客户端凭证（Client ID / Client Secret）
- OAuth端点（Authorization、Token、UserInfo、JWKS）
- 必需的scope
- 用户映射规则（mapper配置）
OAuth 2.0客户端创建后，可分配给一个或多个域。
添加新的OAuth 2.0客户端：
- 登录ThingsBoard。
- 导航至 Security ⇾ OAuth 2.0。
- 打开 OAuth 2.0客户端 选项卡。
- 点击 +（加号）图标。
步骤1: 配置常规客户端信息
在对话框的上部分，配置基本参数：
- Title 输入OAuth 2.0客户端的描述性名称（例如：Google、Auth0、Keycloak、GitHub）。此字段是必填的。
- Provider
从下拉列表中选择认证提供商。支持的提供商包括：Apple、Custom、Facebook、GitHub、Google。
提供商选择定义了默认端点模板和映射行为。
提示：如果你的提供商不在列表中（例如Keycloak、Okta、Azure AD、Auth0等），选择Custom。
- Allowed platforms 选择哪些ThingsBoard平台可以使用此OAuth客户端。例如：仅Web UI、仅移动应用或所有平台（默认）。 此选项用于限制特定客户端的认证方法。
- Client ID和Client secret
输入从身份提供商获取的OAuth 2.0凭证：
- Client ID（必填）
- Client secret（必填）
第2步：配置高级设置（常规）
展开高级设置部分并打开常规选项卡。此部分定义了身份验证期间使用的OAuth 2.0端点。
- 访问令牌URI
定义ThingsBoard用于将授权码交换为访问令牌的提供商端点。示例 (Google)：https://oauth2.googleapis.com/token - 授权URI
定义用户被重定向进行身份验证的端点。示例 (Google)：https://accounts.google.com/o/oauth2/v2/auth - JSON Web Key URI
定义JWKS端点，该端点提供验证JWT令牌所需的公钥。示例 (Google)：https://www.googleapis.com/oauth2/v3/certs - 用户信息URI
定义ThingsBoard用于请求用户详细信息的端点。示例 (Google)：https://openidconnect.googleapis.com/v1/userinfo - 客户端认证方法
定义ThingsBoard在从OAuth 2.0提供商请求访问令牌时如何发送客户端凭证（客户端ID 和客户端密钥）（在授权代码交换为访问令牌期间）。
此参数必须与身份提供商支持（或要求）的方法匹配。
根据UI，以下认证方法可用：- 无。ThingsBoard在请求访问令牌时不发送客户端凭证。
此选项很少使用，仅适用于不需要客户端认证的提供商（通常是公共客户端）。 - 基本（对大多数提供商推荐）。ThingsBoard使用HTTP基本认证标头发送客户端凭证：Authorization: Basic <base64(client_id:client_secret)>
这是最常见且广泛支持的选项（例如，Google、Keycloak、Auth0、Okta）。 - POST。ThingsBoard在POST请求体中与令牌请求参数一起发送客户端凭证。
某些OAuth提供商可能需要此方法，具体取决于其配置。提示：如果令牌交换期间认证失败（例如，由于
invalid_client），请验证所选的客户端认证方法是否与身份提供商配置匹配。
- 无。ThingsBoard在请求访问令牌时不发送客户端凭证。
- 允许用户创建
如果启用，ThingsBoard将在首次登录时自动创建新用户账户（如果用户不存在）。
此选项用于完全自动化的SSO上线流程。 - 启用用户
如果启用，ThingsBoard将自动激活创建的用户账户。
如果禁用，用户将被创建但保持不激活状态，直到管理员手动激活。 - 作用域（Scope）
作用域定义ThingsBoard从身份提供商请求的信息。示例：email openid profile。
作用域直接影响哪些属性可用于用户映射（电子邮件、名称等）。
步骤3.配置高级设置（映射器）
切换到”映射器”选项卡。此部分定义ThingsBoard如何将外部用户信息对象转换为内部ThingsBoard用户，并决定：
- 租户名称
- 客户名称
- 用户权限（Tenant Admin / Customer User）
- 可选用户组（仅PE）
- 默认仪表盘导航设置
ThingsBoard支持不同的映射器类型：基本、自定义、GitHub、Apple
映射器配置是OAuth设置的关键部分，因为它控制自动租户/客户供应逻辑。 有关将外部用户信息映射到ThingsBoard用户的更多详细信息，请参见此处。
步骤4.保存OAuth 2.0客户端
填写所有必填字段后，点击添加以创建OAuth 2.0客户端。
创建后，OAuth客户端就可用于域分配了。
将OAuth 2.0客户端分配给域
创建OAuth 2.0客户端后，您必须将其分配给域。 此步骤定义用户通过特定域访问ThingsBoard时，登录页面上将显示哪些认证提供商。
在ThingsBoard中，域配置充当路由层：当用户打开登录页面时，ThingsBoard确定该域并显示分配给该域的OAuth 2.0登录选项。
打开域配置
要将OAuth 2.0客户端分配给域：
- 登录您的ThingsBoard实例。
- 导航至安全性 ⇾ OAuth 2.0。
- 在域选项卡上，点击+（加号）图标。
这将打开添加域对话框窗口。
步骤1.配置域名
在域名字段中，输入用户将用来访问ThingsBoard的域。示例：my.thingsboard.instance。
此值必须与DNS中配置的和浏览器中使用的实际域相匹配。
步骤2.验证重定向URI模板
ThingsBoard自动根据输入的域生成重定向URI模板。例如：https://my.thingsboard.instance/login/oauth2/code/
此重定向URI必须添加到您的OAuth提供商配置（Google、Auth0、Keycloak等）中作为允许的回调/重定向URL。
要快速复制，请单击字段右侧的复制图标。
步骤3.分配OAuth 2.0客户端
OAuth 2.0客户端部分中，选择应为此域提供OAuth客户端。
有两个可用选项：
- 选项A.选择现有OAuth 2.0客户端
- 在OAuth 2.0客户端字段中点击。
- 从下拉列表中选择现有客户端。
选择后，它将以标签形式出现在字段中。
您可以为同一域分配多个OAuth客户端（例如，Google + Auth0 + Keycloak）。
- 选项B.创建新OAuth 2.0客户端
- 如果所需OAuth客户端不存在，点击创建新。
此步骤将打开添加OAuth 2.0客户端对话框，允许您创建新的OAuth客户端，无需离开当前域设置页面。
可选设置
- 启用OAuth 2.0。
如果此选项被禁用，即使分配了OAuth客户端，域内OAuth登录也不可用。 - 同步到Edge。
如果您使用ThingsBoard Edge且希望OAuth设置应用于Edge侧，请启用同步到Edge开关。
此配置会将OAuth域配置同步到已连接的Edge实例。
步骤4.保存域
点击添加以创建域配置。
结果
域成功创建且OAuth 2.0设置已启用后：
- ThingsBoard将在登录页面上显示分配的OAuth提供商。
- 通过此域访问ThingsBoard的用户将能使用配置的OAuth 2.0客户端进行认证。
- 用户配置和角色映射将遵循在分配OAuth客户端中配置的映射器设置。
映射器部分定义ThingsBoard如何将外部身份提供商的用户信息转换为ThingsBoard用户。
用户成功与OAuth 2.0提供商认证后，ThingsBoard会接收外部用户信息对象（或ID令牌声明）。 映射器负责提取所需属性（电子邮件、名字、姓氏），并配置用户参数与角色分配。
使用映射器设置，ThingsBoard可以自动：
- 创建用户账户。
- 为其分配租户和/或客户。
- 在租户/客户不存在时自动创建。
- 将用户加入指定用户组并设置权限。
映射器配置位于创建或编辑OAuth 2.0客户端时的高级设置→映射选项卡中。
映射器参数
- 用户名属性键
大多数OAuth提供商会返回电子邮件地址作为最稳定的标识，因此推荐值为：email - 映射器类型
ThingsBoard支持多种映射器类型，可用选项取决于所选提供商和ThingsBoard版本。支持的类型包括：BASIC、CUSTOM、GITHUB、APPLE。
每种映射器定义了将外部身份数据映射到ThingsBoard实体的不同方式。
基本映射器
为标准OpenID Connect提供商设计，这些提供商返回典型的用户属性，如电子邮件/名字/姓氏。
此映射器支持使用可配置策略和模式的自动租户/客户供应。
您可以配置什么
基本映射器为您提供了一套可预测的控件：
- 电子邮件属性密钥。此字段是必需的，因为电子邮件通常用作ThingsBoard中的唯一标识符。默认值：email
- 名字/姓氏属性密钥 - 告诉ThingsBoard使用哪些外部字段。
- 租户名称策略。租户名称策略定义ThingsBoard如何为经过身份验证的用户确定租户名称。可用策略：
- 域 - 租户名称源自电子邮件域。这是SaaS环境的最佳选择，其中每个公司都使用自己的电子邮件域。
示例：如果用户电子邮件是： john.doe@company.com ⇾ 那么租户名称将是： company.com - 电子邮件 - 租户名称等于完整的电子邮件地址。此策略通常用于测试或每个用户应该有隔离租户的情况。
示例： john.doe@company.com - 自定义 - 租户名称使用自定义模式生成。这是最灵活的策略，建议您在想要从用户属性构建租户名称时使用。
示例： %{email}
- 域 - 租户名称源自电子邮件域。这是SaaS环境的最佳选择，其中每个公司都使用自己的电子邮件域。
-
租户名称模式。如果租户名称策略是自定义，您可以使用自定义模式指定将在其中创建用户的租户的名称。 您可以使用外部用户信息对象中的属性将它们放入租户的名称中。请使用 %{attribute_key} 作为属性值的占位符。
租户模式示例：
- Demo Tenant # 固定租户名称;
- Demo Tenant %{email} # 若用户邮箱为”test@demo.com”，租户名称将为”Demo Tenant test@demo.com”;
- %{givenName} # 若用户givenName为”Demo User”，租户名称将为”Demo User”。
-
客户名称模式用于定义新用户应分配的客户名称。
可使用外部用户信息对象中的属性拼接客户名称，请使用%{attribute_key}作为属性值占位符。客户名称模式示例：
- Demo Customer # 固定客户名称;
- Demo Customer %{email} # 若用户”email”为”test@demo.com”，客户名称将为”Demo Customer test@demo.com”;
- %{city} # 若用户”city”为”New York”，客户名称将为”New York”。
-
默认仪表板名称用于指定登录后打开的仪表板。
若该仪表板存在且对用户可见，将自动打开。 -
始终全屏。当该选项启用且默认仪表板名称不为空时，用户将以全屏模式打开指定仪表板。
-
父客户名称模式允许在创建客户时自动将其挂到父客户（子客户层级）下。这在OAuth开通过程中自动构建多级客户结构时非常有用。
父客户名称模式示例：
- Demo Parent Customer # 固定的父客户名称;
- Demo Parent Customer %{email} # 如果用户的 “email” 属性为 “test@demo.com”，父客户名称将为 “Demo Parent Customer test@demo.com”;
- %{country} # 如果用户的 “country” 属性为 “Top Customer”，父客户名称将为 “Parent Customer”。
-
用户组名称模式允许ThingsBoard自动将创建的用户添加到一个或多个用户组。默认情况下，新创建用户只会被分配到 All 用户组。
你可以使用外部用户信息对象中的属性来构建用户组名称，请使用 %{attribute_key} 作为属性值占位符。 如果用户组不存在，将自动创建。用户组名称模式示例：
- Tenant Administrators, Customer Users, Managers.. # 固定用户组
- %{job_title} # 如果用户的 “job_title” 属性为 “Manager”，用户将被分配到 “Manager” 用户组
自定义映射器
自定义映射器用于基本映射器不够且需要更复杂开通逻辑的场景。
使用自定义映射器时，ThingsBoard将映射逻辑委托给外部服务。
它允许你实现：
- 基于IdP群组/角色的角色映射；
- 复杂的租户/客户创建规则；
- 与外部CRM/ERP系统集成；
- 允许列表、校验或许可证检查。
工作原理
- ThingsBoard从提供商接收外部用户信息对象。
- ThingsBoard将该对象发送到你的自定义映射端点。
- 你的服务返回ThingsBoard兼容的用户映射响应。
- ThingsBoard根据响应创建或更新用户。
自定义映射器适合对用户开通要求严格的企业部署。
示例
使用Google登录
此示例演示如何使用Google OpenID Connect 配置OAuth 2.0认证。
配置完成后：
- 用户可以使用Google账号登录；
- ThingsBoard会在租户不存在时自动创建；
- 租户名称从用户的电子邮件地址派生；
- 用户以租户管理员身份登录。
用户映射默认使用内置Basic mapper，如果需要更复杂的开通逻辑，可使用Custom mapper。
第1步：在Google API控制台中创建项目
要使用Google OAuth 2.0认证，请在Google API控制台 中创建项目并生成OAuth 2.0凭证。
按照OpenID Connect文档页面 上的官方指引操作，或按照下文步骤执行：
- 导航到凭证。
- 点击创建凭证 → OAuth客户端ID。
- 指定客户端名称（例如ThingsBoard）。
- 将ThingsBoard重定向URI添加到授权重定向URI字段：
1
http(s)://$DOMAIN:$PORT/login/oauth2/code/
其中：
• $DOMAIN 为ThingsBoard主机名（或IP地址）
• $PORT 为ThingsBoard实例的HTTP/HTTPS端口
示例：
1
https://my.thingsboard.instance/login/oauth2/code/
- 点击创建。
Google将生成OAuth 2.0凭证。复制并保存以下值：
- Client ID
- Client Secret
下一步需要用到这些值。
第2步：在ThingsBoard中添加OAuth 2.0客户端
现在在ThingsBoard中配置Google的OAuth 2.0认证：
- 登录ThingsBoard实例。
- 导航至 Security ⇾ OAuth 2.0。
- 在 Domains 选项卡中点击 +（加号）图标。
- 输入域名（或IP地址）。
- 在 OAuth 2.0 clients 区域点击Create new。
在OAuth 2.0客户端配置窗口中：
- 将标题设置为 Google。
- 提供商选择 Google。
- 如有需要设置允许的平台（或保持全选）。
- 填写从Google Console 获取的 Client ID 和 Client Secret。
展开高级设置并配置以下参数：
- 使用官方发现端点列表：Google Discovery。
- 将客户端认证方法设置为 POST。
- 启用允许用户创建。
- 作用域设置为：email openid profile。
切换到映射器部分并配置：
- 映射器类型：BASIC。
- 租户名称策略：CUSTOM。
-
租户名称模式：%{email}（这些属性的更多说明见下文“Basic mapper”部分）。
- 点击Add创建OAuth 2.0客户端。
- 再次点击Add确认域创建。
验证登录
现在打开ThingsBoard登录页面。你会看到使用Google登录按钮，点击并选择你的Google账号。
成功认证后，您将以租户管理员身份登录ThingsBoard。
使用Auth0登录
此示例演示如何使用Auth0 配置OAuth 2.0认证。
配置完成后：
- 用户可以使用Auth0凭证登录；
- ThingsBoard根据用户邮箱域创建或选择租户；
- 对于每个用户，ThingsBoard还会创建一个名称与用户邮箱地址相同的客户；
- 用户以客户用户身份登录。
用户映射默认使用内置Basic mapper，如需更高级的租户/客户开通规则，可使用Custom mapper。
第1步：在Auth0管理控制台创建应用
在配置ThingsBoard之前，需要创建Auth0 应用并获取 Client ID 和 Client Secret。
操作步骤：
- 打开Auth0管理控制台。
- 进入 Applications 并点击 Create Application。
- 应用名称填写 ThingsBoard。
- 选择 Regular Web Application。
- 技术类型选择 Java Spring Boot。
- 打开创建的应用并进入 Settings 选项卡。
- 复制以下值：
- Client ID
- Client Secret。
在允许的回调URL字段中，添加ThingsBoard重定向URI:
1
http(s)://$DOMAIN:$PORT/login/oauth2/code/
其中：
• $DOMAIN 为ThingsBoard主机名（或IP地址）
• $PORT 为ThingsBoard实例的HTTP/HTTPS端口
示例：
1
https://my.thingsboard.instance/login/oauth2/code/
注意：无需配置Application Login URI。
- 在 Advanced Settings 区域可以找到OAuth配置所需端点。
- 点击 Save Changes。
第2步：在ThingsBoard中添加OAuth 2.0客户端
在ThingsBoard中配置Auth0的OAuth 2.0认证：
- 登录ThingsBoard实例。
- 导航至 Security ⇾ OAuth 2.0。
- 在 Domains 选项卡中点击 +（加号）图标。
- 输入域名（或IP地址）。
- 在 OAuth 2.0 clients 区域点击Create new。
在OAuth 2.0客户端配置窗口中：
- 标题设置为 Auth0。
- 提供商选择 Custom。
- 如有需要设置允许的平台（或保持全选）。
- 填写来自Auth0控制台 的 Client ID 和 Client Secret。
展开高级设置并配置：
- 使用Auth0的 Advanced Settings 中的值填入所有必需端点。
- 将客户端认证方法设置为 POST。
- 提供商标签设置为 Auth0。
- 作用域设置为：email openid profile。
进入映射器块并配置：
- 映射器类型：BASIC。
- 租户名称策略：DOMAIN。
-
客户名称模式：%{email}（这些属性的更多说明见下文“Basic mapper”部分）。
- 点击Add创建OAuth 2.0客户端。
- 最后再次点击Add确认域创建。
第3步：验证登录
现在打开ThingsBoard登录页面。你会看到使用Auth0登录按钮，点击并使用Auth0凭证完成认证。
成功认证后，您将以客户登录用户身份登录ThingsBoard。
使用Keycloak登录
此示例演示如何使用Keycloak（OpenID Connect）配置OAuth 2.0认证。
配置完成后：
- 用户可以使用Keycloak凭证登录；
- ThingsBoard会以租户管理员身份登录用户；
- 租户名称从用户邮箱地址派生；
- 若租户不存在，将根据映射器设置自动创建。
用户映射默认使用内置Basic mapper，若需要更复杂的身份到租户映射逻辑，可使用Custom mapper。
第1步：创建Keycloak realm和OpenID Connect客户端
在配置ThingsBoard之前，需要创建Keycloak realm和OpenID Connect客户端，并获取所需OAuth 2.0凭证（Client ID与Client Secret）。
你可以参考Keycloak官方文档，或按以下步骤操作。
启动Keycloak
本示例使用Docker在本地启动Keycloak。
- 确保已安装Docker。
- 运行以下命令在8081端口启动Keycloak，并创建初始管理员用户（admin / admin）：
1
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
登录管理控制台
- 打开Keycloak Admin Console。
- 使用以下账号登录：
- 用户名：admin
- 密码：admin。
创建Realm
Realm是Keycloak中的“工作区”，用于管理应用与用户。
- 点击realm选择器（默认：master）。
- 点击Create realm。
- 将realm名称设为ThingsBoard。
- 点击Create。
创建新客户端
客户端代表使用Keycloak认证的ThingsBoard应用。
- 进入Clients并点击Create client。
- 将client ID设为thingsboard。
- Client type选择OpenID Connect。
- 点击Next。
- 启用Client authentication。
- 确保启用Standard flow。
- 点击Next。
- 在Login settings中添加ThingsBoard重定向URI：
1
http(s)://$DOMAIN:$PORT/login/oauth2/code/
其中：
• $DOMAIN 为ThingsBoard主机名（或IP地址）
• $PORT 为ThingsBoard实例的HTTP/HTTPS端口
示例：
1
https://my.thingsboard.instance/login/oauth2/code/
- 点击保存。
客户端成功创建后，复制凭证：
- Client ID：在Settings选项卡中
- Client Secret：在Credentials选项卡中
端点
ThingsBoard需要Keycloak端点用于OAuth 2.0客户端配置。
获取这些端点最简单的方式是通过OpenID Connect发现文档。
- 导航至 Realm settings。
- 找到并打开 OpenID Endpoint Configuration。
- 启用 Pretty-print 以便阅读。
从该文档中复制以下端点：
- Authorization endpoint
- Token endpoint
- UserInfo endpoint
- JWKS endpoint
关于可用端点的详细说明，请参见Keycloak文档：OIDC layers。
创建用户
仅Keycloak中创建的用户可以通过Keycloak进行认证。
创建用户：
- 导航至 Users。
- 点击 Create new user。
- 填写用户名和邮箱（名/姓为可选）。
- 点击Create
设置密码：
- 打开Credentials选项卡。
- 点击Set password。
- 输入密码。
- 关闭Temporary（避免首次登录强制改密）。
- 点击Save
第3步：将OAuth 2.0客户端分配给域
现在在ThingsBoard中配置Keycloak：
- 登录ThingsBoard。
- 导航至Security ⇾ OAuth 2.0。
- 打开OAuth 2.0 clients选项卡并点击+（plus）图标。
- 标题设置为Keycloak。
- 提供商选择Custom。
- 如有需要指定允许的平台（或保持全选）。
- 填写来自Keycloak Admin Console的Client ID与Client Secret。
展开Advanced settings（高级设置）并配置：
- 使用OpenID Connect discovery document填写以下端点：Access Token URI、Authorization URI、JSON Web Key URI、User Info URI。
- 设置：
- 客户端认证方法：POST
- 提供商标签：Keycloak
- 作用域：email openid profile。
配置映射器：
- 映射器类型：BASIC。
- 租户名称策略：CUSTOM。
-
租户名称模式：%{email}（这些属性的更多说明见下文“Basic mapper”部分）。
- 点击Add创建OAuth 2.0客户端。
添加域： 最后将域绑定到已创建的OAuth 2.0客户端：
- 打开Domains选项卡并点击+（plus）图标。
- 输入域名（或IP地址）。
- 选择Keycloak作为OAuth 2.0客户端。
- 点击Add。
第4步：验证登录
打开ThingsBoard登录页面，你会看到Login with Keycloak按钮。点击并使用Keycloak凭证完成认证。
使用Okta登录
本指南说明如何在ThingsBoard中使用Okta配置OAuth 2.0认证。
配置完成后：
- 用户可以使用Okta账号登录ThingsBoard；
- 用户将以租户管理员身份登录；
- 租户名称等于用户邮箱地址；
- 若租户不存在，ThingsBoard将根据映射器配置自动创建。
用户映射默认使用内置Basic mapper，如需更复杂的开通逻辑，可使用Custom mapper。
第1步：在Okta创建OAuth 2.0客户端
首先需要在Okta创建OAuth 2.0应用并获取Client ID与Client Secret。
操作步骤：
- 打开Okta Developer Console。
- 进入Applications。
- 点击+ Create Application。
- 填写应用名称（例如ThingsBoard）。
- 选择应用类型：Regular Web Application
- 点击Create。
- 在Application Login URIs设置中填写ThingsBoard重定向URI：
1
http(s)://$DOMAIN:$PORT/login/oauth2/code/
其中：
• $DOMAIN 为ThingsBoard主机名（或IP地址）
• $PORT 为ThingsBoard实例的HTTP/HTTPS端口
示例：
1
https://my.thingsboard.instance/login/oauth2/code/
点击Create。
保存应用后，复制生成的值：
- Client ID
- Client Secret
这些值将在配置ThingsBoard时使用。
第2步：在ThingsBoard中添加OAuth 2.0客户端
在ThingsBoard中将Okta配置为OAuth 2.0客户端。
- 登录ThingsBoard实例。
- 导航至Security ⇾ OAuth 2.0。
- 打开OAuth 2.0 clients选项卡。
- 点击+（plus）图标。
在OAuth 2.0 client配置窗口中：
- 标题设置为Okta。
- 提供商选择Custom。
- 如有需要指定允许的平台（或保持All platforms）。
- 填写从Okta获取的Client ID与Client Secret。
展开Advanced settings并配置以下参数：
- Access token URI（示例：https://dev-example.okta.auth0.com/oauth/token）
- Authorization URI（示例：https://dev-example.okta.auth0.com/authorize）
- JSON Web Key URI（示例：https://dev-example.okta.auth0.com/.well-known/jwks.json）
- User info URI（示例：https://dev-example.okta.auth0.com/userinfo）
Okta会提供所需的OAuth端点，可在Okta中获取：
• 在Okta Developer Console中打开应用（ThingsBoard）。
• 进入Advanced settings ⇾ Endpoints，即可看到端点值。
配置其他参数：
- Client authentication method：POST或BASIC（Okta通常使用POST）。
- 启用Allow user creation。
- 若希望自动激活用户，启用Activate user。
- scope设为：email openid profile。
切换到Mapper部分并配置：
- 映射器类型：BASIC。
- 租户名称策略：CUSTOM。
-
租户名称模式：%{email}（这些属性的更多说明见下文“Basic mapper”部分）。
- 点击Add创建OAuth 2.0客户端。
第3步：将OAuth 2.0客户端分配给域
创建OAuth 2.0客户端后，必须将其分配给域。
- 导航至Security → OAuth 2.0。
- 在Domains选项卡编辑现有域或添加新域。
- 在OAuth 2.0 clients字段中选择Okta。
- 点击Add（Save）保存域配置。
第4步：验证登录
使用已配置的域打开ThingsBoard登录页面，你将看到Login with Okta按钮。
点击并使用Okta凭证完成认证。
认证成功后：
- 若租户不存在，ThingsBoard将自动创建；
- 用户以租户管理员身份登录；
- 租户名称与用户邮箱一致。
使用Azure登录
本指南说明如何在ThingsBoard中使用Azure Active Directory（Microsoft Entra ID）配置OAuth 2.0认证。
配置完成后：
- 用户可使用Azure AD账号进行认证；
- 用户以租户管理员身份登录；
- 租户名称等于用户邮箱地址；
- 若租户不存在，ThingsBoard将根据映射器设置自动创建。
用户映射默认使用内置Basic mapper，如需更复杂的身份到租户映射逻辑，可使用Custom mapper。
高级身份定制请参阅微软官方文档：Microsoft identity platform and OpenID Connect protocol。
第1步：在Azure创建OAuth 2.0客户端
首先需要在Azure Active Directory中注册应用。
创建应用：
- 打开Azure Portal。
- 进入Azure Active Directory。
- 打开App registrations。
- 点击New registration。
配置应用：
- Name：ThingsBoard（或任意描述性名称）
- Supported account types：按组织要求选择
- Redirect URI：
- Platform：Web
- URL：
1
http(s)://$DOMAIN:$PORT/login/oauth2/code/
其中：
• $DOMAIN 为ThingsBoard主机名（或IP地址）
• $PORT 为ThingsBoard实例的HTTP/HTTPS端口
示例：
1
https://my.thingsboard.instance/login/oauth2/code/
- 点击Register。
创建Client Secret
此时位于Overview页面，可找到之前设置的Application (client) ID和Client name。
接着打开Authentication选项卡，确保启用access token-based授权，并保存更改。
最后打开Certificates & secrets选项卡，点击+ New client secret，保存生成的密钥value（Client Secret）。
Now we are on the Overview page, where we can find the Application (client) ID and the Client name that we specified earlier.
Next, open the Authentication tab. Make sure to enable authorization on the access token-based. Save changes.
Finally, open the Certificates & secrets tab, and click + New client secret. Save created key value (Client Secret).
获取OAuth端点（OpenID配置）
ThingsBoard需要OAuth端点用于令牌交换与用户验证。
Azure通过OpenID Connect元数据文档提供这些端点：
1
https://login.microsoftonline.com/<TENANT_ID>/v2.0/.well-known/openid-configuration
从该文档中需要以下端点：
- Authorization endpoint
- Token endpoint
- JWKS URI
- UserInfo endpoint (optional)
第2步：在ThingsBoard中添加OAuth 2.0客户端
现在在ThingsBoard中创建对应的OAuth客户端。
- 登录ThingsBoard。
- 导航至Security ⇾ OAuth 2.0。
- 打开OAuth 2.0 clients选项卡。
- 点击+（plus）图标。
配置常规客户端设置
在OAuth 2.0 client配置窗口中：
- Title：Azure Active Directory
- Provider：Custom
- Allowed platforms：All platforms（或选择所需平台）
- Client ID：粘贴Azure Application (client) ID
- Client secret：粘贴Azure Client Secret
配置Advanced settings ⇾ General
展开Advanced settings并配置以下参数：
填写以下字段：
- Authorization URI
- Access token URI
- JSON Web Key URI
- User info URI（可选，取决于配置）
配置其他设置：
- Client authentication method：POST（推荐用于Azure）
- 启用Allow user creation。
- 若希望自动激活用户，启用Activate user。
- Scope：email openid profile。
配置Advanced settings ⇾ Mapper
切换到Mapper选项卡。
推荐的Basic mapper配置：
- User name attribute key：email
- Mapper type：BASIC
- Email attribute key：email
设置租户开通策略：
- Tenant name strategy：CUSTOM
- Tenant name pattern：
1
%{email}
此配置确保：
- 每个用户将登录到与其邮箱同名的租户；
- 若租户不存在，将自动创建。
点击Add创建OAuth 2.0客户端。
第3步：将OAuth 2.0客户端分配给域
创建OAuth客户端后，必须将其分配给域。
- 导航至Security ⇾ OAuth 2.0
- 在Domains选项卡点击+（plus）图标。
在Add domain对话框中：
- 输入域名（或IP地址）。
- 在OAuth 2.0 clients区域选择你的Azure OAuth client。
- 点击Add。
第4步：验证登录流程
使用已配置的域打开ThingsBoard登录页面，你将看到Login with Azure选项。
点击按钮并使用Azure AD凭证完成认证。
认证成功后：
- 若启用自动创建，用户会自动创建；
- 若租户不存在，将自动创建；
- 用户以租户管理员身份登录。
OAuth 2.0客户端的操作
可在OAuth 2.0 clients选项卡中管理OAuth 2.0客户端。
- Add OAuth 2.0 client：点击+（plus）图标，输入客户端标题，选择提供商与允许的平台，填写Client ID与Client Secret，如需可配置高级设置，最后点击Add。
- Edit OAuth 2.0 client：打开客户端详情，点击橙色Edit按钮，更新配置后点击橙色Apply changes。
- Delete OAuth 2.0 client：点击客户端行中的垃圾桶图标并确认删除。
域的操作
可在Domains选项卡中管理OAuth 2.0域映射。
- Add domain：点击+（plus）图标，输入域名，选择一个或多个OAuth 2.0客户端，然后点击Add。
- Edit domain：打开域详情，点击橙色Edit按钮，更新配置后点击橙色Apply changes。
- Delete domain：点击域行中的垃圾桶图标并确认删除。
HaProxy配置
若ThingsBoard部署在HAProxy等负载均衡器后，请配置会话粘性，以确保OAuth流程始终由同一节点处理。
后端示例配置：
1
2
3
4
backend tb-api-backend
...
balance source # balance must be set to 'source'
...
还需确保OAuth相关路径包含在HTTP的ACL映射中：
1
2
3
4
frontend http-in
...
acl tb_api_acl path_beg /api/ /swagger /webjars /v2/ /static/rulenode/ /oauth2/ /login/oauth2/ # '/oauth2/ /login/oauth2/' added
...
以及HTTPS前端：
1
2
3
4
frontend https_in
...
acl tb_api_acl path_beg /api/ /swagger /webjars /v2/ /static/rulenode/ /oauth2/ /login/oauth2/ # '/oauth2/ /login/oauth2/' added
...
您的反馈
如对本示例有任何疑问，请联系我们。