Private Key JWT
Pré-requisitos:
- Configurações básicas
- Verificar se o método de autenticação é valido
- Valor "code" retornado pelo endpoint authorize
Token
URL de Documentação da API : /apidocs/#/OAuth2/post__application__oauth_token
Após o login do usuario com sucesso, voce deve pegar o valor do argumento code
e
dados do client cadastrado e consumir o endpoint https://[ip ou hostname (fqdn)]/<application name>/oauth/token
Parâmetros:
- application:
- Obrigatório: Sim
- Tipo: String
- Localização: Caminho da URL (Path)
- Descrição: Nome da aplicação a ser usada.
- client_id:
- Obrigatório: Sim
- Tipo: String
- Localização: No corpo da requisição JSON
- Descrição: ID do cliente a ser usado na geração do "code"
- code:
- Obrigatório: Sim
- Tipo: String
- Localização: No corpo da requisição JSON.
- Descrição: Codigo retornado no endpoint
authorize
- grant_type:
- Obrigatório: Sim
- Tipo: String
- Localização: No corpo da requisição JSON.
- Descrição: Grant type configurado no client
- redirect_uri:
- Obrigatório: Sim
- Tipo: String
- Localização: No corpo da requisição JSON.
- Descrição: Redirect Uri enviado como parametro do endpoint de
authorize
- client_assertion_type:
- Obrigatório: Sim
- Tipo: String
- Valor: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
- Localização: No corpo da requisição JSON.
- Descrição: Constante especificada em https://datatracker.ietf.org/doc/html/draft-ietf-oauth-jwt-bearer#section-2.2
- client_assertion:
- Obrigatório: Sim
- Tipo: String
- Localização: No corpo da requisição JSON.
- Descrição: Contém o JWT assinado por uma chave privada gerada por alguma criptografia de chave pública.
No exemplo abaixo iremos utilizar o fluxo com o grant_type
sendo authorization_code
e o response_type
como code
Como o Token Endpoint Auth Method
foi definido no exemplo como private_key_jwt
a autenticação é realizada a partir do jwt passado no parâmetro client_assertion
Gerando o par de chaves RSA
Para gerar o par de chaves iremos utilizar o toolkit disponibilizado pela api do Authfy Connect
Executar uma requisição para o endpoint
/jwk/generate
e armazenar o resultado em um arquivo# o arquivo deve conter o par de chaves em três formatos # .pem, base64, e JWK (Json Web Key) curl -X GET "https://[ip ou hostname (fqdn)]/api/jwk/generate?kty=RSA&alg=RS256" \ -H "accept: application/json" > key_pair.txt
- Armazenar a chave pública em formato JWK em um arquivo separado
cat key_pair.txt | \ tr -d [[:space:]] | \ grep -oE \"public_jwk\":\{.*\}? | \ sed -E 's/\"public_jwk\":(\{.*\})/\1/g' | \ sed 's/.$//' > public_key.jwk
Registrando o JWK (Json Web Key) no client
- Registrando o JWK
- O JWK é registrado no client que previamente foi definido com o método de autenticação
private_key_jwt
. Para recordar como se atualiza um client, acesse aqui: Atualizando Clients
- O JWK é registrado no client que previamente foi definido com o método de autenticação
- Registrando o JWK
Estrutura de um JSON WEB TOKEN (JWT)
JWT Header | Explicação |
---|---|
{ "alg":"RS256", "typ":"JWT" } |
"alg": Algoritmo criptográfico usado na assinatura do JWT. Referência: https://www.rfc-editor.org/rfc/rfc7515#section-4.1.1 "typ": Tipo de mídia do JWT. Usado nas aplicações para distinguir estruturas de dados que podem conter outros objetos além de um JWT. Referência: https://www.rfc-editor.org/rfc/rfc7519#section-5.1 |
Payload (JWT Claims) | Explicação |
---|---|
{ "jti":"id_único" "iss":"client_id", "sub":"client_id", "aud":"token_endpoint", "iat":tempo_emitido, "exp":tempo_validade } |
"jti": Identificador único para o JWT. Referência: https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7 "iss": Emissor do token. Referência: https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1 "sub": Identifica a quem pertence o token. Referência: https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2 "aud": Identifica os destinatários aos quais o JWT se destina. Referência: https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3 "iat": Identifica o tempo em que o JWT foi emitido. Referência: https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6 "exp": Identifica o tempo de validade do JWT. Referência: https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4 |
Observação
O tempo dos campos "iat" e "exp" é um valor numérico JSON representando o número de segundos a partir de 1970-01-01T00:00:00Z UTC. Referência: NumericDateUsando utilitários do Linux para calcular "iat" e "exp"
- "iat": Tempo em que o token foi emitido
# +%s representa o número de segundos desde 1970-01-01T00:00:00Z UTC date +%s
"exp": Validade do token
# Para calcular a validade do token, adicione o número de segundos # que irão passar até que o token se torne inválido # No exemplo a seguir o token torna-se inválido 24hrs após sua emissão echo $((`date +%s`+86400))
- "iat": Tempo em que o token foi emitido
Gerando um JWT assinado com o algoritmo RS256 e chaves RSA
Para gerar e assinar o JWT utilizaremos o endpoint
/jwt/sign
do toolkit disponibilizado pela api do Authfy Connect- Extrair a chave privada contida no arquivo key_pair.txt criado na seção Gerando o par de chaves RSA
cat key_pair.txt | \ grep -oE "(-----BEGIN PRIVATE KEY-----.*-----END PRIVATE KEY-----)" \ > private_key.pem
- Realizar a requisição para o endpoint
/jwt/sign
curl -X POST "https://[ip ou hostname (fqdn)]/api/jwt/sign" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d "{ \"headers\":{\"alg\":\"RS256\",\"typ\":\"JWT\"}, \"json\":{\"iss\":\"<client_id>\",\"iat\":<tempo_emitido>,\"exp\":<tempo_validade>,\"aud\":\"https://[ip ou hostname (fqdn)]/<application name>/oauth/token\",\"sub\":\"<client_id>\",\"jti\":\"<id_único>\"}, \"private_key\":\"$(cat private_key.pem)\"}" | \ tr -d "{}, [[:space:]], \"" | \ sed -E 's/jwt:([[:alnum:]]*)/\1/g' > jwt_signed.jwt
- Extrair a chave privada contida no arquivo key_pair.txt criado na seção Gerando o par de chaves RSA
Exemplo de uma requisição usando
private_key_jwt
para autenticaçãocurl -X POST "https://[ip ou hostname (fqdn)]/<application name>/oauth/token" \ -H "accept: application/json" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d client_id=<client_id> \ -d code=<auth_code> \ -d grant_type=authorization_code \ -d redirect_uri=<redirect_uri> \ -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \ -d client_assertion=$(cat jwt_signed.jwt)
O retorno desta chamada deve ser similar ao exemplo abaixo:
{ "access_token": "eyJhbGciOiJSUz[...]EoULcOD4XZtfsTq1j95bg", "expires_in": 3600, "scope": "profile", "token_type": "Bearer" }
UserInfo
URL de Documentação da API : /apidocs/#/OAuth2/get__application__oauth_userinfo
Para recuperar as informações do usuário, utilize o access_token
retornado pelo endpoint acima como valor do
header Authorization: Bearer <access_token>
Parâmetros:
- application name:
- Obrigatório: Sim
- Tipo: String
- Localização: Caminho da URL (Path)
- Descrição: O nome da aplicação a ser usada.
Exemplos:
Curl:
curl -X GET "https://[ip ou hostname (fqdn)]/<application name>/oauth/userinfo" \ -H "accept: application/json" \ -H "Authorization: Bearer <access_token>"
O retorno desta chamada deve ser similar ao exemplo abaixo:
{ "id": "09d97a66-da69-4049-9123-3fdd7c2c2738", "name": "userdocs", "sub": "09d97a66-da69-4049-9123-3fdd7c2c2738", "username": "userdocs" }