doc: update enable-authentication-and-restriction, jwt-auth and wolf-rbac examples. (#1018)
Co-authored-by: Jintao Zhang <tao12345666333@163.com>
diff --git a/docs/en/latest/practices/enable-authentication-and-restriction.md b/docs/en/latest/practices/enable-authentication-and-restriction.md
index e95b9b6..530eea6 100644
--- a/docs/en/latest/practices/enable-authentication-and-restriction.md
+++ b/docs/en/latest/practices/enable-authentication-and-restriction.md
@@ -29,27 +29,116 @@
### Authentication
-#### [`keyAuth`](https://apisix.apache.org/docs/apisix/plugins/key-auth/)
+#### Key Auth
-Consumers add their key either in a header `apikey` to authenticate their requests.
+Consumers add their key either in a header or query string parameter to authenticate their requests. For more information about `Key Auth`, please refer to [APISIX key-auth plugin](https://apisix.apache.org/docs/apisix/plugins/key-auth/).
+Also, we can using the `secretRef` field to reference a K8s Secret object so that we can avoid the hardcoded sensitive data in the ApisixConsumer object. For reference Secret use example, please refer to the [key-auth-reference-secret-object](#key-auth-reference-secret-object).
+
+<details>
+ <summary>Key Auth yaml configure</summary>
```yaml
-keyAuth:
- value:
- key: ${key}
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixConsumer
+metadata:
+ name: ${name}
+spec:
+ authParameter:
+ keyAuth:
+ value:
+ key: ${key} #required
```
-#### [`basicAuth`](https://apisix.apache.org/docs/apisix/plugins/basic-auth/)
+</details>
-Consumers add their key either in a header `Authentication` to authenticate their requests.
+#### Basic Auth
+
+Consumers add their key in a header to authenticate their requests. For more information about `Basic Auth`, please refer to [APISIX basic-auth plugin](https://apisix.apache.org/docs/apisix/plugins/basic-auth/).
+Also, we can using the `secretRef` field to reference a K8s Secret object so that we can avoid the hardcoded sensitive data in the ApisixConsumer object. For reference Secret use example, please refer to the [key-auth-reference-secret-object](#key-auth-reference-secret-object).
+
+<details>
+ <summary>Basic Auth yaml configure</summary>
```yaml
-basicAuth:
- value:
- username: ${username}
- password: ${password}
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixConsumer
+metadata:
+ name: ${name}
+spec:
+ authParameter:
+ basicAuth:
+ value:
+ username: ${username} #required
+ password: ${password} #required
```
+</details>
+
+#### JWT Auth
+
+The consumer then adds its key to the query string parameter, request header, or cookie to verify its request. For more information about `JWT Auth`, please refer to [APISIX jwt-auth plugin](https://apisix.apache.org/docs/apisix/plugins/jwt-auth/).
+Also, we can using the `secretRef` field to reference a K8s Secret object so that we can avoid the hardcoded sensitive data in the ApisixConsumer object. For reference Secret use example, please refer to the [key-auth-reference-secret-object](#key-auth-reference-secret-object).
+
+:::note Need to expose API
+This plugin will add `/apisix/plugin/jwt/sign` to sign. You may need to use `public-api` plugin to expose it.
+:::
+
+<details>
+ <summary>JWT Auth yaml configure</summary>
+
+```yaml
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixConsumer
+metadata:
+ name: ${name}
+spec:
+ authParameter:
+ wolfRbac:
+ value:
+ key: "${key}" #required
+ secret: "${secret}" #optional
+ public_key: "${public_key}" #optional, required when algorithm attribute selects RS256 algorithm.
+ private_key: "{private_key}" #optional, required when algorithm attribute selects RS256 algorithm.
+ algorithm: "${HS256 | HS512 | RS256}" #optional
+ exp: ${ 86400 | token's expire time, in seconds} #optional
+ algorithm: ${true | false} #optional
+```
+
+</details>
+
+#### `Wolf RBAC`
+
+To use wolfRbac authentication, you need to start and install [wolf-server](https://github.com/iGeeky/wolf/blob/master/quick-start-with-docker/README.md). For more information about `Wolf RBAC`, please refer to [APISIX wolf-rbac plugin](https://apisix.apache.org/zh/docs/apisix/plugins/wolf-rbac/).
+Also, we can using the `secretRef` field to reference a K8s Secret object so that we can avoid the hardcoded sensitive data in the ApisixConsumer object. For reference Secret use example, please refer to the [key-auth-reference-secret-object](#key-auth-reference-secret-object).
+
+:::note This plugin will add several APIs
+
+* /apisix/plugin/wolf-rbac/login
+* /apisix/plugin/wolf-rbac/change_pwd
+* /apisix/plugin/wolf-rbac/user_info
+
+You may need to use `public-api` plugin to expose it.
+:::
+
+<details>
+ <summary>Wolf RBAC yaml configure</summary>
+
+```yaml
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixConsumer
+metadata:
+ name: ${name}
+spec:
+ authParameter:
+ wolfRBAC:
+ value:
+ server: "${server of wolf-rbac}" #optional
+ appid: "${appid of wolf-rbac}" #optional
+ header_prefix: "${X- | X-UserId | X-Username | X-Nickname}" #optional
+```
+
+</details>
+
### [Restriction](https://apisix.apache.org/docs/apisix/plugins/consumer-restriction/)
#### `whitelist` or `blacklist`
@@ -57,6 +146,9 @@
`whitelist`: Grant full access to all users specified in the provided list, **has the priority over `allowed_by_methods`**
`blacklist`: Reject connection to all users specified in the provided list, **has the priority over `whitelist`**
+<details>
+ <summary>whitelist or blacklist with consumer-restriction yaml configure</summary>
+
```yaml
plugins:
- name: consumer-restriction
@@ -67,10 +159,15 @@
- "${consumer_name}"
```
+</details>
+
#### `allowed_by_methods`
HTTP methods can be `methods:["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE", "PURGE"]`
+<details>
+ <summary>allowed_by_methods with consumer-restriction yaml configure</summary>
+
```yaml
plugins:
- name: consumer-restriction
@@ -79,15 +176,19 @@
allowed_by_methods:
- user: "${consumer_name}"
methods:
- - "POST"
- - "GET"
+ - "${GET | POST | PUT |...}"
+ - "${GET | POST | PUT |...}"
- user: "${consumer_name}"
methods:
- - "GET"
+ - "${GET | POST | PUT |...}"
```
+</details>
+
## Example
+[Refer to the corresponding e2e test case.](../../../../test/e2e/suite-features/consumer.go)
+
### Prepare env
To use this tutorial, you must deploy `Ingress APISIX` and `httpbin` in Kubernetes cluster.
@@ -103,9 +204,11 @@
### How to enable `Authentication`
+#### Enable `keyAuth`
+
The following is an example. The `keyAuth` is enabled on the specified route to restrict user access.
-Create ApisixConsumer foo:
+* Creates an ApisixConsumer, and set the attributes of plugin `key-auth`:
```shell
kubectl apply -f - <<EOF
@@ -121,7 +224,7 @@
EOF
```
-ApisixRoute:
+* Creates an ApisixRoute, and enable plugin `key-auth`:
```shell
kubectl apply -f - <<EOF
@@ -134,7 +237,7 @@
- name: rule1
match:
hosts:
- - local.httpbin.org
+ - httpbin.org
paths:
- /*
backends:
@@ -146,10 +249,183 @@
EOF
```
-Requests from foo:
+* Requests from foo:
```shell
-kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -H 'apikey:foo-key' -i
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: httpbin.org' -H 'apikey:foo-key' -i
+```
+
+```shell
+HTTP/1.1 200 OK
+...
+```
+
+##### Key Auth reference Secret object
+
+<details>
+ <summary>ApisixRoute with keyAuth consumer using secret example</summary>
+
+* Creates a `Secret` object:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: v1
+kind: Secret
+metadata:
+ name: foovalue
+data:
+ key: Zm9vLWtleQ==
+EOF
+```
+
+* Creates an ApisixConsumer and reference `Secret` object:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixConsumer
+metadata:
+ name: foo
+spec:
+ authParameter:
+ keyAuth:
+ secretRef:
+ name: foovalue
+EOF
+```
+
+* Creates an ApisixRoute, and enables plugin `key-auth`:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixRoute
+metadata:
+ name: httpserver-route
+spec:
+ http:
+ - name: rule1
+ match:
+ hosts:
+ - httpbin.org
+ paths:
+ - /*
+ backends:
+ - serviceName: httpbin
+ servicePort: 80
+ authentication:
+ enable: true
+ type: keyAuth
+EOF
+```
+
+* Requests from foo:
+
+```shell
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: httpbin.org' -H 'apikey:foo-key' -i
+```
+
+```shell
+HTTP/1.1 200 OK
+...
+```
+
+</details>
+
+#### Enable `JWT Auth`
+
+* Creates an ApisixConsumer, and set the attributes of plugin `jwt-auth`:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixConsumer
+metadata:
+ name: foo2
+spec:
+ authParameter:
+ jwtAuth:
+ value:
+ key: foo2-key
+EOF
+```
+
+* Use the `public-api` plugin to expose the public API:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixRoute
+metadata:
+ name: default
+spec:
+ http:
+ - name: public-api
+ match:
+ paths:
+ - /apisix/plugin/jwt/sign
+ backends:
+ - serviceName: apisix-admin
+ servicePort: 9180
+ plugins:
+ - name: public-api
+ enable: true
+EOF
+```
+
+* Creates an ApisixRoute, and enable the jwt-auth plugin:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: apisix.apache.org/v2beta3
+kind: ApisixRoute
+metadata:
+ name: httpbin-route
+spec:
+ http:
+ - name: rule1
+ match:
+ hosts:
+ - httpbin.org
+ paths:
+ - /*
+ backends:
+ - serviceName: httpbin
+ servicePort: 80
+ authentication:
+ enable: true
+ type: jwtAuth
+EOF
+```
+
+* Get the token:
+
+```shell
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=foo2-key -H 'Host: httpbin.org' -i
+```
+
+```shell
+HTTP/1.1 200 OK
+...
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI
+```
+
+* Without token:
+
+```shell
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: httpbin.org' -i
+```
+
+```shell
+HTTP/1.1 401
+...
+{"message":"Missing JWT token in request"}
+```
+
+* Request header with token:
+
+```shell
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: httpbin.org' -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI' -i
```
```shell
@@ -167,7 +443,7 @@
* **consumer_name**: Add the `username` of `consumer` to a whitelist or blacklist (supporting single or multiple consumers) to restrict access to services or routes.
-Create ApisixConsumer jack1:
+* Create ApisixConsumer jack1:
```shell
kubectl apply -f - <<EOF
@@ -183,7 +459,7 @@
EOF
```
-Create ApisixConsumer jack2:
+* Create ApisixConsumer jack2:
```shell
kubectl apply -f - <<EOF
@@ -199,7 +475,7 @@
EOF
```
-ApisixRoute:
+* Creates an ApisixRoute, and enable config `whitelist` of the plugin `consumer-restriction`:
```shell
kubectl apply -f - <<EOF
@@ -212,7 +488,7 @@
- name: rule1
match:
hosts:
- - local.httpbin.org
+ - httpbin.org
paths:
- /*
backends:
@@ -250,10 +526,10 @@
**Example usage**
-Requests from jack1:
+* Requests from jack1:
```shell
-kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -H 'apikey:jack1-key' -i
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: httpbin.org' -H 'apikey:jack1-key' -i
```
```shell
@@ -261,10 +537,10 @@
...
```
-Requests from jack2:
+* Requests from jack2:
```shell
-kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -H 'apikey:jack2-key' -i
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: httpbin.org' -H 'apikey:jack2-key' -i
```
```shell
@@ -277,6 +553,8 @@
This example restrict the user `jack2` to only `GET` on the resource.
+* Creates an ApisixRoute, and enable config `allowed_by_methods` of the plugin `consumer-restriction`:
+
```shell
kubectl apply -f - <<EOF
apiVersion: apisix.apache.org/v2beta3
@@ -288,7 +566,7 @@
- name: rule1
match:
hosts:
- - local.httpbin.org
+ - httpbin.org
paths:
- /*
backends:
@@ -314,10 +592,10 @@
**Example usage**
-Requests from jack1:
+* Requests from jack1:
```shell
-kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -H 'apikey:jack1-key' -i
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: httpbin.org' -H 'apikey:jack1-key' -i
```
```shell
@@ -326,7 +604,7 @@
```
```shell
-kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -H 'apikey:jack1-key' -d '' -i
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: httpbin.org' -H 'apikey:jack1-key' -d '' -i
```
```shell
@@ -334,10 +612,10 @@
...
```
-Requests from jack2:
+* Requests from jack2:
```shell
-kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -H 'apikey:jack2-key' -i
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: httpbin.org' -H 'apikey:jack2-key' -i
```
```shell
@@ -346,7 +624,7 @@
```
```shell
-kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -H 'apikey:jack2-key' -d '' -i
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: httpbin.org' -H 'apikey:jack2-key' -d '' -i
```
```shell
@@ -370,7 +648,7 @@
- name: rule1
match:
hosts:
- - local.httpbin.org
+ - httpbin.org
paths:
- /*
backends:
@@ -394,10 +672,8 @@
EOF
```
-Requests:
-
```shell
-kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: local.httpbin.org' -i
+kubectl exec -it -n ${namespace of Apache APISIX} ${pod of Apache APISIX} -- curl http://127.0.0.1:9080/anything -H 'Host: httpbin.org' -i
```
```shell
