Saltar a contenido

Autenticación OAuth para integraciones

¿Clave de API o OAuth?

Una clave de API autentica un sistema actuando por sí mismo, con los ámbitos que tú le des y sin usuario detrás. OAuth autentica una integración que actúa en nombre de un usuario concreto de HodeiShield — por ejemplo, una CLI que se conecta con tu propia sesión, o un asistente que necesita ver exactamente lo que tú ves y nada más. Si tu integración es un servicio que corre por su cuenta, usa una clave de API. Si es algo que un usuario autoriza para actuar como él, usa OAuth.

Qué obtiene tu integración

Un token OAuth de HodeiShield está atado a un usuario y un único inquilino: el usuario elige, en el momento de autorizar, en cuál de los inquilinos a los que tiene acceso quiere que tu integración opere. El token nunca ve más de un inquilino, y es de sólo lectura — el mismo catálogo de operaciones de /v1, nunca escritura. La única excepción es el ámbito de propuestas act:propose, sólo para el servidor MCP, que registra propuestas que una persona debe aprobar.

1. Descubrimiento

Antes de nada, tu integración necesita saber dónde emitir la petición de autorización. Dos caminos, según lo que ya tengas:

  • Si sólo conoces api.hodeishield.com: pide GET https://api.hodeishield.com/.well-known/oauth-protected-resource (sin autenticar). El documento (RFC 9728) te da authorization_servers, con la URL del servidor de autorización.
  • Si ya conoces el servidor de autorización: pide GET <emisor>/.well-known/oauth-authorization-server (RFC 8414). El documento describe todos los endpoints (autorización, token, revocación, registro), los tipos de concesión soportados y los ámbitos disponibles.

Una petición a /v1 sin credencial válida, o con una caducada, responde 401 con una cabecera WWW-Authenticate que apunta al primero de esos dos documentos — es la forma en que tu integración puede recuperarse de un token vencido sin tener la URL grabada a fuego.

2. Autorizar: con navegador (código + PKCE)

El camino estándar para cualquier integración con interfaz — una CLI, una app de escritorio, un asistente con navegador embebido.

  1. Genera un code_verifier aleatorio y su code_challenge (SHA-256, método S256 — es el único método aceptado; plain se rechaza).
  2. Abre el navegador del usuario en el endpoint de autorización con response_type=code, tu client_id, redirect_uri, code_challenge, code_challenge_method=S256 y los scope que necesites (ver más abajo).
  3. El usuario inicia sesión si hace falta, ve la pantalla de consentimiento — qué pide tu integración y en qué inquilino — y elige. HodeiShield redirige a tu redirect_uri con un código de un solo uso.
  4. Intercambia el código por un token en el endpoint de token, enviando el code_verifier. Recibes un token de acceso opaco (nunca lo parsees ni intentes decodificarlo: no es un JWT) y, si pediste offline_access, un token de refresco.

Si tu integración es un cliente público (sin forma de guardar un secreto — una CLI o una app de escritorio lo son casi siempre), regístrala primero por registro dinámico o pide que te den un client_id preregistrado.

3. Autorizar: sin navegador (device code)

Para una integración que corre en una máquina sin navegador — un servidor, un contenedor, una sesión SSH:

  1. Pide un código de dispositivo al endpoint correspondiente con tu client_id y los scope que necesites. Recibes un device_code (para tu uso), un user_code (corto, para mostrar al humano) y una URL de verificación.
  2. Muestra al usuario el user_code y la URL de verificación, los dos por separado — no sólo el enlace combinado verification_uri_complete. La página de verificación de HodeiShield no acepta un código pre-rellenado: el usuario siempre lo teclea a mano, a propósito, como prueba de que el código viene de su propia pantalla y no de un enlace que le mandó otra persona. Si tu cliente sólo muestra el enlace combinado, el usuario llegará a un campo vacío y tendrá que volver a leer el código en tu terminal de todos modos — muestra los dos desde el principio.
  3. El usuario abre la URL de verificación en cualquier navegador, inicia sesión, teclea el user_code, ve el mismo tipo de pantalla de consentimiento (qué pide tu integración, en qué inquilino) y aprueba.
  4. Mientras tanto, tu integración sondea el endpoint de token con el device_code, al intervalo indicado, hasta que el usuario aprueba (o el código caduca).

