Tokens OAuth

Os endpoints POST /auth/token e POST /oauth2/token são equivalentes: recebem o mesmo formulário application/x-www-form-urlencoded e devolvem a mesma resposta. Eles aceitam dois grants:

Grant	`grant_type`	Quando usar
Password grant	`password`	A integração conhece o usuário e a senha.
Token exchange	`urn:ietf:params:oauth:grant-type:token-exchange`	A integração já tem um JWT emitido por um provedor aceito pelo ambiente.

Nota

O token exchange segue o OAuth 2.0 e o OAuth 2.1. O password grant faz parte do OAuth 2.0, mas não do OAuth 2.1, e pode estar desabilitado no ambiente. Para seguir o OAuth 2.1, peça ao administrador do serviço que desabilite o password grant nos métodos de autenticação da API e use o token exchange ou o Single Sign-On. Veja Compatibilidade com OAuth 2.1.

Password grant

read -r -p 'Usuário: ' API_USER
read -r -s -p 'Senha: ' API_PASSWORD; printf '\n'

curl -i \
  --data-urlencode 'grant_type=password' \
  --data-urlencode "username=$API_USER" \
  --data-urlencode "password=$API_PASSWORD" \
  "$API_BASE/oauth2/token"

Além de validar a senha, o password grant aplica as regras de acesso do ambiente ao usuário.

Token exchange

O token exchange troca um JWT de origem por um token de acesso da API. O único subject_token_type aceito é urn:ietf:params:oauth:token-type:jwt.

Informe também qual provedor configurado no ambiente deve validar o JWT. Há duas formas:

read -r -s -p 'JWT de origem: ' SUBJECT_TOKEN; printf '\n'

curl -i \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
  --data-urlencode "subject_token=$SUBJECT_TOKEN" \
  --data-urlencode 'provider=provedor-jwt' \
  "$API_BASE/auth/token"

read -r -s -p 'JWT de origem: ' SUBJECT_TOKEN; printf '\n'

curl -i \
  -H 'X-STCPDIRECTLINK-JWT-ISSUER: provedor-jwt' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
  --data-urlencode "subject_token=$SUBJECT_TOKEN" \
  "$API_BASE/oauth2/token"

Regras do provedor:

o valor é o identificador do provedor cadastrado pelo administrador, e não precisa ser igual à claim iss do JWT;
se o campo provider e o header forem enviados, o campo provider prevalece;
o header X-STCPDIRECTLINK-JWT-ISSUER só é usado no token exchange e não autentica as rotas protegidas.

Token de impersonação

Integrações técnicas que precisam de uma credencial de longa duração podem usar um token de impersonação em vez de obter um token a cada execução.

O token é gerado pelo administrador do ambiente na interface de supervisão do Riversoft® STCP DirectLink, para um usuário técnico.
Ele carrega um identificador de sessão registrado para o usuário. A cada chamada, a API confere esse identificador; quando o token é substituído, o anterior deixa de ser aceito.
Use-o como token Bearer nas rotas protegidas: Authorization: Bearer <token>.

Atenção

Trate o token de impersonação como uma credencial privilegiada: guarde-o em um cofre de segredos, registre o responsável, a validade e o escopo, defina a rotação e não o reutilize entre ambientes. Ele não substitui o login interativo.

Resposta

Os dois grants devolvem o mesmo formato, com Cache-Control: no-store:

{
  "access_token": "<token>",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "https://api.exemplo.com/directlink/v2"
}

Campo	Descrição
`access_token`	Token a enviar no header `Authorization: Bearer` das rotas protegidas.
`issued_token_type`	Tipo do token emitido: token de acesso OAuth.
`token_type`	Forma de apresentação do token: `Bearer`.
`expires_in`	Validade do token, em segundos. Depende da configuração do ambiente; `3600` é apenas um exemplo.
`scope`	URI da API configurada no ambiente. Não representa uma lista de permissões.

Use o token como mostrado em Sessão e logout.

Erros

Quando o grant ou o token de origem não é aceito, a API responde 400 com um corpo no formato OAuth:

{
  "error": 400,
  "error_description": "<motivo>",
  "error_uri": "<uri-da-api>"
}

O campo error é numérico e identifica a condição reportada pela validação. Veja Códigos e eventos.