产品定价 立即试用
PE MQTT Broker
社区版 专业版 云平台 边缘 PE边缘 IoT网关 许可证服务器 Trendz Analytics 移动应用 PE移动应用 MQTT Broker PE MQTT Broker
文档 > 安全 > OAuth 2.0
入门
安装 架构 API 常见问题
目录

OAuth 2.0

概述

TBMQ专业版支持基于OAuth 2.0协议的外部用户管理平台，为用户提供单点登录（SSO），并自动创建管理员或只读用户。 支持OAuth 2.0的平台示例：Google、Auth0、Keycloak、Okta、Azure等。

OAuth 2.0认证流程

TBMQ支持授权码（Authorization Code）许可类型，用授权码换取访问令牌。 用户被重定向回TBMQ客户端后，平台从URL获取授权码，并向外部用户管理平台请求访问令牌。 通过基础映射器或自定义映射器，将外部平台的用户信息转换为TBMQ内部OAuth 2.0用户。 随后执行常规TBMQ授权流程。

通过外部提供商配置认证

OAuth 2.0客户端与域名分开配置，可复用已配置客户端并简化设置。 要通过外部提供商认证，需先配置带必要凭据的OAuth 2.0客户端。 然后添加新域名或使用已有域名，并将新客户端加入该域名的OAuth 2.0客户端列表。

域名操作

添加域名

添加新域名按以下步骤：

  • 在“OAuth 2.0”页的“域名”标签中，点击“加号”图标添加新域名；
  • 填写域名及OAuth 2.0客户端；
  • 点击“添加”完成。
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".
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.
Domain added.

编辑域名

更新已有域名设置，按以下步骤：

  • 点击域名查看详情；
  • 点击大橙色按钮进入编辑模式；
  • 进行所需修改；
  • 点击“应用更改”保存。
Click on the domain to view its details. Switch to editing mode by clicking the large orange button;
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.
Make the required modifications. Then confirm and save the changes by clicking the "Apply changes" button.

删除域名

删除域名，按以下步骤：

  • 点击要删除域名行的“垃圾桶”图标；
  • 在确认对话框中点击“是”。
Click the "trash" icon in the domain's row you wish to remove;
Click the "trash" icon in the domain's row you wish to remove;
Confirm the deletion by clicking "Yes".
Confirm the deletion by clicking "Yes".

OAuth2.0客户端操作

添加OAuth 2.0客户端

在TBMQ中添加新OAuth 2.0客户端，按以下步骤：

  • 进入“OAuth 2.0”页的“OAuth 2.0客户端”标签，点击“加号”图标；
  • 输入客户端描述性标题；
  • 从下拉菜单选择认证提供商；
  • 填写从认证提供商获取的Client ID和Client Secret；
  • 按需配置高级设置；
  • 点击“添加”完成。
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;
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 "Google" from the dropdown menu as the authentication provider. Provide the Client ID and Client Secret obtained from your authentication provider. Configure advanced settings as necessary. Then, click "Add".
Enter a descriptive title for the client, and select the "Google" from the dropdown menu as the authentication provider. Provide the Client ID and Client Secret obtained from your authentication provider. Configure advanced settings as necessary. Then, click "Add".
New OAuth 2.0 client added.
New OAuth 2.0 client added.

编辑OAuth 2.0客户端

更新已有OAuth 2.0客户端：

  • 点击客户端查看详情；
  • 点击大橙色按钮进入编辑模式；
  • 进行所需修改；
  • 点击“应用更改”保存。
Click on the OAuth 2.0 client to view its details. Switch to editing mode by clicking the large orange button;
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.
Make the required modifications. Then confirm and save the changes by clicking the "Apply changes" button.

删除OAuth 2.0客户端

删除不再使用的客户端：

  • 点击要删除客户端行的“垃圾桶”图标；
  • 在确认对话框中点击“是”。
Click the "trash" icon in the client's row you wish to remove;
Click the "trash" icon in the client's row you wish to remove;
Confirm the deletion by clicking "Yes".
Confirm the deletion by clicking "Yes".

使用Google登录

