hmac-auth
is an authentication plugin that need to work with consumer
. Add HMAC Authentication to a service
or route
.
The consumer
then adds its key to request header to verify its request.
Name | Requirement | Default | Description |
---|---|---|---|
access_key | required | none | Different consumer objects should have different values, and it should be unique. If different consumers use the same access_key , a request matching exception will occur |
secret_key | required | none | Use as a pair with access_key |
algorithm | optional | hmac-sha256 | Encryption algorithm. support hmac-sha1 , hmac-sha256 and hmac-sha512 |
clock_skew | optional | 300 | The clock skew allowed by the signature in seconds. For example, if the time is allowed to skew by 10 seconds, then it should be set to 10 . especially, 0 means not checking timestamp. |
signed_headers | optional | none | Restrict the headers that are added to the encrypted calculation. After the specified, the client request can only specify the headers within this range. When this item is empty, all the headers specified by the client request will be added to the encrypted calculation. Example:[“User-Agent”, “Accept-Language”, “x-custom-a”] |
hmac-auth
optioncurl http://127.0.0.1:9080/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": 10, "signed_headers": ["User-Agent", "Accept-Language", "x-custom-a"] } } }'
hmac-auth
plugincurl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { "uri": "/index.html", "plugins": { "hmac-auth": {} }, "upstream": { "type": "roundrobin", "nodes": { "39.97.63.215:80": 1 } } }'
The calculation formula of the signature is signature = HMAC-SHAx-HEX(secret_key, signning_string)
. From the formula, it can be seen that in order to obtain the signature, two parameters, SECRET_KEY
and SIGNNING_STRING
, are required. Where secret_key is configured by the corresponding consumer, the calculation formula of SIGNNING_STRING
is signning_string = HTTP Method + HTTP URI + canonical_query_string + access_key + timestamp + signed_headers_string
HTTP URI
requirements must start with “/”, those that do not start with “/” need to be added, and the empty path is “/”.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).signed_headers_string
is the result of obtaining the fields specified by the client from the request header and concatenating the strings in order.The coding steps are as follows:
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.
Encoding each item after disassembly is divided into the following two situations.
The signed_headers_string generation steps are as follows:
SIGNED_HEADERS
in the next section Use the generated signature to make a request attempt
.SIGNED_HEADERS
in order from the request header, and splice them together in order. After splicing, a signed_headers_string
is generated.Note: ACCESS_KEY, SIGNATURE, ALGORITHM, TIMESTAMP, SIGNED_HEADERS respectively represent the corresponding variables Note: SIGNED_HEADERS is the headers specified by the client to join the encryption calculation, multiple separated by semicolons, Example: User-Agent;Accept-Language
Authorization
field:$ curl http://127.0.0.1:9080/index.html -H 'Authorization: hmac-auth-v1# + ACCESS_KEY + # + base64_encode(SIGNATURE) + # + ALGORITHM + # + TIMESTAMP + # + SIGNED_HEADERS' -i HTTP/1.1 200 OK Content-Type: text/html Content-Length: 13175 ... Accept-Ranges: bytes <!DOCTYPE html> <html lang="cn"> ...
$ curl http://127.0.0.1:9080/index.html -H 'X-HMAC-SIGNATURE: base64_encode(SIGNATURE)' -H 'X-HMAC-ALGORITHM: ALGORITHM' -H 'X-HMAC-TIMESTAMP: TIMESTAMP' -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">
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:
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { "uri": "/index.html", "plugins": {}, "upstream": { "type": "roundrobin", "nodes": { "39.97.63.215:80": 1 } } }'