Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[improve][doc] Improve the information architecture of the security chapter #17615

Merged
merged 7 commits into from
Sep 20, 2022
Merged

[improve][doc] Improve the information architecture of the security chapter #17615

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
4fd677f
Sidebar re-org
momo-jun Sep 13, 2022
e4b7fcf
Separate TLS encryption/authentication using Keystore to parent topics
momo-jun Sep 13, 2022
0a1ff96
use language-specific tabs to show code snippets
momo-jun Sep 13, 2022
105b468
streamline headings
momo-jun Sep 13, 2022
e2d48d8
Update client-libraries-java.md
momo-jun Sep 14, 2022
bd7f97d
Add code snippet for python clients to support #17482
momo-jun Sep 14, 2022
01d1002
Add code snippet for go clients
momo-jun Sep 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 8 additions & 82 deletions site2/docs/client-libraries-java.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1258,92 +1258,18 @@ For examples of ProtobufNativeSchema, see [`SchemaDefinition` in `Complex type`]

## Authentication

Pulsar currently supports three authentication schemes: [TLS](security-tls-authentication.md), [Athenz](security-athenz.md), and [Oauth2](security-oauth2.md). You can use the Pulsar Java client with all of them.
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)
* [OAuth2](security-oauth2.md#configure-oauth2-authentication-in-pulsar-clients)
* [HTTP basic](security-basic-auth.md#configure-basic-authentication-in-pulsar-clients)

### TLS Authentication

To use [TLS](security-tls-authentication.md), `enableTls` method is deprecated and you need to use "pulsar+ssl://" in serviceUrl to enable, point your Pulsar client to a TLS cert path, and provide paths to cert and key files.

The following is an example.

```java
Map<String, String> authParams = new HashMap();
authParams.put("tlsCertFile", "/path/to/client-cert.pem");
authParams.put("tlsKeyFile", "/path/to/client-key.pem");

Authentication tlsAuth = AuthenticationFactory
.create(AuthenticationTls.class.getName(), authParams);

PulsarClient client = PulsarClient.builder()
.serviceUrl("pulsar+ssl://my-broker.com:6651")
.tlsTrustCertsFilePath("/path/to/cacert.pem")
.authentication(tlsAuth)
.build();
```

### Athenz

To use [Athenz](security-athenz.md) as an authentication provider, you need to [use TLS](#tls-authentication.md) and provide values for four parameters in a hash:

* `tenantDomain`
* `tenantService`
* `providerDomain`
* `privateKey`

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

```java
Map<String, String> authParams = new HashMap();
authParams.put("tenantDomain", "shopping"); // Tenant domain name
authParams.put("tenantService", "some_app"); // Tenant service name
authParams.put("providerDomain", "pulsar"); // Provider domain name
authParams.put("privateKey", "file:///path/to/private.pem"); // Tenant private key path
authParams.put("keyId", "v1"); // Key id for the tenant private key (optional, default: "0")

Authentication athenzAuth = AuthenticationFactory
.create(AuthenticationAthenz.class.getName(), authParams);

PulsarClient client = PulsarClient.builder()
.serviceUrl("pulsar+ssl://my-broker.com:6651")
.tlsTrustCertsFilePath("/path/to/cacert.pem")
.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>`

### Oauth2

The following example shows how to use [Oauth2](security-oauth2.md) as an authentication provider for the Pulsar Java client.

You can use the factory method to configure authentication for Pulsar Java client.

```java
PulsarClient client = PulsarClient.builder()
.serviceUrl("pulsar://broker.example.com:6650/")
.authentication(
AuthenticationFactoryOAuth2.clientCredentials(this.issuerUrl, this.credentialsUrl, this.audience))
.build();
```

In addition, you can also use the encoded parameters to configure authentication for Pulsar Java client.

```java
Authentication auth = AuthenticationFactory
.create(AuthenticationOAuth2.class.getName(), "{"type":"client_credentials","privateKey":"...","issuerUrl":"...","audience":"..."}");
PulsarClient client = PulsarClient.builder()
.serviceUrl("pulsar://broker.example.com:6650/")
.authentication(auth)
.build();
```

## Cluster-level failover

For more concepts and reference information about cluster-level failover, including concept, benefits, use cases, constraints, usage and working principles, see [Cluster-level failover](concepts-cluster-level-failover.md).
For more concepts and reference information about cluster-level failover, including concepts, benefits, use cases, constraints, usage and working principles, see [Cluster-level failover](concepts-cluster-level-failover.md).

:::tip

Expand Down
42 changes: 35 additions & 7 deletions site2/docs/security-athenz.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ title: Authentication using Athenz
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 identify of the client.
[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.

## Athenz authentication settings
## 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.

Expand Down Expand Up @@ -36,7 +36,7 @@ Note that you can specify any action and resource in step 2 since they are not u

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).

## Configure the broker for Athenz
## Enable Athenz authentication on brokers

> ### TLS encryption
>
Expand Down Expand Up @@ -65,13 +65,41 @@ 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).

## Configure clients for Athenz
## Configure Athenz authentication in Pulsar clients

For more information on Pulsar client authentication using Athenz, see the following language-specific docs:
To use Athenz as an authentication provider, you need to [use TLS](#tls-authentication.md) and provide values for four parameters in a hash:
* `tenantDomain`
* `tenantService`
* `providerDomain`
* `privateKey`

* [Java client](client-libraries-java.md#athenz)
You can also set an optional `keyId`. The following is an example.

## Configure CLI tools for Athenz
```java
Map<String, String> authParams = new HashMap();
authParams.put("tenantDomain", "shopping"); // Tenant domain name
authParams.put("tenantService", "some_app"); // Tenant service name
authParams.put("providerDomain", "pulsar"); // Provider domain name
authParams.put("privateKey", "file:///path/to/private.pem"); // Tenant private key path
authParams.put("keyId", "v1"); // Key id for the tenant private key (optional, default: "0")

Authentication athenzAuth = AuthenticationFactory
.create(AuthenticationAthenz.class.getName(), authParams);

PulsarClient client = PulsarClient.builder()
.serviceUrl("pulsar+ssl://my-broker.com:6651")
.tlsTrustCertsFilePath("/path/to/cacert.pem")
.authentication(athenzAuth)
.build();
```

#### Supported pattern formats
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. ### instead of ####?

  2. Other headings are in the format of "Verb + xxx" while this heading is not.

Consider keeping consistent or turning this section into other content formats (like moving lines 97 - 100 to line 74)?

So that users know the relationship between the section Configure Athenz authentication in Pulsar clients and Supported pattern formats

(the info in Supported pattern format can be a part of Configure Athenz authentication in Pulsar clients )

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's copied and pasted here from another topic. I guess the intention was kind of to be a reference sub-topic so that's why #### was used (not shown in the hot links). Thanks for the reminder. It will be evaluated in a further review throughout the topic.

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>`

## Configure Athenz authentication in CLI tools

[Command-line tools](reference-cli-tools.md) like [`pulsar-admin`](/tools/pulsar-admin/), [`pulsar-perf`](reference-cli-tools.md#pulsar-perf), and [`pulsar-client`](reference-cli-tools.md#pulsar-client) use the `conf/client.conf` config file in a Pulsar installation.

Expand Down
31 changes: 28 additions & 3 deletions site2/docs/security-basic-auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,8 +129,11 @@ authParams={"userId":"superuser","password":"admin"}

The following example shows how to configure basic authentication when using Pulsar clients.

<Tabs>
<TabItem value="Java" label="Java" default>
````mdx-code-block
<Tabs groupId="lang-choice"
defaultValue="Java"
values={[{"label":"Java","value":"Java"},{"label":"Python","value":"Python"},{"label":"C++","value":"C++"},{"label":"Go","value":"Go"}]}>
<TabItem value="Java">

```java
AuthenticationBasic auth = new AuthenticationBasic();
Expand All @@ -142,7 +145,7 @@ The following example shows how to configure basic authentication when using Pul
```

</TabItem>
<TabItem value="C++" label="C++" default>
<TabItem value="C++">

```cpp
#include <pulsar/Client.h>
Expand All @@ -158,4 +161,26 @@ The following example shows how to configure basic authentication when using Pul
```

</TabItem>
<TabItem value="Python">

```python
if __name__ == "__main__":
client = Client("pulsar://broker.example.com:6650", authentication=AuthenticationBasic("admin", "123456"))
```

</TabItem>
<TabItem value="Go">

```go
provider, err := pulsar.NewAuthenticationBasic("admin", "123456")
if err != nil {
log.Fatal(err)
}
client, err := pulsar.NewClient(pulsar.ClientOptions{
URL: "pulsar://broker.example.com:6650",
Authentication: provider,
})
```

</TabItem>
</Tabs>
Loading