From fe9537b036ebd2619dcc852c734e71850fbb9338 Mon Sep 17 00:00:00 2001 From: Scaat Feng Date: Mon, 22 Jun 2020 17:23:14 +0800 Subject: [PATCH 1/3] doc: add oauth plugins chinese documentations. --- doc/zh-cn/plugins/oauth.md | 129 +++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 doc/zh-cn/plugins/oauth.md diff --git a/doc/zh-cn/plugins/oauth.md b/doc/zh-cn/plugins/oauth.md new file mode 100644 index 000000000000..2389e30851fa --- /dev/null +++ b/doc/zh-cn/plugins/oauth.md @@ -0,0 +1,129 @@ + + +# 目录 + +- [**名字**](#名字) +- [**属性**](#属性) +- [**令牌自省**](#令牌自省) + +## 名字 + +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`）。 From 7126d965ac62b43d77a3fe50c8ae9ab8b3e22e2b Mon Sep 17 00:00:00 2001 From: Scaat Feng Date: Mon, 22 Jun 2020 17:33:02 +0800 Subject: [PATCH 2/3] doc: update oauth plugins Chinese documentations. --- doc/zh-cn/plugins/oauth.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/zh-cn/plugins/oauth.md b/doc/zh-cn/plugins/oauth.md index 2389e30851fa..3c6d0ec23ff1 100644 --- a/doc/zh-cn/plugins/oauth.md +++ b/doc/zh-cn/plugins/oauth.md @@ -19,15 +19,15 @@ # 目录 -- [**名字**](#名字) -- [**属性**](#属性) +- [**定义**](#定义) +- [**属性列表**](#属性列表) - [**令牌自省**](#令牌自省) -## 名字 +## 定义 OAuth 2 / Open ID Connect（OIDC）插件为 APISIX 提供身份验证和自省功能。 -## 属性 +## 属性列表 |名称 |必选项 |描述| |------- |----- |------| From b41eb47901f8360e690170633082e3ac35d28501 Mon Sep 17 00:00:00 2001 From: Scaat Feng Date: Tue, 23 Jun 2020 09:48:03 +0800 Subject: [PATCH 3/3] doc: add oauth plugin docs link to README.md --- doc/README.md | 1 + doc/zh-cn/README.md | 1 + 2 files changed, 2 insertions(+) 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 身份验证和自省。