本示例使用 Google 进行认证。

将Google外部用户信息映射到OAuth平台时，可使用内置基础映射器。 若基础映射器不满足业务需求，可配置自定义映射器以获得更多灵活性。

准备工作

使用Google OAuth 2.0认证前，需在 Google API Console 中创建项目以获取OAuth 2.0凭据。

参考 OpenID Connect 页面说明或下方步骤配置OAuth 2.0客户端。 配置完成后将获得Client ID和Client Secret。

  • 在左侧菜单进入“凭据”页，在“创建凭据”下拉中选择“OAuth客户端ID”；
  • 输入OAuth客户端名称，并在“已授权的重定向URI”中加入TBMQ重定向URI，格式如下：
1

http(s)://domain:port/login/oauth2/code/
  • 将 domain 替换为您的TBMQ域名，并指定HTTP访问端口。 若域名为 my.tbmq.org，示例：
1

https://my.tbmq.org/login/oauth2/code/
  • 点击“创建”。

OAuth客户端已创建，您将获得 Client ID 和 Client Secret。

Go to the "Credentials" page in the left menu and select "OAuth client ID" from the "Create credentials" dropdown menu;
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";
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;
OAuth client created. You now have credentials consisting of a Client ID and a Client secret;

在TBMQ中将Google配置为OAuth 2.0认证提供商

在TBMQ中通过Google配置OAuth 2.0认证，按以下步骤：

  • 登录TBMQ实例；
  • 进入“安全”下的“OAuth 2.0”页面；
  • 在“域名”标签中点击“加号”图标；
  • 输入TBMQ实例的域名或IP地址；
  • 在“OAuth 2.0客户端”中点击“创建新”添加客户端。
Login to your TBMQ instance. Go to the "OAuth 2.0" page of the "Security" section. While on the "Domains" tab, click the "plus" icon;
Login 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.
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.

添加新OAuth 2.0客户端：

  • 标题输入“Google”；
  • 提供商选择“Google”；
  • 填入 Google API Console 中的Client ID和Client Secret。

展开“高级设置”并配置“通用”区块：

  • 使用此链接查看最新 URL（如“Access Token URI”“Authorization URI”）；
  • 客户端认证方法选择“POST”；
  • 启用“允许创建用户”；
  • 在scope字段添加：email、openid、profile。
Enter "Google" as the title. The provider should be set to "Google". If necessary, specify the allowed platforms, or leave all. Enter the "Client ID" and "Client secret" from the Google API Console. Then, expand the "Advanced settings" menu;
Enter "Google" as the title. The provider should be set to "Google". If necessary, specify the allowed platforms, or leave all. Enter the "Client ID" and "Client secret" from the Google API Console. Then, expand the "Advanced settings" menu;
Let's make the settings for 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";
Let's make the settings for 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";

在“映射器”区块：

  • 映射器类型保持“BASIC”；
  • 指定要分配的角色；
  • 点击“添加”。
Go to the "Mapper" block. Leave the mapper type "BASIC". If necessary, change the user role or leave as it is. Click "Add";
Go to the "Mapper" block. Leave the mapper type "BASIC". If necessary, change the user role or leave as it is. Click "Add";
  • OAuth客户端已成功添加。再次点击“添加”确认域名添加。

新域名已添加完成。

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

登录

进入TBMQ登录页后，将出现“使用Google登录”选项。 选择您的Google账户，即可使用该邮箱登录TBMQ。

Navigate to the TBMQ login screen. We will see an additional "Login with Google" option. Click this button and login using your Google account;
Navigate to the TBMQ login screen. We will see an additional "Login with Google" option. Click this button and login using your Google account;

在“用户”页面可查看新创建的用户。

Go to the "Users" page. There you should find a new user that you have just logged in.
Go to the "Users" page. There you should find a new user that you have just logged in.

使用Auth0登录

本示例通过外部提供商 Auth0 配置 OAuth 认证。

将Auth0外部用户信息映射到OAuth平台时，使用内置基础映射器。

若基础映射器不满足需求，可配置自定义映射器以实现所需映射。

