API de OAuth 2.0 Avanzado

Auris soporta varias extensiones avanzadas de OAuth 2.0 y OpenID Connect más allá del flujo estándar de Código de Autorización + PKCE. Estas capacidades están diseñadas para escenarios de autenticación empresariales y especializados:

• Autorización de Dispositivos (RFC 8628) — para dispositivos con entrada limitada como CLIs, smart TVs e IoT
• Intercambio de Tokens (RFC 8693) — para suplantación y delegación entre servicios
• DPoP (RFC 9449) — para tokens vinculados al remitente resistentes al robo de tokens
• CIBA (Autenticación Backchannel Iniciada por el Cliente) — para autenticación iniciada por un servicio backend sin interacción del navegador
• MFA Adaptativo / Evaluación de Riesgo — para autenticación escalonada dinámica basada en puntuación de riesgo

Todas las funciones avanzadas de OAuth deben habilitarse por aplicación en la Consola de Auris en Aplicaciones > [App] > OAuth Avanzado.

Autorización de Dispositivos (RFC 8628)

El Flujo de Autorización de Dispositivos permite que dispositivos que no pueden mostrar un navegador (CLIs, smart TVs, dispositivos IoT, quioscos) autentiquen usuarios. El dispositivo muestra un código de usuario corto y una URL de verificación; el usuario visita la URL en un dispositivo separado (teléfono, laptop) e ingresa el código para aprobar.

Cuerpo de la solicitud

{
  "client_id": "cli-app-client-id",
  "scope": "openid profile email"
}

Respuesta exitosa

{
  "ok": true,
  "data": {
    "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
    "user_code": "WDJB-MJHT",
    "verification_uri": "https://api.altovar.net/hosted/device",
    "verification_uri_complete": "https://api.altovar.net/hosted/device?user_code=WDJB-MJHT",
    "expires_in": 1800,
    "interval": 5
  }
}

Códigos de error

Sondeo de Tokens

Después de mostrar el código de usuario, el dispositivo sondea el endpoint de token en el intervalo especificado:

Cuerpo de la solicitud

{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "client_id": "cli-app-client-id"
}

Respuesta pendiente (el usuario aún no ha aprobado)

{
  "ok": false,
  "error": {
    "code": "AUTHORIZATION_PENDING",
    "message": "The user has not yet approved the request. Continue polling."
  }
}

Respuesta de ralentización (sondeo demasiado frecuente)

{
  "ok": false,
  "error": {
    "code": "SLOW_DOWN",
    "message": "Polling too frequently. Increase interval by 5 seconds."
  }
}

Respuesta exitosa (usuario aprobó)

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Códigos de error durante el sondeo

Página de Verificación del Usuario

Auris proporciona una página de verificación alojada en /hosted/device donde el usuario:

1. Ingresa el código de usuario de 8 caracteres (o llega a través de verification_uri_complete con el código pre-rellenado)
2. Se autentica usando cualquier método configurado (contraseña, SSO, magic link, 2FA)
3. Aprueba la solicitud de autorización del dispositivo
4. Ve una pantalla de confirmación y puede cerrar la pestaña

Intercambio de Tokens (RFC 8693)

El Intercambio de Tokens permite a un servicio intercambiar un token por otro — ya sea para suplantar a un usuario (actuar como él) o para delegar el acceso (actuar en su nombre mientras se conserva el sujeto original). Esto es esencial en arquitecturas de microservicios donde un API gateway necesita llamar a servicios downstream con diferentes scopes de token.

Cuerpo de la solicitud — Suplantación

La suplantación reemplaza el sujeto por completo. El token resultante tiene al usuario objetivo como claim sub. Úsalo cuando un administrador necesita actuar como un usuario para depuración.

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiJ9...",
  "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "exchange_type": "impersonation",
  "target_user_id": "usr_target123"
}

Cuerpo de la solicitud — Delegación

La delegación conserva el sujeto original y añade un claim act (actor) al token resultante. El servicio downstream puede ver tanto para quién es el token como quién está actuando en su nombre.

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiJ9...",
  "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "exchange_type": "delegation"
}

Respuesta exitosa — Suplantación

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "issuedTokenType": "urn:ietf:params:oauth:token-type:access_token",
    "tokenType": "Bearer",
    "expiresIn": 900
  }
}

El payload JWT del token de suplantación tendrá "sub": "usr_target123" con la identidad original del usuario que suplanta registrada en los registros de auditoría.

Respuesta exitosa — Delegación

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "issuedTokenType": "urn:ietf:params:oauth:token-type:access_token",
    "tokenType": "Bearer",
    "expiresIn": 900
  }
}