Ámbitos

Los ámbitos que un token de usuario puede pedir son de sólo lectura: la misma forma <módulo>:read de una clave de API (supply_risk:read, compliance.nis2:read, evidence:read…), más offline_access si quieres un token de refresco. Ningún otro ámbito de escritura existe en este catálogo — pedirlo no amplía nada, simplemente no se concede. La excepción es act:propose, que sólo se concede al servidor MCP: registra propuestas que una persona de tu organización aprueba en la consola.

El único ámbito que no es <módulo>:read es email: GET /v1/me devuelve user.email sólo a un token que lo lleve, y lo omite en caso contrario (la llamada nunca se rechaza por no tenerlo). La pantalla de consentimiento lo lista. Un cliente que quiera la dirección debe pedir email de forma explícita: el conjunto por defecto de un cliente registrado dinámicamente son los ámbitos de lectura más offline_access, sin email.

El documento de metadatos del servidor de autorización lista los ámbitos disponibles hoy; consulta la visión general de /v1 para lo que cada ámbito habilita.

Si omites scope (RFC 6749 §3.3), los dos flujos se comportan igual:

  • Con navegador (código + PKCE): recibes el conjunto de ámbitos registrado para tu cliente. Para la CLI de HodeiShield, y para un cliente autorregistrado que no lo acotó al registrarse, son todos los ámbitos de lectura más offline_access.
  • Device code: la CLI de HodeiShield recibe el mismo valor por defecto — todos los ámbitos de lectura más offline_access. Cualquier otro cliente tiene que nombrar sus ámbitos; una petición de dispositivo de otro cliente sin scope falla con invalid_scope. Un scope= vacío cuenta como omitido.

En ambos casos el usuario ve la lista completa en la pantalla de consentimiento o de verificación antes de aprobar. Pedir sólo lo que necesitas sigue siendo la mejor práctica.

Refresco

Con offline_access, el token de refresco te permite pedir un token de acceso nuevo sin que el usuario vuelva a pasar por el navegador — mientras el usuario siga teniendo acceso al inquilino que eligió. Un token de refresco usado dos veces (por ejemplo, por un almacenamiento duplicado) se trata como un indicio de robo y la concesión se corta.

Si la cuenta del usuario se suspende, se borra o se desactiva por inactividad, o se suspende su organización, el refresco (y cualquier canje pendiente de un código o de un device code) responde 400 con invalid_grant, y terminan todas las concesiones de ese usuario. Reactivar la cuenta no las devuelve: el usuario tiene que volver a autorizar tu integración.

Un inquilino por token — y qué pasa si cambia

El inquilino que el usuario eligió al autorizar se vuelve a comprobar en cada petición, no sólo al emitir el token. Si el usuario pierde el acceso a ese inquilino — se lo quitan, cambia de rol, la cuenta se suspende — tu siguiente petición con ese token responde 401, inmediatamente, sin esperar a que el token caduque por tiempo. No hay forma de pedir que un token cubra más de un inquilino, ni de cambiarlo sobre un token ya emitido: si tu integración necesita operar en otro inquilino, el usuario tiene que autorizar de nuevo y elegirlo.

Revocación

  • Desde HodeiShield: el usuario puede revocar el acceso de tu integración en cualquier momento desde Mi cuenta › Aplicaciones (ver más abajo). La revocación es inmediata: la siguiente petición con ese token, o con el de refresco asociado, responde 401.
  • Desde tu integración: si tu cliente soporta revocación (RFC 7009), envía el token al endpoint de revocación cuando el usuario cierre sesión en tu integración. Es una buena práctica, no un sustituto de la pantalla de HodeiShield — el usuario siempre puede revocar desde ahí aunque tu integración no llame nunca a revocación. Como exige RFC 7009, el endpoint responde 200 a un token desconocido, caducado o ya revocado, así que reintentar es seguro; un cliente público se autentica sólo con su client_id (none en revocation_endpoint_auth_methods_supported). Si tu cliente no consigue autenticarse — un client_id inexistente, un cliente deshabilitado o un cliente público que envía client_secret —, el endpoint responde 401 con invalid_client. Revocar un token termina todo su acceso: los tokens de acceso y de refresco y el consentimiento de esa integración en ese inquilino, obtenidos de la misma forma (inicio de sesión en el navegador o código de dispositivo). Los accesos de tu integración en otros inquilinos, u obtenidos de la otra forma, no se tocan, y enviar dos veces el mismo token tampoco los alcanza.

