docs: update "Authentication" Plugins #6824

pottekkat · 2022-04-11T14:12:45Z

Signed-off-by: Navendu Pottekkat navendupottekkat@gmail.com

Description

Updates the documentation of the "Authentication" Plugins.

Child PR of #6734

Sorry for big PR 😅

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

…navendu-pottekkat/apisix into docs/plugin-authentication/6734

…ntication/6734

docs/en/latest/plugins/hmac-auth.md

Co-authored-by: homeward <97138894+hf400159@users.noreply.github.com>

juzhiyuan

Others LGTM

docs/en/latest/plugins/authz-keycloak.md

guitu168 · 2022-04-12T10:30:15Z

I will modify the Chinese version synchronously.

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

juzhiyuan

LGTM

bisakhmondal

Very long pr : )

bisakhmondal · 2022-04-13T15:00:17Z

docs/en/latest/plugins/jwt-auth.md

+| 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`. |


Suggested change

| 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. |

bisakhmondal · 2022-04-13T15:06:05Z

docs/en/latest/plugins/jwt-auth.md

+
+[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.


Suggested change

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.

bisakhmondal · 2022-04-13T15:09:28Z

docs/en/latest/plugins/jwt-auth.md


-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`.


Let's not use secret/keys here - people might think it's a vault path.

Suggested change

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.

bisakhmondal · 2022-04-13T15:12:24Z

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.


Suggested change

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.

bisakhmondal · 2022-04-13T15:13:58Z

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.


Please keep this line. It's important to deliver the message.

I had moved the line to above the code block. We do mention this.

bisakhmondal · 2022-04-13T15:16:47Z

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.


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 usernamejackmentioned 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>

pottekkat · 2022-04-14T04:58:41Z

@bisakhmondal I have made the changes as you suggested. Please review.

bisakhmondal

LGTM.

bisakhmondal · 2022-04-14T05:07:25Z

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.


bisakhmondal · 2022-04-14T05:11:54Z

docs/en/latest/plugins/wolf-rbac.md

+<!--
+![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)
+-->


By the way, just curious is it intentional or some debug comment?

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.

Sounds great 👍 . Please make sure you are keeping it tracked in an issue or somewhere so that people know/track the purpose/progress.

bisakhmondal

Nice work

juzhiyuan

LGTM

Co-authored-by: homeward <97138894+hf400159@users.noreply.github.com>

pottekkat added 16 commits April 11, 2022 19:39

Update authz-casbin docs

36f6cb6

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

Update authz-casdoor docs

c203fe4

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

Update authz-keycloak docs

31753d4

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

Update basic-auth docs

51857ba

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

Update forward-auth docs

486ff56

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

Update hmac-auth docs

608722f

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

Update jwt-auth docs

7f4841c

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

Update key-auth docs

ee0fccc

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

Update ldap-auth docs

6431ccb

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

Update opa docs

7035f0c

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

Update openid-connect docs

8fc1430

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

Update wolf-rbac docs

9d829c7

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

Merge branch 'master' into docs/plugin-authentication/6734

a7570b0

fix lint errors

9145dc9

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

Merge branch 'docs/plugin-authentication/6734' of https://github.com/…

7308275

…navendu-pottekkat/apisix into docs/plugin-authentication/6734

Merge remote-tracking branch 'upstream/master' into docs/plugin-authe…

96bea0f

…ntication/6734

guitu168 reviewed Apr 12, 2022

View reviewed changes

docs/en/latest/plugins/hmac-auth.md Outdated Show resolved Hide resolved

Update docs/en/latest/plugins/hmac-auth.md

ec18d92

Co-authored-by: homeward <97138894+hf400159@users.noreply.github.com>

juzhiyuan reviewed Apr 12, 2022

View reviewed changes

docs/en/latest/plugins/authz-keycloak.md Outdated Show resolved Hide resolved

juzhiyuan requested review from bzp2010, bisakhmondal, guoqqqi, gxthrj and lilien1010 April 12, 2022 05:51

guitu168 mentioned this pull request Apr 12, 2022

docs: modify the Chinese version docs. #6833

Closed

apply suggestions from the review

141e0b4

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

juzhiyuan previously approved these changes Apr 13, 2022

View reviewed changes

guitu168 previously approved these changes Apr 13, 2022

View reviewed changes

leslie-tsang previously approved these changes Apr 13, 2022

View reviewed changes

bisakhmondal requested changes Apr 13, 2022

View reviewed changes

apply suggestions from review

0f57da8

Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>

pottekkat dismissed stale reviews from leslie-tsang, guitu168, and juzhiyuan via 0f57da8 April 14, 2022 04:58

bisakhmondal reviewed Apr 14, 2022

View reviewed changes

bisakhmondal approved these changes Apr 14, 2022

View reviewed changes

pottekkat requested review from juzhiyuan and leslie-tsang April 14, 2022 05:52

leslie-tsang approved these changes Apr 14, 2022

View reviewed changes

juzhiyuan approved these changes Apr 14, 2022

View reviewed changes

spacewander merged commit b2f3273 into apache:master Apr 15, 2022

pottekkat deleted the docs/plugin-authentication/6734 branch April 15, 2022 03:40

juzhiyuan mentioned this pull request Apr 20, 2022

docs: update "cors" docs #6877

Merged

Liu-Junlin pushed a commit to Liu-Junlin/apisix that referenced this pull request May 20, 2022

docs: update "Authentication" Plugins (apache#6824)

498ae61

Co-authored-by: homeward <97138894+hf400159@users.noreply.github.com>

spacewander pushed a commit that referenced this pull request Jun 30, 2022

docs: update "Authentication" Plugins (#6824)

3e81e18

Co-authored-by: homeward <97138894+hf400159@users.noreply.github.com>

yzeng25 mentioned this pull request Aug 6, 2024

docs: wrong plugin name occurs in basic-auth doc #11479

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update "Authentication" Plugins #6824

docs: update "Authentication" Plugins #6824

pottekkat commented Apr 11, 2022 •

edited

Loading

juzhiyuan left a comment

guitu168 commented Apr 12, 2022

juzhiyuan left a comment

bisakhmondal left a comment

bisakhmondal Apr 13, 2022

bisakhmondal Apr 13, 2022

bisakhmondal Apr 13, 2022

bisakhmondal Apr 13, 2022

bisakhmondal Apr 13, 2022

pottekkat Apr 14, 2022

bisakhmondal Apr 14, 2022

bisakhmondal Apr 13, 2022

pottekkat commented Apr 14, 2022

bisakhmondal left a comment

bisakhmondal Apr 14, 2022

bisakhmondal Apr 14, 2022

pottekkat Apr 14, 2022

bisakhmondal Apr 14, 2022

bisakhmondal left a comment

juzhiyuan left a comment

	\| 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. \|


		[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.


		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`.

	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).

docs: update "Authentication" Plugins #6824

docs: update "Authentication" Plugins #6824

Conversation

pottekkat commented Apr 11, 2022 • edited Loading

Description

juzhiyuan left a comment

Choose a reason for hiding this comment

guitu168 commented Apr 12, 2022

juzhiyuan left a comment

Choose a reason for hiding this comment

bisakhmondal left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pottekkat commented Apr 14, 2022

bisakhmondal left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bisakhmondal left a comment

Choose a reason for hiding this comment

juzhiyuan left a comment

Choose a reason for hiding this comment

pottekkat commented Apr 11, 2022 •

edited

Loading