El payload JWT del token delegado incluye un claim act:

{
  "sub": "usr_original_user",
  "act": {
    "sub": "usr_acting_service"
  },
  "scope": "read:users"
}

Códigos de error

DPoP — Tokens Vinculados al Remitente (RFC 9449)

La Demostración de Prueba de Posesión (DPoP) vincula tokens a un cliente específico al requerir una prueba criptográfica con cada solicitud. Aunque un token vinculado a DPoP sea robado, no puede usarse sin la clave privada correspondiente.

Cómo Funciona DPoP

1. El cliente genera un par de claves (típicamente EC P-256 o RSA) y mantiene la clave privada segura.
2. En cada solicitud, el cliente crea un JWT de prueba DPoP firmado que contiene el método HTTP, la URL y un jti único.
3. El servidor valida la prueba, extrae la huella del JWK y vincula el token emitido a esa clave.
4. Las llamadas posteriores a la API deben incluir tanto el token DPoP como una nueva prueba DPoP firmada con la misma clave.

Solicitar Tokens Vinculados a DPoP

Incluye un encabezado DPoP con cualquier solicitud de token (login, actualización, intercambio de código de autorización):

POST /api/auth/token HTTP/1.1
Content-Type: application/json
DPoP: eyJhbGciOiJFUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiLi4uIiwieSI6Ii4uLiJ9fQ.eyJodG0iOiJQT1NUIiwiaHR1IjoiaHR0cHM6Ly95b3VyLWF1cmlzLWRvbWFpbi5jb20vYXBpL2F1dGgvdG9rZW4iLCJpYXQiOjE3MDg1MjEyMDAsImp0aSI6InVuaXF1ZS1pZC0xMjMifQ.signature

Estructura del JWT de prueba DPoP

Encabezado:

{
  "alg": "ES256",
  "typ": "dpop+jwt",
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "...",
    "y": "..."
  }
}

Payload:

{
  "htm": "POST",
  "htu": "https://api.altovar.net/api/auth/token",
  "iat": 1708521200,
  "jti": "unique-id-123",
  "nonce": "server-provided-nonce"
}

Respuesta de token con DPoP

Cuando se incluye una prueba DPoP, el token de respuesta está vinculado a DPoP:

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "tokenType": "DPoP",
    "expiresIn": 900
  }
}

Nota que tokenType es "DPoP" en lugar de "Bearer". El JWT del token de acceso contiene un claim cnf (confirmación) con la huella del JWK:

{
  "sub": "usr_abc123",
  "cnf": {
    "jkt": "JWK_THUMBPRINT_BASE64URL"
  }
}

Gestión de Nonce

El servidor puede requerir un nonce para protección contra repetición. Cuando lo hace, la respuesta incluye:

DPoP-Nonce: eyJhbGciOiJIUzI1NiJ9...

Incluye este nonce en las pruebas DPoP posteriores. Si llega una solicitud sin el nonce requerido, el servidor devuelve 400 con un error use_dpop_nonce y un nonce nuevo en el encabezado.

Códigos de error

CIBA — Autenticación Backchannel Iniciada por el Cliente

CIBA permite que un servicio backend inicie la autenticación de un usuario sin requerir que interactúe con una redirección del navegador. En su lugar, el usuario recibe una notificación (push, SMS o email) y aprueba la solicitud en su dispositivo.

Esto es útil para escenarios como la autenticación en centros de llamadas (“Le llamo de su banco, por favor apruebe el inicio de sesión en su teléfono”) o transacciones en puntos de venta.

Cuerpo de la solicitud

{
  "client_id": "backend-service-id",
  "client_secret": "backend-service-secret",
  "scope": "openid profile",
  "login_hint": "[email protected]",
  "binding_message": "Aprobar inicio de sesión para Pedido #12345",
  "requested_expiry": 300
}

Respuesta exitosa

{
  "ok": true,
  "data": {
    "auth_req_id": "ciba_req_abc123def456",
    "expires_in": 300,
    "interval": 5
  }
}

Modos de Notificación

CIBA soporta tres modos de entrega de notificaciones, configurados por aplicación:

Sondeo de Tokens CIBA

Para el modo poll, el servicio sondea el endpoint de token:

{
  "grant_type": "urn:openid:params:grant-type:ciba",
  "auth_req_id": "ciba_req_abc123def456",
  "client_id": "backend-service-id",
  "client_secret": "backend-service-secret"
}

Las respuestas de sondeo siguen el mismo patrón que la Autorización de Dispositivos:

• AUTHORIZATION_PENDING mientras se espera la aprobación del usuario
• SLOW_DOWN si se sondea demasiado frecuentemente
• EXPIRED_TOKEN si la solicitud expiró
• ACCESS_DENIED si el usuario rechazó la solicitud
• Respuesta completa de token al aprobarse