准备工作

现在向列表中添加另一个提供商——Auth0。

要正确应用配置，首先需要获取OAuth 2.0凭证：

  • 进入Auth0管理控制台。打开”Applications”页面，点击”+ Create Application”按钮；
  • 将应用程序命名为”TBMQ”，选择应用程序类型为Regular Web Applications；
  • 接下来选择所使用的技术。请选择Java Spring Boot；
  • 创建应用程序后，您将被重定向到应用程序详情页面。导航到Settings选项卡以查找Client ID和Client Secret；
  • 在Allowed Callback URLs字段中，使用以下格式更新重定向URI：
1

http(s)://domain:port/login/oauth2/code/
  • 将domain替换为您的TBMQ域名，并指定HTTP访问使用的端口。 例如，如果您的域名是my.tbmq.org：
1

https://my.tbmq.org/login/oauth2/code/
文档信息图标

请注意，不需要更新Application Login URI。

  • 在Advanced Settings部分中，您将找到配置OAuth 2.0所需的所有URL（端点）；
  • 点击Save Changes按钮。
To apply the configurations properly, we first need to obtain OAuth 2.0 credentials. Therefore, we first go to the OAuth0 Management Console. Open the "Applications" page, and click "+ Create Application" button;
To apply the configurations properly, we first need to obtain OAuth 2.0 credentials. Therefore, we first go to the OAuth0 Management Console. Open the "Applications" page, and click "+ Create Application" button;
Name your application "TBMQ", and choose the application type - "Regular Web Applications";
Name your application "TBMQ", and choose the application type - "Regular Web Applications";
Afters, you need to choose the technology being used. Please, choose the "Java Spring Boot" technology;
Afters, you need to choose the technology being used. Please, choose the "Java Spring Boot" technology;
Once your application is created, you are redirected to the application details page. Navigate to the "Settings" tab to find the Client ID and Client Secret;
Once your application is created, you are redirected to the application details page. Navigate to the "Settings" tab to find the Client ID and Client Secret;
As well, please update your allowed Callback URLs;
As well, please update your allowed Callback URLs;
In the "Advanced Settings" section you will be able to find all the required URLs (endpoints) for OAuth 2.0 configuration. Click "Save Changes" button.
In the "Advanced Settings" section you will be able to find all the required URLs (endpoints) for OAuth 2.0 configuration. Click "Save Changes" button.

在TBMQ中将Auth0配置为OAuth 2.0认证提供商

要通过Auth0在TBMQ中配置OAuth 2.0认证，请按照以下步骤操作：

  • 登录您的TBMQ实例；
  • 进入”Security”部分中的”OAuth 2.0”页面；
  • 在”Domains”选项卡中，点击”+”图标；
  • 输入您的TBMQ实例的域名或IP地址；
  • 在”OAuth 2.0 clients”部分中点击”Create new”以添加新的客户端。
Login to your TBMQ instance. Go to the "OAuth 2.0" page of the "Security" section. While on the "Domains" tab, click the "plus" icon;
Login 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 of your TBMQ instance. Click "Create new" in the "OAuth 2.0 clients" section to add a new one.
Enter your domain name of your TBMQ instance. Click "Create new" in the "OAuth 2.0 clients" section to add a new one.

添加新的OAuth 2.0客户端：

  • 在打开的窗口中，输入Auth0作为客户端的标题；
  • 从下拉菜单中选择Custom作为提供商；
  • 输入从Auth0管理控制台获取的Client ID和Client Secret。

在”Advanced settings”部分的General块中：

  • 使用从Auth0管理控制台获取的值填写所有必需的URL；
  • 选择POST作为客户端身份验证方法；
  • 输入Auth0作为提供商标签；
  • 在范围字段中添加以下范围：openid、email、profile。
