A autenticação do IXC ACS é baseada em JWTs, uma forma autocontida de Token, que carrega no seu payload um objeto JavaScript e uma assinatura digital. Os JWTs utilizados no ACS são assinados utilizando chaves ECDSA.
Antes de utilizar os JWTs da API do IXCsoft ACS, é necessário entender o funcionamento e gerar seu par de chaves ECDSA.
Verifique o tópico Geração de Chave antes de prosseguir.
Um JWT é formado por três partes principais:
Geralmente, um JWT tem o seguinte formato:
xxxxxx.yyyyyy.zzzzzz
Onde:
xxxxxx: Cabeçalho codificado em Base64Url;yyyyyy: Corpo codificado em Base64Url;zzzzzz: Assinatura dos das duas partes anteriores, codificada em Base64Url;Nunca transmita dados sensíveis em um JWT. As informações armazenadas no corpo do JWT são apenas codificadas, e nenhum tipo de criptografia é aplicado sobre elas. Portanto, quando trafegando sob conexões inseguras, considere seu JWT como desprotegido.
Cada uma das partes do token é um JSON, que deve conter alguns dados específicos. Vamos agora verificar cada uma das
partes do token de autenticação da API do IXCsoft ACS abaixo:
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI2MTg1ODMyNGRlNmNlZjAwMTF
mNTFiMDUiLCJleHAiOjE2MzgyMTU3MDgsImlhdCI6MTYzODIxNDcwOH0.F1DRaeJcQ1oG8Nc
33R0iSEBppEGFUQmLFKDzAaX3e9I2sTLZT0qOerw8nUhbcogAZsZpwQdQdAnU4B0SKIvBDA
Codificado
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9
Decodificado
{
"alg": "ES256",
"typ": "JWT"
}
O cabeçalho de um JWT de autenticação sempre terá o mesmo conteúdo:
typ: O atributo typ indica que esse documento é do tipo JWT;alg: O atributo alg indica qual o algoritmo criptográfico utilizado na assinatura do Token. No caso de Tokens da API do IXC ACS, esse campo sempre será preenchido com o valor ES256.Codificado
eyJpc3MiOiI2MTg1ODMyNGRlNmNlZjAwMTFmNTFiMDUiLCJleHAiOjE2MzgyMTU3MDgsImlhdCI6MTYzODIxNDcwOH0
Decodificado
{
"iss": "61858324de6cef0011f51b05",
"exp": 1638215708,
"iat": 1638214708
}
O corpo do JWT é onde as informações de autenticação do seu Client API devem ser colocadas:
iss: O atributo iss identifica o emissor do JWT. Nesse campo, é necessário adicionar como valor o id do seu Client API, para que ele seja identificado como o emissor do Token e as suas permissões sejam aplicadas ao Token de Acesso subsequente.exp: Atributo que indica quando o Token irá expirar, em UNIX timestamp.iat: Atributo que indica quando o Token foi criado, em UNIX timestamp.Como o Token de Autorização pode ser utilizado para ganhar acesso à Tokens de Acesso, recomendamos que o tempo até a expiração de seu Token de Autorização seja curto, diminuindo a chance de usos maliciosos.
Codificado
F1DRaeJcQ1oG8Nc33R0iSEBppEGFUQmLFKDzAaX3e9I2sTLZT0qOerw8nUhbcogAZsZpwQdQdAnU4B0SKIvBDA
A assinatura é gerada automaticamente no momento de criação do Token, utilizando como base a chave criptográfica do dono do Token. Não carrega nenhuma informação humanamente legível. A assinatura é baseada na Chave Privada.
Após adicionar os dados ao seu Token, assine-o (conforme a sua linguagem de programação) utilizando como algoritmo o ES256 e como chave de assinatura a sua Chave Privada (gerada no tutorial de criação de chaves).
O seu token está pronto para requisitar um token de Acesso. Envie-o ao Endpoint de Autenticação API como um Bearer Token. Para mais informações sobre a utilização das rotas da API e dos Tokens de Autenticação e Acesso, consulte a documentação da API no Swagger.
Para entender melhor como Funcionam JWTs, visite jwt.io.