You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by ur...@apache.org on 2022/03/18 12:03:04 UTC
[pulsar-site] branch main updated: Docs sync done from apache/pulsar(#86442ee)
This is an automated email from the ASF dual-hosted git repository.
urfree pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new fe43a8d Docs sync done from apache/pulsar(#86442ee)
fe43a8d is described below
commit fe43a8db0fd5da442906fc0d3081a6353b1717e3
Author: Pulsar Site Updater <de...@pulsar.apache.org>
AuthorDate: Fri Mar 18 12:02:56 2022 +0000
Docs sync done from apache/pulsar(#86442ee)
---
site2/docs/security-extending.md | 181 ++++----------------
site2/docs/security-oauth2.md | 52 +++++-
site2/docs/security-overview.md | 10 +-
site2/website-next/docs/security-extending.md | 186 ++++-----------------
site2/website-next/docs/security-oauth2.md | 60 ++++++-
site2/website-next/docs/security-overview.md | 10 +-
.../version-2.2.0/security-overview.md | 10 +-
.../version-2.2.1/security-extending.md | 186 ++++-----------------
.../version-2.2.1/security-overview.md | 10 +-
.../version-2.3.0/security-extending.md | 186 ++++-----------------
.../version-2.3.0/security-overview.md | 10 +-
.../version-2.3.1/security-extending.md | 186 ++++-----------------
.../version-2.3.1/security-overview.md | 10 +-
.../version-2.3.2/security-extending.md | 186 ++++-----------------
.../version-2.4.0/security-extending.md | 186 ++++-----------------
.../version-2.4.1/security-extending.md | 186 ++++-----------------
.../version-2.4.2/security-extending.md | 186 ++++-----------------
.../version-2.5.1/security-extending.md | 186 ++++-----------------
.../version-2.5.1/security-overview.md | 10 +-
.../version-2.5.2/security-extending.md | 186 ++++-----------------
.../version-2.5.2/security-overview.md | 10 +-
21 files changed, 490 insertions(+), 1743 deletions(-)
diff --git a/site2/docs/security-extending.md b/site2/docs/security-extending.md
index d7e5d90..ce8b5dd 100644
--- a/site2/docs/security-extending.md
+++ b/site2/docs/security-extending.md
@@ -1,20 +1,20 @@
---
id: security-extending
-title: Extending Authentication and Authorization in Pulsar
-sidebar_label: Extending
+title: Extend Authentication and Authorization in Pulsar
+sidebar_label: Extend Authentication and Authorization
---
Pulsar provides a way to use custom authentication and authorization mechanisms.
## Authentication
-Pulsar supports mutual TLS and Athenz authentication plugins. For how to use these authentication plugins, you can refer to the description in [Security](security-overview.md).
-
-You can use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Proxy and/or Pulsar Broker to validate the credentials.
+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
-For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below you can pass this class when you create a Pulsar client:
+For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below, you can pass this class when you create a Pulsar client.
```java
PulsarClient client = PulsarClient.builder()
@@ -23,173 +23,54 @@ PulsarClient client = PulsarClient.builder()
.build();
```
-You can use 2 interfaces to implement on the client side:
- * `Authentication` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html
- * `AuthenticationDataProvider` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html
-
-
-This in turn needs to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider`. This leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
+You can implement 2 interfaces on the client side:
+ * [`Authentication`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html)
+ * [`AuthenticationDataProvider`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html)
+This in turn requires you to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider` and also leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
-You can find examples for client authentication providers at:
-
- * Mutual TLS Auth -- https://github.com/apache/pulsar/tree/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth
- * Athenz -- https://github.com/apache/pulsar/tree/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth
+You can find the following examples for different client authentication plugins:
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-sasl/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationToken.java)
+ * [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
-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 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.
-In `conf/broker.conf` you can choose to specify a list of valid providers:
+In `conf/broker.conf`, you can choose to specify a list of valid providers:
```properties
# Authentication provider name list, which is comma separated list of class names
authenticationProviders=
```
-To implement `org.apache.pulsar.broker.authentication.AuthenticationProvider` on one single interface:
-```java
-/**
- * Provider of authentication mechanism
- */
-public interface AuthenticationProvider extends Closeable {
-
- /**
- * Perform initialization for the authentication provider
- *
- * @param config
- * broker config object
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration config) throws IOException;
-
- /**
- * @return the authentication method name supported by this provider
- */
- String getAuthMethodName();
-
- /**
- * Validate the authentication for the given credentials with the specified authentication data
- *
- * @param authData
- * provider specific authentication data
- * @return the "role" string for the authenticated connection, if the authentication was successful
- * @throws AuthenticationException
- * if the credentials are not valid
- */
- String authenticate(AuthenticationDataSource authData) throws AuthenticationException;
-
-}
-```
+For the implementation of the `org.apache.pulsar.broker.authentication.AuthenticationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProvider.java).
-The following is the example for Broker authentication plugins:
+You can find the following examples for different broker authentication plugins:
- * Mutual TLS -- https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java
- * Athenz -- https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-sasl/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
+ * [Basic auth](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
## Authorization
Authorization is the operation that checks whether a particular "role" or "principal" has permission to perform a certain operation.
-By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin.
-Note that although the Authentication plugin is designed for use in both the Proxy and Broker,
-the Authorization plugin is designed only for use on the Broker however the Proxy does perform some simple Authorization checks of Roles if authorization is enabled.
+By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin. Note that although the Authentication plugin is designed for use in both the proxy and broker, the Authorization plugin is designed only for use on the broker.
+
+### Broker authorization plugin
-To provide a custom provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
+To provide a custom authorization provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
```properties
# Authorization provider fully qualified class-name
authorizationProvider=org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider
```
-```java
-/**
- * Provider of authorization mechanism
- */
-public interface AuthorizationProvider extends Closeable {
-
- /**
- * Perform initialization for the authorization provider
- *
- * @param conf
- * broker config object
- * @param configCache
- * pulsar zk configuration cache service
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration conf, ConfigurationCacheService configCache) throws IOException;
-
- /**
- * Check if the specified role has permission to send messages to the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to send messages to the topic.
- */
- CompletableFuture<Boolean> canProduceAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- * Check if the specified role has permission to receive messages from the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to receive messages from the topic.
- * @param subscription
- * the subscription name defined by the client
- */
- CompletableFuture<Boolean> canConsumeAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData, String subscription);
-
- /**
- * Check whether the specified role can perform a lookup for the specified topic.
- *
- * For that the caller needs to have producer or consumer permission.
- *
- * @param topicName
- * @param role
- * @return
- * @throws Exception
- */
- CompletableFuture<Boolean> canLookupAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- *
- * Grant authorization-action permission on a namespace to the given client
- *
- * @param namespace
- * @param actions
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br/>
- * IllegalArgumentException when namespace not found<br/>
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(NamespaceName namespace, Set<AuthAction> actions, String role,
- String authDataJson);
-
- /**
- * Grant authorization-action permission on a topic to the given client
- *
- * @param topicName
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br/>
- * IllegalArgumentException when namespace not found<br/>
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(TopicName topicName, Set<AuthAction> actions, String role,
- String authDataJson);
-
-}
-
-```
+For the implementation of the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authorization/AuthorizationProvider.java).
\ No newline at end of file
diff --git a/site2/docs/security-oauth2.md b/site2/docs/security-oauth2.md
index cbb4f9e..7bb12ee 100644
--- a/site2/docs/security-oauth2.md
+++ b/site2/docs/security-oauth2.md
@@ -6,7 +6,7 @@ sidebar_label: Authentication using OAuth 2.0 access tokens
Pulsar supports authenticating clients using OAuth 2.0 access tokens. You can use OAuth 2.0 access tokens to identify a Pulsar client and associate the Pulsar client with some "principal" (or "role"), which is permitted to do some actions, such as publishing messages to a topic or consume messages from a topic.
-This module is used to support the Pulsar client authentication plugin for OAuth 2.0. After communicating with the Oauth 2.0 server, the Pulsar client gets an `access token` from the Oauth 2.0 server, and passes this `access token` to the Pulsar broker to do the authentication. The broker can use the `org.apache.pulsar.broker.authentication.AuthenticationProviderToken`. Or, you can add your own `AuthenticationProvider` to make it with this module.
+This module is used to support the [Pulsar client authentication plugin](security-extending.md/#client-authentication-plugin) for OAuth 2.0. After communicating with the OAuth 2.0 server, the Pulsar client gets an `access token` from the OAuth 2.0 server, and passes this `access token` to the Pulsar broker to do the authentication. The broker can use the `org.apache.pulsar.broker.authentication.AuthenticationProviderToken`. Or, you can add your own `AuthenticationProvider` to make it wit [...]
## Authentication provider configuration
@@ -16,7 +16,7 @@ This library allows you to authenticate the Pulsar client by using an access tok
The authentication type determines how to obtain an access token through an OAuth 2.0 authorization flow.
-#### Note
+> Note
> Currently, the Pulsar Java client only supports the `client_credentials` authentication type .
#### Client credentials
@@ -25,7 +25,7 @@ The following table lists parameters supported for the `client credentials` auth
| Parameter | Description | Example | Required or not |
| --- | --- | --- | --- |
-| `type` | Oauth 2.0 authentication type. | `client_credentials` (default) | Optional |
+| `type` | OAuth 2.0 authentication type. | `client_credentials` (default) | Optional |
| `issuerUrl` | URL of the authentication provider which allows the Pulsar client to obtain an access token | `https://accounts.google.com` | Required |
| `privateKey` | URL to a JSON credentials file | Support the following pattern formats: <br> <li> `file:///path/to/file` <li>`file:/path/to/file` <li> `data:application/json;base64,<base64-encoded value>` | Required |
| `audience` | An OAuth 2.0 "resource server" identifier for the Pulsar cluster | `https://broker.example.com` | Optional |
@@ -70,7 +70,7 @@ In the above example, the mapping relationship is shown as below.
You can use the OAuth2 authentication provider with the following Pulsar clients.
-### Java
+### Java client
You can use the factory method to configure authentication for Pulsar Java client.
@@ -99,7 +99,7 @@ PulsarClient client = PulsarClient.builder()
### C++ client
-The C++ client is similar to the Java client. You need to provide parameters of `issuerUrl`, `private_key` (the credentials file path), and `audience`.
+The C++ client is similar to the Java client. You need to provide the parameters of `issuerUrl`, `private_key` (the credentials file path), and `audience`.
```c++
#include <pulsar/Client.h>
@@ -153,6 +153,48 @@ params = '''
client = Client("pulsar://my-cluster:6650", authentication=AuthenticationOauth2(params))
```
+### Node.js client
+
+To enable OAuth2 authentication in Node.js client, you need to configure OAuth2 authentication.
+This example shows how to configure OAuth2 authentication in Node.js client.
+
+```JavaScript
+ const Pulsar = require('pulsar-client');
+ const issuer_url = process.env.ISSUER_URL;
+ const private_key = process.env.PRIVATE_KEY;
+ const audience = process.env.AUDIENCE;
+ const scope = process.env.SCOPE;
+ const service_url = process.env.SERVICE_URL;
+ const client_id = process.env.CLIENT_ID;
+ const client_secret = process.env.CLIENT_SECRET;
+ (async () => {
+ const params = {
+ issuer_url: issuer_url
+ }
+ if (private_key.length > 0) {
+ params['private_key'] = private_key
+ } else {
+ params['client_id'] = client_id
+ params['client_secret'] = client_secret
+ }
+ if (audience.length > 0) {
+ params['audience'] = audience
+ }
+ if (scope.length > 0) {
+ params['scope'] = scope
+ }
+ const auth = new Pulsar.AuthenticationOauth2(params);
+ // Create a client
+ const client = new Pulsar.Client({
+ serviceUrl: service_url,
+ tlsAllowInsecureConnection: true,
+ authentication: auth,
+ });
+ await client.close();
+ })();
+```
+> Note: The support for OAuth2 authentication is only available in Node.js client 1.6.2 and later versions.
+
## CLI configuration
This section describes how to use Pulsar CLI tools to connect a cluster through OAuth2 authentication plugin.
diff --git a/site2/docs/security-overview.md b/site2/docs/security-overview.md
index a6de902..c9ca445 100644
--- a/site2/docs/security-overview.md
+++ b/site2/docs/security-overview.md
@@ -26,9 +26,11 @@ Apache Pulsar uses a [Authentication Provider](#authentication-providers) to est
Currently Pulsar supports the following authentication providers:
-- [TLS Authentication](security-tls-authentication.md)
-- [Athenz](security-athenz.md)
-- [Kerberos](security-kerberos.md)
-- [JSON Web Token Authentication](security-jwt.md)
+- [TLS authentication](security-tls-authentication.md)
+- [Athenz authentication](security-athenz.md)
+- [Kerberos authentication](security-kerberos.md)
+- [JSON Web Token (JWT) authentication](security-jwt.md)
+- [OAuth 2.0 authentication](security-oauth2.md)
+- Basic authentication
diff --git a/site2/website-next/docs/security-extending.md b/site2/website-next/docs/security-extending.md
index dd0030e..3d3fde6 100644
--- a/site2/website-next/docs/security-extending.md
+++ b/site2/website-next/docs/security-extending.md
@@ -1,20 +1,20 @@
---
id: security-extending
-title: Extending Authentication and Authorization in Pulsar
-sidebar_label: "Extending"
+title: Extend Authentication and Authorization in Pulsar
+sidebar_label: "Extend Authentication and Authorization"
---
Pulsar provides a way to use custom authentication and authorization mechanisms.
## Authentication
-Pulsar supports mutual TLS and Athenz authentication plugins. For how to use these authentication plugins, you can refer to the description in [Security](security-overview).
-
-You can use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Proxy and/or Pulsar Broker to validate the credentials.
+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
-For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below you can pass this class when you create a Pulsar client:
+For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below, you can pass this class when you create a Pulsar client.
```java
@@ -25,24 +25,25 @@ PulsarClient client = PulsarClient.builder()
```
-You can use 2 interfaces to implement on the client side:
- * `Authentication` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html
- * `AuthenticationDataProvider` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html
-
-
-This in turn needs to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider`. This leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
-
+You can implement 2 interfaces on the client side:
+ * [`Authentication`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html)
+ * [`AuthenticationDataProvider`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html)
-You can find examples for client authentication providers at:
+This in turn requires you to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider` and also leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
- * Mutual TLS Auth -- https://github.com/apache/pulsar/tree/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth
- * Athenz -- https://github.com/apache/pulsar/tree/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth
+You can find the following examples for different client authentication plugins:
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-sasl/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationToken.java)
+ * [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
-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 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.
-In `conf/broker.conf` you can choose to specify a list of valid providers:
+In `conf/broker.conf`, you can choose to specify a list of valid providers:
```properties
@@ -51,59 +52,25 @@ authenticationProviders=
```
-To implement `org.apache.pulsar.broker.authentication.AuthenticationProvider` on one single interface:
+For the implementation of the `org.apache.pulsar.broker.authentication.AuthenticationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProvider.java).
-```java
-
-/**
- * Provider of authentication mechanism
- */
-public interface AuthenticationProvider extends Closeable {
-
- /**
- * Perform initialization for the authentication provider
- *
- * @param config
- * broker config object
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration config) throws IOException;
-
- /**
- * @return the authentication method name supported by this provider
- */
- String getAuthMethodName();
-
- /**
- * Validate the authentication for the given credentials with the specified authentication data
- *
- * @param authData
- * provider specific authentication data
- * @return the "role" string for the authenticated connection, if the authentication was successful
- * @throws AuthenticationException
- * if the credentials are not valid
- */
- String authenticate(AuthenticationDataSource authData) throws AuthenticationException;
-
-}
-
-```
+You can find the following examples for different broker authentication plugins:
-The following is the example for Broker authentication plugins:
-
- * Mutual TLS -- https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java
- * Athenz -- https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-sasl/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
+ * [Basic auth](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
## Authorization
Authorization is the operation that checks whether a particular "role" or "principal" has permission to perform a certain operation.
-By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin.
-Note that although the Authentication plugin is designed for use in both the Proxy and Broker,
-the Authorization plugin is designed only for use on the Broker however the Proxy does perform some simple Authorization checks of Roles if authorization is enabled.
+By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin. Note that although the Authentication plugin is designed for use in both the proxy and broker, the Authorization plugin is designed only for use on the broker.
+
+### Broker authorization plugin
-To provide a custom provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
+To provide a custom authorization provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
```properties
@@ -112,95 +79,4 @@ To provide a custom provider, you need to implement the `org.apache.pulsar.broke
```
-```java
-
-/**
- * Provider of authorization mechanism
- */
-public interface AuthorizationProvider extends Closeable {
-
- /**
- * Perform initialization for the authorization provider
- *
- * @param conf
- * broker config object
- * @param configCache
- * pulsar zk configuration cache service
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration conf, ConfigurationCacheService configCache) throws IOException;
-
- /**
- * Check if the specified role has permission to send messages to the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to send messages to the topic.
- */
- CompletableFuture<Boolean> canProduceAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- * Check if the specified role has permission to receive messages from the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to receive messages from the topic.
- * @param subscription
- * the subscription name defined by the client
- */
- CompletableFuture<Boolean> canConsumeAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData, String subscription);
-
- /**
- * Check whether the specified role can perform a lookup for the specified topic.
- *
- * For that the caller needs to have producer or consumer permission.
- *
- * @param topicName
- * @param role
- * @return
- * @throws Exception
- */
- CompletableFuture<Boolean> canLookupAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- *
- * Grant authorization-action permission on a namespace to the given client
- *
- * @param namespace
- * @param actions
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(NamespaceName namespace, Set<AuthAction> actions, String role,
- String authDataJson);
-
- /**
- * Grant authorization-action permission on a topic to the given client
- *
- * @param topicName
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(TopicName topicName, Set<AuthAction> actions, String role,
- String authDataJson);
-
-}
-
-```
-
+For the implementation of the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authorization/AuthorizationProvider.java).
\ No newline at end of file
diff --git a/site2/website-next/docs/security-oauth2.md b/site2/website-next/docs/security-oauth2.md
index eb0ccdb..7545742 100644
--- a/site2/website-next/docs/security-oauth2.md
+++ b/site2/website-next/docs/security-oauth2.md
@@ -6,7 +6,7 @@ sidebar_label: "Authentication using OAuth 2.0 access tokens"
Pulsar supports authenticating clients using OAuth 2.0 access tokens. You can use OAuth 2.0 access tokens to identify a Pulsar client and associate the Pulsar client with some "principal" (or "role"), which is permitted to do some actions, such as publishing messages to a topic or consume messages from a topic.
-This module is used to support the Pulsar client authentication plugin for OAuth 2.0. After communicating with the Oauth 2.0 server, the Pulsar client gets an `access token` from the Oauth 2.0 server, and passes this `access token` to the Pulsar broker to do the authentication. The broker can use the `org.apache.pulsar.broker.authentication.AuthenticationProviderToken`. Or, you can add your own `AuthenticationProvider` to make it with this module.
+This module is used to support the [Pulsar client authentication plugin](security-extending.md/#client-authentication-plugin) for OAuth 2.0. After communicating with the OAuth 2.0 server, the Pulsar client gets an `access token` from the OAuth 2.0 server, and passes this `access token` to the Pulsar broker to do the authentication. The broker can use the `org.apache.pulsar.broker.authentication.AuthenticationProviderToken`. Or, you can add your own `AuthenticationProvider` to make it wit [...]
## Authentication provider configuration
@@ -16,8 +16,11 @@ This library allows you to authenticate the Pulsar client by using an access tok
The authentication type determines how to obtain an access token through an OAuth 2.0 authorization flow.
-#### Note
-> Currently, the Pulsar Java client only supports the `client_credentials` authentication type .
+:::note
+
+Currently, the Pulsar Java client only supports the `client_credentials` authentication type .
+
+:::
#### Client credentials
@@ -25,7 +28,7 @@ The following table lists parameters supported for the `client credentials` auth
| Parameter | Description | Example | Required or not |
| --- | --- | --- | --- |
-| `type` | Oauth 2.0 authentication type. | `client_credentials` (default) | Optional |
+| `type` | OAuth 2.0 authentication type. | `client_credentials` (default) | Optional |
| `issuerUrl` | URL of the authentication provider which allows the Pulsar client to obtain an access token | `https://accounts.google.com` | Required |
| `privateKey` | URL to a JSON credentials file | Support the following pattern formats: <br /> <li> `file:///path/to/file` </li><li>`file:/path/to/file` </li><li> `data:application/json;base64,<base64-encoded value>` </li>| Required |
| `audience` | An OAuth 2.0 "resource server" identifier for the Pulsar cluster | `https://broker.example.com` | Optional |
@@ -74,7 +77,7 @@ In the above example, the mapping relationship is shown as below.
You can use the OAuth2 authentication provider with the following Pulsar clients.
-### Java
+### Java client
You can use the factory method to configure authentication for Pulsar Java client.
@@ -107,7 +110,7 @@ PulsarClient client = PulsarClient.builder()
### C++ client
-The C++ client is similar to the Java client. You need to provide parameters of `issuerUrl`, `private_key` (the credentials file path), and `audience`.
+The C++ client is similar to the Java client. You need to provide the parameters of `issuerUrl`, `private_key` (the credentials file path), and `audience`.
```c++
@@ -167,6 +170,51 @@ client = Client("pulsar://my-cluster:6650", authentication=AuthenticationOauth2(
```
+### Node.js client
+
+To enable OAuth2 authentication in Node.js client, you need to configure OAuth2 authentication.
+This example shows how to configure OAuth2 authentication in Node.js client.
+
+```JavaScript
+
+ const Pulsar = require('pulsar-client');
+ const issuer_url = process.env.ISSUER_URL;
+ const private_key = process.env.PRIVATE_KEY;
+ const audience = process.env.AUDIENCE;
+ const scope = process.env.SCOPE;
+ const service_url = process.env.SERVICE_URL;
+ const client_id = process.env.CLIENT_ID;
+ const client_secret = process.env.CLIENT_SECRET;
+ (async () => {
+ const params = {
+ issuer_url: issuer_url
+ }
+ if (private_key.length > 0) {
+ params['private_key'] = private_key
+ } else {
+ params['client_id'] = client_id
+ params['client_secret'] = client_secret
+ }
+ if (audience.length > 0) {
+ params['audience'] = audience
+ }
+ if (scope.length > 0) {
+ params['scope'] = scope
+ }
+ const auth = new Pulsar.AuthenticationOauth2(params);
+ // Create a client
+ const client = new Pulsar.Client({
+ serviceUrl: service_url,
+ tlsAllowInsecureConnection: true,
+ authentication: auth,
+ });
+ await client.close();
+ })();
+
+```
+
+> Note: The support for OAuth2 authentication is only available in Node.js client 1.6.2 and later versions.
+
## CLI configuration
This section describes how to use Pulsar CLI tools to connect a cluster through OAuth2 authentication plugin.
diff --git a/site2/website-next/docs/security-overview.md b/site2/website-next/docs/security-overview.md
index 91f4ba8..8cbaa09 100644
--- a/site2/website-next/docs/security-overview.md
+++ b/site2/website-next/docs/security-overview.md
@@ -26,9 +26,11 @@ Apache Pulsar uses a [Authentication Provider](#authentication-providers) to est
Currently Pulsar supports the following authentication providers:
-- [TLS Authentication](security-tls-authentication)
-- [Athenz](security-athenz)
-- [Kerberos](security-kerberos)
-- [JSON Web Token Authentication](security-jwt)
+- [TLS authentication](security-tls-authentication)
+- [Athenz authentication](security-athenz)
+- [Kerberos authentication](security-kerberos)
+- [JSON Web Token (JWT) authentication](security-jwt)
+- [OAuth 2.0 authentication](security-oauth2)
+- Basic authentication
diff --git a/site2/website-next/versioned_docs/version-2.2.0/security-overview.md b/site2/website-next/versioned_docs/version-2.2.0/security-overview.md
index 91f4ba8..8cbaa09 100644
--- a/site2/website-next/versioned_docs/version-2.2.0/security-overview.md
+++ b/site2/website-next/versioned_docs/version-2.2.0/security-overview.md
@@ -26,9 +26,11 @@ Apache Pulsar uses a [Authentication Provider](#authentication-providers) to est
Currently Pulsar supports the following authentication providers:
-- [TLS Authentication](security-tls-authentication)
-- [Athenz](security-athenz)
-- [Kerberos](security-kerberos)
-- [JSON Web Token Authentication](security-jwt)
+- [TLS authentication](security-tls-authentication)
+- [Athenz authentication](security-athenz)
+- [Kerberos authentication](security-kerberos)
+- [JSON Web Token (JWT) authentication](security-jwt)
+- [OAuth 2.0 authentication](security-oauth2)
+- Basic authentication
diff --git a/site2/website-next/versioned_docs/version-2.2.1/security-extending.md b/site2/website-next/versioned_docs/version-2.2.1/security-extending.md
index dd0030e..3d3fde6 100644
--- a/site2/website-next/versioned_docs/version-2.2.1/security-extending.md
+++ b/site2/website-next/versioned_docs/version-2.2.1/security-extending.md
@@ -1,20 +1,20 @@
---
id: security-extending
-title: Extending Authentication and Authorization in Pulsar
-sidebar_label: "Extending"
+title: Extend Authentication and Authorization in Pulsar
+sidebar_label: "Extend Authentication and Authorization"
---
Pulsar provides a way to use custom authentication and authorization mechanisms.
## Authentication
-Pulsar supports mutual TLS and Athenz authentication plugins. For how to use these authentication plugins, you can refer to the description in [Security](security-overview).
-
-You can use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Proxy and/or Pulsar Broker to validate the credentials.
+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
-For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below you can pass this class when you create a Pulsar client:
+For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below, you can pass this class when you create a Pulsar client.
```java
@@ -25,24 +25,25 @@ PulsarClient client = PulsarClient.builder()
```
-You can use 2 interfaces to implement on the client side:
- * `Authentication` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html
- * `AuthenticationDataProvider` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html
-
-
-This in turn needs to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider`. This leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
-
+You can implement 2 interfaces on the client side:
+ * [`Authentication`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html)
+ * [`AuthenticationDataProvider`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html)
-You can find examples for client authentication providers at:
+This in turn requires you to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider` and also leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
- * Mutual TLS Auth -- https://github.com/apache/pulsar/tree/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth
- * Athenz -- https://github.com/apache/pulsar/tree/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth
+You can find the following examples for different client authentication plugins:
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-sasl/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationToken.java)
+ * [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
-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 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.
-In `conf/broker.conf` you can choose to specify a list of valid providers:
+In `conf/broker.conf`, you can choose to specify a list of valid providers:
```properties
@@ -51,59 +52,25 @@ authenticationProviders=
```
-To implement `org.apache.pulsar.broker.authentication.AuthenticationProvider` on one single interface:
+For the implementation of the `org.apache.pulsar.broker.authentication.AuthenticationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProvider.java).
-```java
-
-/**
- * Provider of authentication mechanism
- */
-public interface AuthenticationProvider extends Closeable {
-
- /**
- * Perform initialization for the authentication provider
- *
- * @param config
- * broker config object
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration config) throws IOException;
-
- /**
- * @return the authentication method name supported by this provider
- */
- String getAuthMethodName();
-
- /**
- * Validate the authentication for the given credentials with the specified authentication data
- *
- * @param authData
- * provider specific authentication data
- * @return the "role" string for the authenticated connection, if the authentication was successful
- * @throws AuthenticationException
- * if the credentials are not valid
- */
- String authenticate(AuthenticationDataSource authData) throws AuthenticationException;
-
-}
-
-```
+You can find the following examples for different broker authentication plugins:
-The following is the example for Broker authentication plugins:
-
- * Mutual TLS -- https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java
- * Athenz -- https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-sasl/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
+ * [Basic auth](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
## Authorization
Authorization is the operation that checks whether a particular "role" or "principal" has permission to perform a certain operation.
-By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin.
-Note that although the Authentication plugin is designed for use in both the Proxy and Broker,
-the Authorization plugin is designed only for use on the Broker however the Proxy does perform some simple Authorization checks of Roles if authorization is enabled.
+By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin. Note that although the Authentication plugin is designed for use in both the proxy and broker, the Authorization plugin is designed only for use on the broker.
+
+### Broker authorization plugin
-To provide a custom provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
+To provide a custom authorization provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
```properties
@@ -112,95 +79,4 @@ To provide a custom provider, you need to implement the `org.apache.pulsar.broke
```
-```java
-
-/**
- * Provider of authorization mechanism
- */
-public interface AuthorizationProvider extends Closeable {
-
- /**
- * Perform initialization for the authorization provider
- *
- * @param conf
- * broker config object
- * @param configCache
- * pulsar zk configuration cache service
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration conf, ConfigurationCacheService configCache) throws IOException;
-
- /**
- * Check if the specified role has permission to send messages to the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to send messages to the topic.
- */
- CompletableFuture<Boolean> canProduceAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- * Check if the specified role has permission to receive messages from the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to receive messages from the topic.
- * @param subscription
- * the subscription name defined by the client
- */
- CompletableFuture<Boolean> canConsumeAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData, String subscription);
-
- /**
- * Check whether the specified role can perform a lookup for the specified topic.
- *
- * For that the caller needs to have producer or consumer permission.
- *
- * @param topicName
- * @param role
- * @return
- * @throws Exception
- */
- CompletableFuture<Boolean> canLookupAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- *
- * Grant authorization-action permission on a namespace to the given client
- *
- * @param namespace
- * @param actions
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(NamespaceName namespace, Set<AuthAction> actions, String role,
- String authDataJson);
-
- /**
- * Grant authorization-action permission on a topic to the given client
- *
- * @param topicName
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(TopicName topicName, Set<AuthAction> actions, String role,
- String authDataJson);
-
-}
-
-```
-
+For the implementation of the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authorization/AuthorizationProvider.java).
\ No newline at end of file
diff --git a/site2/website-next/versioned_docs/version-2.2.1/security-overview.md b/site2/website-next/versioned_docs/version-2.2.1/security-overview.md
index 91f4ba8..8cbaa09 100644
--- a/site2/website-next/versioned_docs/version-2.2.1/security-overview.md
+++ b/site2/website-next/versioned_docs/version-2.2.1/security-overview.md
@@ -26,9 +26,11 @@ Apache Pulsar uses a [Authentication Provider](#authentication-providers) to est
Currently Pulsar supports the following authentication providers:
-- [TLS Authentication](security-tls-authentication)
-- [Athenz](security-athenz)
-- [Kerberos](security-kerberos)
-- [JSON Web Token Authentication](security-jwt)
+- [TLS authentication](security-tls-authentication)
+- [Athenz authentication](security-athenz)
+- [Kerberos authentication](security-kerberos)
+- [JSON Web Token (JWT) authentication](security-jwt)
+- [OAuth 2.0 authentication](security-oauth2)
+- Basic authentication
diff --git a/site2/website-next/versioned_docs/version-2.3.0/security-extending.md b/site2/website-next/versioned_docs/version-2.3.0/security-extending.md
index dd0030e..3d3fde6 100644
--- a/site2/website-next/versioned_docs/version-2.3.0/security-extending.md
+++ b/site2/website-next/versioned_docs/version-2.3.0/security-extending.md
@@ -1,20 +1,20 @@
---
id: security-extending
-title: Extending Authentication and Authorization in Pulsar
-sidebar_label: "Extending"
+title: Extend Authentication and Authorization in Pulsar
+sidebar_label: "Extend Authentication and Authorization"
---
Pulsar provides a way to use custom authentication and authorization mechanisms.
## Authentication
-Pulsar supports mutual TLS and Athenz authentication plugins. For how to use these authentication plugins, you can refer to the description in [Security](security-overview).
-
-You can use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Proxy and/or Pulsar Broker to validate the credentials.
+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
-For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below you can pass this class when you create a Pulsar client:
+For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below, you can pass this class when you create a Pulsar client.
```java
@@ -25,24 +25,25 @@ PulsarClient client = PulsarClient.builder()
```
-You can use 2 interfaces to implement on the client side:
- * `Authentication` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html
- * `AuthenticationDataProvider` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html
-
-
-This in turn needs to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider`. This leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
-
+You can implement 2 interfaces on the client side:
+ * [`Authentication`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html)
+ * [`AuthenticationDataProvider`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html)
-You can find examples for client authentication providers at:
+This in turn requires you to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider` and also leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
- * Mutual TLS Auth -- https://github.com/apache/pulsar/tree/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth
- * Athenz -- https://github.com/apache/pulsar/tree/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth
+You can find the following examples for different client authentication plugins:
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-sasl/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationToken.java)
+ * [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
-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 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.
-In `conf/broker.conf` you can choose to specify a list of valid providers:
+In `conf/broker.conf`, you can choose to specify a list of valid providers:
```properties
@@ -51,59 +52,25 @@ authenticationProviders=
```
-To implement `org.apache.pulsar.broker.authentication.AuthenticationProvider` on one single interface:
+For the implementation of the `org.apache.pulsar.broker.authentication.AuthenticationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProvider.java).
-```java
-
-/**
- * Provider of authentication mechanism
- */
-public interface AuthenticationProvider extends Closeable {
-
- /**
- * Perform initialization for the authentication provider
- *
- * @param config
- * broker config object
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration config) throws IOException;
-
- /**
- * @return the authentication method name supported by this provider
- */
- String getAuthMethodName();
-
- /**
- * Validate the authentication for the given credentials with the specified authentication data
- *
- * @param authData
- * provider specific authentication data
- * @return the "role" string for the authenticated connection, if the authentication was successful
- * @throws AuthenticationException
- * if the credentials are not valid
- */
- String authenticate(AuthenticationDataSource authData) throws AuthenticationException;
-
-}
-
-```
+You can find the following examples for different broker authentication plugins:
-The following is the example for Broker authentication plugins:
-
- * Mutual TLS -- https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java
- * Athenz -- https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-sasl/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
+ * [Basic auth](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
## Authorization
Authorization is the operation that checks whether a particular "role" or "principal" has permission to perform a certain operation.
-By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin.
-Note that although the Authentication plugin is designed for use in both the Proxy and Broker,
-the Authorization plugin is designed only for use on the Broker however the Proxy does perform some simple Authorization checks of Roles if authorization is enabled.
+By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin. Note that although the Authentication plugin is designed for use in both the proxy and broker, the Authorization plugin is designed only for use on the broker.
+
+### Broker authorization plugin
-To provide a custom provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
+To provide a custom authorization provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
```properties
@@ -112,95 +79,4 @@ To provide a custom provider, you need to implement the `org.apache.pulsar.broke
```
-```java
-
-/**
- * Provider of authorization mechanism
- */
-public interface AuthorizationProvider extends Closeable {
-
- /**
- * Perform initialization for the authorization provider
- *
- * @param conf
- * broker config object
- * @param configCache
- * pulsar zk configuration cache service
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration conf, ConfigurationCacheService configCache) throws IOException;
-
- /**
- * Check if the specified role has permission to send messages to the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to send messages to the topic.
- */
- CompletableFuture<Boolean> canProduceAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- * Check if the specified role has permission to receive messages from the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to receive messages from the topic.
- * @param subscription
- * the subscription name defined by the client
- */
- CompletableFuture<Boolean> canConsumeAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData, String subscription);
-
- /**
- * Check whether the specified role can perform a lookup for the specified topic.
- *
- * For that the caller needs to have producer or consumer permission.
- *
- * @param topicName
- * @param role
- * @return
- * @throws Exception
- */
- CompletableFuture<Boolean> canLookupAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- *
- * Grant authorization-action permission on a namespace to the given client
- *
- * @param namespace
- * @param actions
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(NamespaceName namespace, Set<AuthAction> actions, String role,
- String authDataJson);
-
- /**
- * Grant authorization-action permission on a topic to the given client
- *
- * @param topicName
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(TopicName topicName, Set<AuthAction> actions, String role,
- String authDataJson);
-
-}
-
-```
-
+For the implementation of the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authorization/AuthorizationProvider.java).
\ No newline at end of file
diff --git a/site2/website-next/versioned_docs/version-2.3.0/security-overview.md b/site2/website-next/versioned_docs/version-2.3.0/security-overview.md
index 91f4ba8..8cbaa09 100644
--- a/site2/website-next/versioned_docs/version-2.3.0/security-overview.md
+++ b/site2/website-next/versioned_docs/version-2.3.0/security-overview.md
@@ -26,9 +26,11 @@ Apache Pulsar uses a [Authentication Provider](#authentication-providers) to est
Currently Pulsar supports the following authentication providers:
-- [TLS Authentication](security-tls-authentication)
-- [Athenz](security-athenz)
-- [Kerberos](security-kerberos)
-- [JSON Web Token Authentication](security-jwt)
+- [TLS authentication](security-tls-authentication)
+- [Athenz authentication](security-athenz)
+- [Kerberos authentication](security-kerberos)
+- [JSON Web Token (JWT) authentication](security-jwt)
+- [OAuth 2.0 authentication](security-oauth2)
+- Basic authentication
diff --git a/site2/website-next/versioned_docs/version-2.3.1/security-extending.md b/site2/website-next/versioned_docs/version-2.3.1/security-extending.md
index dd0030e..3d3fde6 100644
--- a/site2/website-next/versioned_docs/version-2.3.1/security-extending.md
+++ b/site2/website-next/versioned_docs/version-2.3.1/security-extending.md
@@ -1,20 +1,20 @@
---
id: security-extending
-title: Extending Authentication and Authorization in Pulsar
-sidebar_label: "Extending"
+title: Extend Authentication and Authorization in Pulsar
+sidebar_label: "Extend Authentication and Authorization"
---
Pulsar provides a way to use custom authentication and authorization mechanisms.
## Authentication
-Pulsar supports mutual TLS and Athenz authentication plugins. For how to use these authentication plugins, you can refer to the description in [Security](security-overview).
-
-You can use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Proxy and/or Pulsar Broker to validate the credentials.
+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
-For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below you can pass this class when you create a Pulsar client:
+For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below, you can pass this class when you create a Pulsar client.
```java
@@ -25,24 +25,25 @@ PulsarClient client = PulsarClient.builder()
```
-You can use 2 interfaces to implement on the client side:
- * `Authentication` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html
- * `AuthenticationDataProvider` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html
-
-
-This in turn needs to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider`. This leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
-
+You can implement 2 interfaces on the client side:
+ * [`Authentication`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html)
+ * [`AuthenticationDataProvider`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html)
-You can find examples for client authentication providers at:
+This in turn requires you to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider` and also leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
- * Mutual TLS Auth -- https://github.com/apache/pulsar/tree/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth
- * Athenz -- https://github.com/apache/pulsar/tree/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth
+You can find the following examples for different client authentication plugins:
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-sasl/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationToken.java)
+ * [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
-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 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.
-In `conf/broker.conf` you can choose to specify a list of valid providers:
+In `conf/broker.conf`, you can choose to specify a list of valid providers:
```properties
@@ -51,59 +52,25 @@ authenticationProviders=
```
-To implement `org.apache.pulsar.broker.authentication.AuthenticationProvider` on one single interface:
+For the implementation of the `org.apache.pulsar.broker.authentication.AuthenticationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProvider.java).
-```java
-
-/**
- * Provider of authentication mechanism
- */
-public interface AuthenticationProvider extends Closeable {
-
- /**
- * Perform initialization for the authentication provider
- *
- * @param config
- * broker config object
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration config) throws IOException;
-
- /**
- * @return the authentication method name supported by this provider
- */
- String getAuthMethodName();
-
- /**
- * Validate the authentication for the given credentials with the specified authentication data
- *
- * @param authData
- * provider specific authentication data
- * @return the "role" string for the authenticated connection, if the authentication was successful
- * @throws AuthenticationException
- * if the credentials are not valid
- */
- String authenticate(AuthenticationDataSource authData) throws AuthenticationException;
-
-}
-
-```
+You can find the following examples for different broker authentication plugins:
-The following is the example for Broker authentication plugins:
-
- * Mutual TLS -- https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java
- * Athenz -- https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-sasl/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
+ * [Basic auth](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
## Authorization
Authorization is the operation that checks whether a particular "role" or "principal" has permission to perform a certain operation.
-By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin.
-Note that although the Authentication plugin is designed for use in both the Proxy and Broker,
-the Authorization plugin is designed only for use on the Broker however the Proxy does perform some simple Authorization checks of Roles if authorization is enabled.
+By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin. Note that although the Authentication plugin is designed for use in both the proxy and broker, the Authorization plugin is designed only for use on the broker.
+
+### Broker authorization plugin
-To provide a custom provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
+To provide a custom authorization provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
```properties
@@ -112,95 +79,4 @@ To provide a custom provider, you need to implement the `org.apache.pulsar.broke
```
-```java
-
-/**
- * Provider of authorization mechanism
- */
-public interface AuthorizationProvider extends Closeable {
-
- /**
- * Perform initialization for the authorization provider
- *
- * @param conf
- * broker config object
- * @param configCache
- * pulsar zk configuration cache service
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration conf, ConfigurationCacheService configCache) throws IOException;
-
- /**
- * Check if the specified role has permission to send messages to the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to send messages to the topic.
- */
- CompletableFuture<Boolean> canProduceAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- * Check if the specified role has permission to receive messages from the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to receive messages from the topic.
- * @param subscription
- * the subscription name defined by the client
- */
- CompletableFuture<Boolean> canConsumeAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData, String subscription);
-
- /**
- * Check whether the specified role can perform a lookup for the specified topic.
- *
- * For that the caller needs to have producer or consumer permission.
- *
- * @param topicName
- * @param role
- * @return
- * @throws Exception
- */
- CompletableFuture<Boolean> canLookupAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- *
- * Grant authorization-action permission on a namespace to the given client
- *
- * @param namespace
- * @param actions
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(NamespaceName namespace, Set<AuthAction> actions, String role,
- String authDataJson);
-
- /**
- * Grant authorization-action permission on a topic to the given client
- *
- * @param topicName
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(TopicName topicName, Set<AuthAction> actions, String role,
- String authDataJson);
-
-}
-
-```
-
+For the implementation of the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authorization/AuthorizationProvider.java).
\ No newline at end of file
diff --git a/site2/website-next/versioned_docs/version-2.3.1/security-overview.md b/site2/website-next/versioned_docs/version-2.3.1/security-overview.md
index 91f4ba8..8cbaa09 100644
--- a/site2/website-next/versioned_docs/version-2.3.1/security-overview.md
+++ b/site2/website-next/versioned_docs/version-2.3.1/security-overview.md
@@ -26,9 +26,11 @@ Apache Pulsar uses a [Authentication Provider](#authentication-providers) to est
Currently Pulsar supports the following authentication providers:
-- [TLS Authentication](security-tls-authentication)
-- [Athenz](security-athenz)
-- [Kerberos](security-kerberos)
-- [JSON Web Token Authentication](security-jwt)
+- [TLS authentication](security-tls-authentication)
+- [Athenz authentication](security-athenz)
+- [Kerberos authentication](security-kerberos)
+- [JSON Web Token (JWT) authentication](security-jwt)
+- [OAuth 2.0 authentication](security-oauth2)
+- Basic authentication
diff --git a/site2/website-next/versioned_docs/version-2.3.2/security-extending.md b/site2/website-next/versioned_docs/version-2.3.2/security-extending.md
index dd0030e..3d3fde6 100644
--- a/site2/website-next/versioned_docs/version-2.3.2/security-extending.md
+++ b/site2/website-next/versioned_docs/version-2.3.2/security-extending.md
@@ -1,20 +1,20 @@
---
id: security-extending
-title: Extending Authentication and Authorization in Pulsar
-sidebar_label: "Extending"
+title: Extend Authentication and Authorization in Pulsar
+sidebar_label: "Extend Authentication and Authorization"
---
Pulsar provides a way to use custom authentication and authorization mechanisms.
## Authentication
-Pulsar supports mutual TLS and Athenz authentication plugins. For how to use these authentication plugins, you can refer to the description in [Security](security-overview).
-
-You can use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Proxy and/or Pulsar Broker to validate the credentials.
+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
-For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below you can pass this class when you create a Pulsar client:
+For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below, you can pass this class when you create a Pulsar client.
```java
@@ -25,24 +25,25 @@ PulsarClient client = PulsarClient.builder()
```
-You can use 2 interfaces to implement on the client side:
- * `Authentication` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html
- * `AuthenticationDataProvider` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html
-
-
-This in turn needs to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider`. This leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
-
+You can implement 2 interfaces on the client side:
+ * [`Authentication`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html)
+ * [`AuthenticationDataProvider`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html)
-You can find examples for client authentication providers at:
+This in turn requires you to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider` and also leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
- * Mutual TLS Auth -- https://github.com/apache/pulsar/tree/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth
- * Athenz -- https://github.com/apache/pulsar/tree/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth
+You can find the following examples for different client authentication plugins:
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-sasl/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationToken.java)
+ * [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
-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 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.
-In `conf/broker.conf` you can choose to specify a list of valid providers:
+In `conf/broker.conf`, you can choose to specify a list of valid providers:
```properties
@@ -51,59 +52,25 @@ authenticationProviders=
```
-To implement `org.apache.pulsar.broker.authentication.AuthenticationProvider` on one single interface:
+For the implementation of the `org.apache.pulsar.broker.authentication.AuthenticationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProvider.java).
-```java
-
-/**
- * Provider of authentication mechanism
- */
-public interface AuthenticationProvider extends Closeable {
-
- /**
- * Perform initialization for the authentication provider
- *
- * @param config
- * broker config object
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration config) throws IOException;
-
- /**
- * @return the authentication method name supported by this provider
- */
- String getAuthMethodName();
-
- /**
- * Validate the authentication for the given credentials with the specified authentication data
- *
- * @param authData
- * provider specific authentication data
- * @return the "role" string for the authenticated connection, if the authentication was successful
- * @throws AuthenticationException
- * if the credentials are not valid
- */
- String authenticate(AuthenticationDataSource authData) throws AuthenticationException;
-
-}
-
-```
+You can find the following examples for different broker authentication plugins:
-The following is the example for Broker authentication plugins:
-
- * Mutual TLS -- https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java
- * Athenz -- https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-sasl/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
+ * [Basic auth](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
## Authorization
Authorization is the operation that checks whether a particular "role" or "principal" has permission to perform a certain operation.
-By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin.
-Note that although the Authentication plugin is designed for use in both the Proxy and Broker,
-the Authorization plugin is designed only for use on the Broker however the Proxy does perform some simple Authorization checks of Roles if authorization is enabled.
+By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin. Note that although the Authentication plugin is designed for use in both the proxy and broker, the Authorization plugin is designed only for use on the broker.
+
+### Broker authorization plugin
-To provide a custom provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
+To provide a custom authorization provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
```properties
@@ -112,95 +79,4 @@ To provide a custom provider, you need to implement the `org.apache.pulsar.broke
```
-```java
-
-/**
- * Provider of authorization mechanism
- */
-public interface AuthorizationProvider extends Closeable {
-
- /**
- * Perform initialization for the authorization provider
- *
- * @param conf
- * broker config object
- * @param configCache
- * pulsar zk configuration cache service
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration conf, ConfigurationCacheService configCache) throws IOException;
-
- /**
- * Check if the specified role has permission to send messages to the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to send messages to the topic.
- */
- CompletableFuture<Boolean> canProduceAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- * Check if the specified role has permission to receive messages from the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to receive messages from the topic.
- * @param subscription
- * the subscription name defined by the client
- */
- CompletableFuture<Boolean> canConsumeAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData, String subscription);
-
- /**
- * Check whether the specified role can perform a lookup for the specified topic.
- *
- * For that the caller needs to have producer or consumer permission.
- *
- * @param topicName
- * @param role
- * @return
- * @throws Exception
- */
- CompletableFuture<Boolean> canLookupAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- *
- * Grant authorization-action permission on a namespace to the given client
- *
- * @param namespace
- * @param actions
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(NamespaceName namespace, Set<AuthAction> actions, String role,
- String authDataJson);
-
- /**
- * Grant authorization-action permission on a topic to the given client
- *
- * @param topicName
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(TopicName topicName, Set<AuthAction> actions, String role,
- String authDataJson);
-
-}
-
-```
-
+For the implementation of the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authorization/AuthorizationProvider.java).
\ No newline at end of file
diff --git a/site2/website-next/versioned_docs/version-2.4.0/security-extending.md b/site2/website-next/versioned_docs/version-2.4.0/security-extending.md
index dd0030e..3d3fde6 100644
--- a/site2/website-next/versioned_docs/version-2.4.0/security-extending.md
+++ b/site2/website-next/versioned_docs/version-2.4.0/security-extending.md
@@ -1,20 +1,20 @@
---
id: security-extending
-title: Extending Authentication and Authorization in Pulsar
-sidebar_label: "Extending"
+title: Extend Authentication and Authorization in Pulsar
+sidebar_label: "Extend Authentication and Authorization"
---
Pulsar provides a way to use custom authentication and authorization mechanisms.
## Authentication
-Pulsar supports mutual TLS and Athenz authentication plugins. For how to use these authentication plugins, you can refer to the description in [Security](security-overview).
-
-You can use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Proxy and/or Pulsar Broker to validate the credentials.
+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
-For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below you can pass this class when you create a Pulsar client:
+For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below, you can pass this class when you create a Pulsar client.
```java
@@ -25,24 +25,25 @@ PulsarClient client = PulsarClient.builder()
```
-You can use 2 interfaces to implement on the client side:
- * `Authentication` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html
- * `AuthenticationDataProvider` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html
-
-
-This in turn needs to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider`. This leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
-
+You can implement 2 interfaces on the client side:
+ * [`Authentication`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html)
+ * [`AuthenticationDataProvider`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html)
-You can find examples for client authentication providers at:
+This in turn requires you to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider` and also leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
- * Mutual TLS Auth -- https://github.com/apache/pulsar/tree/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth
- * Athenz -- https://github.com/apache/pulsar/tree/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth
+You can find the following examples for different client authentication plugins:
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-sasl/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationToken.java)
+ * [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
-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 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.
-In `conf/broker.conf` you can choose to specify a list of valid providers:
+In `conf/broker.conf`, you can choose to specify a list of valid providers:
```properties
@@ -51,59 +52,25 @@ authenticationProviders=
```
-To implement `org.apache.pulsar.broker.authentication.AuthenticationProvider` on one single interface:
+For the implementation of the `org.apache.pulsar.broker.authentication.AuthenticationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProvider.java).
-```java
-
-/**
- * Provider of authentication mechanism
- */
-public interface AuthenticationProvider extends Closeable {
-
- /**
- * Perform initialization for the authentication provider
- *
- * @param config
- * broker config object
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration config) throws IOException;
-
- /**
- * @return the authentication method name supported by this provider
- */
- String getAuthMethodName();
-
- /**
- * Validate the authentication for the given credentials with the specified authentication data
- *
- * @param authData
- * provider specific authentication data
- * @return the "role" string for the authenticated connection, if the authentication was successful
- * @throws AuthenticationException
- * if the credentials are not valid
- */
- String authenticate(AuthenticationDataSource authData) throws AuthenticationException;
-
-}
-
-```
+You can find the following examples for different broker authentication plugins:
-The following is the example for Broker authentication plugins:
-
- * Mutual TLS -- https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java
- * Athenz -- https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-sasl/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
+ * [Basic auth](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
## Authorization
Authorization is the operation that checks whether a particular "role" or "principal" has permission to perform a certain operation.
-By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin.
-Note that although the Authentication plugin is designed for use in both the Proxy and Broker,
-the Authorization plugin is designed only for use on the Broker however the Proxy does perform some simple Authorization checks of Roles if authorization is enabled.
+By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin. Note that although the Authentication plugin is designed for use in both the proxy and broker, the Authorization plugin is designed only for use on the broker.
+
+### Broker authorization plugin
-To provide a custom provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
+To provide a custom authorization provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
```properties
@@ -112,95 +79,4 @@ To provide a custom provider, you need to implement the `org.apache.pulsar.broke
```
-```java
-
-/**
- * Provider of authorization mechanism
- */
-public interface AuthorizationProvider extends Closeable {
-
- /**
- * Perform initialization for the authorization provider
- *
- * @param conf
- * broker config object
- * @param configCache
- * pulsar zk configuration cache service
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration conf, ConfigurationCacheService configCache) throws IOException;
-
- /**
- * Check if the specified role has permission to send messages to the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to send messages to the topic.
- */
- CompletableFuture<Boolean> canProduceAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- * Check if the specified role has permission to receive messages from the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to receive messages from the topic.
- * @param subscription
- * the subscription name defined by the client
- */
- CompletableFuture<Boolean> canConsumeAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData, String subscription);
-
- /**
- * Check whether the specified role can perform a lookup for the specified topic.
- *
- * For that the caller needs to have producer or consumer permission.
- *
- * @param topicName
- * @param role
- * @return
- * @throws Exception
- */
- CompletableFuture<Boolean> canLookupAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- *
- * Grant authorization-action permission on a namespace to the given client
- *
- * @param namespace
- * @param actions
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(NamespaceName namespace, Set<AuthAction> actions, String role,
- String authDataJson);
-
- /**
- * Grant authorization-action permission on a topic to the given client
- *
- * @param topicName
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(TopicName topicName, Set<AuthAction> actions, String role,
- String authDataJson);
-
-}
-
-```
-
+For the implementation of the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authorization/AuthorizationProvider.java).
\ No newline at end of file
diff --git a/site2/website-next/versioned_docs/version-2.4.1/security-extending.md b/site2/website-next/versioned_docs/version-2.4.1/security-extending.md
index dd0030e..3d3fde6 100644
--- a/site2/website-next/versioned_docs/version-2.4.1/security-extending.md
+++ b/site2/website-next/versioned_docs/version-2.4.1/security-extending.md
@@ -1,20 +1,20 @@
---
id: security-extending
-title: Extending Authentication and Authorization in Pulsar
-sidebar_label: "Extending"
+title: Extend Authentication and Authorization in Pulsar
+sidebar_label: "Extend Authentication and Authorization"
---
Pulsar provides a way to use custom authentication and authorization mechanisms.
## Authentication
-Pulsar supports mutual TLS and Athenz authentication plugins. For how to use these authentication plugins, you can refer to the description in [Security](security-overview).
-
-You can use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Proxy and/or Pulsar Broker to validate the credentials.
+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
-For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below you can pass this class when you create a Pulsar client:
+For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below, you can pass this class when you create a Pulsar client.
```java
@@ -25,24 +25,25 @@ PulsarClient client = PulsarClient.builder()
```
-You can use 2 interfaces to implement on the client side:
- * `Authentication` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html
- * `AuthenticationDataProvider` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html
-
-
-This in turn needs to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider`. This leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
-
+You can implement 2 interfaces on the client side:
+ * [`Authentication`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html)
+ * [`AuthenticationDataProvider`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html)
-You can find examples for client authentication providers at:
+This in turn requires you to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider` and also leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
- * Mutual TLS Auth -- https://github.com/apache/pulsar/tree/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth
- * Athenz -- https://github.com/apache/pulsar/tree/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth
+You can find the following examples for different client authentication plugins:
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-sasl/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationToken.java)
+ * [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
-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 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.
-In `conf/broker.conf` you can choose to specify a list of valid providers:
+In `conf/broker.conf`, you can choose to specify a list of valid providers:
```properties
@@ -51,59 +52,25 @@ authenticationProviders=
```
-To implement `org.apache.pulsar.broker.authentication.AuthenticationProvider` on one single interface:
+For the implementation of the `org.apache.pulsar.broker.authentication.AuthenticationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProvider.java).
-```java
-
-/**
- * Provider of authentication mechanism
- */
-public interface AuthenticationProvider extends Closeable {
-
- /**
- * Perform initialization for the authentication provider
- *
- * @param config
- * broker config object
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration config) throws IOException;
-
- /**
- * @return the authentication method name supported by this provider
- */
- String getAuthMethodName();
-
- /**
- * Validate the authentication for the given credentials with the specified authentication data
- *
- * @param authData
- * provider specific authentication data
- * @return the "role" string for the authenticated connection, if the authentication was successful
- * @throws AuthenticationException
- * if the credentials are not valid
- */
- String authenticate(AuthenticationDataSource authData) throws AuthenticationException;
-
-}
-
-```
+You can find the following examples for different broker authentication plugins:
-The following is the example for Broker authentication plugins:
-
- * Mutual TLS -- https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java
- * Athenz -- https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-sasl/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
+ * [Basic auth](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
## Authorization
Authorization is the operation that checks whether a particular "role" or "principal" has permission to perform a certain operation.
-By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin.
-Note that although the Authentication plugin is designed for use in both the Proxy and Broker,
-the Authorization plugin is designed only for use on the Broker however the Proxy does perform some simple Authorization checks of Roles if authorization is enabled.
+By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin. Note that although the Authentication plugin is designed for use in both the proxy and broker, the Authorization plugin is designed only for use on the broker.
+
+### Broker authorization plugin
-To provide a custom provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
+To provide a custom authorization provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
```properties
@@ -112,95 +79,4 @@ To provide a custom provider, you need to implement the `org.apache.pulsar.broke
```
-```java
-
-/**
- * Provider of authorization mechanism
- */
-public interface AuthorizationProvider extends Closeable {
-
- /**
- * Perform initialization for the authorization provider
- *
- * @param conf
- * broker config object
- * @param configCache
- * pulsar zk configuration cache service
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration conf, ConfigurationCacheService configCache) throws IOException;
-
- /**
- * Check if the specified role has permission to send messages to the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to send messages to the topic.
- */
- CompletableFuture<Boolean> canProduceAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- * Check if the specified role has permission to receive messages from the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to receive messages from the topic.
- * @param subscription
- * the subscription name defined by the client
- */
- CompletableFuture<Boolean> canConsumeAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData, String subscription);
-
- /**
- * Check whether the specified role can perform a lookup for the specified topic.
- *
- * For that the caller needs to have producer or consumer permission.
- *
- * @param topicName
- * @param role
- * @return
- * @throws Exception
- */
- CompletableFuture<Boolean> canLookupAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- *
- * Grant authorization-action permission on a namespace to the given client
- *
- * @param namespace
- * @param actions
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(NamespaceName namespace, Set<AuthAction> actions, String role,
- String authDataJson);
-
- /**
- * Grant authorization-action permission on a topic to the given client
- *
- * @param topicName
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(TopicName topicName, Set<AuthAction> actions, String role,
- String authDataJson);
-
-}
-
-```
-
+For the implementation of the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authorization/AuthorizationProvider.java).
\ No newline at end of file
diff --git a/site2/website-next/versioned_docs/version-2.4.2/security-extending.md b/site2/website-next/versioned_docs/version-2.4.2/security-extending.md
index dd0030e..3d3fde6 100644
--- a/site2/website-next/versioned_docs/version-2.4.2/security-extending.md
+++ b/site2/website-next/versioned_docs/version-2.4.2/security-extending.md
@@ -1,20 +1,20 @@
---
id: security-extending
-title: Extending Authentication and Authorization in Pulsar
-sidebar_label: "Extending"
+title: Extend Authentication and Authorization in Pulsar
+sidebar_label: "Extend Authentication and Authorization"
---
Pulsar provides a way to use custom authentication and authorization mechanisms.
## Authentication
-Pulsar supports mutual TLS and Athenz authentication plugins. For how to use these authentication plugins, you can refer to the description in [Security](security-overview).
-
-You can use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Proxy and/or Pulsar Broker to validate the credentials.
+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
-For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below you can pass this class when you create a Pulsar client:
+For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below, you can pass this class when you create a Pulsar client.
```java
@@ -25,24 +25,25 @@ PulsarClient client = PulsarClient.builder()
```
-You can use 2 interfaces to implement on the client side:
- * `Authentication` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html
- * `AuthenticationDataProvider` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html
-
-
-This in turn needs to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider`. This leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
-
+You can implement 2 interfaces on the client side:
+ * [`Authentication`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html)
+ * [`AuthenticationDataProvider`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html)
-You can find examples for client authentication providers at:
+This in turn requires you to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider` and also leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
- * Mutual TLS Auth -- https://github.com/apache/pulsar/tree/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth
- * Athenz -- https://github.com/apache/pulsar/tree/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth
+You can find the following examples for different client authentication plugins:
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-sasl/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationToken.java)
+ * [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
-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 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.
-In `conf/broker.conf` you can choose to specify a list of valid providers:
+In `conf/broker.conf`, you can choose to specify a list of valid providers:
```properties
@@ -51,59 +52,25 @@ authenticationProviders=
```
-To implement `org.apache.pulsar.broker.authentication.AuthenticationProvider` on one single interface:
+For the implementation of the `org.apache.pulsar.broker.authentication.AuthenticationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProvider.java).
-```java
-
-/**
- * Provider of authentication mechanism
- */
-public interface AuthenticationProvider extends Closeable {
-
- /**
- * Perform initialization for the authentication provider
- *
- * @param config
- * broker config object
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration config) throws IOException;
-
- /**
- * @return the authentication method name supported by this provider
- */
- String getAuthMethodName();
-
- /**
- * Validate the authentication for the given credentials with the specified authentication data
- *
- * @param authData
- * provider specific authentication data
- * @return the "role" string for the authenticated connection, if the authentication was successful
- * @throws AuthenticationException
- * if the credentials are not valid
- */
- String authenticate(AuthenticationDataSource authData) throws AuthenticationException;
-
-}
-
-```
+You can find the following examples for different broker authentication plugins:
-The following is the example for Broker authentication plugins:
-
- * Mutual TLS -- https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java
- * Athenz -- https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-sasl/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
+ * [Basic auth](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
## Authorization
Authorization is the operation that checks whether a particular "role" or "principal" has permission to perform a certain operation.
-By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin.
-Note that although the Authentication plugin is designed for use in both the Proxy and Broker,
-the Authorization plugin is designed only for use on the Broker however the Proxy does perform some simple Authorization checks of Roles if authorization is enabled.
+By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin. Note that although the Authentication plugin is designed for use in both the proxy and broker, the Authorization plugin is designed only for use on the broker.
+
+### Broker authorization plugin
-To provide a custom provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
+To provide a custom authorization provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
```properties
@@ -112,95 +79,4 @@ To provide a custom provider, you need to implement the `org.apache.pulsar.broke
```
-```java
-
-/**
- * Provider of authorization mechanism
- */
-public interface AuthorizationProvider extends Closeable {
-
- /**
- * Perform initialization for the authorization provider
- *
- * @param conf
- * broker config object
- * @param configCache
- * pulsar zk configuration cache service
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration conf, ConfigurationCacheService configCache) throws IOException;
-
- /**
- * Check if the specified role has permission to send messages to the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to send messages to the topic.
- */
- CompletableFuture<Boolean> canProduceAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- * Check if the specified role has permission to receive messages from the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to receive messages from the topic.
- * @param subscription
- * the subscription name defined by the client
- */
- CompletableFuture<Boolean> canConsumeAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData, String subscription);
-
- /**
- * Check whether the specified role can perform a lookup for the specified topic.
- *
- * For that the caller needs to have producer or consumer permission.
- *
- * @param topicName
- * @param role
- * @return
- * @throws Exception
- */
- CompletableFuture<Boolean> canLookupAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- *
- * Grant authorization-action permission on a namespace to the given client
- *
- * @param namespace
- * @param actions
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(NamespaceName namespace, Set<AuthAction> actions, String role,
- String authDataJson);
-
- /**
- * Grant authorization-action permission on a topic to the given client
- *
- * @param topicName
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(TopicName topicName, Set<AuthAction> actions, String role,
- String authDataJson);
-
-}
-
-```
-
+For the implementation of the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authorization/AuthorizationProvider.java).
\ No newline at end of file
diff --git a/site2/website-next/versioned_docs/version-2.5.1/security-extending.md b/site2/website-next/versioned_docs/version-2.5.1/security-extending.md
index dd0030e..3d3fde6 100644
--- a/site2/website-next/versioned_docs/version-2.5.1/security-extending.md
+++ b/site2/website-next/versioned_docs/version-2.5.1/security-extending.md
@@ -1,20 +1,20 @@
---
id: security-extending
-title: Extending Authentication and Authorization in Pulsar
-sidebar_label: "Extending"
+title: Extend Authentication and Authorization in Pulsar
+sidebar_label: "Extend Authentication and Authorization"
---
Pulsar provides a way to use custom authentication and authorization mechanisms.
## Authentication
-Pulsar supports mutual TLS and Athenz authentication plugins. For how to use these authentication plugins, you can refer to the description in [Security](security-overview).
-
-You can use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Proxy and/or Pulsar Broker to validate the credentials.
+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
-For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below you can pass this class when you create a Pulsar client:
+For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below, you can pass this class when you create a Pulsar client.
```java
@@ -25,24 +25,25 @@ PulsarClient client = PulsarClient.builder()
```
-You can use 2 interfaces to implement on the client side:
- * `Authentication` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html
- * `AuthenticationDataProvider` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html
-
-
-This in turn needs to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider`. This leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
-
+You can implement 2 interfaces on the client side:
+ * [`Authentication`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html)
+ * [`AuthenticationDataProvider`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html)
-You can find examples for client authentication providers at:
+This in turn requires you to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider` and also leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
- * Mutual TLS Auth -- https://github.com/apache/pulsar/tree/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth
- * Athenz -- https://github.com/apache/pulsar/tree/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth
+You can find the following examples for different client authentication plugins:
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-sasl/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationToken.java)
+ * [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
-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 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.
-In `conf/broker.conf` you can choose to specify a list of valid providers:
+In `conf/broker.conf`, you can choose to specify a list of valid providers:
```properties
@@ -51,59 +52,25 @@ authenticationProviders=
```
-To implement `org.apache.pulsar.broker.authentication.AuthenticationProvider` on one single interface:
+For the implementation of the `org.apache.pulsar.broker.authentication.AuthenticationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProvider.java).
-```java
-
-/**
- * Provider of authentication mechanism
- */
-public interface AuthenticationProvider extends Closeable {
-
- /**
- * Perform initialization for the authentication provider
- *
- * @param config
- * broker config object
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration config) throws IOException;
-
- /**
- * @return the authentication method name supported by this provider
- */
- String getAuthMethodName();
-
- /**
- * Validate the authentication for the given credentials with the specified authentication data
- *
- * @param authData
- * provider specific authentication data
- * @return the "role" string for the authenticated connection, if the authentication was successful
- * @throws AuthenticationException
- * if the credentials are not valid
- */
- String authenticate(AuthenticationDataSource authData) throws AuthenticationException;
-
-}
-
-```
+You can find the following examples for different broker authentication plugins:
-The following is the example for Broker authentication plugins:
-
- * Mutual TLS -- https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java
- * Athenz -- https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-sasl/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
+ * [Basic auth](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
## Authorization
Authorization is the operation that checks whether a particular "role" or "principal" has permission to perform a certain operation.
-By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin.
-Note that although the Authentication plugin is designed for use in both the Proxy and Broker,
-the Authorization plugin is designed only for use on the Broker however the Proxy does perform some simple Authorization checks of Roles if authorization is enabled.
+By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin. Note that although the Authentication plugin is designed for use in both the proxy and broker, the Authorization plugin is designed only for use on the broker.
+
+### Broker authorization plugin
-To provide a custom provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
+To provide a custom authorization provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
```properties
@@ -112,95 +79,4 @@ To provide a custom provider, you need to implement the `org.apache.pulsar.broke
```
-```java
-
-/**
- * Provider of authorization mechanism
- */
-public interface AuthorizationProvider extends Closeable {
-
- /**
- * Perform initialization for the authorization provider
- *
- * @param conf
- * broker config object
- * @param configCache
- * pulsar zk configuration cache service
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration conf, ConfigurationCacheService configCache) throws IOException;
-
- /**
- * Check if the specified role has permission to send messages to the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to send messages to the topic.
- */
- CompletableFuture<Boolean> canProduceAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- * Check if the specified role has permission to receive messages from the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to receive messages from the topic.
- * @param subscription
- * the subscription name defined by the client
- */
- CompletableFuture<Boolean> canConsumeAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData, String subscription);
-
- /**
- * Check whether the specified role can perform a lookup for the specified topic.
- *
- * For that the caller needs to have producer or consumer permission.
- *
- * @param topicName
- * @param role
- * @return
- * @throws Exception
- */
- CompletableFuture<Boolean> canLookupAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- *
- * Grant authorization-action permission on a namespace to the given client
- *
- * @param namespace
- * @param actions
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(NamespaceName namespace, Set<AuthAction> actions, String role,
- String authDataJson);
-
- /**
- * Grant authorization-action permission on a topic to the given client
- *
- * @param topicName
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(TopicName topicName, Set<AuthAction> actions, String role,
- String authDataJson);
-
-}
-
-```
-
+For the implementation of the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authorization/AuthorizationProvider.java).
\ No newline at end of file
diff --git a/site2/website-next/versioned_docs/version-2.5.1/security-overview.md b/site2/website-next/versioned_docs/version-2.5.1/security-overview.md
index 91f4ba8..8cbaa09 100644
--- a/site2/website-next/versioned_docs/version-2.5.1/security-overview.md
+++ b/site2/website-next/versioned_docs/version-2.5.1/security-overview.md
@@ -26,9 +26,11 @@ Apache Pulsar uses a [Authentication Provider](#authentication-providers) to est
Currently Pulsar supports the following authentication providers:
-- [TLS Authentication](security-tls-authentication)
-- [Athenz](security-athenz)
-- [Kerberos](security-kerberos)
-- [JSON Web Token Authentication](security-jwt)
+- [TLS authentication](security-tls-authentication)
+- [Athenz authentication](security-athenz)
+- [Kerberos authentication](security-kerberos)
+- [JSON Web Token (JWT) authentication](security-jwt)
+- [OAuth 2.0 authentication](security-oauth2)
+- Basic authentication
diff --git a/site2/website-next/versioned_docs/version-2.5.2/security-extending.md b/site2/website-next/versioned_docs/version-2.5.2/security-extending.md
index dd0030e..3d3fde6 100644
--- a/site2/website-next/versioned_docs/version-2.5.2/security-extending.md
+++ b/site2/website-next/versioned_docs/version-2.5.2/security-extending.md
@@ -1,20 +1,20 @@
---
id: security-extending
-title: Extending Authentication and Authorization in Pulsar
-sidebar_label: "Extending"
+title: Extend Authentication and Authorization in Pulsar
+sidebar_label: "Extend Authentication and Authorization"
---
Pulsar provides a way to use custom authentication and authorization mechanisms.
## Authentication
-Pulsar supports mutual TLS and Athenz authentication plugins. For how to use these authentication plugins, you can refer to the description in [Security](security-overview).
-
-You can use a custom authentication mechanism by providing the implementation in the form of two plugins. One plugin is for the Client library and the other plugin is for the Pulsar Proxy and/or Pulsar Broker to validate the credentials.
+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
-For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below you can pass this class when you create a Pulsar client:
+For the client library, you need to implement `org.apache.pulsar.client.api.Authentication`. By entering the command below, you can pass this class when you create a Pulsar client.
```java
@@ -25,24 +25,25 @@ PulsarClient client = PulsarClient.builder()
```
-You can use 2 interfaces to implement on the client side:
- * `Authentication` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html
- * `AuthenticationDataProvider` -> http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html
-
-
-This in turn needs to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider`. This leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
-
+You can implement 2 interfaces on the client side:
+ * [`Authentication`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/Authentication.html)
+ * [`AuthenticationDataProvider`](http://pulsar.apache.org/api/client/org/apache/pulsar/client/api/AuthenticationDataProvider.html)
-You can find examples for client authentication providers at:
+This in turn requires you to provide the client credentials in the form of `org.apache.pulsar.client.api.AuthenticationDataProvider` and also leaves the chance to return different kinds of authentication token for different types of connection or by passing a certificate chain to use for TLS.
- * Mutual TLS Auth -- https://github.com/apache/pulsar/tree/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth
- * Athenz -- https://github.com/apache/pulsar/tree/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth
+You can find the following examples for different client authentication plugins:
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-client-auth-sasl/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationToken.java)
+ * [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
-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 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.
-In `conf/broker.conf` you can choose to specify a list of valid providers:
+In `conf/broker.conf`, you can choose to specify a list of valid providers:
```properties
@@ -51,59 +52,25 @@ authenticationProviders=
```
-To implement `org.apache.pulsar.broker.authentication.AuthenticationProvider` on one single interface:
+For the implementation of the `org.apache.pulsar.broker.authentication.AuthenticationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProvider.java).
-```java
-
-/**
- * Provider of authentication mechanism
- */
-public interface AuthenticationProvider extends Closeable {
-
- /**
- * Perform initialization for the authentication provider
- *
- * @param config
- * broker config object
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration config) throws IOException;
-
- /**
- * @return the authentication method name supported by this provider
- */
- String getAuthMethodName();
-
- /**
- * Validate the authentication for the given credentials with the specified authentication data
- *
- * @param authData
- * provider specific authentication data
- * @return the "role" string for the authenticated connection, if the authentication was successful
- * @throws AuthenticationException
- * if the credentials are not valid
- */
- String authenticate(AuthenticationDataSource authData) throws AuthenticationException;
-
-}
-
-```
+You can find the following examples for different broker authentication plugins:
-The following is the example for Broker authentication plugins:
-
- * Mutual TLS -- https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java
- * Athenz -- https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java
+ * [Mutual TLS](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderTls.java)
+ * [Athenz](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-athenz/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderAthenz.java)
+ * [Kerberos](https://github.com/apache/pulsar/blob/master/pulsar-broker-auth-sasl/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderSasl.java)
+ * [JSON Web Token (JWT)](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
+ * [Basic auth](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java)
## Authorization
Authorization is the operation that checks whether a particular "role" or "principal" has permission to perform a certain operation.
-By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin.
-Note that although the Authentication plugin is designed for use in both the Proxy and Broker,
-the Authorization plugin is designed only for use on the Broker however the Proxy does perform some simple Authorization checks of Roles if authorization is enabled.
+By default, you can use the embedded authorization provider provided by Pulsar. You can also configure a different authorization provider through a plugin. Note that although the Authentication plugin is designed for use in both the proxy and broker, the Authorization plugin is designed only for use on the broker.
+
+### Broker authorization plugin
-To provide a custom provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
+To provide a custom authorization provider, you need to implement the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, put this class in the Pulsar broker classpath and configure the class in `conf/broker.conf`:
```properties
@@ -112,95 +79,4 @@ To provide a custom provider, you need to implement the `org.apache.pulsar.broke
```
-```java
-
-/**
- * Provider of authorization mechanism
- */
-public interface AuthorizationProvider extends Closeable {
-
- /**
- * Perform initialization for the authorization provider
- *
- * @param conf
- * broker config object
- * @param configCache
- * pulsar zk configuration cache service
- * @throws IOException
- * if the initialization fails
- */
- void initialize(ServiceConfiguration conf, ConfigurationCacheService configCache) throws IOException;
-
- /**
- * Check if the specified role has permission to send messages to the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to send messages to the topic.
- */
- CompletableFuture<Boolean> canProduceAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- * Check if the specified role has permission to receive messages from the specified fully qualified topic name.
- *
- * @param topicName
- * the fully qualified topic name associated with the topic.
- * @param role
- * the app id used to receive messages from the topic.
- * @param subscription
- * the subscription name defined by the client
- */
- CompletableFuture<Boolean> canConsumeAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData, String subscription);
-
- /**
- * Check whether the specified role can perform a lookup for the specified topic.
- *
- * For that the caller needs to have producer or consumer permission.
- *
- * @param topicName
- * @param role
- * @return
- * @throws Exception
- */
- CompletableFuture<Boolean> canLookupAsync(TopicName topicName, String role,
- AuthenticationDataSource authenticationData);
-
- /**
- *
- * Grant authorization-action permission on a namespace to the given client
- *
- * @param namespace
- * @param actions
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(NamespaceName namespace, Set<AuthAction> actions, String role,
- String authDataJson);
-
- /**
- * Grant authorization-action permission on a topic to the given client
- *
- * @param topicName
- * @param role
- * @param authDataJson
- * additional authdata in json format
- * @return CompletableFuture
- * @completesWith <br />
- * IllegalArgumentException when namespace not found<br />
- * IllegalStateException when failed to grant permission
- */
- CompletableFuture<Void> grantPermissionAsync(TopicName topicName, Set<AuthAction> actions, String role,
- String authDataJson);
-
-}
-
-```
-
+For the implementation of the `org.apache.pulsar.broker.authorization.AuthorizationProvider` interface, refer to [here](https://github.com/apache/pulsar/blob/master/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authorization/AuthorizationProvider.java).
\ No newline at end of file
diff --git a/site2/website-next/versioned_docs/version-2.5.2/security-overview.md b/site2/website-next/versioned_docs/version-2.5.2/security-overview.md
index 91f4ba8..8cbaa09 100644
--- a/site2/website-next/versioned_docs/version-2.5.2/security-overview.md
+++ b/site2/website-next/versioned_docs/version-2.5.2/security-overview.md
@@ -26,9 +26,11 @@ Apache Pulsar uses a [Authentication Provider](#authentication-providers) to est
Currently Pulsar supports the following authentication providers:
-- [TLS Authentication](security-tls-authentication)
-- [Athenz](security-athenz)
-- [Kerberos](security-kerberos)
-- [JSON Web Token Authentication](security-jwt)
+- [TLS authentication](security-tls-authentication)
+- [Athenz authentication](security-athenz)
+- [Kerberos authentication](security-kerberos)
+- [JSON Web Token (JWT) authentication](security-jwt)
+- [OAuth 2.0 authentication](security-oauth2)
+- Basic authentication