Client authentication using OAuth 2.0 access tokens
Pulsar支持使用 OAuth 2.0 访问令牌方式验证客户端。 你可以使用 Oauth 2.0 访问令牌来识别 Pulsar 客户端。通过给 Pulsar 客户端关联一些 “principal” 或 “role”,可以用来授权客户端允许执行某些操作 (例如:发布消息主题或从主题消费消息) 。
这个模块用于支持 OAuth 2.0 的 Pulsar 客户端认证插件。 在与 Oauth 2.0 服务端发起通信后,Pulsar 会从 Oauth 2.0 服务端获取到访问令牌
。然后将这个访问令牌
传递给 Pulsar broker 进行身份认证。 默认情况下,Broker 可以配置使用 org.apache.pulsar.broker.authentication.AuthenticationProviderToken
来进行认证。 或者你可以添加你自己的AuthenticationProvider
来进行认证。
配置认证提供者
这个库允许你使用从OAuth 2.0 认证服务器获取的访问令牌,来认证 Pulsar 客户端。身份认证服务是一个令牌发行者。
认证类型
认证类型决定如何通过 OAuth 2.0 授权流程获取访问令牌。
Note
目前,Pulsar Java 客户端只支持
客户端认证
这一种认证类型。
客户端凭据
以下表格是 客户端凭据
认证类型支持的参数列表。
参数名 | 说明 | 示例 | 是否必选项 |
---|---|---|---|
type | Oauth 2.0 认证类型 | 客户端凭据 (默认) | 可选 |
issuerUrl | 认证提供商的URL,Pulsar 客户端降根据这个URL 获取到访问令牌。 | https://accounts.google.com | Required |
privateKey | JSON凭据文件的 URL | 支持如下的格式:file:///path/to/file file:/path/to/file data:application/json;base64,<base64-encoded value> | Required |
audience | Pulsar 集群的 OAuth 2.0 “资源服务” 的标识符 | https://broker.example.com | Required |
凭据文件包含客户端认证类型使用的服务帐户凭据。 以下是一个凭据文件 credentials_file.json
示例:
{
"type": "client_credentials",
"client_id": "d9ZyX97q1ef8Cr81WHVC4hFQ64vSlDK3",
"client_secret": "on1uJ...k6F6R",
"client_email": "1234567890-abcdefghijklmnopqrstuvwxyz@developer.gserviceaccount.com",
"issuer_url": "https://accounts.google.com"
}
在上面的示例中,凭据类型默认设置成client_credentials
。 字段 “client_id” 和 “client_secret” 是必须的。
典型的 OAuth2 请求映射
如下是一个典型的 Oauth2 请求,用于从 Oauth2 服务器获取到访问令牌。
curl --request POST \
--url https://dev-kt-aa9ne.us.auth0.com \
--header 'content-type: application/json' \
--data '{
"client_id":"Xd23RHsUnvUlP7wchjNYOaIfazgeHd9x",
"client_secret":"rT7ps7WY8uhdVuBTKWZkttwLdQotmdEliaM5rLfmgNibvqziZ-g07ZH52N_poGAb",
"audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/",
"grant_type":"client_credentials"}'
在上面的例子中,映射关系如下所示:
- 此插件中
issuerUrl
参数映射到--url https://dev-kt-aa9ne.us.auth0.com
。 - 此插件中
privateKey
文件参数至少包含client_id
和client_secret
两个字段。 - 此插件中
audience
参数映射到audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"
。
客户端配置
你可以在以下的 Pulsar 客户端中使用 Oauth2 认证。
Java
你可以在 Pulsar Java 客户端中使用工厂方法配置身份认证操作。
String issuerUrl = "https://dev-kt-aa9ne.us.auth0.com";
String credentialsUrl = "file:///path/to/KeyFile.json";
String audience = "https://dev-kt-aa9ne.us.auth0.com/api/v2/";
PulsarClient client = PulsarClient.builder()
.serviceUrl("pulsar://broker.example.com:6650/")
.authentication(
AuthenticationFactoryOAuth2.clientCredentials(issuerUrl, credentialsUrl, audience))
.build();
此外,你也可以在 Pulsar 客户端中使用编码参数来配置身份认证。
Authentication auth = AuthenticationFactory
.create(AuthenticationOAuth2.class.getName(), "{"type":"client_credentials","privateKey":"./key/path/..","issuerUrl":"...","audience":"..."}");
PulsarClient client = PulsarClient.builder()
.serviceUrl("pulsar://broker.example.com:6650/")
.authentication(auth)
.build();
C++ client
C++ 客户端和 Java 客户端类似。 你必须提供issuerUrl
、private_key
(凭据文件路径)和 audience 三个参数。
#include <pulsar/Client.h>
pulsar::ClientConfiguration config;
std::string params = R"({
"issuer_url": "https://dev-kt-aa9ne.us.auth0.com",
"private_key": "../../pulsar-broker/src/test/resources/authentication/token/cpp_credentials_file.json",
"audience": "https://dev-kt-aa9ne.us.auth0.com/api/v2/"})";
config.setAuth(pulsar::AuthOauth2::create(params));
pulsar::Client client("pulsar://broker.example.com:6650/", config);
Go client
如果要在 Go 客户端中启用 OAuth2 认证,需要先配置 OAuth2 认证信息。 如下是一个在 GO 客户端中配置 OAuth2 认证的示例。
oauth := pulsar.NewAuthenticationOAuth2(map[string]string{
"type": "client_credentials",
"issuerUrl": "https://dev-kt-aa9ne.us.auth0.com",
"audience": "https://dev-kt-aa9ne.us.auth0.com/api/v2/",
"privateKey": "/path/to/privateKey",
"clientId": "0Xx...Yyxeny",
})
client, err := pulsar.NewClient(pulsar.ClientOptions{
URL: "pulsar://my-cluster:6650",
Authentication: oauth,
})
Python client
如果要在 Python 客户端中启用 OAuth2 认证,需要先配置 OAuth2 认证信息。 如下是一个在 Python 客户端中配置 OAuth2 认证的示例。
from pulsar import Client, AuthenticationOauth2
params = '''
{
"issuer_url": "https://dev-kt-aa9ne.us.auth0.com",
"private_key": "/path/to/privateKey",
"audience": "https://dev-kt-aa9ne.us.auth0.com/api/v2/"
}
'''
client = Client("pulsar://my-cluster:6650", authentication=AuthenticationOauth2(params))
CLI 配置
本节介绍如何使用 Pulsar CLI 工具通过 OAuth2 身份验证插件连接到 Pulsar 集群。
pulsar-admin
以下示例展示了,如何使用 pulsar-admin 命令通过 OAuth2 身份验证插件连接到 Pulsar 集群。
bin/pulsar-admin --admin-url https://streamnative.cloud:443 \
--auth-plugin org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2 \
--auth-params '{"privateKey":"file:///path/to/key/file.json",
"issuerUrl":"https://dev-kt-aa9ne.us.auth0.com",
"audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"}' \
tenants list
admin-url
参数设置成 Web 服务的URL。 Web 服务 URL 由三部分组成: 协议,主机名,端口。例如:pulsar://localhost:6650
。 基于配置的 Key 文件设置 privateKey
, issuerUrl
, and audience
参数的值。 了解更多详情, 请参考 认证类型 .
pulsar-client
以下示例展示了,如何使用 pulsar-client 命令通过 OAuth2 身份验证插件连接到 Pulsar 集群。
bin/pulsar-client \
--url SERVICE_URL \
--auth-plugin org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2 \
--auth-params '{"privateKey":"file:///path/to/key/file.json",
"issuerUrl":"https://dev-kt-aa9ne.us.auth0.com",
"audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"}' \
produce test-topic -m "test-message" -n 10
admin-url
参数设置成 Web 服务的URL。 Web 服务 URL 由三部分组成: 协议,主机名,端口。例如:pulsar://localhost:6650
。 基于配置的 Key 文件设置 privateKey
, issuerUrl
, and audience
参数的值。 了解更多详情, 请参考 认证类型 .
pulsar-perf
以下示例展示了,如何使用 pulsar-perf 命令通过 OAuth2 身份验证插件连接到 Pulsar 集群。
bin/pulsar-perf produce --service-url pulsar+ssl://streamnative.cloud:6651 \
--auth_plugin org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2 \
--auth-params '{"privateKey":"file:///path/to/key/file.json",
"issuerUrl":"https://dev-kt-aa9ne.us.auth0.com",
"audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"}' \
-r 1000 -s 1024 test-topic
admin-url
参数设置成 Web 服务的URL。 Web 服务 URL 由三部分组成: 协议,主机名,端口。例如:pulsar://localhost:6650
。 基于配置的 Key 文件设置 privateKey
, issuerUrl
, and audience
参数的值。 了解更多详情, 请参考 认证类型 .