Enter "OAuth0" as the title for the client. Select "Custom" as the provider. Now enter the "Client ID" and "Client secret" obtained from the OAuth0 Management Console. In the "General" block of the "Advanced settings" section, fill in all the necessary URLs. The client authentication method should be set to "POST". Enter "OAuth0" as the provider label. Add the following scopes in the scope field: "openid", "email", "profile";
Enter "OAuth0" as the title for the client. Select "Custom" as the provider. Now enter the "Client ID" and "Client secret" obtained from the OAuth0 Management Console. In the "General" block of the "Advanced settings" section, fill in all the necessary URLs. The client authentication method should be set to "POST". Enter "OAuth0" as the provider label. Add the following scopes in the scope field: "openid", "email", "profile";


前往”Mapper”块：

  • 将映射器类型保留为BASIC；
  • 指定要使用的角色；
  • 点击Add以完成新OAuth 2.0客户端的添加。
Proceed to the "Mapper" block. Leave the mapper type "BASIC". If necessary, change the user role or leave as it is. Click "Add" to confirm adding the OAuth 2 client.
Proceed to the "Mapper" block. Leave the mapper type "BASIC". If necessary, change the user role or leave as it is. Click "Add" to confirm adding the OAuth 2 client.
  • Auth0客户端已成功添加。再次点击Add确认域名的添加。
The OAuth0 client has been successfully added. Click "Add" again to confirm the addition of the domain.
The OAuth0 client has been successfully added. Click "Add" again to confirm the addition of the domain.
A new domain has been added.
A new domain has been added.

登录

导航到登录屏幕。您现在将找到Auth0登录方法。 点击”Login with Auth0”按钮。

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.
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.

进入”Users”页面。您将看到已创建新用户。

Go to the "Users" page. There you should find a new user that you have just logged in.
Go to the "Users" page. There you should find a new user that you have just logged in.

使用Keycloak登录

本示例使用 Keycloak 进行认证。

将Keycloak外部用户信息映射到OAuth平台时，使用内置基础映射器。

若基础映射器不满足需求，可配置自定义映射器以实现所需映射。

准备工作

要使用Keycloak进行身份验证，您需要在Keycloak中设置一个项目来获取OAuth 2.0凭证。 遵循官方说明或以下步骤。 最后，您应该拥有一个新的Keycloak客户端，其凭证包括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
Run this command to start Keycloak on local the port 8081 and create an initial admin user with the username admin and password admin.
Run this command to start Keycloak on local the port 8081 and create an initial admin user with the username admin and password admin.

登录到管理控制台

Log in to the Keycloak Admin Console using your username and password.
Log in to the Keycloak Admin Console using your username and password.

创建领域

  • 点击master领域旁的”Keycloak”，然后点击”Create realm”按钮；
  • 在领域名称字段中输入ThingsBoard，然后点击”Create”。

新领域已创建。

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

创建新客户端

客户端代表请求用户身份验证的应用程序或服务。

  • 在左侧菜单中进入”Clients”页面，点击”Create client”按钮；
  • 输入thingsboard作为客户端ID。将客户端类型保留为OpenID Connect。点击”Next”；
  • 启用Client authentication选项。确认已启用Standard flow。点击”Next”；
  • 在”Login settings”部分中，使用以下格式在Authorized Redirect URIs部分添加TBMQ重定向URI：
1

http(s)://domain:port/login/oauth2/code/
  • 将domain替换为您的TBMQ域名，并指定HTTP访问使用的端口。 例如，如果您的域名是my.thingsboard.instance：
1

https://my.thingsboard.instance/login/oauth2/code/
  • 点击”Save”。

客户端创建成功。

Go to the "Clients" page in the left-hand menu, and click the "Create client" button;
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";
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";
Turn on "Client authentication" option. Confirm that "Standard flow" is enabled. Click "Next";
In the "Login settings" section, add the ThingsBoard redirect URI to the "Authorized Redirect URIs" section. Then, click "Save";
In the "Login settings" section, add the ThingsBoard redirect URI to the "Authorized Redirect URIs" section. Then, click "Save";
Client created successfully.
Client created successfully.


现在您拥有包括Client ID和Client Secret的凭证。 Client ID在”Settings”选项卡上可用。Client Secret位于”Credentials”选项卡上。

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

端点