Códigos de error

Evaluación de Riesgo y MFA Adaptativo

Auris realiza una evaluación de riesgo automática en cada intento de autenticación. La puntuación de riesgo se calcula a partir de cinco factores ponderados y determina si se requieren pasos de autenticación adicionales (MFA escalonado).

Factores de Puntuación de Riesgo

Niveles de riesgo: LOW (0-30), MEDIUM (31-60), HIGH (61-80), CRITICAL (81-100).

Cuando la puntuación de riesgo supera los umbrales configurados, Auris desafía automáticamente al usuario con MFA escalonado antes de emitir tokens. Los claims acr (Referencia de Clase de Contexto de Autenticación) y amr (Referencias de Métodos de Autenticación) en el JWT reflejan el nivel de autenticación real alcanzado.

Parámetros de consulta

Respuesta exitosa

{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "risk_abc123",
        "userId": "usr_def456",
        "score": 72,
        "level": "HIGH",
        "factors": {
          "ipReputation": { "score": 85, "isVpn": true, "isProxy": false },
          "deviceTrust": { "score": 50, "isNewDevice": true },
          "geoAnomaly": { "score": 90, "distance": 5200, "timeSinceLastLogin": 1800 },
          "behavior": { "score": 60, "unusualTime": true },
          "actionSensitivity": { "score": 75 }
        },
        "actionTaken": "step_up_mfa",
        "ipAddress": "203.0.113.42",
        "country": "CN",
        "city": "Beijing",
        "createdAt": "2025-02-18T03:45:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 156, "totalPages": 8 }
  }
}

Respuesta exitosa

{
  "ok": true,
  "data": [
    {
      "id": "rule_abc123",
      "name": "Bloquear rangos VPN conocidos",
      "condition": {
        "field": "ipReputation.isVpn",
        "operator": "equals",
        "value": true
      },
      "action": "block",
      "scoreModifier": 40,
      "isActive": true,
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ]
}

Cuerpo de la solicitud

{
  "name": "Requerir MFA para nuevos países",
  "condition": {
    "field": "geoAnomaly.isNewCountry",
    "operator": "equals",
    "value": true
  },
  "action": "step_up_mfa",
  "scoreModifier": 30,
  "isActive": true
}

Campos de condición disponibles: ipReputation.isVpn, ipReputation.isProxy, ipReputation.isDatacenter, deviceTrust.isNewDevice, geoAnomaly.isNewCountry, geoAnomaly.distance, behavior.unusualTime, behavior.failedAttempts.

Operadores disponibles: equals, not_equals, greater_than, less_than, contains, in.

Respuesta exitosa

{
  "ok": true,
  "data": {
    "id": "rule_def456",
    "name": "Requerir MFA para nuevos países",
    "condition": {
      "field": "geoAnomaly.isNewCountry",
      "operator": "equals",
      "value": true
    },
    "action": "step_up_mfa",
    "scoreModifier": 30,
    "isActive": true,
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Cuerpo de la solicitud

{
  "name": "Requerir MFA para nuevos países (actualizado)",
  "scoreModifier": 50,
  "isActive": true
}

Respuesta exitosa

{
  "ok": true,
  "data": { "deleted": true }
}

ACR y AMR en Tokens

Cuando el MFA adaptativo activa la autenticación escalonada, el JWT emitido incluye los claims acr y amr que los servicios downstream pueden usar para verificar la solidez de la autenticación:

{
  "sub": "usr_abc123",
  "acr": "urn:auris:acr:mfa",
  "amr": ["pwd", "otp"],
  "iat": 1708521200,
  "exp": 1708522100
}

Los servidores de recursos pueden requerir un nivel mínimo de acr para operaciones sensibles verificando los claims del JWT antes de procesar la solicitud.

Referencia de Permisos

Relacionado

• DPoP (Prueba de Posesión) — Cómo funciona la validación de prueba DPoP
• Flujo de Autorización de Dispositivos — Detalles del protocolo de flujo de dispositivos
• CIBA (Autenticación Backchannel) — Arquitectura del protocolo CIBA
• Intercambio de Tokens (RFC 8693) — Detalles del protocolo de intercambio de tokens
• Implementar DPoP — Integración DPoP paso a paso
• Flujo de Autorización de Dispositivos — Guía de integración del flujo de dispositivos
• Guía CIBA — Tutorial de integración CIBA
• Intercambio de Tokens — Guía de suplantación y delegación
• OAuth2 Avanzado — Configurar funciones avanzadas de OAuth2 desde la Consola