Client authentication using OAuth 2.0 access tokens

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 客户端只支持 客户端认证 这一种认证类型。

客户端凭据

以下表格是 客户端凭据 认证类型支持的参数列表。

参数名	Description	示例	是否必选项
`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/oauth/token \
  --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:              "puslar://my-cluster:6650",
        Authentication:   oauth,
})

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

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

Authentication using OAuth 2.0 access tokens