Autenticar-se na API
01Em uma frase #sec_36fbfa52
A API REVIEWIT aceita apenas um modo de autenticação — credenciais de cliente OAuth 2.0 — e conhece apenas máquinas: não existe nenhuma maneira de chamar a API em nome de uma pessoa.
02Uma identidade de máquina, nunca um utilizador #sec_ca4b0dd0
É uma escolha, não uma limitação a contornar. Uma decisão de recertificação tira todo o seu valor da sua imputabilidade a uma pessoa que olhou, julgou e que responde por ela. Uma identidade de máquina não pode suportar este tipo de decisão — portanto, a API não a autoriza, e o seu modo de autenticação torna-a impossível em vez de desaconselhada.
Concretamente: o único fluxo autorizado é client_credentials. Os fluxos que pressupõem um utilizador perante um navegador — código de autorização, palavra-passe, implícito — não estão ativados. Um cliente que os tente recebe uma recusa do servidor de tokens, não uma página de ligação.
03Obter um token #sec_02b8bbd6
O ponto de chamada é POST /connect/token. Ele espera os parâmetros padrão do fluxo de credenciais de cliente, em application/x-www-form-urlencoded.
POST /connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=VOTRE_CLIENT_ID
&client_secret=VOTRE_SECRET
&scope=campaigns.read reviews.readA resposta traz um token de acesso e a sua duração de vida.
{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600
}O token apresenta-se então em cada chamada, no cabeçalho Authorization.
Authorization: Bearer eyJhbGciOi...04O que dura um token #sec_4d63dc43
Sessenta minutos por defeito. O valor é um ajuste de implementação (Api:AccessTokenMinutes): a sua instalação pode tê-lo encurtado, nunca alongado sem que o editor o saiba.
Não solicite um token por chamada. O ponto de chamada de tokens tem o seu próprio limite de débito, mais baixo que o dos pontos de chamada de dados: sessenta por minuto. Um cliente que solicita um token a cada pedido esgota este limite bem antes do das dados, e fica bloqueado na autenticação enquanto o seu quota de leitura está intacto. Conserve o token e renove-o à medida que se aproxima da sua data de vencimento.
05O token é assinado, não é encriptado #sec_fb3f6e49
O token é um JWT assinado por um certificado. É legível: qualquer pessoa que o detenha pode ler o seu conteúdo — o identificador do cliente, os âmbitos concedidos, a data de expiração.
Isto é deliberado. A confidencialidade do transporte é assegurada por TLS; a encriptação do token não acrescentaria nada contra um atacante que já o detenha e tornaria ilegíveis as ferramentas de diagnóstico que ajudam a compreender uma recusa. Por outro lado, um token que vaza é um token utilizável: é tratado como um segredo até a sua expiração.
06Os âmbitos #sec_682200d2
Um âmbito é um direito de leitura ou escrita num domínio. O token só contém o que vocês pedem, e o cliente só obtém o que lhe foi concedido no registo: pedir mais não dá mais.
| Âmbito | O que abre |
|---|---|
| campaigns.read | As campanhas de recertificação |
| reviews.read | As revisões e as suas decisões |
| evidence.read | As provas assinadas |
| resources.read | Os recursos examinados |
| audit.read | O registo de auditoria |
| deletions.read | Os pedidos de eliminação |
| webhooks.manage | As subscrições aos eventos |
Existem quatro âmbitos sem que nenhum ponto de chamada ainda os exija: campaigns.manage, delegations.manage, collect.trigger e deletions.manage. Estão declarados porque o servidor de tokens os conhece, e um cliente pode solicitá-los; não abrem hoje nenhuma escrita, porque os pontos de chamada correspondentes ainda não existem. Pedi-los não quebra nada e não serve para nada.
07Peça o mínimo possível #sec_00fcfeab
Um âmbito concedido permanece concedido. Peça os que a integração precisa, não aqueles de que ela poderia precisar um dia: quando chegar o dia, um âmbito é adicionado numa linha, enquanto um token que vaza leva tudo o que ele continha.
08Verificar o que um token contém #sec_b38a4efa
Dois pontos de chamada de diagnóstico respondem à questão sem que seja necessário descodificar o token manualmente.
GET /api/v1/diagnostics/whoami diz que cliente vocês é e que âmbitos vocês tem. GET /api/v1/diagnostics/scope-probe diz se um âmbito dado passa a porta.
Servem para compreender uma recusa. Um 403 numa chamada de dados é diagnosticado em três segundos com o primeiro, e em três horas sem ele.
09A reter #sec_082cfbe9
Um modo de autenticação, aquele das máquinas. Um token de uma hora, conservado e reutilizado. Âmbitos solicitados com a maior precisão possível. E dois pontos de chamada de diagnóstico que respondem antes de abrir um ticket.