Skip to content

Commit

Permalink
[improve][doc] Improve the authentication enablement workflow across …
Browse files Browse the repository at this point in the history 
…multiple providers (apache#18035)

* Update security-athenz.md

* improve auth overview

* address review comments

* Improve OAuth2 authentication

* improve Kerberos authentication

* Update security-athenz.md
  • Loading branch information
@momo-jun
momo-jun authored Oct 27, 2022
1 parent 6657fe4 commit a48bc8b
Show file tree
Hide file tree
Showing 8 changed files with 475 additions and 458 deletions.
2 changes: 1 addition & 1 deletion site2/docs/client-libraries-java.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1262,7 +1262,7 @@ Pulsar currently supports the following authentication mechansims:
* [TLS](security-tls-authentication.md#configure-tls-authentication-in-pulsar-clients)
* [JWT](security-jwt.md#configure-jwt-authentication-in-pulsar-clients)
* [Athenz](security-athenz.md#configure-athenz-authentication-in-pulsar-clients)
* [Kerberos](security-kerberos.md#java-client-and-java-admin-client)
* [Kerberos](security-kerberos.md#configure-kerberos-authentication-in-pulsar-clients)
* [OAuth2](security-oauth2.md#configure-oauth2-authentication-in-pulsar-clients)
* [HTTP basic](security-basic-auth.md#configure-basic-authentication-in-pulsar-clients)
Expand Down
163 changes: 130 additions & 33 deletions site2/docs/security-athenz.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,42 +6,43 @@ sidebar_label: "Authentication using Athenz"

[Athenz](https://github.com/AthenZ/athenz) is a role-based authentication/authorization system. In Pulsar, you can use Athenz role tokens (also known as *z-tokens*) to establish the identity of the client.

## Enable Athenz authentication

A [decentralized Athenz system](https://github.com/AthenZ/athenz/blob/master/docs/decent_authz_flow.md) contains an [authori**Z**ation **M**anagement **S**ystem](https://github.com/AthenZ/athenz/blob/master/docs/setup_zms.md) (ZMS) server and an [authori**Z**ation **T**oken **S**ystem](https://github.com/AthenZ/athenz/blob/master/docs/setup_zts) (ZTS) server.

To begin, you need to set up Athenz service access control. You need to create domains for the *provider* (which provides some resources to other services with some authentication/authorization policies) and the *tenant* (which is provisioned to access some resources in a provider). In this case, the provider corresponds to the Pulsar service itself and the tenant corresponds to each application using Pulsar (typically, a [tenant](reference-terminology.md#tenant) in Pulsar).
## Prerequisites

To begin, you need to set up Athenz service access control by creating domains for the *provider* (which provides some resources to other services with some authentication/authorization policies) and the *tenant* (which is provisioned to access some resources in a provider). In this case, the provider corresponds to the Pulsar service itself and the tenant corresponds to each application using Pulsar (typically, a [tenant](reference-terminology.md#tenant) in Pulsar).

### Create the tenant domain and service
### Create a tenant domain and service

On the [tenant](reference-terminology.md#tenant) side, you need to do the following things:
On the tenant side, do the followings:

1. Create a domain, such as `shopping`
2. Generate a private/public key pair
3. Create a service, such as `some_app`, on the domain with the public key
1. Create a domain, such as `shopping`.
2. Generate a private/public key pair.
3. Create a service, such as `some_app`, on the domain with the public key.

Note that you need to specify the private key generated in step 2 when the Pulsar client connects to the [broker](reference-terminology.md#broker) (see client configuration examples for [Java](client-libraries-java.md) and [C++](client-libraries-cpp.md)).
Note that you need to specify the private key generated in step 2 when the Pulsar client connects to the broker.

For more specific steps involving the Athenz UI, refer to [Example Service Access Control Setup](https://github.com/AthenZ/athenz/blob/master/docs/example_service_athenz_setup.md#client-tenant-domain).

### Create the provider domain and add the tenant service to some role members
### Create a provider domain and add the tenant service to role members

On the provider side, you need to do the following things:

1. Create a domain, such as `pulsar`
2. Create a role
3. Add the tenant service to members of the role
1. Create a domain, such as `pulsar`.
2. Create a role.
3. Add the tenant service to the members of the role.

Note that you can specify any action and resource in step 2 since they are not used on Pulsar. In other words, Pulsar uses the Athenz role token only for authentication, *not* for authorization.

For more specific steps involving UI, refer to [Example Service Access Control Setup](https://github.com/AthenZ/athenz/blob/master/docs/example_service_athenz_setup.md#server-provider-domain).
For more specific steps involving the Athenz UI, refer to [Example Service Access Control Setup](https://github.com/AthenZ/athenz/blob/master/docs/example_service_athenz_setup.md#server-provider-domain).

## Enable Athenz authentication on brokers

> ### TLS encryption
>
> Note that when you are using Athenz as an authentication provider, you had better use TLS encryption
> as it can protect role tokens from being intercepted and reused. (for more details involving TLS encryption see [Architecture - Data Model](https://github.com/AthenZ/athenz/blob/master/docs/data_model)).
:::note

When you are using Athenz as an authentication provider, it's highly recommended to use [TLS encryption](security-tls-transport.md) as it can protect role tokens from being intercepted and reused. For more details involving TLS encryption, see [Architecture - Data Model](https://github.com/AthenZ/athenz/blob/master/docs/data_model).

:::

In the `conf/broker.conf` configuration file in your Pulsar installation, you need to provide the class name of the Athenz authentication provider as well as a comma-separated list of provider domain names.

Expand All @@ -52,11 +53,6 @@ authorizationEnabled=true
authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderAthenz
athenzDomainNames=pulsar

# Enable TLS
tlsEnabled=true
tlsCertificateFilePath=/path/to/broker-cert.pem
tlsKeyFilePath=/path/to/broker-key.pem

# Authentication settings of the broker itself. Used when the broker connects to other brokers, either in same or other clusters
brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationAthenz
brokerClientAuthenticationParameters={"tenantDomain":"shopping","tenantService":"some_app","providerDomain":"pulsar","privateKey":"file:///path/to/private.pem","keyId":"v1"}
Expand All @@ -65,18 +61,49 @@ brokerClientAuthenticationParameters={"tenantDomain":"shopping","tenantService":
> A full listing of parameters is available in the `conf/broker.conf` file, you can also find the default
> values for those parameters in [Broker Configuration](reference-configuration.md#broker).
## Enable Athenz authentication on proxies

Configure the required parameters in the `conf/proxy.conf` file in your Pulsar installation.

```properties
# Add the Athenz auth provider
authenticationEnabled=true
authorizationEnabled=true
authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderAthenz
athenzDomainNames=pulsar

brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationAthenz
brokerClientAuthenticationParameters={"tenantDomain":"shopping","tenantService":"some_app","providerDomain":"pulsar","privateKey":"file:///path/to/private.pem","keyId":"v1"}
```

## Configure Athenz authentication in Pulsar clients

To use Athenz as an authentication provider, you need to [use TLS](#tls-encryption) and provide values for four parameters in a hash:
To use Athenz as an authentication provider, you need to provide values for four parameters in a hash:
* `tenantDomain`
* `tenantService`
* `providerDomain`
* `privateKey`

:::tip

The `privateKey` parameter supports the following three pattern formats:
* `file:///path/to/file`
* `file:/path/to/file`
* `data:application/x-pem-file;base64,<base64-encoded value>`

:::

You can also set an optional `keyId`. The following is an example.

````mdx-code-block
<Tabs groupId="lang-choice"
defaultValue="Java"
values={[{"label":"Java","value":"Java"},{"label":"Python","value":"Python"},{"label":"C++","value":"C++"},{"label":"Node.js","value":"Node.js"},{"label":"Go","value":"Go"}]}>
<TabItem value="Java">
```java
Map<String, String> authParams = new HashMap();
authParams.put("ztsUrl", "http://localhost:9998");
authParams.put("tenantDomain", "shopping"); // Tenant domain name
authParams.put("tenantService", "some_app"); // Tenant service name
authParams.put("providerDomain", "pulsar"); // Provider domain name
Expand All @@ -87,17 +114,88 @@ Authentication athenzAuth = AuthenticationFactory
.create(AuthenticationAthenz.class.getName(), authParams);
PulsarClient client = PulsarClient.builder()
.serviceUrl("pulsar+ssl://my-broker.com:6651")
.tlsTrustCertsFilePath("/path/to/cacert.pem")
.serviceUrl("pulsar://my-broker.com:6650")
.authentication(athenzAuth)
.build();
```
#### Supported pattern formats
The `privateKey` parameter supports the following three pattern formats:
* `file:///path/to/file`
* `file:/path/to/file`
* `data:application/x-pem-file;base64,<base64-encoded value>`
</TabItem>
<TabItem value="Python">
```python
authPlugin = "athenz"
authParams = """
{
"tenantDomain": "shopping",
"tenantService": "some_app",
"providerDomain": "pulsar",
"privateKey": "file:///path/to/private.pem",
"ztsUrl": "http://localhost:9998"
}
"""
client = Client(
"pulsar://my-broker.com:6650",
authentication=Authentication(authPlugin, authParams),
)
```
</TabItem>
<TabItem value="C++">
```cpp
std::string params = R"({
"tenantDomain": "shopping",
"tenantService": "some_app",
"providerDomain": "pulsar",
"privateKey": "file:///path/to/private.pem",
"ztsUrl": "http://localhost:9998"
})";
pulsar::AuthenticationPtr auth = pulsar::AuthAthenz::create(params);
ClientConfiguration config = ClientConfiguration();
config.setAuth(auth);
Client client("pulsar://my-broker.com:6650", config);
```
</TabItem>
<TabItem value="Node.js">
```javascript
const auth = new Pulsar.AuthenticationAthenz({
tenantDomain: "shopping",
tenantService: "some_app",
providerDomain: "pulsar",
privateKey: "file:///path/to/private.pem",
ztsUrl: "http://localhost:9998"
});
const client = new Pulsar.Client({
serviceUrl: 'pulsar://my-broker.com:6650',
authentication: auth
});
```
</TabItem>
<TabItem value="Go">
```go
provider := pulsar.NewAuthenticationAthenz(
"pulsar",
"shopping",
"some_app",
"file:///path/to/private.pem",
"v1",
"",
"http://localhost:9998")
client, err := pulsarNewClient(ClientOptions{
URL: "pulsar://my-broker.com:6650",
Authentication: basicAuth,
})
```
</TabItem>
</Tabs>
````

## Configure Athenz authentication in CLI tools

Expand All @@ -117,5 +215,4 @@ authParams={"tenantDomain":"shopping","tenantService":"some_app","providerDomain
useTls=true
tlsAllowInsecureConnection=false
tlsTrustCertsFilePath=/path/to/cacert.pem
```

```
8 changes: 4 additions & 4 deletions site2/docs/security-extending.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ Pulsar provides a way to use custom authentication and authorization mechanisms.
## Authentication

You can use a custom authentication mechanism by providing the implementation in the form of two plugins.
* Client authentication plugin
* Proxy/Broker authentication plugin
* Client authentication plugin `org.apache.pulsar.client.api.AuthenticationDataProvider` provides the authentication data for broker/proxy.
* Broker/Proxy authentication plugin `org.apache.pulsar.broker.authentication.AuthenticationProvider` authenticates the authentication data from clients.

### Client authentication plugin

Expand All @@ -37,9 +37,9 @@ You can find the following examples for different client authentication plugins:
* [OAuth 2.0](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/AuthenticationOAuth2.java)
* [Basic auth](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationBasic.java)

### Proxy/Broker authentication plugin
### Broker/Proxy authentication plugin

On the proxy/broker side, you need to configure the corresponding plugin to validate the credentials that the client sends. The proxy and broker can support multiple authentication providers at the same time.
On the broker/proxy side, you need to configure the corresponding plugin to validate the credentials that the client sends. The proxy and broker can support multiple authentication providers at the same time.

In `conf/broker.conf`, you can choose to specify a list of valid providers:

Expand Down
Loading

0 comments on commit a48bc8b

Please sign in to comment.