-
Notifications
You must be signed in to change notification settings - Fork 2.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: update "Authentication" Plugins #6824
docs: update "Authentication" Plugins #6824
Conversation
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
…navendu-pottekkat/apisix into docs/plugin-authentication/6734
Co-authored-by: homeward <97138894+hf400159@users.noreply.github.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Others LGTM
I will modify the Chinese version synchronously. |
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Very long pr : )
docs/en/latest/plugins/jwt-auth.md
Outdated
| 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`. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| 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`. | | |
| 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
Outdated
|
||
[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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. | |
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
Outdated
|
||
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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's not use secret/keys
here - people might think it's a vault path.
The current version of Apache APISIX expects the key names of the secret/keys in Vault to be `secret`, `public_key`, `private_key`. | |
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
Outdated
@@ -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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 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.
@@ -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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please keep this line. It's important to deliver the message.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I had moved the line to above the code block. We do mention this.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Gotcha!
docs/en/latest/plugins/jwt-auth.md
Outdated
@@ -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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
jackmentioned 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.
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
0f57da8
@bisakhmondal I have made the changes as you suggested. Please review. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM.
@@ -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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Gotcha!
<!-- | ||
![add a consumer](https://raw.githubusercontent.com/apache/apisix/master/docs/assets/images/plugin/wolf-rbac-1.png) | ||
|
||
![enable wolf-rbac plugin](https://raw.githubusercontent.com/apache/apisix/master/docs/assets/images/plugin/wolf-rbac-2.png) | ||
--> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
By the way, just curious is it intentional or some debug comment?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It was intentional. We can move the docs for the dashboard to a single place. It gets repeated on every page. I commented this out just so that we know we have these images. Can delete these images or repurpose them on different pages in the future.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sounds great 👍 . Please make sure you are keeping it tracked in an issue or somewhere so that people know/track the purpose/progress.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice work
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM
Co-authored-by: homeward <97138894+hf400159@users.noreply.github.com>
Co-authored-by: homeward <97138894+hf400159@users.noreply.github.com>
Signed-off-by: Navendu Pottekkat navendupottekkat@gmail.com
Description
Updates the documentation of the "Authentication" Plugins.
Child PR of #6734
Sorry for big PR 😅