作为完全兼容的OpenID Connect提供商，Keycloak公开了一组端点，应用程序和服务可以使用这些端点进行身份验证和授权。

  • 进入”Realm settings”页面；
  • 向下滚动并找到”OpenID Endpoint Configuration”链接，然后点击它；
  • 将打开一个新窗口显示配置。选中”Pretty-print”选项以便于阅读。

在这里您可以找到Access Token URI、Authorization URI、JSON Web Key URI和User Info URI等值，这些是在TBMQ中配置OAuth 2.0客户端所需的。 可用端点的描述在这里提供。

Go to the "Realm settings" page in the left-hand menu. Scroll down and locate the link to "OpenID Endpoint Configuration", then click on it;
Go to the "Realm settings" page in the left-hand menu. Scroll down and locate the link to "OpenID Endpoint Configuration", then click on it;
A new window with OpenID Endpoint Configuration will open. Check the "Pretty-print" option to make the data view more user-friendly. Here you found "Access token URI," "Authorization URI," "JSON Web Key URI," and "User info URI," which are necessary for configuring the OAuth 2.0 client in ThingsBoard.
A new window with OpenID Endpoint Configuration will open. Check the "Pretty-print" option to make the data view more user-friendly. Here you found "Access token URI," "Authorization URI," "JSON Web Key URI," and "User info URI," which are necessary for configuring the OAuth 2.0 client in ThingsBoard.

创建用户

现在添加一个用户。只有添加的用户才能通过Keycloak进行身份验证。

  • 在左侧菜单中进入”Users”页面；
  • 点击”Create new user”；
  • 输入用户名和电子邮件地址。名字和姓氏是可选的；
  • 点击”Create”。

用户已创建。

Go to the "Users" page in the left-hand menu. Click "Create new user";
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";
Enter the username and email address in the form. First name and last name are optional. Then, click "Create";
The user has been created;
The user has been created;

为此用户设置密码：

  • 导航到”Credentials”选项卡并点击Set password；
  • 填写密码表单。将Temporary切换为Off，以便用户在首次登录时不被强制更改密码；
  • 点击Save password。

密码已成功设置。

Navigate to the "Credentials" tab. Click "Set password";
Navigate to the "Credentials" tab. Click "Set password";
Fill in the "Set password" form with a password. Toggle "Temporary" to "Off" so that the user does not need to update this password at the first login. Click "Save";
Fill in the "Set password" form with a password. Toggle "Temporary" to "Off" so that the user does not need to update this password at the first login. Click "Save";
Confirm the set password by clicking the "Save password";
Confirm the set password by clicking the "Save password";
The password has been successfully.
The password has been successfully.

在TBMQ中将Keycloak配置为OAuth 2.0认证提供商

要通过Keycloak在TBMQ中配置OAuth 2.0认证，请按照以下步骤操作：

  • 登录您的TBMQ实例；
  • 进入”Security”部分中的”OAuth 2.0”页面；
  • 导航到”OAuth 2.0 clients”选项卡，点击”+”图标；
  • 输入Keycloak作为标题；
  • 从下拉菜单中选择Custom作为提供商；
  • 输入从Keycloak控制台检索的Client ID和Client Secret。

然后展开”Advanced settings”菜单并配置”General”块：

  • 使用端点配置文件查找Access Token URI、Authorization URI、JSON Web Key URI和User Info URI的当前值。填入相应的字段；
  • 将客户端身份验证方法设置为POST；
  • 输入Keycloak作为提供商标签；
  • 添加以下范围：email、openid、profile。
Login 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 to add a new client;
Login 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 to add a new client;
Enter "Keycloak" as the title. Select the "Custom" from the dropdown menu as the authentication provider. Now enter the "Client ID" and "Client secret" using the values retrieved from the Keycloak console. In the "General" block of the "Advanced settings" section, fill in all the necessary URLs. The client authentication method should be set to "POST". Enter "Keycloak" as the provider label. Add the following scopes in the scope field: "openid", "email", "profile";
Enter "Keycloak" as the title. Select the "Custom" from the dropdown menu as the authentication provider. Now enter the "Client ID" and "Client secret" using the values retrieved from the Keycloak console. In the "General" block of the "Advanced settings" section, fill in all the necessary URLs. The client authentication method should be set to "POST". Enter "Keycloak" as the provider label. Add the following scopes in the scope field: "openid", "email", "profile";

