diff --git a/docs/en/latest/plugins/authz-casbin.md b/docs/en/latest/plugins/authz-casbin.md index d26bd3a4e956..d20455d8c8cf 100644 --- a/docs/en/latest/plugins/authz-casbin.md +++ b/docs/en/latest/plugins/authz-casbin.md @@ -1,5 +1,11 @@ --- title: authz-casbin +keywords: + - APISIX + - Plugin + - Authz Casbin + - authz-casbin +description: This document contains information about the Apache APISIX authz-casbin Plugin. --- -### 2. add a Route or add a Service, and enable the `basic-auth` plugin +Once you have created a Consumer object, you can then configure a Route or a Service to authenticate requests: ```shell curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' @@ -88,52 +92,42 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13 }' ``` -## Test Plugin +## Example usage -- missing Authorization header +After you have configured the Plugin as mentioned above, you can make a request to the Route as shown below: ```shell -$ curl -i http://127.0.0.1:9080/hello -HTTP/1.1 401 Unauthorized -... -{"message":"Missing authorization in request"} +curl -i -ufoo:bar http://127.0.0.1:9080/hello ``` -- user is not exists: - -```shell -$ curl -i -ubar:bar http://127.0.0.1:9080/hello -HTTP/1.1 401 Unauthorized +``` +HTTP/1.1 200 OK ... -{"message":"Invalid user authorization"} +hello, world ``` -- password is invalid: +If the request is not authorized, an error will be thrown: ```shell -$ curl -i -ufoo:foo http://127.0.0.1:9080/hello HTTP/1.1 401 Unauthorized ... -{"message":"Invalid user authorization"} +{"message":"Missing authorization in request"} ``` -- success: +And if the user or password is not valid: ```shell -$ curl -i -ufoo:bar http://127.0.0.1:9080/hello -HTTP/1.1 200 OK +HTTP/1.1 401 Unauthorized ... -hello, world +{"message":"Invalid user authorization"} ``` ## Disable Plugin -When you want to disable the `basic-auth` plugin, it is very simple, -you can delete the corresponding json configuration in the plugin configuration, -no need to restart the service, it will take effect immediately: +To disable the `jwt-auth` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. ```shell -$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -X PUT -d ' +curl http://127.0.0.1:9080/apisix/admin/routes/1 -X PUT -d ' { "methods": ["GET"], "uri": "/hello", diff --git a/docs/en/latest/plugins/forward-auth.md b/docs/en/latest/plugins/forward-auth.md index f7426642b77c..7aa928ce42c1 100644 --- a/docs/en/latest/plugins/forward-auth.md +++ b/docs/en/latest/plugins/forward-auth.md @@ -1,5 +1,11 @@ --- title: forward-auth +keywords: + - APISIX + - Plugin + - Forward Authentication + - forward-auth +description: This document contains information about the Apache APISIX forward-auth Plugin. --- -2. add a Route or add a Service, and enable the `hmac-auth` plugin +Next, you can configure the Plugin to a Route or a Service: ```shell curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' @@ -86,38 +92,37 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13 }' ``` -## Test Plugin +## Example usage + +### Generating the signature -### generate signature: +The formula for calculating the signature is `signature = HMAC-SHAx-HEX(secret_key, signing_string)`. -The calculation formula of the signature is `signature = HMAC-SHAx-HEX(secret_key, signing_string)`. From the formula, it can be seen that in order to obtain the signature, two parameters, `SECRET_KEY` and `signing_STRING`, are required. Where secret_key is configured by the corresponding consumer, the calculation formula of `signing_string` is `signing_string = HTTP Method + \n + HTTP URI + \n + canonical_query_string + \n + access_key + \n + Date + \n + signed_headers_string`. If one of the items in signing_string does not exist, you also need to use an empty string instead. +In order to generate the signature, two parameters, `secret_key` and `signing_string` are required. The `secret_key` is configured by a Consumer and the `signing_string` is calculated as `signing_string = HTTP Method + \n + HTTP URI + \n + canonical_query_string + \n + access_key + \n + Date + \n + signed_headers_string`. If any of the terms are missing, they are replaced by an empty string. The different terms in this calculation are explained below: -1. **HTTP Method** : Refers to the GET, PUT, POST and other request methods defined in the HTTP protocol, and must be in all uppercase. -2. **HTTP URI** : `HTTP URI` requirements must start with "/", those that do not start with "/" need to be added, and the empty path is "/". -3. **Date** : Date in http header(GMT format). -4. **canonical_query_string** :`canonical_query_string` is the result of encoding the `query` in the URL (`query` is the string "key1 = valve1 & key2 = valve2" after the "?" in the URL). -5. **signed_headers_string** :`signed_headers_string` is the result of obtaining the fields specified by the client from the request header and concatenating the strings in order. +- **HTTP Method** : HTTP request method in uppercase. For example, GET, PUT, POST etc. +- **HTTP URI** : HTTP URI. Should start with "/" and "/" denotes an empty path. +- **Date** : Date in the HTTP header in GMT format. +- **canonical_query_string** : The result of encoding the query string in the URL (the string "key1 = value1 & key2 = value2" after the "?" in the URL). +- **signed_headers_string** : Concatenation of the specified request headers. -> The coding steps of canonical_query_string are as follows: +The algorithm for generating `canonical_query_string` is described below: -* Extract the `query` item in the URL, that is, the string "key1 = valve1 & key2 = valve2" after the "?" in the URL. -* Split the `query` into several items according to the & separator, each item is in the form of key=value or only key. -* According to whether the uri parameter is encoded, there are two situations: -* When `encode_uri_params` is true: - * Encoding each item after disassembly is divided into the following two situations. - * When the item has only key, the conversion formula is uri_encode(key) + "=". - * When the item is in the form of key=value, the conversion formula is in the form of uri_encode(key) + "=" + uri_encode(value). Here value can be an empty string. - * After converting each item, sort by key in lexicographic order (ASCII code from small to large), and connect them with the & symbol to generate the corresponding canonical_query_string. -* When `encode_uri_params` is false: - * Encoding each item after disassembly is divided into the following two situations. - * When the item has only key, the conversion formula is key + "=". - * When the item is in the form of key=value, the conversion formula is in the form of key + "=" + value. Here value can be an empty string. - * After converting each item, sort by key in lexicographic order (ASCII code from small to large), and connect them with the & symbol to generate the corresponding canonical_query_string. +1. Extract the query terms from the URL. +2. Split the query terms into key-value pairs by using `&` as the separator. +3. If `encode_uri_params` is `true`: + 1. If there are only keys, the conversion formula is `uri_encode(key) + "="`. + 2. If there are both keys and values, the conversion formula is `uri_encode(key) + "=" + uri_encode(value)`. Here, the value can even be an empty string. + 3. Sort by key in lexicographic order and connect them with & symbol to generate the corresponding `canonical_query_string`. +4. If `encode_uri_params` is `false`: + 1. If there are only keys, the conversion formula is `key + "="`. + 2. If there are both keys and values, the conversion formula is `key + "=" + value`. Here, the value can even be an empty string. + 3. Sort by key in lexicographic order and connect them with & symbol to generate the corresponding `canonical_query_string`. -> The signed_headers_string generation steps are as follows: +And the algorithm for generating the `signed_headers_string` is as follows: -* Obtain the headers specified to be added to the calculation from the request header. For details, please refer to the placement of `SIGNED_HEADERS` in the next section `Use the generated signature to make a request attempt`. -* Take out the headers specified by `SIGNED_HEADERS` in order from the request header, and splice them together in order of `name:value`. After splicing, a `signed_headers_string` is generated. +1. Obtain the specified headers to add to the calculation from the request header. +2. Splice the specified headers in `name:value` format. This is the `signed_headers_string`. ```plain HeaderKey1 + ":" + HeaderValue1 + "\n"\+ @@ -126,18 +131,16 @@ HeaderKey2 + ":" + HeaderValue2 + "\n"\+ HeaderKeyN + ":" + HeaderValueN + "\n" ``` -**Signature string splicing example** - -Take the following request as an example: +The example below shows signature string splicing: ```shell -$ curl -i http://127.0.0.1:9080/index.html?name=james&age=36 \ +curl -i http://127.0.0.1:9080/index.html?name=james&age=36 \ -H "X-HMAC-SIGNED-HEADERS: User-Agent;x-custom-a" \ -H "x-custom-a: test" \ -H "User-Agent: curl/7.29.0" ``` -The `signing_string` generated according to the `signature generation formula` is: +The `signing_string` generated according to the algorithm above is: ```plain "GET @@ -150,11 +153,9 @@ x-custom-a:test " ``` -Note: The last request header also needs + `\n`. - -**Generate Signature** +The last request header also needs + `\n`. -Use Python to generate the signature `SIGNATURE`: +The Python code below shows how to generate the signature: ```python import base64 @@ -181,22 +182,30 @@ print(base64.b64encode(hash.digest())) | --------- | -------------------------------------------- | | SIGNATURE | 8XV1GB7Tq23OJcoz6wjqTs4ZLxr9DiLoY4PxzScWGYg= | -### Request body checking +You can also refer to [Generating HMAC signatures](../examples/plugins-hmac-auth-generate-signature.md) for how to generate signatures for different programming languages. -When `validate_request_body` is assigned to `true`, the plugin will check the request body. The plugin will calculate the hmac-sha value of the request body，and check against the `X-HMAC-DIGEST` header. +### Validating request body + +When the `validate_request_body` attribute is set to `true`, the Plugin will calculate the HMAC-SHA value of the request body and checks it again the `X-HMAC-DIGEST` header: ``` X-HMAC-DIGEST: base64(hmac-sha()) ``` -When there is no request body, you can set `X-HMAC-DIGEST` value to the hmac-sha of empty string. +If there is no request body, you can set the `X-HMAC-DIGEST` value to the HMAC-SHA of an empty string. + +:::note + +To calculate the digest of the request body, the Plugin will load the body to memory which can cause high memory consumption if the body is large. To avoid this, you can limit the max allowed body size by configuring `max_req_body` (default 512KB). Request bodies larger than the set size will be rejected. -**Note:** The plugin will load the request body to memory to calculate the digest of the request body, which might cause high memory consumption with large bodies. You can limit the max allowed body size by the configuration of `max_req_body`(default=512KB), request body larger than that will be rejected. +::: -### Use the generated signature to try the request +### Using the generated signature to make requests + +You can now use the generated signature to make requests as shown below: ```shell -$ curl -i "http://127.0.0.1:9080/index.html?name=james&age=36" \ +curl -i "http://127.0.0.1:9080/index.html?name=james&age=36" \ -H "X-HMAC-SIGNATURE: 8XV1GB7Tq23OJcoz6wjqTs4ZLxr9DiLoY4PxzScWGYg=" \ -H "X-HMAC-ALGORITHM: hmac-sha256" \ -H "X-HMAC-ACCESS-KEY: user-key" \ @@ -204,7 +213,9 @@ $ curl -i "http://127.0.0.1:9080/index.html?name=james&age=36" \ -H "X-HMAC-SIGNED-HEADERS: User-Agent;x-custom-a" \ -H "x-custom-a: test" \ -H "User-Agent: curl/7.29.0" +``` +```shell HTTP/1.1 200 OK Content-Type: text/html; charset=utf-8 Transfer-Encoding: chunked @@ -214,12 +225,13 @@ Server: APISIX/2.2 ...... ``` -**Below are two assembly forms of signature information** +The signature can be put in the `Authorization` header of the request: -* The signature information is put together in the request header `Authorization` field: +```shell +curl http://127.0.0.1:9080/index.html -H 'Authorization: hmac-auth-v1# + ACCESS_KEY + # + base64_encode(SIGNATURE) + # + ALGORITHM + # + DATE + # + SIGNED_HEADERS' -i +``` ```shell -$ curl http://127.0.0.1:9080/index.html -H 'Authorization: hmac-auth-v1# + ACCESS_KEY + # + base64_encode(SIGNATURE) + # + ALGORITHM + # + DATE + # + SIGNED_HEADERS' -i HTTP/1.1 200 OK Content-Type: text/html Content-Length: 13175 @@ -231,10 +243,13 @@ Accept-Ranges: bytes ... ``` -* The signature information is separately placed in the request header: +Or, the signature can be placed separately in another request header: + +```shell +curl http://127.0.0.1:9080/index.html -H 'X-HMAC-SIGNATURE: base64_encode(SIGNATURE)' -H 'X-HMAC-ALGORITHM: ALGORITHM' -H 'Date: DATE' -H 'X-HMAC-ACCESS-KEY: ACCESS_KEY' -H 'X-HMAC-SIGNED-HEADERS: SIGNED_HEADERS' -i +``` ```shell -$ curl http://127.0.0.1:9080/index.html -H 'X-HMAC-SIGNATURE: base64_encode(SIGNATURE)' -H 'X-HMAC-ALGORITHM: ALGORITHM' -H 'Date: DATE' -H 'X-HMAC-ACCESS-KEY: ACCESS_KEY' -H 'X-HMAC-SIGNED-HEADERS: SIGNED_HEADERS' -i HTTP/1.1 200 OK Content-Type: text/html Content-Length: 13175 @@ -245,15 +260,16 @@ Accept-Ranges: bytes ``` -**Note:** +:::note + +1. If there are multiple signed headers, they must be separated by `;`. For example, `x-custom-header-a;x-custom-header-b`. +2. `SIGNATURE` needs to be base64 encoded for encryption. -1. **ACCESS_KEY, SIGNATURE, ALGORITHM, DATE, SIGNED_HEADERS respectively represent the corresponding variables** -2. **SIGNED_HEADERS is the headers specified by the client to join the encryption calculation. If there are multiple headers, they must be separated by ";": `x-custom-header-a;x-custom-header-b`** -3. **SIGNATURE needs to use base64 for encryption: `base64_encode(SIGNATURE)`** +::: -## Custom header key +### Using custom header keys -We can customize header key for auth parameters by adding the attribute configuration of the plugin under `plugin_attr` in `conf / config.yaml`. +You can use custom header keys for the auth parameters by changing the `plugin_attr` in your configuration file (`conf/config.yaml`): ```yaml plugin_attr: @@ -266,10 +282,19 @@ plugin_attr: body_digest_key: X-APISIX-HMAC-BODY-DIGEST ``` -**After customizing the header, request example:** +Now you can use the new keys while making a request: + +```shell +curl http://127.0.0.1:9080/index.html \ +-H 'X-APISIX-HMAC-SIGNATURE: base64_encode(SIGNATURE)' \ +-H 'X-APISIX-HMAC-ALGORITHM: ALGORITHM' \ +-H 'X-APISIX-DATE: DATE' \ +-H 'X-APISIX-HMAC-ACCESS-KEY: ACCESS_KEY' \ +-H 'X-APISIX-HMAC-SIGNED-HEADERS: SIGNED_HEADERS' \ +-H 'X-APISIX-HMAC-BODY-DIGEST: BODY_DIGEST' -i +``` ```shell -$ curl http://127.0.0.1:9080/index.html -H 'X-APISIX-HMAC-SIGNATURE: base64_encode(SIGNATURE)' -H 'X-APISIX-HMAC-ALGORITHM: ALGORITHM' -H 'X-APISIX-DATE: DATE' -H 'X-APISIX-HMAC-ACCESS-KEY: ACCESS_KEY' -H 'X-APISIX-HMAC-SIGNED-HEADERS: SIGNED_HEADERS' -H 'X-APISIX-HMAC-BODY-DIGEST: BODY_DIGEST' -i HTTP/1.1 200 OK Content-Type: text/html Content-Length: 13175 @@ -280,37 +305,12 @@ Accept-Ranges: bytes ``` -### Enable request body checking - -```shell -$ curl -X "POST" "http://localhost:9080/index.html?age=36&name=james" \ - -H 'X-HMAC-ACCESS-KEY: my-access-key' \ - -H 'X-HMAC-SIGNATURE: lSWO4vcyVoZG5bn8miHudzABAeJQd8tqEHyM7RsjeiU=' \ - -H 'X-HMAC-ALGORITHM: hmac-sha256' \ - -H 'Date: Tue, 24 Aug 2021 03:19:21 GMT' \ - -H 'X-HMAC-SIGNED-HEADERS: User-Agent;X-HMAC-DIGEST' \ - -H 'User-Agent: curl/7.29.0' \ - -H 'X-HMAC-DIGEST: L9b/+QMvhvnoUlSw5vq+kHPqnZiHGl61T8oavMVTaC4=' \ - -H 'Content-Type: text/plain; charset=utf-8' \ - -d "{\"hello\":\"world\"}" - -HTTP/1.1 200 OK -Content-Type: text/html; charset=utf-8 -Transfer-Encoding: chunked -Connection: keep-alive -Date: Tue, 14 Sep 2021 03:28:14 GMT -Server: APISIX/2.9 -... -``` - ## Disable Plugin -When you want to disable the `hmac-auth` plugin, it is very simple, -you can delete the corresponding json configuration in the plugin configuration, -no need to restart the service, it will take effect immediately: +To disable the `hmac-auth` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. ```shell -$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { "uri": "/index.html", "plugins": {}, @@ -322,24 +322,3 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f } }' ``` - -## Generate Signature Examples - -Take HMAC SHA256 as an example to introduce the signature generation examples in different languages. -Need to pay attention to the handling of newline characters in signature strings in various languages, which can easily lead to the problem of `{"message":"Invalid signature"}`. - -Example inputs: - -| Variable | Value | -| -------- | -------------------------- | -| secret | the shared secret key here | -| message | this is signature string | - -Example outputs: - -| Type | Hash | -| ------ | ---------------------------------------------------------------- | -| hexit | ad1b76c7e5054009380edca35d3f36cc5b6f45c82ee02ea3af64197ebddb9345 | -| base64 | rRt2x+UFQAk4DtyjXT82zFtvRcgu4C6jr2QZfr3bk0U= | - -Please refer to [**HMAC Generate Signature Examples**](../examples/plugins-hmac-auth-generate-signature.md) diff --git a/docs/en/latest/plugins/jwt-auth.md b/docs/en/latest/plugins/jwt-auth.md index 5f2c6437bd1c..f6591a1994b1 100644 --- a/docs/en/latest/plugins/jwt-auth.md +++ b/docs/en/latest/plugins/jwt-auth.md @@ -1,5 +1,11 @@ --- title: jwt-auth +keywords: + - APISIX + - Plugin + - JWT Auth + - jwt-auth +description: This document contains information about the Apache APISIX jwt-auth Plugin. --- -## Test Plugin - -#### Get the Token in `jwt-auth` Plugin: +## Example usage -First, you need to set up the route for the API that signs the token, which will use the [public-api](public-api.md) plugin. +You need to first setup a Route for an API that signs the token using the [public-api](public-api.md) Plugin: ```shell -$ curl http://127.0.0.1:9080/apisix/admin/routes/jas -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +curl http://127.0.0.1:9080/apisix/admin/routes/jas -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { "uri": "/apisix/plugin/jwt/sign", "plugins": { @@ -205,12 +237,15 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/jas -H 'X-API-KEY: edd1c9f03433 }' ``` -Let's get a token. +Now, we can get a token: -* without extension payload: +- Without extension payload: ```shell -$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key -i +curl http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key -i +``` + +``` HTTP/1.1 200 OK Date: Wed, 24 Jul 2019 10:33:31 GMT Content-Type: text/plain @@ -221,10 +256,13 @@ Server: APISIX web server eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI ``` -* with extension payload: +- With extension payload: ```shell -$ curl -G --data-urlencode 'payload={"uid":10000,"uname":"test"}' http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key -i +curl -G --data-urlencode 'payload={"uid":10000,"uname":"test"}' http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key -i +``` + +``` HTTP/1.1 200 OK Date: Wed, 21 Apr 2021 06:43:59 GMT Content-Type: text/plain; charset=utf-8 @@ -235,21 +273,13 @@ Server: APISIX/2.4 eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1bmFtZSI6InRlc3QiLCJ1aWQiOjEwMDAwLCJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTYxOTA3MzgzOX0.jI9-Rpz1gc3u8Y6lZy8I43RXyCu0nSHANCvfn0YZUCY ``` -#### Try Request with Token - -* without token: +You can now use this token while making requests: ```shell -$ curl http://127.0.0.1:9080/index.html -i -HTTP/1.1 401 Unauthorized -... -{"message":"Missing JWT token in request"} +curl http://127.0.0.1:9080/index.html -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI' -i ``` -* request header with token: - -```shell -$ curl http://127.0.0.1:9080/index.html -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI' -i +``` HTTP/1.1 200 OK Content-Type: text/html Content-Length: 13175 @@ -261,10 +291,21 @@ Accept-Ranges: bytes ... ``` -* request params with token: +Without the token, you will receive an error: ```shell -$ curl http://127.0.0.1:9080/index.html?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI -i +HTTP/1.1 401 Unauthorized +... +{"message":"Missing JWT token in request"} +``` + +You can also pass the token as query parameters: + +```shell +curl http://127.0.0.1:9080/index.html?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI -i +``` + +``` HTTP/1.1 200 OK Content-Type: text/html Content-Length: 13175 @@ -276,10 +317,13 @@ Accept-Ranges: bytes ... ``` -* request cookie with token: +And also as cookies: ```shell -$ curl http://127.0.0.1:9080/index.html --cookie jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI -i +curl http://127.0.0.1:9080/index.html --cookie jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI -i +``` + +``` HTTP/1.1 200 OK Content-Type: text/html Content-Length: 13175 @@ -293,12 +337,10 @@ Accept-Ranges: bytes ## Disable Plugin -When you want to disable the `jwt-auth` plugin, it is very simple, -you can delete the corresponding json configuration in the plugin configuration, -no need to restart the service, it will take effect immediately: +To disable the `jwt-auth` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. ```shell -$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { "methods": ["GET"], "uri": "/index.html", diff --git a/docs/en/latest/plugins/key-auth.md b/docs/en/latest/plugins/key-auth.md index 400b6c56adea..c2b47d71aad8 100644 --- a/docs/en/latest/plugins/key-auth.md +++ b/docs/en/latest/plugins/key-auth.md @@ -1,5 +1,11 @@ --- title: key-auth +keywords: + - APISIX + - Plugin + - Key Auth + - key-auth +description: This document contains information about the Apache APISIX key-auth Plugin. --- + +## Example usage -Use the `public-api` plugin to expose the public API. +You can use the `public-api` Plugin to expose the API: ```shell -$ curl http://127.0.0.1:9080/apisix/admin/routes/wal -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +curl http://127.0.0.1:9080/apisix/admin/routes/wal -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { "uri": "/apisix/plugin/wolf-rbac/login", "plugins": { @@ -115,20 +124,17 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/wal -H 'X-API-KEY: edd1c9f03433 }' ``` -You also need to setup the `change_pwd` and `user_info` routes together. +Similarly, you can setup the Routes for `change_pwd` and `user_info`. -#### Login and get `wolf-rbac` token: - -The following `appid`, `username`, and `password` must be real ones in the wolf system. -`authType` is the authentication type, `1` is password authentication, `2` is `LDAP` authentication. The default is `1`. `wolf` supports `LDAP` authentication since version 0.5.0 - -* Login as `POST application/json` +You can now login and get a wolf `rbac_token`: ```shell curl http://127.0.0.1:9080/apisix/plugin/wolf-rbac/login -i \ -H "Content-Type: application/json" \ -d '{"appid": "restful", "username":"test", "password":"user-password", "authType":1}' +``` +```shell HTTP/1.1 200 OK Date: Wed, 24 Jul 2019 10:33:31 GMT Content-Type: text/plain @@ -138,7 +144,15 @@ Server: APISIX web server {"rbac_token":"V1#restful#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts","user_info":{"nickname":"test","username":"test","id":"749"}} ``` -* Login as `POST x-www-form-urlencoded` +:::note + +The `appid`, `username`, and `password` must be configured in the wolf system. + +`authType` is the authentication type—1 for password authentication (default) and 2 for LDAP authentication (v0.5.0+). + +::: + +You can also make a post request with `x-www-form-urlencoded` instead of JSON: ```shell curl http://127.0.0.1:9080/apisix/plugin/wolf-rbac/login -i \ @@ -146,71 +160,79 @@ curl http://127.0.0.1:9080/apisix/plugin/wolf-rbac/login -i \ -d 'appid=restful&username=test&password=user-password' ``` -#### try request with token +Now you can test the Route: -* without token +- without token: ```shell curl http://127.0.0.1:9080/ -H"Host: www.baidu.com" -i +``` +``` HTTP/1.1 401 Unauthorized ... {"message":"Missing rbac token in request"} ``` -* request header(Authorization) with token: +- with token in `Authorization` header: ```shell curl http://127.0.0.1:9080/ -H"Host: www.baidu.com" \ -H 'Authorization: V1#restful#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts' -i +``` +```shell HTTP/1.1 200 OK ``` -* request header(x-rbac-token) with token: +- with token in `x-rbac-token` header: ```shell curl http://127.0.0.1:9080/ -H"Host: www.baidu.com" \ -H 'x-rbac-token: V1#restful#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts' -i +``` - +```shell HTTP/1.1 200 OK ``` -* request params with token: +- with token in request parameters: ```shell curl 'http://127.0.0.1:9080?rbac_token=V1%23restful%23eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts' -H"Host: www.baidu.com" -i +``` - +```shell HTTP/1.1 200 OK ``` -* request cookie with token: +- with token in cookie: ```shell curl http://127.0.0.1:9080 -H"Host: www.baidu.com" \ --cookie x-rbac-token=V1#restful#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts -i +``` - +``` HTTP/1.1 200 OK ``` -#### Get `RBAC` user information +And to get a user information: ```shell curl http://127.0.0.1:9080/apisix/plugin/wolf-rbac/user_info \ --cookie x-rbac-token=V1#restful#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts -i +``` - +```shell HTTP/1.1 200 OK { "user_info":{ @@ -229,24 +251,23 @@ HTTP/1.1 200 OK } ``` -#### Change 'RBAC' user password +And to change a user's password: ```shell curl http://127.0.0.1:9080/apisix/plugin/wolf-rbac/change_pwd \ -H "Content-Type: application/json" \ --cookie x-rbac-token=V1#restful#eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NzQ5LCJ1c2VybmFtZSI6InRlc3QiLCJtYW5hZ2VyIjoiIiwiYXBwaWQiOiJyZXN0ZnVsIiwiaWF0IjoxNTc5NDQ5ODQxLCJleHAiOjE1ODAwNTQ2NDF9.n2-830zbhrEh6OAxn4K_yYtg5pqfmjpZAjoQXgtcuts -i \ -X PUT -d '{"oldPassword": "old password", "newPassword": "new password"}' +``` - +```shell HTTP/1.1 200 OK {"message":"success to change password"} ``` ## Disable Plugin -When you want to disable the `wolf-rbac` plugin, it is very simple, - you can delete the corresponding json configuration in the plugin configuration, - no need to restart the service, it will take effect immediately: +To disable the `wolf-rbac` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. ```shell curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '