From ec75e07a16a9c31aab540261bdf9dc0f10f3ea65 Mon Sep 17 00:00:00 2001
From: HuanliMeng <48120384+Huanli-Meng@users.noreply.github.com>
Date: Mon, 6 Jul 2020 22:25:58 +0800
Subject: [PATCH 1/2]  a new authentication method

---
 site2/docs/security-oauth.md | 103 +++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 site2/docs/security-oauth.md

diff --git a/site2/docs/security-oauth.md b/site2/docs/security-oauth.md
new file mode 100644
index 0000000000000..1205d1296c1e9
--- /dev/null
+++ b/site2/docs/security-oauth.md
@@ -0,0 +1,103 @@
+---
+id: security-oauth
+title: Client authentication using OAuth 2.0 access tokens
+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.
+
+## Configure authentication provider
+
+This library allows you to authenticate the Pulsar client by using an access token that is obtained from an OAuth 2.0 authorization service, which acts as a _token issuer_.
+
+### Authentication types
+
+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 `client_credentials` .
+
+#### Client credentials
+
+The following table lists parameters supported for `client credentials`.
+
+| Parameter | Description | Example | Required or not |
+| --- | --- | --- | --- |
+| `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  | See [supported pattern formats](#supported-pattern-formats-of-privatekey). | Required |
+| `audience`  | An OAuth 2.0 "resource server" identifier for the Pulsar cluster | `https://broker.example.com` | Required |
+
+### Supported Pattern Formats of `privateKey`
+
+The `privateKey` parameter supports the following three pattern formats, and contains client Credentials.
+
+- `file:///path/to/file`
+- `file:/path/to/file`
+- `data:application/json;base64,<base64-encoded value>`
+
+The credentials file contains service account credentials for use with the client credentials authentication type.
+
+The following shows an example of a credentials file `credentials_file.json`.
+
+```json
+{
+  "type": "client_credentials",
+  "client_id": "d9ZyX97q1ef8Cr81WHVC4hFQ64vSlDK3",
+  "client_secret": "on1uJ...k6F6R",
+  "client_email": "1234567890-abcdefghijklmnopqrstuvwxyz@developer.gserviceaccount.com",
+  "issuer_url": "https://accounts.google.com"
+}
+```
+
+The default type is `client_credentials`, and for this type, fields "client_id" and "client_secret" is required.
+
+### Example for a typical original Oauth2 request mapping
+
+A typical original Oauth2 request, which is used to obtain the access token from Oauth2 server, is like this: 
+
+```bash
+curl --request POST \
+  --url https://dev-kt-aa9ne.us.auth0.com/oauth/token \
+  --header 'content-type: application/json' \
+  --data '{
+  "client_id":"Xd23RHsUnvUlP7wchjNYOaIfazgeHd9x",
+  "client_secret":"rT7ps7WY8uhdVuBTKWZkttwLdQotmdEliaM5rLfmgNibvqziZ-g07ZH52N_poGAb",
+  "audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/",
+  "grant_type":"client_credentials"}'
+```
+
+In which,
+
+- `issuerUrl` parameter in this plugin is mapped to `--url https://dev-kt-aa9ne.us.auth0.com/oauth/token`
+- `privateKey` file parameter in this plugin should at least contains fields `client_id` and `client_secret`.
+- `audience` parameter in this plugin is mapped to  `"audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"`
+
+## Pulsar client configuration
+
+You can use the provider with the following Pulsar clients.
+
+### Java
+
+You can use the factory method:
+
+```java
+PulsarClient client = PulsarClient.builder()
+    .serviceUrl("pulsar://broker.example.com:6650/")
+    .authentication(
+        AuthenticationFactoryOAuth2.clientCredentials(this.issuerUrl, this.credentialsUrl, this.audience))
+    .build();
+```
+
+Similarly, you can use encoded parameters:
+
+```java
+Authentication auth = AuthenticationFactory
+    .create(AuthenticationOAuth2.class.getName(), "{"type":"client_credentials","privateKey":"...","issuerUrl":"...","audience":"..."}");
+PulsarClient client = PulsarClient.builder()
+    .serviceUrl("pulsar://broker.example.com:6650/")
+    .authentication(auth)
+    .build();
+```
\ No newline at end of file

From 578345d0897f603d1af98e05a5f35d3db0b38002 Mon Sep 17 00:00:00 2001
From: HuanliMeng <48120384+Huanli-Meng@users.noreply.github.com>
Date: Tue, 7 Jul 2020 17:11:44 +0800
Subject: [PATCH 2/2] update doc for auth2

---
 site2/docs/client-libraries-java.md | 27 ++++++++++++++++++-
 site2/docs/security-oauth.md        | 42 +++++++++++------------------
 site2/website/sidebars.json         |  1 +
 3 files changed, 43 insertions(+), 27 deletions(-)

diff --git a/site2/docs/client-libraries-java.md b/site2/docs/client-libraries-java.md
index 516042eae112b..bfa80fe744728 100644
--- a/site2/docs/client-libraries-java.md
+++ b/site2/docs/client-libraries-java.md
@@ -796,7 +796,7 @@ The following schema formats are currently available for Java:
 
 ## Authentication
 
-Pulsar currently supports two authentication schemes: [TLS](security-tls-authentication.md) and [Athenz](security-athenz.md). You can use the Pulsar Java client with both.
+Pulsar currently supports three authentication schemes: [TLS](security-tls-authentication.md), [Athenz](security-athenz.md), and [Oauth2](security-oauth.md). You can use the Pulsar Java client with all of them.
 
 ### TLS Authentication
 
