You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2022/01/21 14:15:20 UTC
[GitHub] [apisix-website] yzeng25 opened a new pull request #852: docs: add blog for Vault
yzeng25 opened a new pull request #852:
URL: https://github.com/apache/apisix-website/pull/852
Changes:
Add blog for Vault integration.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
👷 Deploy Preview for *apache-apisix* processing.
🔨 Explore the source changes: 8e05dea1ee7bfc27de408c5488fcb535c14d69d3
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61ee5c9e9bd3540007714b83](https://app.netlify.com/sites/apache-apisix/deploys/61ee5c9e9bd3540007714b83)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
✔️ Deploy Preview for *apache-apisix* ready!
🔨 Explore the source changes: dc01c7b8f723110458766bc7eae98a30898d2021
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61ee6cad1a3a9a000900f3c6](https://app.netlify.com/sites/apache-apisix/deploys/61ee6cad1a3a9a000900f3c6)
😎 Browse the preview: [https://deploy-preview-852--apache-apisix.netlify.app](https://deploy-preview-852--apache-apisix.netlify.app)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] yzeng25 commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r791312277
##########
File path: website/blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,373 @@
+---
+title: "HashiCorp Vault Secure Storage Backend in Apache APISIX Ecosystem"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "Yilin Zeng"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- Ecosystem
+description: This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+
+<!--truncate-->
+
+With the rise of microservice-based architecture, keeping things secure has become much more challenging than earlier. We are far beyond the point where our 100 instances of backend servers are accessing our database server with a single static secret credential because if in case of a credential leakage the whole system is compromised and revocation of that credential causes a massive service outage (now no one can access anything unless the instances are reconfigured). We can't eliminate the possibility of a security breach because sometimes unexpected does happen. Instead, it's totally up to us to control the blast radius in these situations. To tackle scenarios like this, a popular solution like [HashiCorp Vault](https://www.vaultproject.io/) comes into the picture in a production environment to act as an identity-based secrets and encryption management system. In this article, I have demonstrated how to integrate Vault with Apache APISIX (a cloud-native API Gateway) [jwt-auth p
lugin](https://apisix.apache.org/docs/apisix/plugins/jwt-auth) to effectively use excellence from both worlds.
+
+## What is Vault
+
+HashiCorp Vault is designed to help organizations manage access to secrets and transmit them safely within an organization. Secrets are defined as any form of sensitive credentials that need to be tightly controlled and monitored and can be used to unlock sensitive information. Secrets could be in the form of passwords, API keys, SSH keys, RSA tokens, or OTP. In the real world where it is very common to have a secret sprawl where secrets get stored into the config file or as a variable in actual program code which as a consequence sometimes even end up in a version control system like GitHub, BitBucket or GitLab, possess a major threat in security. Vault solves this problem by centralizing secrets. It provides encrypted storage for static secrets, generation of dynamic secrets with a TTL lease, authentication of users (machines or humans) to make sure they’re authorized to access a particular secret and many more. So that even in case of a security breach the blast radius is much
small and contained.
+
+Vault makes it very easy to control and manage access by providing us with a unilateral interface to manage every secret in your infrastructure. Not only that, it also provides the flexibility to create detailed audit logs and keep track of who accessed what.
+
+
+
+## About APISIX jwt-auth Plugin
+
+It is an authentication plugin that can be attached to any APISIX route to perform JWT (JSON web token, [read more](https://jwt.io/introduction)) authentication before the request gets forwarded to the upstream URI. In short, it is a secure authentication mechanism that leads to authorization to critical resources. Typically, a private key, or a text secret, is used by the issuer to sign the JWT. The receiver of the JWT will verify the signature to ensure that the token hasn’t been altered after it was signed by the issuer. The total integrity of the whole jwt mechanism depends on the signing secret (may it be a text secret of RSA keypairs). That makes it difficult for unauthenticated sources to guess the signing key and attempt to change the claims within the JWT.
+
+So the storage of these keys in a secure environment is extremely crucial. Falling into wrong hands may jeopardize the security of the whole infrastructure. Though we from the APISIX side take all the means to follow standard SecOps practices, it's quite natural in the production environment to have a centralized key management solution like HashiCorp vault to have elaborate audit trails, periodic key rotation, key revocation etc. And it would be quite a troublesome issue if each time you have to update Apache APISIX configuration whenever a key rotation occurs throughout the infrastructure.
+
+## Steps to Use Vault with Apache APISIX
+
+For integration with Vault, Apache APISIX needs to be loaded with vault configuration at [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml).
+
+Internally, APISIX communicates with vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1). As most enterprise solution prefers to stick with KV Secrets Engine - Version 1 in their production environment, during the initial phase of APISIX-Vault support we have gone with version 1 only. In later releases, we will add the support of K/V version 2.
+
+The main idea of using vault, instead of the APISIX etcd backend is the security concern in a low trust environment. We, the APISIX developers, understand your priorities seriously. That's why we recommend using vault access tokens that are short scoped and can grant APISIX server limited access.
+
+### Configure Vault
+
+If you have already a Vault instance running with the necessary privileges, feel free to skip this section. This section shares the best practices to use Vault inside the Apache APISIX ecosystem. Please follow the steps mentioned below.
+
+#### Step 1: Spin Up a Vault Server
+
+Here you have multiple options, feel free to choose between docker, precompiled binary or building from source. As to communicate with the vault server, you need a vault CLI client, I would prefer going with precompiled binary instead of the Docker approach. Anyway, it's totally up to you (feel free to consult [Vault's official installation docs](https://www.vaultproject.io/docs/install)). To spin up a development server, please run the following command.
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+Set your current CLI with the correct environment variables.
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+Enable vault k/v version 1 secret engine backend with a suitable path prefix. In this demo, we are going to choose the `kv` path so that we don't have a collision with the vault default secret path for kv version 2.
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### Step 2: Generate a Vault Access Token for APISIX
+
+This article is regarding using vault in `jwt-auth` plugin perspective. So, for an APISIX consumer (if you are unfamiliar with consumers in the APISIX ecosystem, please read the [document about Apache APISIX Consumer](https://apisix.apache.org/docs/apisix/architecture-design/consumer)) with username `jack` the `jwt-auth` plugin looks up (if enabled with vault configuration) for secret/s at `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` into vault kv storage. In this context, if you are assigning `kv/apisix` namespace (vault path) as `vault.prefix` inside config.yaml for all apisix related data retrieval, we suggest you to create a policy for path `kv/apisix/consumer/*`. The extra asterisk (*) at the end ensure the policy allows read for any path that has a `kv/apisix/consumer` prefix.
+
+Create a policy file in HashiCorp Configuration Language (HCL).
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+Applying the policy into vault instance.
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+Generate a token with the newly defined policy that has been configured with the small access boundary.
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+In this demonstration `s.KUWFVhIXgoRuQbbp3j1eMVGa` is your access token.
+
+### Adding vault configuration into Apache APISIX
+
+As discussed earlier, Apache APISIX communicates with Vault instance through Vault HTTP APIs. The necessary configuration must be added into [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml).
+Here is the brief information about different fields that you can use:
+
+- host: The host address where the vault server is running.
+- timeout: HTTP timeout for each request.
+- token: The generated token from vault instance that can grant access to read data from the vault.
+- prefix: enabling a prefix allows you to better enforcement of policies, generate limited scoped tokens and tightly control the data that can be accessed from APISIX. Valid prefixes are (`kv/apisix`, `secret` etc.)
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### Create an APISIX Consumer
+
+APISIX has a consumer-level abstraction that goes side by side with authentication scenarios. To enable authentication for any APISIX route, a consumer is needed with a suitable configuration for that specific type of authentication service. Then only APISIX can forward the request to the upstream URI by successfully performing authentication wrt. the consumer configuration. APISIX consumer has two fields - one is `username` (required) to identify one consumer from the others and another is `plugins` that holds the consumer specific plugin configurations.
+
+Here, in this article, we will create a consumer with `jwt-auth` plugin. It performs JWT authentication for the respective route/s or service/s.
+
+To enable `jwt-auth` with vault configuration, make a request to:
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+Here the plugin looks up for key secret inside vault path (`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`) for consumer `jack` mentioned in the consumer config and uses it for subsequent signing and jwt verification. If the key is not found in the same path, the plugin logs error and fails to perform jwt authentication.
+
+#### Set Up a Test Upstream Server
+
+To test the behaviour, you can create a route for an upstream (a simple ping handler that returns pong). You can set it up with a plain go HTTP-Server.
+
+```go
+// simple upstream server
+package main
+
+
+import "net/http"
+
+
+func ping(w http.ResponseWriter, req *http.Request) {
+ w.Write([]byte("secure/pong\n"))
+}
+
+
+func main() {
+ http.HandleFunc("/secure/ping", ping)
+ http.ListenAndServe(":9999", nil)
+}
+```
+
+#### Create an APISIX Route with Authentication Enabled
+
+Create an APISIX route with this secure ping HTTP server and `jwt-auth` authentication plugin enabled.
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "jwt-auth": {}
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:9999": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/secure/ping"
+}'
+```
+
+#### Generate Token from jwt-auth Plugin
+
+Now sign a jwt secret from APISIX that can be used and passed for making requests to the `http://localhost:9080/secure/ping` proxy route to the APISIX server.
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign\?key\=test-key -i
+HTTP/1.1 200 OK
+Date: Tue, 18 Jan 2022 07:50:57 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODY1N30.nkyev1_KUapVgY_QVYETsSApA6gEkDWS8tsHFV1EpD8
+```
+
+In the previous step, if you see something like the `failed to sign jwt` message please make sure you have a secret key stored into vault `kv/apisix/consumers/jack/jwt-auth` path.
+
+```shell
+# example
+$ vault kv put kv/apisix/consumer/jack/jwt-auth secret=$ecr3t-c0d3
+Success! Data written to: kv/apisix/consumer/jack/jwt-auth
+```
+
+#### Request APISIX Server
+
+Now, make a request to the APISIX proxy for route `/secure/ping`. Upon successful validation, it will forward the request to our go HTTP server.
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODU5M30.IYudBr7FTgRme70u4rEBoYNtGmGByzgfGlt8hctI__Q' -i
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+Content-Length: 12
+Connection: keep-alive
+Date: Tue, 18 Jan 2022 08:00:04 GMT
+Server: APISIX/2.11.0
+
+
+secure/pong
+```
+
+Any request without a valid jwt will throw an `HTTP 401 Unauthorized` error.
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -i
+HTTP/1.1 401 Unauthorized
+Date: Tue, 18 Jan 2022 08:00:33 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+{"message":"Missing JWT token in request"}
+```
+
+### Different Use Cases Where Vault Can be Integrated with APISIX jwt-auth plugin
+
+Apache APISIX `jwt-auth` plugin can be configured to fetch simple text secret keys as well as RS256 public-private key pairs from vault storage.
+
+:::note
+For the early version of this integration support, the plugin expects the key name of secrets stored into the vault path is among [ `secret`, `public_key`, `private_key`] to successfully use the key. In future releases, we are going to add the support of referencing custom-named keys.
+:::
+
+1. You have stored HS256 signing secret inside the vault and you want to use it for jwt signing and verification.
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "key-1",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ Here the plugin looks up for key `secret` inside vault path (`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`) for consumer jack mentioned in the consumer config and uses it for subsequent signing and jwt verification. If the key is not found in the same path, the plugin logs an error and fails to perform jwt authentication.
+
+2. RS256 RSA keypairs, both public and private keys are stored in the vault.
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jim",
+ "plugins": {
+ "jwt-auth": {
+ "key": "rsa-keypair",
+ "algorithm": "RS256",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ The plugin looks up for `public_key` and `private_key` keys inside vault kv path (`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`) for `jim` mentioned inside plugin vault configuration. If not found, authentication fails.
+
+ If you are unsure, how to store public and private keys into vault kv storage, use this command
+
+ ```shell
+ # provided, your current directory contains the files named "public.pem" and "private.pem"
+ $ vault kv put kv/apisix/consumer/jim/jwt-auth public_key=@public.pem private_key=@private.pem
+ Success! Data written to: kv/apisix/consumer/jim/jwt-auth
+ ```
+
+3. Public key in consumer configuration, while the private key is in the vault.
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "john",
+ "plugins": {
+ "jwt-auth": {
+ "key": "user-key",
+ "algorithm": "RS256",
+ "public_key": "-----BEGIN PUBLIC KEY-----\n……\n-----END PUBLIC KEY-----"
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ This plugin uses RSA public key from consumer configuration and uses the private key directly fetched from the vault.
+
+### Disable Vault from Plugin
+
+Now, to disable the vault lookup from the `jwt-auth` plugin simply remove the empty vault object from the consumer plugin configuration (in this case it is `jack`). This will make the jwt plugin to lookup signing secrets (both HS256/HS512 or RS512 keypairs) into plugin configuration for subsequent requests to the URI route where the `jwt-auth` configuration has been enabled. Even if you have vault configuration enabled in APISIX `config.yaml` no request will be sent to the vault server.
+
+APISIX plugins are hot-reloaded, therefore is no need to restart APISIX.
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "secret": "my-secret-key"
+ }
+ }
+}'
+```
+
+## Summary
+
+This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+
+Feel free to start a discussion in [GitHub Discussions](https://github.com/apache/apisix/discussions) or communicate via the [mailing list](https://apisix.apache.org/zh/docs/general/subscribe-guide).
Review comment:
sure
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
✔️ Deploy Preview for *apache-apisix* ready!
🔨 Explore the source changes: f04929e07010bd59fadf9449a69fa52477c264cf
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61eac318a4b23b00071cda8b](https://app.netlify.com/sites/apache-apisix/deploys/61eac318a4b23b00071cda8b)
😎 Browse the preview: [https://deploy-preview-852--apache-apisix.netlify.app](https://deploy-preview-852--apache-apisix.netlify.app)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] juzhiyuan commented on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
juzhiyuan commented on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1019662578
cc @guoqqqi @oil-oil to have a review 😉
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790443850
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
Review comment:
```suggestion
在这里，你有多种选择，可以自由选择 Docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
✔️ Deploy Preview for *apache-apisix* ready!
🔨 Explore the source changes: 2110565e07b177c7367a3a7af2eee596526e6cfd
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61eabff04746f000081cd5e9](https://app.netlify.com/sites/apache-apisix/deploys/61eabff04746f000081cd5e9)
😎 Browse the preview: [https://deploy-preview-852--apache-apisix.netlify.app](https://deploy-preview-852--apache-apisix.netlify.app)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] bisakhmondal commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
bisakhmondal commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r791094923
##########
File path: website/blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,373 @@
+---
+title: "HashiCorp Vault Secure Storage Backend in Apache APISIX Ecosystem"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "Yilin Zeng"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- Ecosystem
+description: This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+tags: [Technology,Ecosystem,Authentication]
Review comment:
```suggestion
tags: [Technology,Authentication]
```
`Ecosystem` doesn't go with it very well. WDYT?
##########
File path: website/blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,373 @@
+---
+title: "HashiCorp Vault Secure Storage Backend in Apache APISIX Ecosystem"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "Yilin Zeng"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- Ecosystem
Review comment:
```suggestion
- Apache APISIX
- HashiCorp
- Vault
- jwt-auth
- Authentication
```
##########
File path: website/blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,373 @@
+---
+title: "HashiCorp Vault Secure Storage Backend in Apache APISIX Ecosystem"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "Yilin Zeng"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- Ecosystem
+description: This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+
+<!--truncate-->
+
+With the rise of microservice-based architecture, keeping things secure has become much more challenging than earlier. We are far beyond the point where our 100 instances of backend servers are accessing our database server with a single static secret credential because if in case of a credential leakage the whole system is compromised and revocation of that credential causes a massive service outage (now no one can access anything unless the instances are reconfigured). We can't eliminate the possibility of a security breach because sometimes unexpected does happen. Instead, it's totally up to us to control the blast radius in these situations. To tackle scenarios like this, a popular solution like [HashiCorp Vault](https://www.vaultproject.io/) comes into the picture in a production environment to act as an identity-based secrets and encryption management system. In this article, I have demonstrated how to integrate Vault with Apache APISIX (a cloud-native API Gateway) [jwt-auth p
lugin](https://apisix.apache.org/docs/apisix/plugins/jwt-auth) to effectively use excellence from both worlds.
+
+## What is Vault
+
+HashiCorp Vault is designed to help organizations manage access to secrets and transmit them safely within an organization. Secrets are defined as any form of sensitive credentials that need to be tightly controlled and monitored and can be used to unlock sensitive information. Secrets could be in the form of passwords, API keys, SSH keys, RSA tokens, or OTP. In the real world where it is very common to have a secret sprawl where secrets get stored into the config file or as a variable in actual program code which as a consequence sometimes even end up in a version control system like GitHub, BitBucket or GitLab, possess a major threat in security. Vault solves this problem by centralizing secrets. It provides encrypted storage for static secrets, generation of dynamic secrets with a TTL lease, authentication of users (machines or humans) to make sure they’re authorized to access a particular secret and many more. So that even in case of a security breach the blast radius is much
small and contained.
+
+Vault makes it very easy to control and manage access by providing us with a unilateral interface to manage every secret in your infrastructure. Not only that, it also provides the flexibility to create detailed audit logs and keep track of who accessed what.
+
+
+
+## About APISIX jwt-auth Plugin
+
+It is an authentication plugin that can be attached to any APISIX route to perform JWT (JSON web token, [read more](https://jwt.io/introduction)) authentication before the request gets forwarded to the upstream URI. In short, it is a secure authentication mechanism that leads to authorization to critical resources. Typically, a private key, or a text secret, is used by the issuer to sign the JWT. The receiver of the JWT will verify the signature to ensure that the token hasn’t been altered after it was signed by the issuer. The total integrity of the whole jwt mechanism depends on the signing secret (may it be a text secret of RSA keypairs). That makes it difficult for unauthenticated sources to guess the signing key and attempt to change the claims within the JWT.
+
+So the storage of these keys in a secure environment is extremely crucial. Falling into wrong hands may jeopardize the security of the whole infrastructure. Though we from the APISIX side take all the means to follow standard SecOps practices, it's quite natural in the production environment to have a centralized key management solution like HashiCorp vault to have elaborate audit trails, periodic key rotation, key revocation etc. And it would be quite a troublesome issue if each time you have to update Apache APISIX configuration whenever a key rotation occurs throughout the infrastructure.
+
+## Steps to Use Vault with Apache APISIX
+
+For integration with Vault, Apache APISIX needs to be loaded with vault configuration at [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml).
+
+Internally, APISIX communicates with vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1). As most enterprise solution prefers to stick with KV Secrets Engine - Version 1 in their production environment, during the initial phase of APISIX-Vault support we have gone with version 1 only. In later releases, we will add the support of K/V version 2.
+
+The main idea of using vault, instead of the APISIX etcd backend is the security concern in a low trust environment. We, the APISIX developers, understand your priorities seriously. That's why we recommend using vault access tokens that are short scoped and can grant APISIX server limited access.
+
+### Configure Vault
+
+If you have already a Vault instance running with the necessary privileges, feel free to skip this section. This section shares the best practices to use Vault inside the Apache APISIX ecosystem. Please follow the steps mentioned below.
+
+#### Step 1: Spin Up a Vault Server
+
+Here you have multiple options, feel free to choose between docker, precompiled binary or building from source. As to communicate with the vault server, you need a vault CLI client, I would prefer going with precompiled binary instead of the Docker approach. Anyway, it's totally up to you (feel free to consult [Vault's official installation docs](https://www.vaultproject.io/docs/install)). To spin up a development server, please run the following command.
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+Set your current CLI with the correct environment variables.
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+Enable vault k/v version 1 secret engine backend with a suitable path prefix. In this demo, we are going to choose the `kv` path so that we don't have a collision with the vault default secret path for kv version 2.
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### Step 2: Generate a Vault Access Token for APISIX
+
+This article is regarding using vault in `jwt-auth` plugin perspective. So, for an APISIX consumer (if you are unfamiliar with consumers in the APISIX ecosystem, please read the [document about Apache APISIX Consumer](https://apisix.apache.org/docs/apisix/architecture-design/consumer)) with username `jack` the `jwt-auth` plugin looks up (if enabled with vault configuration) for secret/s at `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` into vault kv storage. In this context, if you are assigning `kv/apisix` namespace (vault path) as `vault.prefix` inside config.yaml for all apisix related data retrieval, we suggest you to create a policy for path `kv/apisix/consumer/*`. The extra asterisk (*) at the end ensure the policy allows read for any path that has a `kv/apisix/consumer` prefix.
+
+Create a policy file in HashiCorp Configuration Language (HCL).
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+Applying the policy into vault instance.
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+Generate a token with the newly defined policy that has been configured with the small access boundary.
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+In this demonstration `s.KUWFVhIXgoRuQbbp3j1eMVGa` is your access token.
+
+### Adding vault configuration into Apache APISIX
+
+As discussed earlier, Apache APISIX communicates with Vault instance through Vault HTTP APIs. The necessary configuration must be added into [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml).
+Here is the brief information about different fields that you can use:
+
+- host: The host address where the vault server is running.
+- timeout: HTTP timeout for each request.
+- token: The generated token from vault instance that can grant access to read data from the vault.
+- prefix: enabling a prefix allows you to better enforcement of policies, generate limited scoped tokens and tightly control the data that can be accessed from APISIX. Valid prefixes are (`kv/apisix`, `secret` etc.)
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### Create an APISIX Consumer
+
+APISIX has a consumer-level abstraction that goes side by side with authentication scenarios. To enable authentication for any APISIX route, a consumer is needed with a suitable configuration for that specific type of authentication service. Then only APISIX can forward the request to the upstream URI by successfully performing authentication wrt. the consumer configuration. APISIX consumer has two fields - one is `username` (required) to identify one consumer from the others and another is `plugins` that holds the consumer specific plugin configurations.
+
+Here, in this article, we will create a consumer with `jwt-auth` plugin. It performs JWT authentication for the respective route/s or service/s.
+
+To enable `jwt-auth` with vault configuration, make a request to:
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+Here the plugin looks up for key secret inside vault path (`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`) for consumer `jack` mentioned in the consumer config and uses it for subsequent signing and jwt verification. If the key is not found in the same path, the plugin logs error and fails to perform jwt authentication.
+
+#### Set Up a Test Upstream Server
+
+To test the behaviour, you can create a route for an upstream (a simple ping handler that returns pong). You can set it up with a plain go HTTP-Server.
+
+```go
+// simple upstream server
+package main
+
+
+import "net/http"
+
+
+func ping(w http.ResponseWriter, req *http.Request) {
+ w.Write([]byte("secure/pong\n"))
+}
+
+
+func main() {
+ http.HandleFunc("/secure/ping", ping)
+ http.ListenAndServe(":9999", nil)
+}
+```
+
+#### Create an APISIX Route with Authentication Enabled
+
+Create an APISIX route with this secure ping HTTP server and `jwt-auth` authentication plugin enabled.
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "jwt-auth": {}
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:9999": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/secure/ping"
+}'
+```
+
+#### Generate Token from jwt-auth Plugin
+
+Now sign a jwt secret from APISIX that can be used and passed for making requests to the `http://localhost:9080/secure/ping` proxy route to the APISIX server.
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign\?key\=test-key -i
+HTTP/1.1 200 OK
+Date: Tue, 18 Jan 2022 07:50:57 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODY1N30.nkyev1_KUapVgY_QVYETsSApA6gEkDWS8tsHFV1EpD8
+```
+
+In the previous step, if you see something like the `failed to sign jwt` message please make sure you have a secret key stored into vault `kv/apisix/consumers/jack/jwt-auth` path.
+
+```shell
+# example
+$ vault kv put kv/apisix/consumer/jack/jwt-auth secret=$ecr3t-c0d3
+Success! Data written to: kv/apisix/consumer/jack/jwt-auth
+```
+
+#### Request APISIX Server
+
+Now, make a request to the APISIX proxy for route `/secure/ping`. Upon successful validation, it will forward the request to our go HTTP server.
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODU5M30.IYudBr7FTgRme70u4rEBoYNtGmGByzgfGlt8hctI__Q' -i
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+Content-Length: 12
+Connection: keep-alive
+Date: Tue, 18 Jan 2022 08:00:04 GMT
+Server: APISIX/2.11.0
+
+
+secure/pong
+```
+
+Any request without a valid jwt will throw an `HTTP 401 Unauthorized` error.
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -i
+HTTP/1.1 401 Unauthorized
+Date: Tue, 18 Jan 2022 08:00:33 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+{"message":"Missing JWT token in request"}
+```
+
+### Different Use Cases Where Vault Can be Integrated with APISIX jwt-auth plugin
+
+Apache APISIX `jwt-auth` plugin can be configured to fetch simple text secret keys as well as RS256 public-private key pairs from vault storage.
+
+:::note
+For the early version of this integration support, the plugin expects the key name of secrets stored into the vault path is among [ `secret`, `public_key`, `private_key`] to successfully use the key. In future releases, we are going to add the support of referencing custom-named keys.
+:::
+
+1. You have stored HS256 signing secret inside the vault and you want to use it for jwt signing and verification.
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "key-1",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ Here the plugin looks up for key `secret` inside vault path (`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`) for consumer jack mentioned in the consumer config and uses it for subsequent signing and jwt verification. If the key is not found in the same path, the plugin logs an error and fails to perform jwt authentication.
+
+2. RS256 RSA keypairs, both public and private keys are stored in the vault.
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jim",
+ "plugins": {
+ "jwt-auth": {
+ "key": "rsa-keypair",
+ "algorithm": "RS256",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ The plugin looks up for `public_key` and `private_key` keys inside vault kv path (`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`) for `jim` mentioned inside plugin vault configuration. If not found, authentication fails.
+
+ If you are unsure, how to store public and private keys into vault kv storage, use this command
+
+ ```shell
+ # provided, your current directory contains the files named "public.pem" and "private.pem"
+ $ vault kv put kv/apisix/consumer/jim/jwt-auth public_key=@public.pem private_key=@private.pem
+ Success! Data written to: kv/apisix/consumer/jim/jwt-auth
+ ```
+
+3. Public key in consumer configuration, while the private key is in the vault.
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "john",
+ "plugins": {
+ "jwt-auth": {
+ "key": "user-key",
+ "algorithm": "RS256",
+ "public_key": "-----BEGIN PUBLIC KEY-----\n……\n-----END PUBLIC KEY-----"
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ This plugin uses RSA public key from consumer configuration and uses the private key directly fetched from the vault.
+
+### Disable Vault from Plugin
+
+Now, to disable the vault lookup from the `jwt-auth` plugin simply remove the empty vault object from the consumer plugin configuration (in this case it is `jack`). This will make the jwt plugin to lookup signing secrets (both HS256/HS512 or RS512 keypairs) into plugin configuration for subsequent requests to the URI route where the `jwt-auth` configuration has been enabled. Even if you have vault configuration enabled in APISIX `config.yaml` no request will be sent to the vault server.
+
+APISIX plugins are hot-reloaded, therefore is no need to restart APISIX.
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "secret": "my-secret-key"
+ }
+ }
+}'
+```
+
+## Summary
+
+This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+
+Feel free to start a discussion in [GitHub Discussions](https://github.com/apache/apisix/discussions) or communicate via the [mailing list](https://apisix.apache.org/zh/docs/general/subscribe-guide).
Review comment:
```suggestion
Feel free to start a discussion in [GitHub Discussions](https://github.com/apache/apisix/discussions) or communicate via the [mailing list](https://apisix.apache.org/docs/general/subscribe-guide).
```
Btw, just wondering if it is possible to add a ref to my blog? Hehe😅
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790445804
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 第2步：为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。因此，对于一个APISIX 消费者 `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个消费者层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务的配置的消费者。然后，只有 APISIX 可以通过成功执行消费者配置方面的认证，将请求转发到上游 URI。APISIX 消费者有两个字段：一个是 `username`（必填项），用于识别消费者，另一个是 `plugins`，用于保存消费者所使用的特定插件配置。
+
+在这里，在这篇文章中，我们将用 `jwt-auth` 插件创建一个消费者。它为各自的路由或服务执行 JWT认证。
+
+运行以下命令，启用 Vault 配置的 `jwt-auth`。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+在这里，插件在消费者配置中提到的消费者 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件会记录错误，并且无法执行 jwt 验证。
+
+#### 设置一个测试的上游 server
+
+为了测试这个行为，你可以为一个上游创建一个路由（一个简单的 ping 处理程序，返回 pong）。你可以用一个普通的 go HTTP-Server 来设置它。
Review comment:
返回 pong 还是返回 ping
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
✔️ Deploy Preview for *apache-apisix* ready!
🔨 Explore the source changes: 8e05dea1ee7bfc27de408c5488fcb535c14d69d3
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61ee5c9e9bd3540007714b83](https://app.netlify.com/sites/apache-apisix/deploys/61ee5c9e9bd3540007714b83)
😎 Browse the preview: [https://deploy-preview-852--apache-apisix.netlify.app](https://deploy-preview-852--apache-apisix.netlify.app)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
✔️ Deploy Preview for *apache-apisix* ready!
🔨 Explore the source changes: 7131af89e2adda8a05417ea47710c455b5779b43
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61ef6397b0837e00088a0259](https://app.netlify.com/sites/apache-apisix/deploys/61ef6397b0837e00088a0259)
😎 Browse the preview: [https://deploy-preview-852--apache-apisix.netlify.app](https://deploy-preview-852--apache-apisix.netlify.app)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790443046
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
Review comment:
```suggestion
本文演示了如何将 Vault 与 Apache APISIX 的 `jwt-auth` 插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
✔️ Deploy Preview for *apache-apisix* ready!
🔨 Explore the source changes: fb24609c80c13623219ae557e52bf923daca16e7
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61ee6a28d784c600083848dc](https://app.netlify.com/sites/apache-apisix/deploys/61ee6a28d784c600083848dc)
😎 Browse the preview: [https://deploy-preview-852--apache-apisix.netlify.app](https://deploy-preview-852--apache-apisix.netlify.app)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
👷 Deploy Preview for *apache-apisix* processing.
🔨 Explore the source changes: fb24609c80c13623219ae557e52bf923daca16e7
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61ee6a28d784c600083848dc](https://app.netlify.com/sites/apache-apisix/deploys/61ee6a28d784c600083848dc)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790447941
##########
File path: website/blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,373 @@
+---
+title: "HashiCorp Vault Secure Storage Backend in Apache APISIX Ecosystem"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "Yilin Zeng"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- Ecosystem
+description: This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+
+<!--truncate-->
+
+With the rise of microservice-based architecture, keeping things secure has become much more challenging than earlier. We are far beyond the point where our 100 instances of backend servers are accessing our database server with a single static secret credential because if in case of a credential leakage the whole system is compromised and revocation of that credential causes a massive service outage (now no one can access anything unless the instances are reconfigured). We can't eliminate the possibility of a security breach because sometimes unexpected does happen. Instead, it's totally up to us to control the blast radius in these situations. To tackle scenarios like this, a popular solution like [HashiCorp Vault](https://www.vaultproject.io/) comes into the picture in a production environment to act as an identity-based secrets and encryption management system. In this article, I have demonstrated how to integrate Vault with Apache APISIX (a cloud-native API Gateway) [jwt-auth p
lugin](https://apisix.apache.org/docs/apisix/plugins/jwt-auth) to effectively use excellence from both worlds.
+
+## What is Vault
+
+HashiCorp Vault is designed to help organizations manage access to secrets and transmit them safely within an organization. Secrets are defined as any form of sensitive credentials that need to be tightly controlled and monitored and can be used to unlock sensitive information. Secrets could be in the form of passwords, API keys, SSH keys, RSA tokens, or OTP. In the real world where it is very common to have a secret sprawl where secrets get stored into the config file or as a variable in actual program code which as a consequence sometimes even end up in a version control system like GitHub, BitBucket or GitLab, possess a major threat in security. Vault solves this problem by centralizing secrets. It provides encrypted storage for static secrets, generation of dynamic secrets with a TTL lease, authentication of users (machines or humans) to make sure they’re authorized to access a particular secret and many more. So that even in case of a security breach the blast radius is much
small and contained.
+
+Vault makes it very easy to control and manage access by providing us with a unilateral interface to manage every secret in your infrastructure. Not only that, it also provides the flexibility to create detailed audit logs and keep track of who accessed what.
+
+
+
+## About APISIX jwt-auth Plugin
+
+It is an authentication plugin that can be attached to any APISIX route to perform JWT (JSON web token, [read more](https://jwt.io/introduction)) authentication before the request gets forwarded to the upstream URI. In short, it is a secure authentication mechanism that leads to authorization to critical resources. Typically, a private key, or a text secret, is used by the issuer to sign the JWT. The receiver of the JWT will verify the signature to ensure that the token hasn’t been altered after it was signed by the issuer. The total integrity of the whole jwt mechanism depends on the signing secret (may it be a text secret of RSA keypairs). That makes it difficult for unauthenticated sources to guess the signing key and attempt to change the claims within the JWT.
+
+So the storage of these keys in a secure environment is extremely crucial. Falling into wrong hands may jeopardize the security of the whole infrastructure. Though we from the APISIX side take all the means to follow standard SecOps practices, it's quite natural in the production environment to have a centralized key management solution like HashiCorp vault to have elaborate audit trails, periodic key rotation, key revocation etc. And it would be quite a troublesome issue if each time you have to update Apache APISIX configuration whenever a key rotation occurs throughout the infrastructure.
+
+## Steps to Use Vault with Apache APISIX
+
+For integration with Vault, Apache APISIX needs to be loaded with vault configuration at [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml).
+
+Internally, APISIX communicates with vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1). As most enterprise solution prefers to stick with KV Secrets Engine - Version 1 in their production environment, during the initial phase of APISIX-Vault support we have gone with version 1 only. In later releases, we will add the support of K/V version 2.
+
+The main idea of using vault, instead of the APISIX etcd backend is the security concern in a low trust environment. We, the APISIX developers, understand your priorities seriously. That's why we recommend using vault access tokens that are short scoped and can grant APISIX server limited access.
+
+### Configure Vault
+
+If you have already a Vault instance running with the necessary privileges, feel free to skip this section. This section shares the best practices to use Vault inside the Apache APISIX ecosystem. Please follow the steps mentioned below.
+
+#### Step 1: Spin Up a Vault Server
+
+Here you have multiple options, feel free to choose between docker, precompiled binary or building from source. As to communicate with the vault server, you need a vault CLI client, I would prefer going with precompiled binary instead of the Docker approach. Anyway, it's totally up to you (feel free to consult [Vault's official installation docs](https://www.vaultproject.io/docs/install)). To spin up a development server, please run the following command.
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+Set your current CLI with the correct environment variables.
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+Enable vault k/v version 1 secret engine backend with a suitable path prefix. In this demo, we are going to choose the `kv` path so that we don't have a collision with the vault default secret path for kv version 2.
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### Step 2: Generate a Vault Access Token for APISIX
+
+This article is regarding using vault in jwt-auth plugin perspective. So, for an APISIX consumer (if you are unfamiliar with consumers in the APISIX ecosystem, please read the [document about Apache APISIX Consumer](https://apisix.apache.org/docs/apisix/architecture-design/consumer)) with username `jack` the jwt-auth plugin looks up (if enabled with vault configuration) for secret/s at `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` into vault kv storage. In this context, if you are assigning `kv/apisix` namespace (vault path) as `vault.prefix` inside config.yaml for all apisix related data retrieval, we suggest you to create a policy for path `kv/apisix/consumer/*`. The extra asterisk (*) at the end ensure the policy allows read for any path that has a `kv/apisix/consumer` prefix.
Review comment:
```suggestion
This article is regarding using vault in `jwt-auth` plugin perspective. So, for an APISIX consumer (if you are unfamiliar with consumers in the APISIX ecosystem, please read the [document about Apache APISIX Consumer](https://apisix.apache.org/docs/apisix/architecture-design/consumer)) with username `jack` the `jwt-auth` plugin looks up (if enabled with vault configuration) for secret/s at `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` into vault kv storage. In this context, if you are assigning `kv/apisix` namespace (vault path) as `vault.prefix` inside config.yaml for all apisix related data retrieval, we suggest you to create a policy for path `kv/apisix/consumer/*`. The extra asterisk (*) at the end ensure the policy allows read for any path that has a `kv/apisix/consumer` prefix.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] juzhiyuan merged pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
juzhiyuan merged pull request #852:
URL: https://github.com/apache/apisix-website/pull/852
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
👷 Deploy Preview for *apache-apisix* processing.
🔨 Explore the source changes: b96772fe1088a68f11e1eadb28685fea14e1f221
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61ee62ee0210e500070d39e9](https://app.netlify.com/sites/apache-apisix/deploys/61ee62ee0210e500070d39e9)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790445252
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 第2步：为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。因此，对于一个APISIX 消费者 `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个消费者层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务的配置的消费者。然后，只有 APISIX 可以通过成功执行消费者配置方面的认证，将请求转发到上游 URI。APISIX 消费者有两个字段：一个是 `username`（必填项），用于识别消费者，另一个是 `plugins`，用于保存消费者所使用的特定插件配置。
Review comment:
```suggestion
APISIX 有一个消费者层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务配置的消费者。之后将通过 APISIX 成功执行消费者配置方面的认证请求转发到上游 URI。APISIX 消费者有两个字段：一个是 `username`（必填项），用于识别消费者；另一个是 `plugins`，用于保存消费者所使用的特定插件配置。
```
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 第2步：为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。因此，对于一个APISIX 消费者 `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个消费者层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务的配置的消费者。然后，只有 APISIX 可以通过成功执行消费者配置方面的认证，将请求转发到上游 URI。APISIX 消费者有两个字段：一个是 `username`（必填项），用于识别消费者，另一个是 `plugins`，用于保存消费者所使用的特定插件配置。
+
+在这里，在这篇文章中，我们将用 `jwt-auth` 插件创建一个消费者。它为各自的路由或服务执行 JWT认证。
Review comment:
```suggestion
在这里，在这篇文章中，我们将用 `jwt-auth` 插件创建一个消费者。它为各自的路由或服务执行 JWT 认证。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790445892
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 第2步：为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。因此，对于一个APISIX 消费者 `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个消费者层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务的配置的消费者。然后，只有 APISIX 可以通过成功执行消费者配置方面的认证，将请求转发到上游 URI。APISIX 消费者有两个字段：一个是 `username`（必填项），用于识别消费者，另一个是 `plugins`，用于保存消费者所使用的特定插件配置。
+
+在这里，在这篇文章中，我们将用 `jwt-auth` 插件创建一个消费者。它为各自的路由或服务执行 JWT认证。
+
+运行以下命令，启用 Vault 配置的 `jwt-auth`。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+在这里，插件在消费者配置中提到的消费者 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件会记录错误，并且无法执行 jwt 验证。
+
+#### 设置一个测试的上游 server
+
+为了测试这个行为，你可以为一个上游创建一个路由（一个简单的 ping 处理程序，返回 pong）。你可以用一个普通的 go HTTP-Server 来设置它。
+
+```go
+// simple upstream server
+package main
+
+
+import "net/http"
+
+
+func ping(w http.ResponseWriter, req *http.Request) {
+ w.Write([]byte("secure/pong\n"))
+}
+
+
+func main() {
+ http.HandleFunc("/secure/ping", ping)
+ http.ListenAndServe(":9999", nil)
+}
+```
+
+#### 创建一个启用了认证的 APISIX 路由
+
+用这个安全的 ping HTTP server和启用了 jwt-auth 认证插件创建一个 APISIX 路由。
Review comment:
```suggestion
用这个安全的 ping HTTP server 和启用了 `jwt-auth` 认证插件创建一个 APISIX 路由。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790444212
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 第2步：为 Apache APISIX 生成一个 Vault 访问令牌
Review comment:
```suggestion
#### 第 2 步：为 Apache APISIX 生成一个 Vault 访问令牌
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
👷 Deploy Preview for *apache-apisix* processing.
🔨 Explore the source changes: 7131af89e2adda8a05417ea47710c455b5779b43
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61ef6397b0837e00088a0259](https://app.netlify.com/sites/apache-apisix/deploys/61ef6397b0837e00088a0259)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] commented on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] commented on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
👷 Deploy Preview for *apache-apisix* processing.
🔨 Explore the source changes: 2110565e07b177c7367a3a7af2eee596526e6cfd
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61eabff04746f000081cd5e9](https://app.netlify.com/sites/apache-apisix/deploys/61eabff04746f000081cd5e9)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790446968
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 第2步：为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。因此，对于一个APISIX 消费者 `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个消费者层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务的配置的消费者。然后，只有 APISIX 可以通过成功执行消费者配置方面的认证，将请求转发到上游 URI。APISIX 消费者有两个字段：一个是 `username`（必填项），用于识别消费者，另一个是 `plugins`，用于保存消费者所使用的特定插件配置。
+
+在这里，在这篇文章中，我们将用 `jwt-auth` 插件创建一个消费者。它为各自的路由或服务执行 JWT认证。
+
+运行以下命令，启用 Vault 配置的 `jwt-auth`。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+在这里，插件在消费者配置中提到的消费者 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件会记录错误，并且无法执行 jwt 验证。
+
+#### 设置一个测试的上游 server
+
+为了测试这个行为，你可以为一个上游创建一个路由（一个简单的 ping 处理程序，返回 pong）。你可以用一个普通的 go HTTP-Server 来设置它。
+
+```go
+// simple upstream server
+package main
+
+
+import "net/http"
+
+
+func ping(w http.ResponseWriter, req *http.Request) {
+ w.Write([]byte("secure/pong\n"))
+}
+
+
+func main() {
+ http.HandleFunc("/secure/ping", ping)
+ http.ListenAndServe(":9999", nil)
+}
+```
+
+#### 创建一个启用了认证的 APISIX 路由
+
+用这个安全的 ping HTTP server和启用了 jwt-auth 认证插件创建一个 APISIX 路由。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "jwt-auth": {}
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:9999": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/secure/ping"
+}'
+```
+
+#### 从 jwt-auth 插件生成令牌
+
+现在从 APISIX 签署一个 jwt 密文，可以用于并通过向 APISIX server的 `http://localhost:9080/secure/ping` 代理路由发出请求。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign\?key\=test-key -i
+HTTP/1.1 200 OK
+Date: Tue, 18 Jan 2022 07:50:57 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODY1N30.nkyev1_KUapVgY_QVYETsSApA6gEkDWS8tsHFV1EpD8
+```
+
+在上一步中，如果你看到类似 `failed to sign jwt` 的信息，请确保你有一个私有密钥存储在vault `kv/apisix/consumers/jack/jwt-aut` 路径中。
+
+```shell
+# example
+$ vault kv put kv/apisix/consumer/jack/jwt-auth secret=$ecr3t-c0d3
+Success! Data written to: kv/apisix/consumer/jack/jwt-auth
+```
+
+#### 向 APISIX Server 发送请求
+
+现在，向 APISIX 代理发出一个路由 `/secure/ping` 的请求。验证成功后，它将把请求转发给我们的 go HTTP server。
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODU5M30.IYudBr7FTgRme70u4rEBoYNtGmGByzgfGlt8hctI__Q' -i
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+Content-Length: 12
+Connection: keep-alive
+Date: Tue, 18 Jan 2022 08:00:04 GMT
+Server: APISIX/2.11.0
+
+
+secure/pong
+```
+
+任何无效的 jwt 请求都会抛出 `HTTP 401 Unauthorized` 的错误。
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -i
+HTTP/1.1 401 Unauthorized
+Date: Tue, 18 Jan 2022 08:00:33 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+{"message":"Missing JWT token in request"}
+```
+
+### Vault 与 APISIX jwt-auth 插件集成的不同用例
+
+Apache APISIX `jwt-auth` 插件可以被配置为从 Vault 存储中获取简单的文本密钥以及 RS256 公私密钥对。
+
+:::note
+对于该集成支持的早期版本，该插件希望存储到金库路径中的密钥名称在 [`secret`, `public_key`, `private_key`] 之间，以成功使用该密钥。在未来的版本中，我们将增加对引用自定义命名的密钥的支持。
+:::
+
+1. 你在 Vault 内存储了 HS256 签名密钥，你想用它来进行 jwt 签名和验证。
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "key-1",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ 在这里，插件在消费者配置中提到的消费者用户 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件将记录一个错误，并且无法执行 jwt 验证。
+
+2. RS256 RSA 密钥对，公钥和私钥都存储在 Vault 中。
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jim",
+ "plugins": {
+ "jwt-auth": {
+ "key": "rsa-keypair",
+ "algorithm": "RS256",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ The plugin looks up for `public_key` and `private_key` keys inside vault kv path (`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`) for `jim` mentioned inside plugin vault configuration. If not found, authentication fails.
+ 该插件在 Vault 键值对 路径（`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`）中为插件 Vault 配置中提到的用户 `jim` 查找 `public_key` 和 `private_key`。如果没有找到，认证失败。
+
+ 如果你不确定如何将公钥和私钥存储到 Vault 键值对 中，请使用这个命令。
+
+ ```shell
+ # provided, your current directory contains the files named "public.pem" and "private.pem"
+ $ vault kv put kv/apisix/consumer/jim/jwt-auth public_key=@public.pem private_key=@private.pem
+ Success! Data written to: kv/apisix/consumer/jim/jwt-auth
+ ```
+
+3. 消费者配置中的公钥，而私钥在 Vault 中。
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "john",
+ "plugins": {
+ "jwt-auth": {
+ "key": "user-key",
+ "algorithm": "RS256",
+ "public_key": "-----BEGIN PUBLIC KEY-----\n……\n-----END PUBLIC KEY-----"
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ 这个插件使用来自消费者配置的 RSA 公钥，并使用直接从 Vault 获取的私钥。
+
+### 禁用 Vault 插件
+
+现在，要禁用 `jwt-auth` 插件的 Vault 查询，只需从消费者插件配置中删除空的 Vault 对象（本例中是 `jack`）。这将使 jwt 插件在随后对已启用 jwt-auth 配置的 URI 路由的请求中，将查找签名密钥（包括 HS256/HS512 或 RS512 密钥对）纳入插件配置。即使你在 APISIX `config.yaml` 中启用了 Vault 配置，也不会有请求被发送到 Vault server。
Review comment:
```suggestion
现在，要禁用 `jwt-auth` 插件的 Vault 查询，只需从消费者插件配置中删除空的 Vault 对象（本例中是 `jack`）。这将使 JWT 插件在随后对已启用 `jwt-auth` 配置的 URI 路由的请求中，将查找签名密钥（包括 HS256/HS512 或 RS512 密钥对）纳入插件配置。即使你在 APISIX `config.yaml` 中启用了 Vault 配置，也不会有请求被发送到 Vault server。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] zaunist commented on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
zaunist commented on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1020856328
LGTM
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] yzeng25 commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r791312277
##########
File path: website/blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,373 @@
+---
+title: "HashiCorp Vault Secure Storage Backend in Apache APISIX Ecosystem"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "Yilin Zeng"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- Ecosystem
+description: This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+
+<!--truncate-->
+
+With the rise of microservice-based architecture, keeping things secure has become much more challenging than earlier. We are far beyond the point where our 100 instances of backend servers are accessing our database server with a single static secret credential because if in case of a credential leakage the whole system is compromised and revocation of that credential causes a massive service outage (now no one can access anything unless the instances are reconfigured). We can't eliminate the possibility of a security breach because sometimes unexpected does happen. Instead, it's totally up to us to control the blast radius in these situations. To tackle scenarios like this, a popular solution like [HashiCorp Vault](https://www.vaultproject.io/) comes into the picture in a production environment to act as an identity-based secrets and encryption management system. In this article, I have demonstrated how to integrate Vault with Apache APISIX (a cloud-native API Gateway) [jwt-auth p
lugin](https://apisix.apache.org/docs/apisix/plugins/jwt-auth) to effectively use excellence from both worlds.
+
+## What is Vault
+
+HashiCorp Vault is designed to help organizations manage access to secrets and transmit them safely within an organization. Secrets are defined as any form of sensitive credentials that need to be tightly controlled and monitored and can be used to unlock sensitive information. Secrets could be in the form of passwords, API keys, SSH keys, RSA tokens, or OTP. In the real world where it is very common to have a secret sprawl where secrets get stored into the config file or as a variable in actual program code which as a consequence sometimes even end up in a version control system like GitHub, BitBucket or GitLab, possess a major threat in security. Vault solves this problem by centralizing secrets. It provides encrypted storage for static secrets, generation of dynamic secrets with a TTL lease, authentication of users (machines or humans) to make sure they’re authorized to access a particular secret and many more. So that even in case of a security breach the blast radius is much
small and contained.
+
+Vault makes it very easy to control and manage access by providing us with a unilateral interface to manage every secret in your infrastructure. Not only that, it also provides the flexibility to create detailed audit logs and keep track of who accessed what.
+
+
+
+## About APISIX jwt-auth Plugin
+
+It is an authentication plugin that can be attached to any APISIX route to perform JWT (JSON web token, [read more](https://jwt.io/introduction)) authentication before the request gets forwarded to the upstream URI. In short, it is a secure authentication mechanism that leads to authorization to critical resources. Typically, a private key, or a text secret, is used by the issuer to sign the JWT. The receiver of the JWT will verify the signature to ensure that the token hasn’t been altered after it was signed by the issuer. The total integrity of the whole jwt mechanism depends on the signing secret (may it be a text secret of RSA keypairs). That makes it difficult for unauthenticated sources to guess the signing key and attempt to change the claims within the JWT.
+
+So the storage of these keys in a secure environment is extremely crucial. Falling into wrong hands may jeopardize the security of the whole infrastructure. Though we from the APISIX side take all the means to follow standard SecOps practices, it's quite natural in the production environment to have a centralized key management solution like HashiCorp vault to have elaborate audit trails, periodic key rotation, key revocation etc. And it would be quite a troublesome issue if each time you have to update Apache APISIX configuration whenever a key rotation occurs throughout the infrastructure.
+
+## Steps to Use Vault with Apache APISIX
+
+For integration with Vault, Apache APISIX needs to be loaded with vault configuration at [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml).
+
+Internally, APISIX communicates with vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1). As most enterprise solution prefers to stick with KV Secrets Engine - Version 1 in their production environment, during the initial phase of APISIX-Vault support we have gone with version 1 only. In later releases, we will add the support of K/V version 2.
+
+The main idea of using vault, instead of the APISIX etcd backend is the security concern in a low trust environment. We, the APISIX developers, understand your priorities seriously. That's why we recommend using vault access tokens that are short scoped and can grant APISIX server limited access.
+
+### Configure Vault
+
+If you have already a Vault instance running with the necessary privileges, feel free to skip this section. This section shares the best practices to use Vault inside the Apache APISIX ecosystem. Please follow the steps mentioned below.
+
+#### Step 1: Spin Up a Vault Server
+
+Here you have multiple options, feel free to choose between docker, precompiled binary or building from source. As to communicate with the vault server, you need a vault CLI client, I would prefer going with precompiled binary instead of the Docker approach. Anyway, it's totally up to you (feel free to consult [Vault's official installation docs](https://www.vaultproject.io/docs/install)). To spin up a development server, please run the following command.
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+Set your current CLI with the correct environment variables.
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+Enable vault k/v version 1 secret engine backend with a suitable path prefix. In this demo, we are going to choose the `kv` path so that we don't have a collision with the vault default secret path for kv version 2.
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### Step 2: Generate a Vault Access Token for APISIX
+
+This article is regarding using vault in `jwt-auth` plugin perspective. So, for an APISIX consumer (if you are unfamiliar with consumers in the APISIX ecosystem, please read the [document about Apache APISIX Consumer](https://apisix.apache.org/docs/apisix/architecture-design/consumer)) with username `jack` the `jwt-auth` plugin looks up (if enabled with vault configuration) for secret/s at `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` into vault kv storage. In this context, if you are assigning `kv/apisix` namespace (vault path) as `vault.prefix` inside config.yaml for all apisix related data retrieval, we suggest you to create a policy for path `kv/apisix/consumer/*`. The extra asterisk (*) at the end ensure the policy allows read for any path that has a `kv/apisix/consumer` prefix.
+
+Create a policy file in HashiCorp Configuration Language (HCL).
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+Applying the policy into vault instance.
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+Generate a token with the newly defined policy that has been configured with the small access boundary.
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+In this demonstration `s.KUWFVhIXgoRuQbbp3j1eMVGa` is your access token.
+
+### Adding vault configuration into Apache APISIX
+
+As discussed earlier, Apache APISIX communicates with Vault instance through Vault HTTP APIs. The necessary configuration must be added into [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml).
+Here is the brief information about different fields that you can use:
+
+- host: The host address where the vault server is running.
+- timeout: HTTP timeout for each request.
+- token: The generated token from vault instance that can grant access to read data from the vault.
+- prefix: enabling a prefix allows you to better enforcement of policies, generate limited scoped tokens and tightly control the data that can be accessed from APISIX. Valid prefixes are (`kv/apisix`, `secret` etc.)
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### Create an APISIX Consumer
+
+APISIX has a consumer-level abstraction that goes side by side with authentication scenarios. To enable authentication for any APISIX route, a consumer is needed with a suitable configuration for that specific type of authentication service. Then only APISIX can forward the request to the upstream URI by successfully performing authentication wrt. the consumer configuration. APISIX consumer has two fields - one is `username` (required) to identify one consumer from the others and another is `plugins` that holds the consumer specific plugin configurations.
+
+Here, in this article, we will create a consumer with `jwt-auth` plugin. It performs JWT authentication for the respective route/s or service/s.
+
+To enable `jwt-auth` with vault configuration, make a request to:
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+Here the plugin looks up for key secret inside vault path (`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`) for consumer `jack` mentioned in the consumer config and uses it for subsequent signing and jwt verification. If the key is not found in the same path, the plugin logs error and fails to perform jwt authentication.
+
+#### Set Up a Test Upstream Server
+
+To test the behaviour, you can create a route for an upstream (a simple ping handler that returns pong). You can set it up with a plain go HTTP-Server.
+
+```go
+// simple upstream server
+package main
+
+
+import "net/http"
+
+
+func ping(w http.ResponseWriter, req *http.Request) {
+ w.Write([]byte("secure/pong\n"))
+}
+
+
+func main() {
+ http.HandleFunc("/secure/ping", ping)
+ http.ListenAndServe(":9999", nil)
+}
+```
+
+#### Create an APISIX Route with Authentication Enabled
+
+Create an APISIX route with this secure ping HTTP server and `jwt-auth` authentication plugin enabled.
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "jwt-auth": {}
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:9999": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/secure/ping"
+}'
+```
+
+#### Generate Token from jwt-auth Plugin
+
+Now sign a jwt secret from APISIX that can be used and passed for making requests to the `http://localhost:9080/secure/ping` proxy route to the APISIX server.
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign\?key\=test-key -i
+HTTP/1.1 200 OK
+Date: Tue, 18 Jan 2022 07:50:57 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODY1N30.nkyev1_KUapVgY_QVYETsSApA6gEkDWS8tsHFV1EpD8
+```
+
+In the previous step, if you see something like the `failed to sign jwt` message please make sure you have a secret key stored into vault `kv/apisix/consumers/jack/jwt-auth` path.
+
+```shell
+# example
+$ vault kv put kv/apisix/consumer/jack/jwt-auth secret=$ecr3t-c0d3
+Success! Data written to: kv/apisix/consumer/jack/jwt-auth
+```
+
+#### Request APISIX Server
+
+Now, make a request to the APISIX proxy for route `/secure/ping`. Upon successful validation, it will forward the request to our go HTTP server.
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODU5M30.IYudBr7FTgRme70u4rEBoYNtGmGByzgfGlt8hctI__Q' -i
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+Content-Length: 12
+Connection: keep-alive
+Date: Tue, 18 Jan 2022 08:00:04 GMT
+Server: APISIX/2.11.0
+
+
+secure/pong
+```
+
+Any request without a valid jwt will throw an `HTTP 401 Unauthorized` error.
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -i
+HTTP/1.1 401 Unauthorized
+Date: Tue, 18 Jan 2022 08:00:33 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+{"message":"Missing JWT token in request"}
+```
+
+### Different Use Cases Where Vault Can be Integrated with APISIX jwt-auth plugin
+
+Apache APISIX `jwt-auth` plugin can be configured to fetch simple text secret keys as well as RS256 public-private key pairs from vault storage.
+
+:::note
+For the early version of this integration support, the plugin expects the key name of secrets stored into the vault path is among [ `secret`, `public_key`, `private_key`] to successfully use the key. In future releases, we are going to add the support of referencing custom-named keys.
+:::
+
+1. You have stored HS256 signing secret inside the vault and you want to use it for jwt signing and verification.
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "key-1",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ Here the plugin looks up for key `secret` inside vault path (`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`) for consumer jack mentioned in the consumer config and uses it for subsequent signing and jwt verification. If the key is not found in the same path, the plugin logs an error and fails to perform jwt authentication.
+
+2. RS256 RSA keypairs, both public and private keys are stored in the vault.
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jim",
+ "plugins": {
+ "jwt-auth": {
+ "key": "rsa-keypair",
+ "algorithm": "RS256",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ The plugin looks up for `public_key` and `private_key` keys inside vault kv path (`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`) for `jim` mentioned inside plugin vault configuration. If not found, authentication fails.
+
+ If you are unsure, how to store public and private keys into vault kv storage, use this command
+
+ ```shell
+ # provided, your current directory contains the files named "public.pem" and "private.pem"
+ $ vault kv put kv/apisix/consumer/jim/jwt-auth public_key=@public.pem private_key=@private.pem
+ Success! Data written to: kv/apisix/consumer/jim/jwt-auth
+ ```
+
+3. Public key in consumer configuration, while the private key is in the vault.
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "john",
+ "plugins": {
+ "jwt-auth": {
+ "key": "user-key",
+ "algorithm": "RS256",
+ "public_key": "-----BEGIN PUBLIC KEY-----\n……\n-----END PUBLIC KEY-----"
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ This plugin uses RSA public key from consumer configuration and uses the private key directly fetched from the vault.
+
+### Disable Vault from Plugin
+
+Now, to disable the vault lookup from the `jwt-auth` plugin simply remove the empty vault object from the consumer plugin configuration (in this case it is `jack`). This will make the jwt plugin to lookup signing secrets (both HS256/HS512 or RS512 keypairs) into plugin configuration for subsequent requests to the URI route where the `jwt-auth` configuration has been enabled. Even if you have vault configuration enabled in APISIX `config.yaml` no request will be sent to the vault server.
+
+APISIX plugins are hot-reloaded, therefore is no need to restart APISIX.
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "secret": "my-secret-key"
+ }
+ }
+}'
+```
+
+## Summary
+
+This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+
+Feel free to start a discussion in [GitHub Discussions](https://github.com/apache/apisix/discussions) or communicate via the [mailing list](https://apisix.apache.org/zh/docs/general/subscribe-guide).
Review comment:
sure
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790444344
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 第2步：为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。因此，对于一个APISIX 消费者 `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
Review comment:
```suggestion
本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。因此，对于一个 APISIX 消费者 `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
👷 Deploy Preview for *apache-apisix* processing.
🔨 Explore the source changes: dc01c7b8f723110458766bc7eae98a30898d2021
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61ee6cad1a3a9a000900f3c6](https://app.netlify.com/sites/apache-apisix/deploys/61ee6cad1a3a9a000900f3c6)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] yzeng25 commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
yzeng25 commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r792292782
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,383 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 认证
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断，对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 `jwt-auth` 插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在 APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 Docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的介绍。因此，对于一个 APISIX Consumer `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个 Consumer 层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务配置的 Consumer。之后将通过 APISIX 成功执行 Consumer 配置方面的认证请求转发到上游 URI。APISIX Consumer 有两个字段：一个是 `username`（必填项），用于识别 Consumer；另一个是 `plugins`，用于保存 Consumer 所使用的特定插件配置。
+
+在这里，在这篇文章中，我们将用 `jwt-auth` 插件创建一个 Consumer。它为各自的路由或服务执行 JWT 认证。
+
+运行以下命令，启用 Vault 配置的 `jwt-auth`。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+在这里，插件在 Consumer 配置中提到的 Consumer `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件会记录错误，并且无法执行 JWT 验证。
+
+#### 设置一个测试的上游 server
+
+为了测试这个行为，你可以为一个上游创建一个路由（一个简单的 ping 处理程序，返回 pong）。你可以用一个普通的 go HTTP-Server 来设置它。
+
+```go
+// simple upstream server
+package main
+
+
+import "net/http"
+
+
+func ping(w http.ResponseWriter, req *http.Request) {
+ w.Write([]byte("secure/pong\n"))
+}
+
+
+func main() {
+ http.HandleFunc("/secure/ping", ping)
+ http.ListenAndServe(":9999", nil)
+}
+```
+
+#### 创建一个启用了认证的 APISIX 路由
+
+用这个安全的 ping HTTP server 和启用了 `jwt-auth` 认证插件创建一个 APISIX 路由。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "jwt-auth": {}
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:9999": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/secure/ping"
+}'
+```
+
+#### 从 jwt-auth 插件生成令牌
+
+现在从 APISIX 签署一个 JWT 密文，可以用于并通过向 APISIX server 的 `http://localhost:9080/secure/ping` 代理路由发出请求。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign\?key\=test-key -i
+HTTP/1.1 200 OK
+Date: Tue, 18 Jan 2022 07:50:57 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODY1N30.nkyev1_KUapVgY_QVYETsSApA6gEkDWS8tsHFV1EpD8
+```
+
+在上一步中，如果你看到类似 `failed to sign jwt` 的信息，请确保你有一个私有密钥存储在 vault `kv/apisix/consumers/jack/jwt-aut` 路径中。
+
+```shell
+# example
+$ vault kv put kv/apisix/consumer/jack/jwt-auth secret=$ecr3t-c0d3
+Success! Data written to: kv/apisix/consumer/jack/jwt-auth
+```
+
+#### 向 APISIX Server 发送请求
+
+现在，向 APISIX 代理发出一个路由 `/secure/ping` 的请求。验证成功后，它将把请求转发给我们的 go HTTP server。
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODU5M30.IYudBr7FTgRme70u4rEBoYNtGmGByzgfGlt8hctI__Q' -i
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+Content-Length: 12
+Connection: keep-alive
+Date: Tue, 18 Jan 2022 08:00:04 GMT
+Server: APISIX/2.11.0
+
+
+secure/pong
+```
+
+任何无效的 JWT 请求都会抛出 `HTTP 401 Unauthorized` 的错误。
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -i
+HTTP/1.1 401 Unauthorized
+Date: Tue, 18 Jan 2022 08:00:33 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+{"message":"Missing JWT token in request"}
+```
+
+### Vault 与 APISIX jwt-auth 插件集成的不同用例
+
+Apache APISIX `jwt-auth` 插件可以被配置为从 Vault 存储中获取简单的文本密钥以及 RS256 公私密钥对。
+
+:::note
+对于该集成支持的早期版本，该插件希望存储到金库路径中的密钥名称在 [`secret`, `public_key`, `private_key`] 之间，以成功使用该密钥。在未来的版本中，我们将增加对引用自定义命名的密钥的支持。
+:::
+
+1. 你在 Vault 内存储了 HS256 签名密钥，你想用它来进行 jwt 签名和验证。
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "key-1",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ 在这里，插件在 Consumer 配置中提到的 Consumer 用户 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件将记录一个错误，并且无法执行 JWT 验证。
+
+2. RS256 RSA 密钥对，公钥和私钥都存储在 Vault 中。
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jim",
+ "plugins": {
+ "jwt-auth": {
+ "key": "rsa-keypair",
+ "algorithm": "RS256",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ The plugin looks up for `public_key` and `private_key` keys inside vault kv path (`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`) for `jim` mentioned inside plugin vault configuration. If not found, authentication fails.
Review comment:
solved in https://github.com/apache/apisix-website/pull/857
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,383 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 认证
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断，对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 `jwt-auth` 插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在 APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 Docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的介绍。因此，对于一个 APISIX Consumer `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个 Consumer 层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务配置的 Consumer。之后将通过 APISIX 成功执行 Consumer 配置方面的认证请求转发到上游 URI。APISIX Consumer 有两个字段：一个是 `username`（必填项），用于识别 Consumer；另一个是 `plugins`，用于保存 Consumer 所使用的特定插件配置。
+
+在这里，在这篇文章中，我们将用 `jwt-auth` 插件创建一个 Consumer。它为各自的路由或服务执行 JWT 认证。
+
+运行以下命令，启用 Vault 配置的 `jwt-auth`。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+在这里，插件在 Consumer 配置中提到的 Consumer `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件会记录错误，并且无法执行 JWT 验证。
+
+#### 设置一个测试的上游 server
+
+为了测试这个行为，你可以为一个上游创建一个路由（一个简单的 ping 处理程序，返回 pong）。你可以用一个普通的 go HTTP-Server 来设置它。
+
+```go
+// simple upstream server
+package main
+
+
+import "net/http"
+
+
+func ping(w http.ResponseWriter, req *http.Request) {
+ w.Write([]byte("secure/pong\n"))
+}
+
+
+func main() {
+ http.HandleFunc("/secure/ping", ping)
+ http.ListenAndServe(":9999", nil)
+}
+```
+
+#### 创建一个启用了认证的 APISIX 路由
+
+用这个安全的 ping HTTP server 和启用了 `jwt-auth` 认证插件创建一个 APISIX 路由。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "jwt-auth": {}
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:9999": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/secure/ping"
+}'
+```
+
+#### 从 jwt-auth 插件生成令牌
+
+现在从 APISIX 签署一个 JWT 密文，可以用于并通过向 APISIX server 的 `http://localhost:9080/secure/ping` 代理路由发出请求。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign\?key\=test-key -i
+HTTP/1.1 200 OK
+Date: Tue, 18 Jan 2022 07:50:57 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODY1N30.nkyev1_KUapVgY_QVYETsSApA6gEkDWS8tsHFV1EpD8
+```
+
+在上一步中，如果你看到类似 `failed to sign jwt` 的信息，请确保你有一个私有密钥存储在 vault `kv/apisix/consumers/jack/jwt-aut` 路径中。
+
+```shell
+# example
+$ vault kv put kv/apisix/consumer/jack/jwt-auth secret=$ecr3t-c0d3
+Success! Data written to: kv/apisix/consumer/jack/jwt-auth
+```
+
+#### 向 APISIX Server 发送请求
+
+现在，向 APISIX 代理发出一个路由 `/secure/ping` 的请求。验证成功后，它将把请求转发给我们的 go HTTP server。
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODU5M30.IYudBr7FTgRme70u4rEBoYNtGmGByzgfGlt8hctI__Q' -i
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+Content-Length: 12
+Connection: keep-alive
+Date: Tue, 18 Jan 2022 08:00:04 GMT
+Server: APISIX/2.11.0
+
+
+secure/pong
+```
+
+任何无效的 JWT 请求都会抛出 `HTTP 401 Unauthorized` 的错误。
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -i
+HTTP/1.1 401 Unauthorized
+Date: Tue, 18 Jan 2022 08:00:33 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+{"message":"Missing JWT token in request"}
+```
+
+### Vault 与 APISIX jwt-auth 插件集成的不同用例
+
+Apache APISIX `jwt-auth` 插件可以被配置为从 Vault 存储中获取简单的文本密钥以及 RS256 公私密钥对。
+
+:::note
+对于该集成支持的早期版本，该插件希望存储到金库路径中的密钥名称在 [`secret`, `public_key`, `private_key`] 之间，以成功使用该密钥。在未来的版本中，我们将增加对引用自定义命名的密钥的支持。
+:::
+
+1. 你在 Vault 内存储了 HS256 签名密钥，你想用它来进行 jwt 签名和验证。
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "key-1",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ 在这里，插件在 Consumer 配置中提到的 Consumer 用户 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件将记录一个错误，并且无法执行 JWT 验证。
+
+2. RS256 RSA 密钥对，公钥和私钥都存储在 Vault 中。
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jim",
+ "plugins": {
+ "jwt-auth": {
+ "key": "rsa-keypair",
+ "algorithm": "RS256",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ The plugin looks up for `public_key` and `private_key` keys inside vault kv path (`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`) for `jim` mentioned inside plugin vault configuration. If not found, authentication fails.
+ 该插件在 Vault 键值对 路径（`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`）中为插件 Vault 配置中提到的用户 `jim` 查找 `public_key` 和 `private_key`。如果没有找到，认证失败。
Review comment:
solved in https://github.com/apache/apisix-website/pull/857
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] bzp2010 commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
bzp2010 commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790533696
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断，对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 `jwt-auth` 插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在 APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 Docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。因此，对于一个 APISIX Consumer `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
Review comment:
> 本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。
本文是关于如何在 `jwt-auth` 插件中使用 Vault 的介绍。
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] guoqqqi commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
guoqqqi commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r792288332
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,383 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 认证
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断，对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 `jwt-auth` 插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在 APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 Docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的介绍。因此，对于一个 APISIX Consumer `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个 Consumer 层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务配置的 Consumer。之后将通过 APISIX 成功执行 Consumer 配置方面的认证请求转发到上游 URI。APISIX Consumer 有两个字段：一个是 `username`（必填项），用于识别 Consumer；另一个是 `plugins`，用于保存 Consumer 所使用的特定插件配置。
+
+在这里，在这篇文章中，我们将用 `jwt-auth` 插件创建一个 Consumer。它为各自的路由或服务执行 JWT 认证。
+
+运行以下命令，启用 Vault 配置的 `jwt-auth`。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+在这里，插件在 Consumer 配置中提到的 Consumer `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件会记录错误，并且无法执行 JWT 验证。
+
+#### 设置一个测试的上游 server
+
+为了测试这个行为，你可以为一个上游创建一个路由（一个简单的 ping 处理程序，返回 pong）。你可以用一个普通的 go HTTP-Server 来设置它。
+
+```go
+// simple upstream server
+package main
+
+
+import "net/http"
+
+
+func ping(w http.ResponseWriter, req *http.Request) {
+ w.Write([]byte("secure/pong\n"))
+}
+
+
+func main() {
+ http.HandleFunc("/secure/ping", ping)
+ http.ListenAndServe(":9999", nil)
+}
+```
+
+#### 创建一个启用了认证的 APISIX 路由
+
+用这个安全的 ping HTTP server 和启用了 `jwt-auth` 认证插件创建一个 APISIX 路由。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "jwt-auth": {}
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:9999": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/secure/ping"
+}'
+```
+
+#### 从 jwt-auth 插件生成令牌
+
+现在从 APISIX 签署一个 JWT 密文，可以用于并通过向 APISIX server 的 `http://localhost:9080/secure/ping` 代理路由发出请求。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign\?key\=test-key -i
+HTTP/1.1 200 OK
+Date: Tue, 18 Jan 2022 07:50:57 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODY1N30.nkyev1_KUapVgY_QVYETsSApA6gEkDWS8tsHFV1EpD8
+```
+
+在上一步中，如果你看到类似 `failed to sign jwt` 的信息，请确保你有一个私有密钥存储在 vault `kv/apisix/consumers/jack/jwt-aut` 路径中。
+
+```shell
+# example
+$ vault kv put kv/apisix/consumer/jack/jwt-auth secret=$ecr3t-c0d3
+Success! Data written to: kv/apisix/consumer/jack/jwt-auth
+```
+
+#### 向 APISIX Server 发送请求
+
+现在，向 APISIX 代理发出一个路由 `/secure/ping` 的请求。验证成功后，它将把请求转发给我们的 go HTTP server。
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODU5M30.IYudBr7FTgRme70u4rEBoYNtGmGByzgfGlt8hctI__Q' -i
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+Content-Length: 12
+Connection: keep-alive
+Date: Tue, 18 Jan 2022 08:00:04 GMT
+Server: APISIX/2.11.0
+
+
+secure/pong
+```
+
+任何无效的 JWT 请求都会抛出 `HTTP 401 Unauthorized` 的错误。
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -i
+HTTP/1.1 401 Unauthorized
+Date: Tue, 18 Jan 2022 08:00:33 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+{"message":"Missing JWT token in request"}
+```
+
+### Vault 与 APISIX jwt-auth 插件集成的不同用例
+
+Apache APISIX `jwt-auth` 插件可以被配置为从 Vault 存储中获取简单的文本密钥以及 RS256 公私密钥对。
+
+:::note
+对于该集成支持的早期版本，该插件希望存储到金库路径中的密钥名称在 [`secret`, `public_key`, `private_key`] 之间，以成功使用该密钥。在未来的版本中，我们将增加对引用自定义命名的密钥的支持。
+:::
+
+1. 你在 Vault 内存储了 HS256 签名密钥，你想用它来进行 jwt 签名和验证。
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "key-1",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ 在这里，插件在 Consumer 配置中提到的 Consumer 用户 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件将记录一个错误，并且无法执行 JWT 验证。
+
+2. RS256 RSA 密钥对，公钥和私钥都存储在 Vault 中。
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jim",
+ "plugins": {
+ "jwt-auth": {
+ "key": "rsa-keypair",
+ "algorithm": "RS256",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ The plugin looks up for `public_key` and `private_key` keys inside vault kv path (`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`) for `jim` mentioned inside plugin vault configuration. If not found, authentication fails.
+ 该插件在 Vault 键值对 路径（`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`）中为插件 Vault 配置中提到的用户 `jim` 查找 `public_key` 和 `private_key`。如果没有找到，认证失败。
Review comment:
```suggestion
该插件在 Vault 键值对路径（`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`）中为插件 Vault 配置中提到的用户 `jim` 查找 `public_key` 和 `private_key`。如果没有找到，认证失败。
```
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,383 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 认证
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断，对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 `jwt-auth` 插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在 APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 Docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的介绍。因此，对于一个 APISIX Consumer `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个 Consumer 层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务配置的 Consumer。之后将通过 APISIX 成功执行 Consumer 配置方面的认证请求转发到上游 URI。APISIX Consumer 有两个字段：一个是 `username`（必填项），用于识别 Consumer；另一个是 `plugins`，用于保存 Consumer 所使用的特定插件配置。
+
+在这里，在这篇文章中，我们将用 `jwt-auth` 插件创建一个 Consumer。它为各自的路由或服务执行 JWT 认证。
+
+运行以下命令，启用 Vault 配置的 `jwt-auth`。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+在这里，插件在 Consumer 配置中提到的 Consumer `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件会记录错误，并且无法执行 JWT 验证。
+
+#### 设置一个测试的上游 server
+
+为了测试这个行为，你可以为一个上游创建一个路由（一个简单的 ping 处理程序，返回 pong）。你可以用一个普通的 go HTTP-Server 来设置它。
+
+```go
+// simple upstream server
+package main
+
+
+import "net/http"
+
+
+func ping(w http.ResponseWriter, req *http.Request) {
+ w.Write([]byte("secure/pong\n"))
+}
+
+
+func main() {
+ http.HandleFunc("/secure/ping", ping)
+ http.ListenAndServe(":9999", nil)
+}
+```
+
+#### 创建一个启用了认证的 APISIX 路由
+
+用这个安全的 ping HTTP server 和启用了 `jwt-auth` 认证插件创建一个 APISIX 路由。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "jwt-auth": {}
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:9999": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/secure/ping"
+}'
+```
+
+#### 从 jwt-auth 插件生成令牌
+
+现在从 APISIX 签署一个 JWT 密文，可以用于并通过向 APISIX server 的 `http://localhost:9080/secure/ping` 代理路由发出请求。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign\?key\=test-key -i
+HTTP/1.1 200 OK
+Date: Tue, 18 Jan 2022 07:50:57 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODY1N30.nkyev1_KUapVgY_QVYETsSApA6gEkDWS8tsHFV1EpD8
+```
+
+在上一步中，如果你看到类似 `failed to sign jwt` 的信息，请确保你有一个私有密钥存储在 vault `kv/apisix/consumers/jack/jwt-aut` 路径中。
+
+```shell
+# example
+$ vault kv put kv/apisix/consumer/jack/jwt-auth secret=$ecr3t-c0d3
+Success! Data written to: kv/apisix/consumer/jack/jwt-auth
+```
+
+#### 向 APISIX Server 发送请求
+
+现在，向 APISIX 代理发出一个路由 `/secure/ping` 的请求。验证成功后，它将把请求转发给我们的 go HTTP server。
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODU5M30.IYudBr7FTgRme70u4rEBoYNtGmGByzgfGlt8hctI__Q' -i
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+Content-Length: 12
+Connection: keep-alive
+Date: Tue, 18 Jan 2022 08:00:04 GMT
+Server: APISIX/2.11.0
+
+
+secure/pong
+```
+
+任何无效的 JWT 请求都会抛出 `HTTP 401 Unauthorized` 的错误。
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -i
+HTTP/1.1 401 Unauthorized
+Date: Tue, 18 Jan 2022 08:00:33 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+{"message":"Missing JWT token in request"}
+```
+
+### Vault 与 APISIX jwt-auth 插件集成的不同用例
+
+Apache APISIX `jwt-auth` 插件可以被配置为从 Vault 存储中获取简单的文本密钥以及 RS256 公私密钥对。
+
+:::note
+对于该集成支持的早期版本，该插件希望存储到金库路径中的密钥名称在 [`secret`, `public_key`, `private_key`] 之间，以成功使用该密钥。在未来的版本中，我们将增加对引用自定义命名的密钥的支持。
+:::
+
+1. 你在 Vault 内存储了 HS256 签名密钥，你想用它来进行 jwt 签名和验证。
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "key-1",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ 在这里，插件在 Consumer 配置中提到的 Consumer 用户 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件将记录一个错误，并且无法执行 JWT 验证。
+
+2. RS256 RSA 密钥对，公钥和私钥都存储在 Vault 中。
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jim",
+ "plugins": {
+ "jwt-auth": {
+ "key": "rsa-keypair",
+ "algorithm": "RS256",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ The plugin looks up for `public_key` and `private_key` keys inside vault kv path (`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`) for `jim` mentioned inside plugin vault configuration. If not found, authentication fails.
Review comment:
```suggestion
```
Excess?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] zaunist commented on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
zaunist commented on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1020856328
LGTM
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] guoqqqi commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
guoqqqi commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790516623
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断，对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 `jwt-auth` 插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在 APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 Docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。因此，对于一个 APISIX 消费者 `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个消费者层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务配置的消费者。之后将通过 APISIX 成功执行消费者配置方面的认证请求转发到上游 URI。APISIX 消费者有两个字段：一个是 `username`（必填项），用于识别消费者；另一个是 `plugins`，用于保存消费者所使用的特定插件配置。
Review comment:
Are we better off not translating for the `consumer`?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
👷 Deploy Preview for *apache-apisix* processing.
🔨 Explore the source changes: 6b8c25ea5be759a42c28974b0633ac2c1b819ff7
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61ef644051ae6b0008bcce51](https://app.netlify.com/sites/apache-apisix/deploys/61ef644051ae6b0008bcce51)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
👷 Deploy Preview for *apache-apisix* processing.
🔨 Explore the source changes: f04929e07010bd59fadf9449a69fa52477c264cf
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61eac318a4b23b00071cda8b](https://app.netlify.com/sites/apache-apisix/deploys/61eac318a4b23b00071cda8b)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790446003
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 第2步：为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。因此，对于一个APISIX 消费者 `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个消费者层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务的配置的消费者。然后，只有 APISIX 可以通过成功执行消费者配置方面的认证，将请求转发到上游 URI。APISIX 消费者有两个字段：一个是 `username`（必填项），用于识别消费者，另一个是 `plugins`，用于保存消费者所使用的特定插件配置。
+
+在这里，在这篇文章中，我们将用 `jwt-auth` 插件创建一个消费者。它为各自的路由或服务执行 JWT认证。
+
+运行以下命令，启用 Vault 配置的 `jwt-auth`。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+在这里，插件在消费者配置中提到的消费者 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件会记录错误，并且无法执行 jwt 验证。
+
+#### 设置一个测试的上游 server
+
+为了测试这个行为，你可以为一个上游创建一个路由（一个简单的 ping 处理程序，返回 pong）。你可以用一个普通的 go HTTP-Server 来设置它。
+
+```go
+// simple upstream server
+package main
+
+
+import "net/http"
+
+
+func ping(w http.ResponseWriter, req *http.Request) {
+ w.Write([]byte("secure/pong\n"))
+}
+
+
+func main() {
+ http.HandleFunc("/secure/ping", ping)
+ http.ListenAndServe(":9999", nil)
+}
+```
+
+#### 创建一个启用了认证的 APISIX 路由
+
+用这个安全的 ping HTTP server和启用了 jwt-auth 认证插件创建一个 APISIX 路由。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "jwt-auth": {}
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:9999": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/secure/ping"
+}'
+```
+
+#### 从 jwt-auth 插件生成令牌
+
+现在从 APISIX 签署一个 jwt 密文，可以用于并通过向 APISIX server的 `http://localhost:9080/secure/ping` 代理路由发出请求。
Review comment:
```suggestion
现在从 APISIX 签署一个 JWT 密文，可以用于并通过向 APISIX server 的 `http://localhost:9080/secure/ping` 代理路由发出请求。
```
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 第2步：为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。因此，对于一个APISIX 消费者 `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个消费者层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务的配置的消费者。然后，只有 APISIX 可以通过成功执行消费者配置方面的认证，将请求转发到上游 URI。APISIX 消费者有两个字段：一个是 `username`（必填项），用于识别消费者，另一个是 `plugins`，用于保存消费者所使用的特定插件配置。
+
+在这里，在这篇文章中，我们将用 `jwt-auth` 插件创建一个消费者。它为各自的路由或服务执行 JWT认证。
+
+运行以下命令，启用 Vault 配置的 `jwt-auth`。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+在这里，插件在消费者配置中提到的消费者 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件会记录错误，并且无法执行 jwt 验证。
+
+#### 设置一个测试的上游 server
+
+为了测试这个行为，你可以为一个上游创建一个路由（一个简单的 ping 处理程序，返回 pong）。你可以用一个普通的 go HTTP-Server 来设置它。
+
+```go
+// simple upstream server
+package main
+
+
+import "net/http"
+
+
+func ping(w http.ResponseWriter, req *http.Request) {
+ w.Write([]byte("secure/pong\n"))
+}
+
+
+func main() {
+ http.HandleFunc("/secure/ping", ping)
+ http.ListenAndServe(":9999", nil)
+}
+```
+
+#### 创建一个启用了认证的 APISIX 路由
+
+用这个安全的 ping HTTP server和启用了 jwt-auth 认证插件创建一个 APISIX 路由。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "jwt-auth": {}
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:9999": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/secure/ping"
+}'
+```
+
+#### 从 jwt-auth 插件生成令牌
+
+现在从 APISIX 签署一个 jwt 密文，可以用于并通过向 APISIX server的 `http://localhost:9080/secure/ping` 代理路由发出请求。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign\?key\=test-key -i
+HTTP/1.1 200 OK
+Date: Tue, 18 Jan 2022 07:50:57 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODY1N30.nkyev1_KUapVgY_QVYETsSApA6gEkDWS8tsHFV1EpD8
+```
+
+在上一步中，如果你看到类似 `failed to sign jwt` 的信息，请确保你有一个私有密钥存储在vault `kv/apisix/consumers/jack/jwt-aut` 路径中。
Review comment:
```suggestion
在上一步中，如果你看到类似 `failed to sign jwt` 的信息，请确保你有一个私有密钥存储在 vault `kv/apisix/consumers/jack/jwt-aut` 路径中。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790446186
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 第2步：为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。因此，对于一个APISIX 消费者 `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个消费者层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务的配置的消费者。然后，只有 APISIX 可以通过成功执行消费者配置方面的认证，将请求转发到上游 URI。APISIX 消费者有两个字段：一个是 `username`（必填项），用于识别消费者，另一个是 `plugins`，用于保存消费者所使用的特定插件配置。
+
+在这里，在这篇文章中，我们将用 `jwt-auth` 插件创建一个消费者。它为各自的路由或服务执行 JWT认证。
+
+运行以下命令，启用 Vault 配置的 `jwt-auth`。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+在这里，插件在消费者配置中提到的消费者 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件会记录错误，并且无法执行 jwt 验证。
+
+#### 设置一个测试的上游 server
+
+为了测试这个行为，你可以为一个上游创建一个路由（一个简单的 ping 处理程序，返回 pong）。你可以用一个普通的 go HTTP-Server 来设置它。
+
+```go
+// simple upstream server
+package main
+
+
+import "net/http"
+
+
+func ping(w http.ResponseWriter, req *http.Request) {
+ w.Write([]byte("secure/pong\n"))
+}
+
+
+func main() {
+ http.HandleFunc("/secure/ping", ping)
+ http.ListenAndServe(":9999", nil)
+}
+```
+
+#### 创建一个启用了认证的 APISIX 路由
+
+用这个安全的 ping HTTP server和启用了 jwt-auth 认证插件创建一个 APISIX 路由。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "jwt-auth": {}
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:9999": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/secure/ping"
+}'
+```
+
+#### 从 jwt-auth 插件生成令牌
+
+现在从 APISIX 签署一个 jwt 密文，可以用于并通过向 APISIX server的 `http://localhost:9080/secure/ping` 代理路由发出请求。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign\?key\=test-key -i
+HTTP/1.1 200 OK
+Date: Tue, 18 Jan 2022 07:50:57 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODY1N30.nkyev1_KUapVgY_QVYETsSApA6gEkDWS8tsHFV1EpD8
+```
+
+在上一步中，如果你看到类似 `failed to sign jwt` 的信息，请确保你有一个私有密钥存储在vault `kv/apisix/consumers/jack/jwt-aut` 路径中。
+
+```shell
+# example
+$ vault kv put kv/apisix/consumer/jack/jwt-auth secret=$ecr3t-c0d3
+Success! Data written to: kv/apisix/consumer/jack/jwt-auth
+```
+
+#### 向 APISIX Server 发送请求
+
+现在，向 APISIX 代理发出一个路由 `/secure/ping` 的请求。验证成功后，它将把请求转发给我们的 go HTTP server。
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODU5M30.IYudBr7FTgRme70u4rEBoYNtGmGByzgfGlt8hctI__Q' -i
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+Content-Length: 12
+Connection: keep-alive
+Date: Tue, 18 Jan 2022 08:00:04 GMT
+Server: APISIX/2.11.0
+
+
+secure/pong
+```
+
+任何无效的 jwt 请求都会抛出 `HTTP 401 Unauthorized` 的错误。
Review comment:
```suggestion
任何无效的 JWT 请求都会抛出 `HTTP 401 Unauthorized` 的错误。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
✔️ Deploy Preview for *apache-apisix* canceled.
🔨 Explore the source changes: b96772fe1088a68f11e1eadb28685fea14e1f221
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61ee62ee0210e500070d39e9](https://app.netlify.com/sites/apache-apisix/deploys/61ee62ee0210e500070d39e9)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790446804
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 第2步：为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。因此，对于一个APISIX 消费者 `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个消费者层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务的配置的消费者。然后，只有 APISIX 可以通过成功执行消费者配置方面的认证，将请求转发到上游 URI。APISIX 消费者有两个字段：一个是 `username`（必填项），用于识别消费者，另一个是 `plugins`，用于保存消费者所使用的特定插件配置。
+
+在这里，在这篇文章中，我们将用 `jwt-auth` 插件创建一个消费者。它为各自的路由或服务执行 JWT认证。
+
+运行以下命令，启用 Vault 配置的 `jwt-auth`。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+在这里，插件在消费者配置中提到的消费者 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件会记录错误，并且无法执行 jwt 验证。
+
+#### 设置一个测试的上游 server
+
+为了测试这个行为，你可以为一个上游创建一个路由（一个简单的 ping 处理程序，返回 pong）。你可以用一个普通的 go HTTP-Server 来设置它。
+
+```go
+// simple upstream server
+package main
+
+
+import "net/http"
+
+
+func ping(w http.ResponseWriter, req *http.Request) {
+ w.Write([]byte("secure/pong\n"))
+}
+
+
+func main() {
+ http.HandleFunc("/secure/ping", ping)
+ http.ListenAndServe(":9999", nil)
+}
+```
+
+#### 创建一个启用了认证的 APISIX 路由
+
+用这个安全的 ping HTTP server和启用了 jwt-auth 认证插件创建一个 APISIX 路由。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "jwt-auth": {}
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:9999": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/secure/ping"
+}'
+```
+
+#### 从 jwt-auth 插件生成令牌
+
+现在从 APISIX 签署一个 jwt 密文，可以用于并通过向 APISIX server的 `http://localhost:9080/secure/ping` 代理路由发出请求。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign\?key\=test-key -i
+HTTP/1.1 200 OK
+Date: Tue, 18 Jan 2022 07:50:57 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODY1N30.nkyev1_KUapVgY_QVYETsSApA6gEkDWS8tsHFV1EpD8
+```
+
+在上一步中，如果你看到类似 `failed to sign jwt` 的信息，请确保你有一个私有密钥存储在vault `kv/apisix/consumers/jack/jwt-aut` 路径中。
+
+```shell
+# example
+$ vault kv put kv/apisix/consumer/jack/jwt-auth secret=$ecr3t-c0d3
+Success! Data written to: kv/apisix/consumer/jack/jwt-auth
+```
+
+#### 向 APISIX Server 发送请求
+
+现在，向 APISIX 代理发出一个路由 `/secure/ping` 的请求。验证成功后，它将把请求转发给我们的 go HTTP server。
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODU5M30.IYudBr7FTgRme70u4rEBoYNtGmGByzgfGlt8hctI__Q' -i
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+Content-Length: 12
+Connection: keep-alive
+Date: Tue, 18 Jan 2022 08:00:04 GMT
+Server: APISIX/2.11.0
+
+
+secure/pong
+```
+
+任何无效的 jwt 请求都会抛出 `HTTP 401 Unauthorized` 的错误。
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -i
+HTTP/1.1 401 Unauthorized
+Date: Tue, 18 Jan 2022 08:00:33 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+{"message":"Missing JWT token in request"}
+```
+
+### Vault 与 APISIX jwt-auth 插件集成的不同用例
+
+Apache APISIX `jwt-auth` 插件可以被配置为从 Vault 存储中获取简单的文本密钥以及 RS256 公私密钥对。
+
+:::note
+对于该集成支持的早期版本，该插件希望存储到金库路径中的密钥名称在 [`secret`, `public_key`, `private_key`] 之间，以成功使用该密钥。在未来的版本中，我们将增加对引用自定义命名的密钥的支持。
+:::
+
+1. 你在 Vault 内存储了 HS256 签名密钥，你想用它来进行 jwt 签名和验证。
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "key-1",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ 在这里，插件在消费者配置中提到的消费者用户 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件将记录一个错误，并且无法执行 jwt 验证。
+
+2. RS256 RSA 密钥对，公钥和私钥都存储在 Vault 中。
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jim",
+ "plugins": {
+ "jwt-auth": {
+ "key": "rsa-keypair",
+ "algorithm": "RS256",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ The plugin looks up for `public_key` and `private_key` keys inside vault kv path (`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`) for `jim` mentioned inside plugin vault configuration. If not found, authentication fails.
+ 该插件在 Vault 键值对 路径（`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`）中为插件 Vault 配置中提到的用户 `jim` 查找 `public_key` 和 `private_key`。如果没有找到，认证失败。
+
+ 如果你不确定如何将公钥和私钥存储到 Vault 键值对 中，请使用这个命令。
Review comment:
```suggestion
如果你不确定如何将公钥和私钥存储到 Vault 键值对中，请使用这个命令。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790445529
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
+
+使用 Vault 而不是 APISIX etcd 后端的主要顾虑是在低信任度环境下的安全问题。因为 Vault 访问令牌是小范围的，可以授予 APISIX server 有限的权限。
+
+### 配置 Vault
+
+本节分享了在 Apache APISIX 生态系统中使用 Vault 的最佳实践。如果你已经有了一个具有必要权限的 Vault 实例在运行，请跳过本节。
+
+#### 启动 Vault server
+
+在这里，你有多种选择，可以自由选择 docker、预编译二进制包或从源代码构建。至于与 Vault server 的通信，你需要一个 Vault CLI 客户端。请运行以下命令启动 server：
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+用正确的环境变量设置 Vault CLI 客户端。
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+用一个合适的 `path` 前缀启用 vault k/v version 1的密钥引擎后端。在这个演示中，我们要选择 `kv` 路径，这样就不会与 vault 默认的 `kv` version 2 的密钥路径发生冲突。
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### 第2步：为 Apache APISIX 生成一个 Vault 访问令牌
+
+本文是关于在 `jwt-auth` 插件中使用 Vault 的观点。因此，对于一个APISIX 消费者 `jack`，`jwt-auth` 插件会在 `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` 中查找（如果启用了 Vault 配置）`secret/s` 到 Vault 键值对 存储。在这种情况下，如果你将 `kv/apisix` 命名空间（Vault 路径）指定为`config.yaml` 内的 `vault.prefix`，用于所有 APISIX 相关数据的检索，我们建议你为路径 `kv/apisix/consumer/` 创建一个策略。最后的星号（*）确保策略允许读取任何具有 `kv/apisix/consumer` 前缀的路径。
+
+用 HashiCorp 配置语言（HCL）创建一个策略文件。
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+将策略应用于 Vault 实例。
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+用新定义的策略生成一个令牌，该策略已被配置为很小的访问边界。
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+在这个例子中，`s.KUWFVhIXgoRuQbbp3j1eMVGa` 是你的访问令牌。
+
+### 在 Apache APISIX 中添加 Vault 配置
+
+Apache APISIX 通过 Vault HTTP APIs 与 Vault 实例进行通信。必要的配置必须被添加到 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中。
+
+下面是关于你可以使用的不同字段的简要信息。
+
+- host： 运行 Vault server 的主机地址。
+- timeout： 每次请求的 HTTP 超时。
+- token： 从 Vault 实例生成的令牌，授予从 Vault 读取数据的权限。
+- prefix：启用前缀可以更好地执行策略，生成有限范围的令牌，严格控制可以从 APISIX 访问的数据。有效的前缀是（`kv/apisix`、`secret`等）。
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### 创建一个 APISIX Consumer
+
+APISIX 有一个消费者层面的抽象，与认证方案并列。为了启用任何 APISIX 路由的认证，需要一个具有适合该特定类型认证服务的配置的消费者。然后，只有 APISIX 可以通过成功执行消费者配置方面的认证，将请求转发到上游 URI。APISIX 消费者有两个字段：一个是 `username`（必填项），用于识别消费者，另一个是 `plugins`，用于保存消费者所使用的特定插件配置。
+
+在这里，在这篇文章中，我们将用 `jwt-auth` 插件创建一个消费者。它为各自的路由或服务执行 JWT认证。
+
+运行以下命令，启用 Vault 配置的 `jwt-auth`。
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+在这里，插件在消费者配置中提到的消费者 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 jwt 验证。如果在同一路径中没有找到密钥，该插件会记录错误，并且无法执行 jwt 验证。
Review comment:
```suggestion
在这里，插件在消费者配置中提到的消费者 `jack` 的 Vault 路径（`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`）中查找密钥 `secret`，并使用它进行后续的签名和 JWT 验证。如果在同一路径中没有找到密钥，该插件会记录错误，并且无法执行 JWT 验证。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790443594
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
+
+虽然我们不能提前预知将来会出现哪些安全漏洞，但是我们可以通过配置多个密钥来控制这些安全漏洞的影响范围。为了避免这样的情况，像 HashiCorp Vault （下文简称 Vault）这样密钥凭证解决方案应运而生。
+
+本文演示了如何将 Vault 与 Apache APISIX 的 jwt-auth插件集成，在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+## 什么是 Vault
+
+Vault 旨在帮助用户管理服务密钥的访问权限，并在多个服务之间安全地传输这些密钥。密钥可以是任何形式的凭证，因为密钥可用于解锁敏感信息，所以需要严密控制密钥。密钥的形式可以是密码、API 密钥、SSH 密钥、RSA 令牌或 OTP。事实上，密钥泄露的情况非常普遍：密钥通常被储存在配置文件中，或作为变量被储存在代码中，如果没有妥善保存，密钥甚至会出现在 GitHub、BitBucket 或 GitLab 等公开可见的代码库中，从而对安全构成了重大威胁。Vault 通过集中密钥解决了这个问题。它为静态密钥提供加密存储，生成具有 TTL 租约的动态密钥，对用户进行认证，以确保他们有权限访问特定的密钥。因此，即使在安全漏洞的情况下，影响范围也小得多，并能得到更好的控制。
+
+Vault 提供了一个用户界面用于密钥管理，使控制和管理权限变得非常容易。不仅如此，它还提供了灵活且详细审计日志功能，能跟踪到所有用户的历史访问记录。
+
+
+
+## jwt-auth 插件介绍
+
+`jwt-auth` 是一个认证插件，可以附加到任何 APISIX 路由上，在请求被转发到上游 URI 之前执行 JWT 认证。通常情况下，发行者使用私钥或文本密钥来签署 JWT。JWT 的接收者将验证签名，以确保令牌在被发行者签名后没有被改变。整个 JWT 机制的整体完整性取决于签名密钥（或 RSA 密钥对的文本密钥）。这使得未经认证的来源很难猜到签名密钥并试图改变 JWT 中的声明。
+
+因此，在安全的环境中存储这些密钥是非常关键的。如果密钥落入坏人之手，可能会危及整个基础设施的安全。虽然 Apache APISIX 采取了一切手段来遵循标准的 SecOps 实践，但在生产环境中有一个集中的密钥管理解决方案也是一件好事。例如 Vault，有详细的审计日志，定时的密钥轮换，密钥撤销等功能。如果每次在整个基础设施发生密钥轮换时，你都要更新 Apache APISIX 配置，这将是一个相当麻烦的问题。
+
+## 如何集成 Vault 和 Apache APISIX
+
+为了与 Vault 集成，Apache APISIX 需要在 [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件中加载 Vault 的相关配置信息。
+
+Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
Review comment:
```suggestion
Apache APISIX 与 Vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1) 进行通信。由于大多数企业解决方案倾向于在生产环境中使用 KV Secrets Engine - Version 1，在 APISIX-Vault 支持的初始阶段，我们只使用这个版本。在以后的版本中，我们将增加对 K/V - Version 2 的支持。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] SylviaBABY commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r790442830
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,379 @@
+---
+title: "Apache APISIX 集成 HashiCorp Vault，生态系统再添一员"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- 插件生态
+description: 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> 本文为大家带来了 Apache APISIX 即将发布的 Vault 插件以及相关细节。在为服务提供高并发低延迟的卓越性能的同时，为服务的安全保驾护航。
+
+<!--truncate-->
+
+随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断。对开发者来说，服务大规模中断是开发者最不想看到事情。
Review comment:
```suggestion
随着微服务架构的兴起，保持服务安全变得比以前更有挑战性。多个后端 server 实例使用单一的静态密钥凭访问数据库 server 会带来巨大的风险。如果发生密钥凭证泄露，整个系统都会受到影响。为了解决密钥凭证泄露所带来的影响，只能撤销这个密钥凭证。而撤销密钥凭证会导致大规模的服务中断，对开发者来说这是最不想看到事情。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#issuecomment-1018540999
✔️ Deploy Preview for *apache-apisix* ready!
🔨 Explore the source changes: 6b8c25ea5be759a42c28974b0633ac2c1b819ff7
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/61ef644051ae6b0008bcce51](https://app.netlify.com/sites/apache-apisix/deploys/61ef644051ae6b0008bcce51)
😎 Browse the preview: [https://deploy-preview-852--apache-apisix.netlify.app](https://deploy-preview-852--apache-apisix.netlify.app)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] bisakhmondal commented on a change in pull request #852: docs: add blog for Vault
Posted by GitBox <gi...@apache.org>.
bisakhmondal commented on a change in pull request #852:
URL: https://github.com/apache/apisix-website/pull/852#discussion_r791094923
##########
File path: website/blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,373 @@
+---
+title: "HashiCorp Vault Secure Storage Backend in Apache APISIX Ecosystem"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "Yilin Zeng"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- Ecosystem
+description: This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+tags: [Technology,Ecosystem,Authentication]
Review comment:
```suggestion
tags: [Technology,Authentication]
```
`Ecosystem` doesn't go with it very well. WDYT?
##########
File path: website/blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,373 @@
+---
+title: "HashiCorp Vault Secure Storage Backend in Apache APISIX Ecosystem"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "Yilin Zeng"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- Ecosystem
Review comment:
```suggestion
- Apache APISIX
- HashiCorp
- Vault
- jwt-auth
- Authentication
```
##########
File path: website/blog/2022/01/21/apisix-hashicorp-vault-integration.md
##########
@@ -0,0 +1,373 @@
+---
+title: "HashiCorp Vault Secure Storage Backend in Apache APISIX Ecosystem"
+authors:
+ - name: "Bisakh Mondal"
+ title: "Author"
+ url: "https://github.com/bisakhmondal"
+ image_url: "https://avatars.githubusercontent.com/u/41498427?v=4"
+ - name: "Yilin Zeng"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://avatars.githubusercontent.com/u/36651058?v=4"
+keywords:
+- Apache APISIX
+- HashiCorp
+- Vault
+- jwt-auth
+- Ecosystem
+description: This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+tags: [Technology,Ecosystem,Authentication]
+---
+
+> This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+
+<!--truncate-->
+
+With the rise of microservice-based architecture, keeping things secure has become much more challenging than earlier. We are far beyond the point where our 100 instances of backend servers are accessing our database server with a single static secret credential because if in case of a credential leakage the whole system is compromised and revocation of that credential causes a massive service outage (now no one can access anything unless the instances are reconfigured). We can't eliminate the possibility of a security breach because sometimes unexpected does happen. Instead, it's totally up to us to control the blast radius in these situations. To tackle scenarios like this, a popular solution like [HashiCorp Vault](https://www.vaultproject.io/) comes into the picture in a production environment to act as an identity-based secrets and encryption management system. In this article, I have demonstrated how to integrate Vault with Apache APISIX (a cloud-native API Gateway) [jwt-auth p
lugin](https://apisix.apache.org/docs/apisix/plugins/jwt-auth) to effectively use excellence from both worlds.
+
+## What is Vault
+
+HashiCorp Vault is designed to help organizations manage access to secrets and transmit them safely within an organization. Secrets are defined as any form of sensitive credentials that need to be tightly controlled and monitored and can be used to unlock sensitive information. Secrets could be in the form of passwords, API keys, SSH keys, RSA tokens, or OTP. In the real world where it is very common to have a secret sprawl where secrets get stored into the config file or as a variable in actual program code which as a consequence sometimes even end up in a version control system like GitHub, BitBucket or GitLab, possess a major threat in security. Vault solves this problem by centralizing secrets. It provides encrypted storage for static secrets, generation of dynamic secrets with a TTL lease, authentication of users (machines or humans) to make sure they’re authorized to access a particular secret and many more. So that even in case of a security breach the blast radius is much
small and contained.
+
+Vault makes it very easy to control and manage access by providing us with a unilateral interface to manage every secret in your infrastructure. Not only that, it also provides the flexibility to create detailed audit logs and keep track of who accessed what.
+
+
+
+## About APISIX jwt-auth Plugin
+
+It is an authentication plugin that can be attached to any APISIX route to perform JWT (JSON web token, [read more](https://jwt.io/introduction)) authentication before the request gets forwarded to the upstream URI. In short, it is a secure authentication mechanism that leads to authorization to critical resources. Typically, a private key, or a text secret, is used by the issuer to sign the JWT. The receiver of the JWT will verify the signature to ensure that the token hasn’t been altered after it was signed by the issuer. The total integrity of the whole jwt mechanism depends on the signing secret (may it be a text secret of RSA keypairs). That makes it difficult for unauthenticated sources to guess the signing key and attempt to change the claims within the JWT.
+
+So the storage of these keys in a secure environment is extremely crucial. Falling into wrong hands may jeopardize the security of the whole infrastructure. Though we from the APISIX side take all the means to follow standard SecOps practices, it's quite natural in the production environment to have a centralized key management solution like HashiCorp vault to have elaborate audit trails, periodic key rotation, key revocation etc. And it would be quite a troublesome issue if each time you have to update Apache APISIX configuration whenever a key rotation occurs throughout the infrastructure.
+
+## Steps to Use Vault with Apache APISIX
+
+For integration with Vault, Apache APISIX needs to be loaded with vault configuration at [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml).
+
+Internally, APISIX communicates with vault server [KV secret engine v1](https://www.vaultproject.io/docs/secrets/kv/kv-v1) HTTP [APIs](https://www.vaultproject.io/api/secret/kv/kv-v1). As most enterprise solution prefers to stick with KV Secrets Engine - Version 1 in their production environment, during the initial phase of APISIX-Vault support we have gone with version 1 only. In later releases, we will add the support of K/V version 2.
+
+The main idea of using vault, instead of the APISIX etcd backend is the security concern in a low trust environment. We, the APISIX developers, understand your priorities seriously. That's why we recommend using vault access tokens that are short scoped and can grant APISIX server limited access.
+
+### Configure Vault
+
+If you have already a Vault instance running with the necessary privileges, feel free to skip this section. This section shares the best practices to use Vault inside the Apache APISIX ecosystem. Please follow the steps mentioned below.
+
+#### Step 1: Spin Up a Vault Server
+
+Here you have multiple options, feel free to choose between docker, precompiled binary or building from source. As to communicate with the vault server, you need a vault CLI client, I would prefer going with precompiled binary instead of the Docker approach. Anyway, it's totally up to you (feel free to consult [Vault's official installation docs](https://www.vaultproject.io/docs/install)). To spin up a development server, please run the following command.
+
+```shell
+$ vault server -dev -dev-root-token-id=root
+…
+WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
+and starts unsealed with a single unseal key. The root token is already
+authenticated to the CLI, so you can immediately begin using Vault.
+You may need to set the following environment variable:
+export VAULT_ADDR='http://127.0.0.1:8200'
+The unseal key and root token are displayed below in case you want to
+seal/unseal the Vault or re-authenticate.
+Unseal Key: 12hURx2eDPKK1tzK+8TkgH9pPhPNJFpyfc/imCLgJKY=
+Root Token: root
+Development mode should NOT be used in production installations!
+```
+
+Set your current CLI with the correct environment variables.
+
+```shell
+$ export VAULT_ADDR='http://127.0.0.1:8200'
+$ export VAULT_TOKEN='root'
+```
+
+Enable vault k/v version 1 secret engine backend with a suitable path prefix. In this demo, we are going to choose the `kv` path so that we don't have a collision with the vault default secret path for kv version 2.
+
+```shell
+$ vault secrets enable -path=kv -version=1 kv
+Success! Enabled the kv secrets engine at: kv/
+
+
+# To reconfirm the status, run
+$ vault secrets list
+Path Type Accessor Description
+---- ---- -------- -----------
+cubbyhole/ cubbyhole cubbyhole_4eeb394c per-token private secret storage
+identity/ identity identity_5ca6201e identity store
+kv/ kv kv_92cd6d37 n/a
+secret/ kv kv_6dd46a53 key/value secret storage
+sys/ system system_2045ddb1 system endpoints used for control, policy and debugging
+```
+
+#### Step 2: Generate a Vault Access Token for APISIX
+
+This article is regarding using vault in `jwt-auth` plugin perspective. So, for an APISIX consumer (if you are unfamiliar with consumers in the APISIX ecosystem, please read the [document about Apache APISIX Consumer](https://apisix.apache.org/docs/apisix/architecture-design/consumer)) with username `jack` the `jwt-auth` plugin looks up (if enabled with vault configuration) for secret/s at `<vault.prefix inside config.yaml>/consumer/<consumer.username>/jwt-auth` into vault kv storage. In this context, if you are assigning `kv/apisix` namespace (vault path) as `vault.prefix` inside config.yaml for all apisix related data retrieval, we suggest you to create a policy for path `kv/apisix/consumer/*`. The extra asterisk (*) at the end ensure the policy allows read for any path that has a `kv/apisix/consumer` prefix.
+
+Create a policy file in HashiCorp Configuration Language (HCL).
+
+```shell
+$ tee apisix-policy.hcl << EOF
+path "kv/apisix/consumer/*" {
+ capabilities = ["read"]
+}
+EOF
+```
+
+Applying the policy into vault instance.
+
+```shell
+$ vault policy write apisix-policy apisix-policy.hcl
+
+Success! Uploaded policy: apisix-policy
+```
+
+Generate a token with the newly defined policy that has been configured with the small access boundary.
+
+```shell
+$ vault token create -policy="apisix-policy"
+
+
+Key Value
+--- -----
+token s.KUWFVhIXgoRuQbbp3j1eMVGa
+token_accessor nPXT3q0mfZkLmhshfioOyx8L
+token_duration 768h
+token_renewable true
+token_policies ["apisix-policy" "default"]
+identity_policies []
+policies ["apisix-policy" "default"]
+```
+
+In this demonstration `s.KUWFVhIXgoRuQbbp3j1eMVGa` is your access token.
+
+### Adding vault configuration into Apache APISIX
+
+As discussed earlier, Apache APISIX communicates with Vault instance through Vault HTTP APIs. The necessary configuration must be added into [config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml).
+Here is the brief information about different fields that you can use:
+
+- host: The host address where the vault server is running.
+- timeout: HTTP timeout for each request.
+- token: The generated token from vault instance that can grant access to read data from the vault.
+- prefix: enabling a prefix allows you to better enforcement of policies, generate limited scoped tokens and tightly control the data that can be accessed from APISIX. Valid prefixes are (`kv/apisix`, `secret` etc.)
+
+```shell
+vault:
+ host: 'http://0.0.0.0:8200'
+ timeout: 10
+ token: 's.KUWFVhIXgoRuQbbp3j1eMVGa'
+ prefix: 'kv/apisix'
+```
+
+### Create an APISIX Consumer
+
+APISIX has a consumer-level abstraction that goes side by side with authentication scenarios. To enable authentication for any APISIX route, a consumer is needed with a suitable configuration for that specific type of authentication service. Then only APISIX can forward the request to the upstream URI by successfully performing authentication wrt. the consumer configuration. APISIX consumer has two fields - one is `username` (required) to identify one consumer from the others and another is `plugins` that holds the consumer specific plugin configurations.
+
+Here, in this article, we will create a consumer with `jwt-auth` plugin. It performs JWT authentication for the respective route/s or service/s.
+
+To enable `jwt-auth` with vault configuration, make a request to:
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "vault": {}
+ }
+ }
+}'
+```
+
+Here the plugin looks up for key secret inside vault path (`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`) for consumer `jack` mentioned in the consumer config and uses it for subsequent signing and jwt verification. If the key is not found in the same path, the plugin logs error and fails to perform jwt authentication.
+
+#### Set Up a Test Upstream Server
+
+To test the behaviour, you can create a route for an upstream (a simple ping handler that returns pong). You can set it up with a plain go HTTP-Server.
+
+```go
+// simple upstream server
+package main
+
+
+import "net/http"
+
+
+func ping(w http.ResponseWriter, req *http.Request) {
+ w.Write([]byte("secure/pong\n"))
+}
+
+
+func main() {
+ http.HandleFunc("/secure/ping", ping)
+ http.ListenAndServe(":9999", nil)
+}
+```
+
+#### Create an APISIX Route with Authentication Enabled
+
+Create an APISIX route with this secure ping HTTP server and `jwt-auth` authentication plugin enabled.
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "jwt-auth": {}
+ },
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:9999": 1
+ },
+ "type": "roundrobin"
+ },
+ "uri": "/secure/ping"
+}'
+```
+
+#### Generate Token from jwt-auth Plugin
+
+Now sign a jwt secret from APISIX that can be used and passed for making requests to the `http://localhost:9080/secure/ping` proxy route to the APISIX server.
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign\?key\=test-key -i
+HTTP/1.1 200 OK
+Date: Tue, 18 Jan 2022 07:50:57 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODY1N30.nkyev1_KUapVgY_QVYETsSApA6gEkDWS8tsHFV1EpD8
+```
+
+In the previous step, if you see something like the `failed to sign jwt` message please make sure you have a secret key stored into vault `kv/apisix/consumers/jack/jwt-auth` path.
+
+```shell
+# example
+$ vault kv put kv/apisix/consumer/jack/jwt-auth secret=$ecr3t-c0d3
+Success! Data written to: kv/apisix/consumer/jack/jwt-auth
+```
+
+#### Request APISIX Server
+
+Now, make a request to the APISIX proxy for route `/secure/ping`. Upon successful validation, it will forward the request to our go HTTP server.
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ0ZXN0LWtleSIsImV4cCI6MTY0MjU3ODU5M30.IYudBr7FTgRme70u4rEBoYNtGmGByzgfGlt8hctI__Q' -i
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+Content-Length: 12
+Connection: keep-alive
+Date: Tue, 18 Jan 2022 08:00:04 GMT
+Server: APISIX/2.11.0
+
+
+secure/pong
+```
+
+Any request without a valid jwt will throw an `HTTP 401 Unauthorized` error.
+
+```shell
+$ curl http://127.0.0.1:9080/secure/ping -i
+HTTP/1.1 401 Unauthorized
+Date: Tue, 18 Jan 2022 08:00:33 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Server: APISIX/2.11.0
+
+
+{"message":"Missing JWT token in request"}
+```
+
+### Different Use Cases Where Vault Can be Integrated with APISIX jwt-auth plugin
+
+Apache APISIX `jwt-auth` plugin can be configured to fetch simple text secret keys as well as RS256 public-private key pairs from vault storage.
+
+:::note
+For the early version of this integration support, the plugin expects the key name of secrets stored into the vault path is among [ `secret`, `public_key`, `private_key`] to successfully use the key. In future releases, we are going to add the support of referencing custom-named keys.
+:::
+
+1. You have stored HS256 signing secret inside the vault and you want to use it for jwt signing and verification.
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "key-1",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ Here the plugin looks up for key `secret` inside vault path (`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`) for consumer jack mentioned in the consumer config and uses it for subsequent signing and jwt verification. If the key is not found in the same path, the plugin logs an error and fails to perform jwt authentication.
+
+2. RS256 RSA keypairs, both public and private keys are stored in the vault.
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "jim",
+ "plugins": {
+ "jwt-auth": {
+ "key": "rsa-keypair",
+ "algorithm": "RS256",
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ The plugin looks up for `public_key` and `private_key` keys inside vault kv path (`<vault.prefix from conf.yaml>/consumer/jim/jwt-auth`) for `jim` mentioned inside plugin vault configuration. If not found, authentication fails.
+
+ If you are unsure, how to store public and private keys into vault kv storage, use this command
+
+ ```shell
+ # provided, your current directory contains the files named "public.pem" and "private.pem"
+ $ vault kv put kv/apisix/consumer/jim/jwt-auth public_key=@public.pem private_key=@private.pem
+ Success! Data written to: kv/apisix/consumer/jim/jwt-auth
+ ```
+
+3. Public key in consumer configuration, while the private key is in the vault.
+
+ ```shell
+ $ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "username": "john",
+ "plugins": {
+ "jwt-auth": {
+ "key": "user-key",
+ "algorithm": "RS256",
+ "public_key": "-----BEGIN PUBLIC KEY-----\n……\n-----END PUBLIC KEY-----"
+ "vault": {}
+ }
+ }
+ }'
+ ```
+
+ This plugin uses RSA public key from consumer configuration and uses the private key directly fetched from the vault.
+
+### Disable Vault from Plugin
+
+Now, to disable the vault lookup from the `jwt-auth` plugin simply remove the empty vault object from the consumer plugin configuration (in this case it is `jack`). This will make the jwt plugin to lookup signing secrets (both HS256/HS512 or RS512 keypairs) into plugin configuration for subsequent requests to the URI route where the `jwt-auth` configuration has been enabled. Even if you have vault configuration enabled in APISIX `config.yaml` no request will be sent to the vault server.
+
+APISIX plugins are hot-reloaded, therefore is no need to restart APISIX.
+
+```shell
+$ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "username": "jack",
+ "plugins": {
+ "jwt-auth": {
+ "key": "test-key",
+ "secret": "my-secret-key"
+ }
+ }
+}'
+```
+
+## Summary
+
+This article brings you the upcoming release of the Vault-Apache APISIX integration and related details.
+
+Feel free to start a discussion in [GitHub Discussions](https://github.com/apache/apisix/discussions) or communicate via the [mailing list](https://apisix.apache.org/zh/docs/general/subscribe-guide).
Review comment:
```suggestion
Feel free to start a discussion in [GitHub Discussions](https://github.com/apache/apisix/discussions) or communicate via the [mailing list](https://apisix.apache.org/docs/general/subscribe-guide).
```
Btw, just wondering if it is possible to add a ref to my blog? Hehe😅
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org