title: hmac-auth keywords:
The hmac-auth
Plugin adds HMAC authentication to a Route or a Service.
This Plugin works with a Consumer object and a consumer of your API has to add its key to the request header for verification.
Name | Type | Required | Default | Valid values | Description |
---|---|---|---|---|---|
access_key | string | True | Unique key of a Consumer. If different Consumers have the same key, a request matching exception will occur. | ||
secret_key | string | True | Used in pair with access_key . This field supports saving the value in Secret Manager using the APISIX Secret resource. | ||
algorithm | string | False | “hmac-sha256” | [“hmac-sha1”, “hmac-sha256”, “hmac-sha512”] | Encryption algorithm used. |
clock_skew | integer | False | 0 | Clock skew allowed by the signature in seconds. Setting it to 0 will skip checking the date. | |
signed_headers | array[string] | False | List of headers to be used in the encryption algorithm. If specified, the client request can only contain the specified headers. When unspecified, all the headers are used in the encryption algorithm. | ||
keep_headers | boolean | False | false | [ true, false ] | When set to true , keeps the request headers X-HMAC-SIGNATURE , X-HMAC-ALGORITHM and X-HMAC-SIGNED-HEADERS in the HTTP request after successful authentication. Otherwise, the headers are removed. |
encode_uri_params | boolean | False | true | [ true, false ] | When set to true encodes the URI parameters. For example, params1=hello%2Cworld is encoded whereas, params2=hello,world is not. |
validate_request_body | boolean | False | false | [ true, false ] | When set to true , validates the request body. |
max_req_body | integer | False | 512 * 1024 | Max size of the request body to allow. |
NOTE: encrypt_fields = {"secret_key"}
is also defined in the schema, which means that the field will be stored encrypted in etcd. See encrypted storage fields.
First we enable the Plugin on a Consumer object as shown below:
curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { "username": "jack", "plugins": { "hmac-auth": { "access_key": "user-key", "secret_key": "my-secret-key", "clock_skew": 0, "signed_headers": ["User-Agent", "Accept-Language", "x-custom-a"] } } }'
You can also use the APISIX Dashboard to complete the operation through a web UI.
Next, you can configure the Plugin to a Route or a Service:
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { "uri": "/index.html", "plugins": { "hmac-auth": {} }, "upstream": { "type": "roundrobin", "nodes": { "127.0.0.1:1980": 1 } } }'
The formula for calculating the signature is signature = HMAC-SHAx-HEX(secret_key, signing_string)
.
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
. The different terms in this calculation are explained below:
:::tip
If any of the terms are missing, they are replaced by an empty string.
:::
The algorithm for generating canonical_query_string
is described below:
&
as the separator.encode_uri_params
is true
:uri_encode(key) + "="
.uri_encode(key) + "=" + uri_encode(value)
. Here, the value can even be an empty string.canonical_query_string
.encode_uri_params
is false
:key + "="
.key + "=" + value
. Here, the value can even be an empty string.canonical_query_string
.And the algorithm for generating the signed_headers_string
is as follows:
name:value
format. This is the signed_headers_string
.HeaderKey1 + ":" + HeaderValue1 + "\n"\+ HeaderKey2 + ":" + HeaderValue2 + "\n"\+ ... HeaderKeyN + ":" + HeaderValueN + "\n"
The example below shows signature string splicing:
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"
signing_string
as"GET"
/index.html
, and the signing_string
is obtained from the HTTP Method + \n + HTTP URI as"GET /index.html"
name=james&age=36
, assuming that encode_uri_params
is false. According to the algorithm of canonical_query_string
, the focus is on dictionary sorting of key
to get age=36&name=james
."GET /index.html age=36&name=james"
access_key
is user-key
, and the signing_string
is obtained from HTTP Method + \n + HTTP URI + \n + canonical_query_string + \n + access_key as"GET /index.html age=36&name=james user-key"
Tue, 19 Jan 2021 11:33:20 GMT
, and the signing_string
is obtained from the HTTP Method + \n + HTTP URI + \n + canonical_query_string + \n + access_key + \n + Date as"GET /index.html age=36&name=james user-key Tue, 19 Jan 2021 11:33:20 GMT"
signed_headers_string
is used to specify the headers involved in the signature, which in the above example includes User-Agent: curl/7.29.0
and x-custom-a: test
.And the signing_string
is obtained from the HTTP Method + \n + HTTP URI + \n + canonical_query_string + \n + access_key + \n + Date + \n as
"GET /index.html age=36&name=james user-key Tue, 19 Jan 2021 11:33:20 GMT User-Agent:curl/7.29.0 x-custom-a:test "
The Python code below shows how to generate the signature:
import base64 import hashlib import hmac secret = bytes('my-secret-key', 'utf-8') message = bytes("""GET /index.html age=36&name=james user-key Tue, 19 Jan 2021 11:33:20 GMT User-Agent:curl/7.29.0 x-custom-a:test """, 'utf-8') hash = hmac.new(secret, message, hashlib.sha256) # to lowercase base64 print(base64.b64encode(hash.digest()))
Type | Hash |
---|---|
SIGNATURE | 8XV1GB7Tq23OJcoz6wjqTs4ZLxr9DiLoY4PxzScWGYg= |
You can also refer to Generating HMAC signatures for how to generate signatures for different programming languages.
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(<body>))
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.
:::
You can now use the generated signature to make requests as shown below:
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" \ -H "Date: Tue, 19 Jan 2021 11:33:20 GMT" \ -H "X-HMAC-SIGNED-HEADERS: User-Agent;x-custom-a" \ -H "x-custom-a: test" \ -H "User-Agent: curl/7.29.0"
HTTP/1.1 200 OK Content-Type: text/html; charset=utf-8 Transfer-Encoding: chunked Connection: keep-alive Date: Tue, 19 Jan 2021 11:33:20 GMT Server: APISIX/2.2 ......
The signature can be put in the Authorization
header of the request:
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 ... Accept-Ranges: bytes <!DOCTYPE html> <html lang="cn"> ...
Or, the signature can be placed separately in another request header:
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 ... Accept-Ranges: bytes <!DOCTYPE html> <html lang="cn">
:::note
;
. For example, x-custom-header-a;x-custom-header-b
.SIGNATURE
needs to be base64 encoded for encryption.:::
You can use custom header keys for the auth parameters by changing the plugin_attr
in your configuration file (conf/config.yaml
):
plugin_attr: hmac-auth: signature_key: X-APISIX-HMAC-SIGNATURE algorithm_key: X-APISIX-HMAC-ALGORITHM date_key: X-APISIX-DATE access_key: X-APISIX-HMAC-ACCESS-KEY signed_headers_key: X-APISIX-HMAC-SIGNED-HEADERS body_digest_key: X-APISIX-HMAC-BODY-DIGEST
Now you can use the new keys while making a request:
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 ... Accept-Ranges: bytes <!DOCTYPE html> <html lang="cn">
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.
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { "uri": "/index.html", "plugins": {}, "upstream": { "type": "roundrobin", "nodes": { "127.0.0.1:1980": 1 } } }'