@@ -855,3 +855,28 @@ PulsarClient client = PulsarClient.builder()
 > * `file:///path/to/file`
 > * `file:/path/to/file`
 > * `data:application/x-pem-file;base64,<base64-encoded value>`
+
+### Oauth2
+
+The following example shows how to use [Oauth2](security-oauth.md) as an authentication provider for the Pulsar Java client.
+
+You can use the factory method to configure authentication for Pulsar Java client.
+
+```java
+PulsarClient client = PulsarClient.builder()
+    .serviceUrl("pulsar://broker.example.com:6650/")
+    .authentication(
+        AuthenticationFactoryOAuth2.clientCredentials(this.issuerUrl, this.credentialsUrl, this.audience))
+    .build();
+```
+
+In addition, you can also use the encoded parameters to configure authentication for Pulsar Java client.
+
+```java
+Authentication auth = AuthenticationFactory
+    .create(AuthenticationOAuth2.class.getName(), "{"type":"client_credentials","privateKey":"...","issuerUrl":"...","audience":"..."}");
+PulsarClient client = PulsarClient.builder()
+    .serviceUrl("pulsar://broker.example.com:6650/")
+    .authentication(auth)
+    .build();
+```
\ No newline at end of file
diff --git a/site2/docs/security-oauth.md b/site2/docs/security-oauth.md
index 1205d1296c1e9..b399deae5ac46 100644
--- a/site2/docs/security-oauth.md
+++ b/site2/docs/security-oauth.md
@@ -8,7 +8,7 @@ Pulsar supports authenticating clients using OAuth 2.0 access tokens. You can us
 
 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.
 
-## Configure authentication provider
+## Authentication provider configuration
 
 This library allows you to authenticate the Pulsar client by using an access token that is obtained from an OAuth 2.0 authorization service, which acts as a _token issuer_.
 
@@ -17,30 +17,20 @@ 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 `client_credentials` .
+> Currently, the Pulsar Java client only supports the `client_credentials` authentication type .
 
 #### Client credentials
 
-The following table lists parameters supported for `client credentials`.
+The following table lists parameters supported for the `client credentials` authentication type.
 
 | Parameter | Description | Example | Required or not |
 | --- | --- | --- | --- |
 | `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  | See [supported pattern formats](#supported-pattern-formats-of-privatekey). | 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` | Required |
 
-### Supported Pattern Formats of `privateKey`
-
-The `privateKey` parameter supports the following three pattern formats, and contains client Credentials.
-
-- `file:///path/to/file`
-- `file:/path/to/file`
-- `data:application/json;base64,<base64-encoded value>`
-
-The credentials file contains service account credentials for use with the client credentials authentication type.
-
-The following shows an example of a credentials file `credentials_file.json`.
+The credentials file contains service account credentials used with the client authentication type. The following shows an example of a credentials file `credentials_file.json`.
 
 ```json
 {
@@ -52,11 +42,11 @@ The following shows an example of a credentials file `credentials_file.json`.
 }
 ```
 
-The default type is `client_credentials`, and for this type, fields "client_id" and "client_secret" is required.
+In the above example, the authentication type is set to `client_credentials` by default. And the fields "client_id" and "client_secret" are required.
 
-### Example for a typical original Oauth2 request mapping
+### Typical original Oauth2 request mapping
 
-A typical original Oauth2 request, which is used to obtain the access token from Oauth2 server, is like this: 
+The following shows a typical original Oauth2 request, which is used to obtain the access token from the Oauth2 server.
 
 ```bash
 curl --request POST \
@@ -69,19 +59,19 @@ curl --request POST \
   "grant_type":"client_credentials"}'
 ```
 
-In which,
+In the above example, the mapping relationship is shown as below.
 
-- `issuerUrl` parameter in this plugin is mapped to `--url https://dev-kt-aa9ne.us.auth0.com/oauth/token`
-- `privateKey` file parameter in this plugin should at least contains fields `client_id` and `client_secret`.
-- `audience` parameter in this plugin is mapped to  `"audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"`
+- The `issuerUrl` parameter in this plugin is mapped to `--url https://dev-kt-aa9ne.us.auth0.com/oauth/token`.
+- The `privateKey` file parameter in this plugin should at least contains the `client_id` and `client_secret` fields.
+- The `audience` parameter in this plugin is mapped to  `"audience":"https://dev-kt-aa9ne.us.auth0.com/api/v2/"`.
 
-## Pulsar client configuration
+## Client Configuration
 
-You can use the provider with the following Pulsar clients.
+You can use the Oauth2 authentication provider with the following Pulsar clients.
 
 ### Java
 
-You can use the factory method:
+You can use the factory method to configure authentication for Pulsar Java client.
 
 ```java
 PulsarClient client = PulsarClient.builder()
@@ -91,7 +81,7 @@ PulsarClient client = PulsarClient.builder()
     .build();
 ```
 
-Similarly, you can use encoded parameters:
+In addition, you can also use the encoded parameters to configure authentication for Pulsar Java client.
 
 ```java
 Authentication auth = AuthenticationFactory
diff --git a/site2/website/sidebars.json b/site2/website/sidebars.json
index cf0574bc24d5f..13baa26f64de9 100644
--- a/site2/website/sidebars.json
+++ b/site2/website/sidebars.json
@@ -87,6 +87,7 @@
       "security-jwt",
       "security-athenz",
       "security-kerberos",
+      "security-oauth"
       "security-authorization",
       "security-encryption",
       "security-extending",