进入”Mapper”块：

  • 将映射器类型保留为BASIC；
  • 指定要使用的角色；
  • 点击Add确认。

新的OAuth 2.0客户端已添加。

Go to the "Mapper" block. Leave the mapper type "BASIC". If necessary, change the user role or leave as it is. Click "Add" to confirm adding the OAuth 2 client;
Go to the "Mapper" block. Leave the mapper type "BASIC". If necessary, change the user role or leave as it is. Click "Add" to confirm adding the OAuth 2 client;
A new OAuth 2.0 client has been added.
A new OAuth 2.0 client has been added.


现在添加一个新域名：

  • 进入”OAuth 2.0”页的”Domains”选项卡，点击”+”图标；
  • 输入您的TBMQ实例的域名或IP地址；
  • 指定Keycloak作为OAuth 2.0客户端；
  • 再次点击Add确认。

新域名已添加。

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

登录

进入TBMQ登录屏幕。您现在将看到Login with Keycloak选项。 点击此按钮。将打开一个窗口提示您登录到Keycloak账户。 输入您的Keycloak凭证并点击Sign In。您现在已使用Keycloak登录TBMQ。

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 TBMQ login screen. You will see an additional option, "Login with Keycloak". Click this button and login using your Keycloak credentials;

进入”Users”页面。您将发现已创建新用户。

Go to the "Users" page. There you should find a new user that you have just logged in.
Go to the "Users" page. There you should find a new user that you have just logged in.

将外部用户映射到TBMQ内部用户结构

将外部用户信息对象映射为TBMQ用户时，可使用 Basic、Custom、GitHub和Apple映射器。

基础映射器

基础映射器按预定义规则将外部OAuth 2.0用户信息对象合并为TBMQ OAuth 2.0用户。

使用基础映射器时，将映射器类型设为Basic。

To use a basic mapper, set mapper type "Basic".
To use a basic mapper, set mapper type "Basic".

可用属性说明：

  • 允许创建用户：启用后，若TBMQ中尚不存在该用户账户，将自动创建。 禁用时，若没有对应的TBMQ用户，使用外部OAuth 2.0提供商登录将返回 access denied 错误。

  • 邮箱属性键：外部OAuth 2.0用户信息中用于TBMQ用户邮箱的属性键。

  • 名属性键：外部OAuth 2.0用户信息中用于TBMQ用户名的属性键。

  • 姓属性键：外部OAuth 2.0用户信息中用于TBMQ用户姓的属性键。

  • 角色：从预定义角色中选择分配给用户的角色。

若用户通过 OAuth 2.0 登录且启用了 Allow user creation 选项，系统会自动创建用户账号。 这些用户创建时未设置密码，可继续使用 Single Sign-On (SSO) 登录。 若用户希望通过常规 username/password 登录，需进入 Account → Security 并设置新密码。 修改密码时，Current password 字段留空即可。

自定义映射器

若基础映射器不满足业务需求，可配置自定义映射器以实现所需逻辑。

自定义映射器为与TBMQ微服务并列运行的独立微服务。TBMQ将所有映射请求转发至该微服务，并期望返回TBMQ OAuth 2.0用户对象。

可参考此基础实现作为自定义映射器起点。

使用自定义映射器时，将映射器类型设为Custom。

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

可用属性说明：

  • URL：自定义映射器端点的URL；
  • username：若自定义映射器端点启用了基本认证，在此填写 username；
  • password：若自定义映射器端点启用了基本认证，在此填写 password。

HAProxy配置

若TBMQ运行在HAProxy等负载均衡器之后，需正确配置均衡算法以确保会话落在同一TBMQ实例：

1
2
3
4

backend tbmq-api-backend
  ...
  balance source # balance 必须设为 'source'
  ...

同时为HTTP和HTTPS请求配置ACL映射：

1
2
3
4

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

1
2
3
4

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