Cerrar sesión en HodeiShield no es lo mismo

Cerrar todas las sesiones de la consola de HodeiShield no revoca los tokens OAuth de tu integración. Son dos credenciales distintas con dos ciclos de vida distintos. Si necesitas cortar el acceso de una integración, hazlo desde Accesos de aplicaciones.

Errores

Toda petición a /v1 sin una credencial válida — sin token, un token caducado, uno revocado o uno que ya no cubre el ámbito o el inquilino que pide — responde 401, con WWW-Authenticate: Bearer resource_metadata="https://api.hodeishield.com/.well-known/oauth-protected-resource". Un token válido que no tiene el ámbito que la operación requiere responde 403, con el detalle de qué ámbito faltaba — a diferencia del 401, aquí sí sabes que el problema es de permisos, no de credencial. Un token válido cuyo inquilino no tiene una licencia en vigor (ninguna, suspendida, revocada o caducada) también responde 403, con details.code a LICENCE_INACTIVE: lo mismo ocurre con una clave de API del inquilino, y deja de ocurrir en cuanto se renueva la licencia. Durante el periodo de gracia de una licencia /v1 sigue respondiendo, porque todo lo que sirve es lectura. Un token cuyo ámbito nombra un módulo que el inquilino no tiene activo también recibe 403, con details.code MODULE_NOT_ENTITLED (ver Autenticación).

Clientes MCP y registro dinámico

Si tu integración es un cliente MCP (Model Context Protocol) — un asistente que se conecta al servidor MCP de HodeiShield — no necesitas que nadie te dé un client_id de antemano: puedes registrarte tú mismo contra el endpoint de registro dinámico, sin autenticar, siguiendo la especificación de autorización de MCP. HodeiShield sólo admite clientes públicos (sin secreto) con concesión de código y de refresco; cualquier otra forma de registro se rechaza. Tu redirect_uris debe ser una dirección loopback (una app nativa o una CLI, RFC 8252) o un host https:// que el operador de HodeiShield haya autorizado para clientes autorregistrados — una redirección https:// arbitraria se rechaza en el registro. Si tu integración es un cliente web alojado, pide a HodeiShield que añada tu host de retorno antes de registrarte. La pantalla de consentimiento marca estas integraciones como no verificadas — registradas por sí mismas, no por HodeiShield — y muestra el host al que redirigirá, para que el usuario pueda detectar un cliente que se hace pasar por otro.

Accesos de aplicaciones

En Mi cuenta › Aplicaciones, cada usuario ve cada acceso que conserva algún token válido: qué integración, en qué inquilino, cómo se obtuvo (inicio de sesión en el navegador o código de dispositivo), con qué ámbitos, desde cuándo y cuándo aceptó la API por última vez uno de sus tokens (registrado al minuto). Desde ahí puede revocar cualquier acceso — inmediato, y no requiere que la integración esté conectada en ese momento. Revocar sólo afecta a ese inquilino y a ese flujo: el acceso de la misma integración en otro inquilino, o obtenido de la otra forma, queda como estaba. Un acceso sin ningún token vivo (por ejemplo, tras cerrar sesión la integración) pero cuyo consentimiento del navegador sigue guardado aparece como «sin sesiones activas» para que también puedas retirarlo.

Algunos eventos de la cuenta terminan a la vez todos los accesos del usuario, sin ninguna acción en Aplicaciones: cambiar o restablecer la contraseña, y que un administrador revoque las sesiones de la persona. Los tokens de la integración dejan de funcionar y la persona vuelve a iniciar sesión desde la CLI o el cliente MCP. Retirar al usuario de un inquilino termina sólo los accesos ligados a ese inquilino. Cerrar sesión en la consola, revocar una sola sesión de la consola, quitar un passkey o cambiar un rol no terminan ningún acceso: revócalos desde Aplicaciones.