Autenticar con la API
01En una frase #sec_36fbfa52
La API REVIEWIT solo acepta un modo de autenticación — credenciales de cliente OAuth 2.0 — y solo conoce máquinas: no hay forma de llamar a la API en nombre de una persona.
02Una identidad de máquina, nunca un usuario #sec_ca4b0dd0
Es una elección, no una limitación que hay que eludir. Una decisión de recertificación obtiene todo su valor de su imputabilidad a una persona que ha mirado, juzgado y respondido. Una identidad de máquina no puede llevar este tipo de decisión — por lo tanto, la API no lo permite, y su modo de autenticación lo hace imposible en lugar de desaconsejarlo.
En la práctica: el único flujo autorizado es client_credentials . Los flujos que suponen un usuario frente a un navegador — código de autorización, contraseña, implícito — no están activados. Un cliente que los intente recibirá un rechazo del servidor de tokens, no una página de inicio de sesión.
03Obtener un token #sec_02b8bbd6
El punto de llamada es POST /connect/token . Espera los parámetros estándar del flujo de credenciales de cliente, en 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.readLa respuesta lleva un token de acceso y su duración.
{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600
}El token se presenta a continuación en cada llamada, en el encabezado Authorization.
Authorization: Bearer eyJhbGciOi...04Cuánto dura un token #sec_4d63dc43
Sesenta minutos por defecto. El valor es una configuración de implementación ( Api:AccessTokenMinutes ): su instalación puede haberlo acortado, nunca alargado sin que el editor lo sepa.
No solicite un token por llamada. El punto de llamada de tokens tiene su propio límite de caudal, más bajo que el de los puntos de llamada de datos: sesenta por minuto. Un cliente que vuelve a solicitar un token en cada solicitud agota este límite mucho antes que el de los datos, y se encuentra bloqueado en la autenticación mientras que su cuota de lectura está intacta. Conserve el token y renúevelo cuando se acerque a su vencimiento.
05El token está firmado, no está cifrado #sec_fb3f6e49
El token es un JWT firmado por un certificado. Es legible: cualquiera que lo tenga puede leer su contenido — el identificador del cliente, los alcances concedidos, la fecha de vencimiento.
Es deliberado. La confidencialidad del transporte está asegurada por TLS; el cifrado del token no añadiría nada contra un atacante que ya lo tiene, y haría ilegibles las herramientas de diagnóstico que ayudan a entender un rechazo. Por el contrario, un token que se filtra es un token utilizable: se trata como un secreto hasta su vencimiento.
06Los alcances #sec_682200d2
Un alcance es un derecho de lectura o escritura sobre un dominio. El token solo lleva lo que usted solicita, y el cliente solo obtiene lo que se le ha concedido en el registro: pedir más no da más.
| Alcance | Lo que abre |
|---|---|
| campaigns.read | Las campañas de recertificación |
| reviews.read | Las revisiones y sus decisiones |
| evidence.read | Las pruebas firmadas |
| resources.read | Los recursos examinados |
| audit.read | La pista de auditoría |
| deletions.read | Las solicitudes de eliminación |
| webhooks.manage | Las suscripciones a eventos |
Cuatro alcances existen sin que ningún punto de llamada los exija todavía: campaigns.manage, delegations.manage, collect.trigger y deletions.manage. Están declarados porque el servidor de tokens los conoce, y un cliente puede solicitarlos; no abren ninguna escritura hoy en día, porque los puntos de llamada correspondientes no existen todavía. Solicitarlos no rompe nada y no sirve para nada.
07Pida lo menos posible #sec_00fcfeab
Un alcance concedido sigue concedido. Pida aquellos que la integración necesita, no aquellos que podría necesitar algún día: cuando llegue el momento, se añade un alcance en una línea, mientras que un token que se filtra se lleva todo lo que llevaba.
08Verificar lo que lleva un token #sec_b38a4efa
Dos puntos de llamada de diagnóstico responden a la pregunta sin necesidad de decodificar el token a mano.
GET /api/v1/diagnostics/whoami dice qué cliente es usted y qué alcances lleva. GET /api/v1/diagnostics/scope-probe dice si un alcance dado pasa la puerta.
Sirven para entender un rechazo. Un 403 en una llamada de datos se diagnostica en tres segundos con el primero, y en tres horas sin él.
09Para recordar #sec_082cfbe9
Un modo de autenticación, el de las máquinas. Un token de una hora, conservado y reutilizado. Alcances solicitados al mínimo. Y dos puntos de llamada de diagnóstico que responden antes de que se abra un ticket.