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/04/13 15:18:25 UTC
[GitHub] [apisix] bisakhmondal commented on a diff in pull request #6824: docs: update "Authentication" Plugins
bisakhmondal commented on code in PR #6824:
URL: https://github.com/apache/apisix/pull/6824#discussion_r849589972
##########
docs/en/latest/plugins/jwt-auth.md:
##########
@@ -23,47 +29,58 @@ title: jwt-auth
## Description
-`jwt-auth` is an authentication plugin that need to work with `consumer`. Add JWT Authentication to a `service` or `route`.
+The `jwt-auth` Plugin is used to add [JWT](https://jwt.io/) authentication to a [Service](../terminology/service.md) or a [Route](../terminology/route.md).
-The `consumer` then adds its key to the query string parameter, request header, or `cookie` to verify its request.
+A [Consumer](../terminology/consumer.md) of the service then needs to provide a key through a query string, a request header or a cookie to verify its request.
-For more information on JWT, refer to [JWT](https://jwt.io/) for more information.
-
-`jwt-auth` plugin can be integrated with HashiCorp Vault for storing and fetching secrets, RSA key pairs from its encrypted kv engine. See the [examples](#enable-jwt-auth-with-vault-compatibility) below to have an overview of how things work.
+The `jwt-auth` Plugin can be integrated with [HashiCorp Vault](https://www.vaultproject.io/) to store and fetch secrets and RSA keys pairs from its [encrypted KV engine](https://www.vaultproject.io/docs/secrets/kv). Learn more from the [examples](#enable-jwt-auth-with-vault-compatibility) below.
## Attributes
-For consumer side:
+For Consumer:
+
+| Name | Type | Required | Default | Valid values | Description |
+|---------------|---------|-------------------------------------------------------|---------|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| key | string | True | | | Unique key for a Consumer. |
+| secret | string | False | | | The encryption key. If unspecified, auto generated in the background. |
+| public_key | string | True if `RS256` is set for the `algorithm` attribute. | | | RSA public key. |
+| private_key | string | True if `RS256` is set for the `algorithm` attribute. | | | RSA private key. |
+| algorithm | string | False | "HS256" | ["HS256", "HS512", "RS256"] | Encryption algorithm. |
+| exp | integer | False | 86400 | [1,...] | Expiry time of the token in seconds. |
+| base64_secret | boolean | False | false | | Set to true if the secret is base64 encoded. |
+| vault | object | False | | | Set to true to use Vault for storing and retrieving secret (secret for HS256/HS512 or public_key and private_key for RS256). By default, the Vault path is `kv/apisix/consumer//jwt-auth`. |
Review Comment:
```suggestion
| vault | object | False | | | Set to true to use Vault for storing and retrieving secret (secret for HS256/HS512 or public_key and private_key for RS256). By default, the Vault path is `kv/apisix/consumer/<consumer_name>/jwt-auth`. `consumer_name` is the name of your consumer that you have defined while creating a consumer object in APISIX. |
```
##########
docs/en/latest/plugins/jwt-auth.md:
##########
@@ -114,15 +135,23 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-### Enable jwt-auth with Vault Compatibility
+### Usage with HashiCorp Vault
+
+[HashiCorp Vault](https://www.vaultproject.io/) offers a centralized key management solution and it can be used along with APISIX for authentication.
+
+So, if your organization changes the secret/keys (secret for HS256/HS512 or public_key and private_key for RS256) and you don't want to update the APISIX consumer each time or if you don't want to use the key through the Admin API, you can use Vault and the `jwt-auth` Plugin.
Review Comment:
```suggestion
So, if your organization changes the secret/keys (secret for HS256/HS512 or public_key and private_key for RS256) frequently and you don't want to update the APISIX consumer each time or if you don't want to use the key through the Admin API (to reduce secret sprawl), you can enable Vault support into the `jwt-auth` Plugin.
```
##########
docs/en/latest/plugins/jwt-auth.md:
##########
@@ -114,15 +135,23 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-### Enable jwt-auth with Vault Compatibility
+### Usage with HashiCorp Vault
+
+[HashiCorp Vault](https://www.vaultproject.io/) offers a centralized key management solution and it can be used along with APISIX for authentication.
+
+So, if your organization changes the secret/keys (secret for HS256/HS512 or public_key and private_key for RS256) and you don't want to update the APISIX consumer each time or if you don't want to use the key through the Admin API, you can use Vault and the `jwt-auth` Plugin.
+
+:::note
-Sometimes, it's quite natural in production to have a centralized key management solution like [HashiCorp Vault](https://www.vaultproject.io/) where you don't have to update the APISIX consumer each time some part of your organization changes the signing secret key (secret for HS256/HS512 or public_key and private_key for RS256) and/or for privacy concerns you don't want to use the key through APISIX admin APIs. APISIX got you covered here. The `jwt-auth` is capable of referencing keys from vault.
+The current version of Apache APISIX expects the key names of the secret/keys in Vault to be `secret`, `public_key`, `private_key`.
Review Comment:
Let's not use `secret/keys` here - people might think it's a vault path.
```suggestion
The current version of Apache APISIX expects the key name of secrets stored in the Vault path is among [ `secret`, `public_key`, `private_key` ]. The first one is for HS256/HS512 and the last two are for the RS256 algorithm.
```
##########
docs/en/latest/plugins/jwt-auth.md:
##########
@@ -174,29 +207,20 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f1
}'
```
-This plugin uses rsa public key from consumer configuration and uses the private key directly fetched from vault.
Review Comment:
Please keep this line. It's important to deliver the message.
##########
docs/en/latest/plugins/jwt-auth.md:
##########
@@ -137,14 +166,16 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f1
}'
```
-Here the plugin looks up for key `secret` inside vault path (`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`) for consumer username `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.
+The Plugin will look for a key "secret" in the provided Vault path (`<vault.prefix>/consumer/jack/jwt-auth`) and uses it for JWT authentication.
Review Comment:
```suggestion
The Plugin will look for a key "secret" in the provided Vault path (`<vault.prefix>/consumer/jack/jwt-auth`) and uses it for JWT authentication. The vault prefix can be set in the config yaml file based on the base path that you have chosen while enabling the Vault kv secret engine (eg: `vault secrets enable -path=foobar kv`, you should use `foobar` as `vault.prefix` in the config file).
```
Just to give some context.
##########
docs/en/latest/plugins/jwt-auth.md:
##########
@@ -137,14 +166,16 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f1
}'
```
-Here the plugin looks up for key `secret` inside vault path (`<vault.prefix from conf.yaml>/consumer/jack/jwt-auth`) for consumer username `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.
+The Plugin will look for a key "secret" in the provided Vault path (`<vault.prefix>/consumer/jack/jwt-auth`) and uses it for JWT authentication.
Review Comment:
Also this message is important, can we embed it here somehow as the lookup is dynamic based on the username of the consumer and users should know what would happen if the key path is empty (though obvious but we should be explicit i think). WDYT?
`
consumer username `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.
`
--
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