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

客户端凭据

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

参数名说明示例是否必选项
typeOauth 2.0 认证类型客户端凭据 (默认)可选
issuerUrl认证提供商的URL，Pulsar 客户端降根据这个URL 获取到访问令牌。https://accounts.google.comRequired
privateKeyJSON凭据文件的 URL支持如下的格式:
  • file:///path/to/file
  • file:/path/to/file
  • data:application/json;base64,<base64-encoded value>
    		• Required
    audiencePulsar 集群的 OAuth 2.0 “资源服务” 的标识符https://broker.example.comRequired

    凭据文件包含客户端认证类型使用的服务帐户凭据。 以下是一个凭据文件 credentials_file.json 示例：

    1. {
    2.   "type": "client_credentials",
    3.   "client_id": "d9ZyX97q1ef8Cr81WHVC4hFQ64vSlDK3",
    4.   "client_secret": "on1uJ...k6F6R",
    5.   "client_email": "1234567890-abcdefghijklmnopqrstuvwxyz@developer.gserviceaccount.com",
    6.   "issuer_url": "https://accounts.google.com"
    7. }

    在上面的示例中，凭据类型默认设置成client_credentials。 字段 “client_id” 和 “client_secret” 是必须的。

    典型的 OAuth2 请求映射

    如下是一个典型的 Oauth2 请求，用于从 Oauth2 服务器获取到访问令牌。

    1. curl --request POST \
    2.   --url https://dev-kt-aa9ne.us.auth0.com \
    3.   --header 'content-type: application/json' \
    4.   --data '{
    5.   "client_id":"Xd23RHsUnvUlP7wchjNYOaIfazgeHd9x",
    6.   "client_secret":"rT7ps7WY8uhdVuBTKWZkttwLdQotmdEliaM5rLfmgNibvqziZ-g07ZH52N_poGAb",
    7.   "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/",
    8.   "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 客户端中使用工厂方法配置身份认证操作。

    1. String issuerUrl = "https://dev-kt-aa9ne.us.auth0.com";
    2. String credentialsUrl = "file:///path/to/KeyFile.json";
    3. String audience = "https://dev-kt-aa9ne.us.auth0.com/api/v2/";
    5. PulsarClient client = PulsarClient.builder()
    6.     .serviceUrl("pulsar://broker.example.com:6650/")
    7.     .authentication(
    8.         AuthenticationFactoryOAuth2.clientCredentials(issuerUrl, credentialsUrl, audience))
    9.     .build();

    此外，你也可以在 Pulsar 客户端中使用编码参数来配置身份认证。

    1. Authentication auth = AuthenticationFactory
    2.     .create(AuthenticationOAuth2.class.getName(), "{"type":"client_credentials","privateKey":"./key/path/..","issuerUrl":"...","audience":"..."}");
    3. PulsarClient client = PulsarClient.builder()
    4.     .serviceUrl("pulsar://broker.example.com:6650/")
    5.     .authentication(auth)
    6.     .build();

    C++ client

    C++ 客户端和 Java 客户端类似。 你必须提供issuerUrl、private_key(凭据文件路径)和 audience 三个参数。

    1. #include <pulsar/Client.h>
    3. pulsar::ClientConfiguration config;
    4. std::string params = R"({
    5.     "issuer_url": "https://dev-kt-aa9ne.us.auth0.com",
    6.     "private_key": "../../pulsar-broker/src/test/resources/authentication/token/cpp_credentials_file.json",
    7.     "audience": "https://dev-kt-aa9ne.us.auth0.com/api/v2/"})";
    9. config.setAuth(pulsar::AuthOauth2::create(params));
    11. pulsar::Client client("pulsar://broker.example.com:6650/", config);

    Go client

    如果要在 Go 客户端中启用 OAuth2 认证，需要先配置 OAuth2 认证信息。 如下是一个在 GO 客户端中配置 OAuth2 认证的示例。

    1. oauth := pulsar.NewAuthenticationOAuth2(map[string]string{
    2.         "type":       "client_credentials",
    3.         "issuerUrl":  "https://dev-kt-aa9ne.us.auth0.com",
    4.         "audience":   "https://dev-kt-aa9ne.us.auth0.com/api/v2/",
    5.         "privateKey": "/path/to/privateKey",
    6.         "clientId":   "0Xx...Yyxeny",
    7.     })
    8. client, err := pulsar.NewClient(pulsar.ClientOptions{
    9.         URL:              "pulsar://my-cluster:6650",
    10.         Authentication:   oauth,
    11. })

    Python client

    如果要在 Python 客户端中启用 OAuth2 认证，需要先配置 OAuth2 认证信息。 如下是一个在 Python 客户端中配置 OAuth2 认证的示例。

    1. from pulsar import Client, AuthenticationOauth2
    3. params = '''
    4. {
    5.     "issuer_url": "https://dev-kt-aa9ne.us.auth0.com",
    6.     "private_key": "/path/to/privateKey",
    7.     "audience": "https://dev-kt-aa9ne.us.auth0.com/api/v2/"
    8. }
    9. '''
    11. client = Client("pulsar://my-cluster:6650", authentication=AuthenticationOauth2(params))

    CLI 配置

    本节介绍如何使用 Pulsar CLI 工具通过 OAuth2 身份验证插件连接到 Pulsar 集群。

    pulsar-admin

    以下示例展示了，如何使用 pulsar-admin 命令通过 OAuth2 身份验证插件连接到 Pulsar 集群。

    1. bin/pulsar-admin --admin-url https://streamnative.cloud:443 \
    2. --auth-plugin org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2 \
    3. --auth-params '{"privateKey":"file:///path/to/key/file.json",
    4.     "issuerUrl":"https://dev-kt-aa9ne.us.auth0.com",
    5.     "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"}' \
    6. tenants list

    admin-url 参数设置成 Web 服务的URL。 Web 服务 URL 由三部分组成: 协议，主机名，端口。例如：pulsar://localhost:6650。 基于配置的 Key 文件设置 privateKey, issuerUrl, and audience 参数的值。 了解更多详情, 请参考 认证类型.

    pulsar-client

    以下示例展示了，如何使用 pulsar-client 命令通过 OAuth2 身份验证插件连接到 Pulsar 集群。

    1. bin/pulsar-client \
    2. --url SERVICE_URL \
    3. --auth-plugin org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2 \
    4. --auth-params '{"privateKey":"file:///path/to/key/file.json",
    5.     "issuerUrl":"https://dev-kt-aa9ne.us.auth0.com",
    6.     "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"}' \
    7. 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 集群。

    1. bin/pulsar-perf produce --service-url pulsar+ssl://streamnative.cloud:6651 \
    2. --auth_plugin org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2 \
    3. --auth-params '{"privateKey":"file:///path/to/key/file.json",
    4.     "issuerUrl":"https://dev-kt-aa9ne.us.auth0.com",
    5.     "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"}' \
    6. -r 1000 -s 1024 test-topic

    admin-url 参数设置成 Web 服务的URL。 Web 服务 URL 由三部分组成: 协议，主机名，端口。例如：pulsar://localhost:6650。 基于配置的 Key 文件设置 privateKey, issuerUrl, and audience 参数的值。 了解更多详情, 请参考 认证类型.