Introdução ao Plugin hmac-auth

O plugin hmac-auth no APISIX é essencial para autenticar requisições baseadas em HMAC. Deve ser utilizado em conjunto com um Consumer, onde o cliente inclui chaves de segurança nos cabeçalhos da requisição para validação. Este guia aborda os principais aspectos de configuração e uso.

Parâmetros de Configuração

• algorithm: Define o algoritmo de hash, padrão hmac-sha256. Opções incluem hmac-sha1, hmac-sha256 e hmac-sha512. O cliente deve enviar o cabeçalho X-HMAC-ALGORITHM com o valor correspondente.
• clock_skew: Define o tempo máximo permitido de desvio entre o timestamp da requisição e o do servidor, em segundos.
• access_key: Identificador único para o Consumer, semelhante a um app_id. O cliente inclui este valor no cabeçalho X-HMAC-ACCESS-KEY.
• signed_headers: Lista de cabeçalhos que participam no cálculo da assinatura. O cliente envia estes cabeçalhos em X-HMAC-SIGNED-HEADERS.
• X-HMAC-SIGNATURE: Cabeçalho contendo a assinatura gerada pelo cliente.

Configuração do Consumidor

Para configurar um Consumer com o plugin hmac-auth, adicione-o ao perfil e defina um access_key exclusivo. Este consumidor pode suportar múltiplas capacidades de autenticação, como hmac-auth e key-auth para métodos mais simples.

Processo de Geração da Assinatura

A assinatura é construída iterativamente. Considere a seguinte requisição de exemplo:

curl -i http://127.0.0.1:9080/index.html?nome=jorge&idade=36 \
-H "X-HMAC-SIGNED-HEADERS: User-Agent;x-custom-a" \
-H "x-custom-a: teste" \
-H "User-Agent: curl/7.29.0"

O processo segue estas etapas:

1. Enicie com o método HTTP, por exemplo, GET, formando a string base.
2. Concatene o URI, como /index.html, separado por uma nova linha.
3. Adicione os parâmetros da query ordenados alfabeticamente: idade=36&nome=jorge (supondo encode_uri_params como false).
4. Inclua o access_key, como chave-usuario.
5. Enexe a data no formato GMT, como Qua, 20 Out 2021 09:15:30 GMT.
6. Finalize com os cabeçalhos assinados, por exemplo, User-Agent:curl/7.29.0 e x-custom-a:teste, seguidos por uma nova linha.

A string completa para assinatura resulta em:

GET
/index.html
idade=36&nome=jorge
chave-usuario
Qua, 20 Out 2021 09:15:30 GMT
User-Agent:curl/7.29.0
x-custom-a:teste

Validação do Corpo da Requisição

Quando validate_request_body é ativado, o plugin calcula o hash HMAC-SHA do corpo da requisição e compara com o valor no cabeçalho X-HMAC-DIGEST. A fórmula é: X-HMAC-DIGEST: base64(hmac-sha(corpo)). Para requisições sem corpo, use uma string vazia. Note que habilitar isso pode aumentar o consumo de memória para corpos grandes; configure max_req_body (padrão 512KB) para limitar o tamanho.

Exemplo de Implementação em Python

Para gerar a assinatura HMAC-SHA256, utilize um script Python adaptado. Veja um exemplo reescrito com variáveis modificadas:

import base64
import hashlib
import hmac

chave_secreta = bytes('minha-chave-secreta', 'utf-8')
string_para_assinatura = bytes("""GET
/index.html
idade=36&nome=jorge
chave-usuario
Qua, 20 Out 2021 09:15:30 GMT
User-Agent:curl/7.29.0
x-custom-a:teste
""", 'utf-8')

hmac_digest = hmac.new(chave_secreta, string_para_assinatura, hashlib.sha256)
assinatura_codificada = base64.b64encode(hmac_digest.digest()).decode('utf-8')

print(assinatura_codificada)

Este código produz uma assinatura como exemplificado abaixo:

Testando a Requisição

Após gerar a assinatura, envie a requisição com todos os cabeçalhos necessários. Exemplo usando curl:

curl -i "http://127.0.0.1:9080/index.html?nome=jorge&idade=36" \
-H "X-HMAC-SIGNATURE: 8XV1GB7Tq23OJcoz6wjqTs4ZLxr9DiLoY4PxzScWGYg=" \
-H "X-HMAC-ALGORITHM: hmac-sha256" \
-H "X-HMAC-ACCESS-KEY: chave-usuario" \
-H "Date: Qua, 20 Out 2021 09:15:30 GMT" \
-H "X-HMAC-SIGNED-HEADERS: User-Agent;x-custom-a" \
-H "x-custom-a: teste" \
-H "User-Agent: curl/7.29.0"

Alternativamente, a assinatura pode ser incluída no campo Authorization seguindo o formato: hmac-auth-v1#ACCESS_KEY#base64_encode(SIGNATURE)#ALGORITHM#DATE#SIGNED_HEADERS.