跳到主要内容
版本：Latest-3.5

OAuth 2.0 认证

本文介绍如何在 StarRocks 中启用 OAuth 2.0 认证。

从 v3.5.0 开始，StarRocks 支持使用 OAuth 2.0 对客户端访问进行认证。您可以在 Web UI 和 JDBC 驱动程序上通过 HTTP 启用 OAuth 2.0 认证。

StarRocks 使用 Authorization Code 流程，该流程将授权码交换为令牌。通常，该流程包括以下步骤：

  1. StarRocks 协调器将用户的浏览器重定向到授权服务器。
  2. 用户在授权服务器上进行身份验证。
  3. 请求被批准后，浏览器被重定向回 StarRocks FE，并附带授权码。
  4. StarRocks 协调器将授权码交换为令牌。

本文介绍如何在 StarRocks 中手动创建和认证用户以使用 OAuth 2.0。有关如何使用安全集成将 StarRocks 与您的 OAuth 2.0 服务集成的说明，请参阅 Authenticate with Security Integration。有关如何在您的 OAuth 2.0 服务中认证用户组的更多信息，请参阅 Authenticate User Groups。

前提条件​

如果您希望从 MySQL 客户端连接到 StarRocks，MySQL 客户端版本必须为 9.2 或更高版本。有关更多信息，请参阅 MySQL 官方文档。

使用 OAuth 2.0 创建用户​

创建用户时，通过 IDENTIFIED WITH authentication_oauth2 [AS '{xxx}'] 指定认证方法为 OAuth 2.0。{xxx} 是用户的 OAuth 2.0 属性。。除了当前方式，您还可以在 FE 配置文件中配置默认的 OAuth 2.0 属性。您需要手动修改所有 fe.conf 文件并重启所有 FE 使之生效。配置默认属性后，当您省略 AS '{xxx}' 部分时，StarRocks 会使用您配置文件中指定的默认属性。

语法：

CREATE USER <username> IDENTIFIED WITH authentication_oauth2 [AS 
'{
  "auth_server_url": "<auth_server_url>",
  "token_server_url": "<token_server_url>",
  "client_id": "<client_id>",
  "client_secret": "<client_secret>",
  "redirect_url": "<redirect_url>",
  "jwks_url": "<jwks_url>",
  "principal_field": "<principal_field>",
  "required_issuer": "<required_issuer>",
  "required_audience": "<required_audience>"
}']
属性名对应 FE 配置项描述
auth_server_urloauth2_auth_server_url授权 URL。用户浏览器将被重定向到此 URL，以开始 OAuth 2.0 授权过程。
token_server_urloauth2_token_server_url授权服务器上用于获取访问令牌的端点 URL。
client_idoauth2_client_idStarRocks 客户端的公共标识符。
client_secretoauth2_client_secret用于授权 StarRocks 客户端与授权服务器通信的密钥。
redirect_urloauth2_redirect_urlOAuth 2.0 认证成功后，用户浏览器将被重定向到的 URL。授权码将发送到此 URL。在大多数情况下，需要配置为 http://<starrocks_fe_url>:<fe_http_port>/api/oauth2。
jwks_urloauth2_jwks_urlJSON Web Key Set (JWKS) 服务的 URL 或 conf 目录下本地文件的路径。
principal_fieldoauth2_principal_field用于标识 JWT 中表示主体 (sub) 的字段的字符串。默认值为 sub。此字段的值必须与登录 StarRocks 的用户名相同。
required_issueroauth2_required_issuer(可选) 用于标识 JWT 中发行者 (iss) 的字符串列表。仅当列表中的某个值与 JWT 发行者匹配时，JWT 才被视为有效。
required_audienceoauth2_required_audience(可选) 用于标识 JWT 中受众 (aud) 的字符串列表。仅当列表中的某个值与 JWT 受众匹配时，JWT 才被视为有效。

示例：

CREATE USER tom IDENTIFIED WITH authentication_oauth2 AS 
'{
  "auth_server_url": "http://localhost:38080/realms/master/protocol/openid-connect/auth",
  "token_server_url": "http://localhost:38080/realms/master/protocol/openid-connect/token",
  "client_id": "12345",
  "client_secret": "LsWyD9vPcM3LHxLZfzJsuoBwWQFBLcoR",
  "redirect_url": "http://localhost:8030/api/oauth2",
  "jwks_url": "http://localhost:38080/realms/master/protocol/openid-connect/certs",
  "principal_field": "preferred_username",
  "required_issuer": "http://localhost:38080/realms/master",
  "required_audience": "12345"
}';

如您已经使用 FE 配置项进行配置，则可以直接使用以下语句：

CREATE USER tom IDENTIFIED WITH authentication_oauth2;

使用 OAuth 2.0 从 JDBC 客户端连接​

StarRocks 支持 MySQL 协议。您可以自定义 MySQL 插件以自动启动浏览器登录方法。 可参考官方 JDBC OAuth2 插件示例代码：starrocks-jdbc-oauth2-plugin。

使用 OAuth 2.0 从 MySQL 客户端连接​

若不适合自动调用浏览器登录（如命令行/服务器环境），StarRocks 也支持原生 MySQL 客户端或 JDBC 驱动接入：

  • 初次连接时，StarRocks 返回一个认证 URL；
  • 用户需手动访问该 URL，在 Web 浏览器完成认证流程；
  • 认证完成即可开始正常交互。