From 550cf743d15115de2618f24d23a873890109fe0d Mon Sep 17 00:00:00 2001
From: Scaat Feng <scaat.feng@gmail.com>
Date: Tue, 23 Jun 2020 10:35:26 +0800
Subject: [PATCH] doc: add oauth plugins Chinese docs. (#1754)

---
 doc/README.md              |   1 +
 doc/zh-cn/README.md        |   1 +
 doc/zh-cn/plugins/oauth.md | 129 +++++++++++++++++++++++++++++++++++++
 3 files changed, 131 insertions(+)
 create mode 100644 doc/zh-cn/plugins/oauth.md

diff --git a/doc/README.md b/doc/README.md
index 3f9142adc04d..bcbf648bca96 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -67,6 +67,7 @@ Plugins
 * [batch-requests](plugins/batch-requests.md): Allow you send mutiple http api via **http pipeline**.
 * [authz-keycloak](plugins/authz-keycloak.md): Authorization with Keycloak Identity Server.
 * [uri-blocker](plugins/uri-blocker.md): Block client request by URI.
+* [oauth](plugins/oauth.md): Provides OAuth 2 authentication and introspection.
 
 Deploy to the Cloud
 =======
diff --git a/doc/zh-cn/README.md b/doc/zh-cn/README.md
index 9b2c6c5a0f33..61874d452361 100644
--- a/doc/zh-cn/README.md
+++ b/doc/zh-cn/README.md
@@ -68,3 +68,4 @@ Reference document
 * [batch-requests](plugins/batch-requests.md): 以 **http pipeline** 的方式在网关一次性发起多个 `http` 请求。
 * [authz-keycloak](plugins/authz-keycloak-cn.md): 支持 Keycloak 身份认证服务器
 * [uri-blocker](plugins/uri-blocker.md): 根据 URI 拦截用户请求。
+* [oauth](plugins/oauth.md): 提供 OAuth 2 身份验证和自省。
diff --git a/doc/zh-cn/plugins/oauth.md b/doc/zh-cn/plugins/oauth.md
new file mode 100644
index 000000000000..3c6d0ec23ff1
--- /dev/null
+++ b/doc/zh-cn/plugins/oauth.md
@@ -0,0 +1,129 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+# 目录
+
+- [**定义**](#定义)
+- [**属性列表**](#属性列表)
+- [**令牌自省**](#令牌自省)
+
+## 定义
+
+OAuth 2 / Open ID Connect（OIDC）插件为 APISIX 提供身份验证和自省功能。
+
+## 属性列表
+
+|名称           |必选项    |描述|
+|-------        |-----          |------|
+|client_id      |必要的       |OAuth 客户端 ID|
+|client_secret  |必要的       |OAuth 客户端 secret|
+|discovery      |必要的       |身份服务器的发现端点的 URL|
+|realm          |可选的       |用于认证的领域； 默认为apisix|
+|bearer_only    |可选的       |设置为“true”将检查请求中带有承载令牌的授权标头； 默认为`false`|
+|logout_path    |可选的       |默认是`/logout`|
+|redirect_uri   |可选的       |默认是 `ngx.var.request_uri`|
+|timeout        |可选的       |默认是 3 秒|
+|ssl_verify     |可选的       |默认是 `false`|
+|introspection_endpoint                 |可选的       |身份服务器的令牌验证端点的 URL|
+|introspection_endpoint_auth_method     |可选的       |令牌自省的认证方法名称 |
+|public_key     |可选的       |验证令牌的公钥 |
+|token_signing_alg_values_expected     |可选的       |用于对令牌进行签名的算法 |
+
+### 令牌自省
+
+令牌自省通过针对 Oauth 2 授权服务器验证令牌来帮助验证请求。
+前提条件是，您应该在身份服务器中创建受信任的客户端，并生成用于自省的有效令牌（JWT）。
+下图显示了通过网关进行令牌自省的示例（成功）流程。
+
+![token introspection](../../images/plugin/oauth-1.png)
+
+以下是 curl 命令，用于将插件启用到外部服务。
+通过自省请求标头中提供的令牌，此路由将保护 https://httpbin.org/get（echo 服务）。
+
+```bash
+curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+    "uri":"/get",
+    "plugins":{
+        "proxy-rewrite":{
+            "scheme":"https"
+        },
+        "openid-connect":{
+            "client_id":"api_six_client_id",
+            "client_secret":"client_secret_code",
+            "discovery":"full_URL_of_the_discovery_endpoint",
+            "introspection_endpoint":"full_URL_of_introspection_endpoint",
+            "bearer_only":true,
+            "realm":"master",
+            "introspection_endpoint_auth_method":"client_secret_basic"
+        }
+    },
+    "upstream":{
+        "type":"roundrobin",
+        "nodes":{
+            "httpbin.org:443":1
+        }
+    }
+}'
+```
+
+以下命令可用于访问新路由。
+
+```bash
+curl -i -X GET http://127.0.0.1:9080/get -H "Host: httpbin.org" -H "Authorization: Bearer {replace_jwt_token}"
+```
+
+#### 公钥自省
+
+您还可以提供 JWT 令牌的公钥来验证令牌。 如果您提供了公共密钥和令牌自省端点，则将执行公共密钥工作流，而不是通过身份服务器进行验证。如果要减少额外的网络呼叫并加快过程，可以使用此方法。
+
+以下配置显示了如何向路由添加公钥自省。
+
+```bash
+curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+    "uri":"/get",
+    "plugins":{
+        "proxy-rewrite":{
+            "scheme":"https"
+        },
+        "openid-connect":{
+            "client_id":"api_six_client_id",
+            "client_secret":"client_secret_code",
+            "discovery":"full_URL_of_the_discovery_endpoint",
+            "bearer_only":true,
+            "realm":"master",
+            "token_signing_alg_values_expected":"RS256",
+            "public_key":"-----BEGIN CERTIFICATE-----
+            {public_key}
+            -----END CERTIFICATE-----"
+        }
+    },
+    "upstream":{
+        "type":"roundrobin",
+        "nodes":{
+            "httpbin.org:443":1
+        }
+    }
+}'
+```
+
+## 故障排除
+
+如果 APISIX 无法解析/连接到身份提供者，请检查/修改DNS设置（`conf / config.yaml`）。