Documentación

Primeros pasos

Authagonal proporciona a cada inquilino un servidor OIDC totalmente compatible con estándares. Cada inquilino obtiene su propia URL de emisor, documento de descubrimiento y endpoints de token — sin infraestructura compartida entre inquilinos. Puedes pasar de cero a un flujo de inicio de sesión funcional en menos de 5 minutos.

Crear un inquilino

Regístrate en authagonal.io y elige un slug para tu inquilino. El slug se convierte en tu dominio de emisor: {slug}.authagonal.io. Después de crear tu cuenta, verifica tu dirección de correo electrónico para activar el inquilino.

Elige un slug único para tu inquilino durante el registro

Registrar un cliente

Navega a Clientes en la barra lateral del portal y haz clic en Crear. Ingresa un clientId y un clientName para tu aplicación. Luego configura al menos una URI de redirección — aquí es donde se envían los usuarios después de autenticarse. Por ejemplo: https://app.example.com/callback.

Registrar un nuevo cliente OAuth en el portal

Tu primer inicio de sesión

La forma más rápida de integrar es con oidc-client-ts, una biblioteca de cliente OIDC ligera para aplicaciones JavaScript y TypeScript.

import { UserManager } from 'oidc-client-ts';

const mgr = new UserManager({
  authority: 'https://acme.authagonal.io',
  client_id: 'my-app',
  redirect_uri: 'https://app.example.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

// Redirect to login
mgr.signinRedirect();

// On callback page
const user = await mgr.signinRedirectCallback();
console.log(user.profile); // { sub, email, name, ... }

Si prefieres un enfoque mínimo sin biblioteca, puedes usar el flujo estándar de código de autorización OAuth 2.0 con fetch simple:

// 1. Redirect the user to the authorization endpoint
const authorizeUrl = new URL('https://acme.authagonal.io/connect/authorize');
authorizeUrl.searchParams.set('client_id', 'my-app');
authorizeUrl.searchParams.set('redirect_uri', 'https://app.example.com/callback');
authorizeUrl.searchParams.set('response_type', 'code');
authorizeUrl.searchParams.set('scope', 'openid profile email');
authorizeUrl.searchParams.set('code_challenge', codeChallenge);
authorizeUrl.searchParams.set('code_challenge_method', 'S256');
window.location.href = authorizeUrl.toString();

// 2. On the callback page, exchange the code for tokens
const res = await fetch('https://acme.authagonal.io/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: new URLSearchParams(window.location.search).get('code')!,
    redirect_uri: 'https://app.example.com/callback',
    client_id: 'my-app',
    code_verifier: codeVerifier,
  }),
});

const tokens = await res.json();
// tokens.id_token, tokens.access_token, tokens.refresh_token

La página de inicio de sesión predeterminada para tu inquilino

Panel de control

El panel de control del portal te ofrece una visión en tiempo real de tu inquilino. Presenta las métricas más importantes — crecimiento de usuarios, actividad de autenticación y navegación rápida a todas las funcionalidades del portal.

Resumen

En la parte superior del panel de control verás un mensaje de bienvenida junto con tu recuento total actual de usuarios. Debajo, un gráfico de Usuarios activos diarios muestra un historial de 7 días de usuarios únicos que se autenticaron cada día, dándote un pulso rápido sobre las tendencias de interacción.

La pantalla principal del panel de control con gráfico de DAU y resumen de actividad

Métricas de actividad

El panel de métricas de actividad muestra cuatro tarjetas de estadísticas que resumen eventos clave de autenticación:

• Inicios de sesión exitosos — flujos de autenticación completados en total
• Inicios de sesión fallidos — credenciales incorrectas, cuentas bloqueadas o rechazos por política
• Usuarios activos — usuarios únicos que se autenticaron en el período seleccionado
• Operaciones SCIM — eventos de aprovisionamiento de usuarios y grupos desde IdPs conectados

Usa los filtros de rango de tiempo para alternar entre 24 horas, 3 días, 7 días y 30 días. Todas las tarjetas de estadísticas y gráficos se actualizan para reflejar la ventana seleccionada.

Métricas de actividad con rango de tiempo configurable

Navegación rápida

Debajo del panel de métricas, las tarjetas de navegación enlazan directamente a cada funcionalidad principal: Clientes, Usuarios, Grupos, Roles, SSO, SCIM, Marca y Configuración. Cada tarjeta muestra una breve descripción para que los nuevos miembros del equipo puedan orientarse rápidamente.

Clientes

Los clientes OAuth representan las aplicaciones que autentican usuarios a través de tu inquilino. Cada cliente tiene su propia configuración de URIs de redirección, alcances, tipos de concesión, duraciones de tokens y política de MFA.

Lista de clientes

La página de Clientes muestra una tabla con todos los clientes registrados. Cada fila muestra el clientId, nombre para mostrar, tipos de concesión permitidos como insignias de colores y si PKCE está habilitado. Haz clic en cualquier fila para abrir el editor de configuración completo.

Lista de clientes con insignias de tipo de concesión e indicadores de PKCE

Crear un cliente

Haz clic en Crear cliente para registrar una nueva aplicación. Necesitas proporcionar dos campos:

• clientId — un identificador único para el cliente (por ejemplo, my-spa)
• clientName — un nombre para mostrar legible por humanos

Registrar un nuevo cliente OAuth

Eliminar un cliente

Para eliminar un cliente, abre la configuración del cliente y haz clic en el botón Eliminar cliente en la parte inferior de la página. Se te pedirá confirmar antes de que el cliente sea eliminado permanentemente. Todas las sesiones activas y tokens del cliente eliminado se invalidan inmediatamente.

Referencia de configuración de cliente

Cada cliente tiene un conjunto completo de opciones de configuración organizadas en varias secciones.

Configuración general

URIs

Los campos de URI utilizan una entrada de etiquetas — escribe un valor y presiona Enter o coma para añadirlo. Haz clic en la X de cualquier etiqueta para eliminarla.

Campos de entrada de etiquetas para configurar URIs

Alcances y tipos de concesión

Duraciones de tokens

Configurar duraciones de tokens por cliente

URIs de logout

Los clientes pueden registrar URIs de logout tanto back-channel como front-channel. Ambas son opcionales — configura las que coincidan con cómo tu aplicación limpia su sesión.

Política de MFA

Cada cliente puede anular la política de MFA a nivel de inquilino con una configuración por cliente. El menú desplegable de política de MFA ofrece tres opciones:

Anulación de política de MFA por cliente

SSO empresarial

El SSO empresarial permite que tus clientes traigan su propio proveedor de identidad. Authagonal soporta tanto la federación SAML 2.0 como OIDC con enrutamiento basado en dominio, para que los usuarios sean dirigidos automáticamente al IdP correcto según su dirección de correo electrónico.

Enrutamiento SSO basado en dominio

Conexiones SAML 2.0

Para crear una conexión SAML, navega a la página de SSO y selecciona la pestaña SAML. Proporciona lo siguiente:

Cuando guardas la conexión, Authagonal obtiene el documento de metadatos e importa el certificado de firma del IdP, la URL del endpoint SSO y el formato del identificador de nombre. Los metadatos se actualizan periódicamente para incorporar las rotaciones de certificados.

Crear una conexión SSO SAML 2.0

Conexiones OIDC

Para crear una conexión de federación OIDC, selecciona la pestaña OIDC y proporciona:

Crear una conexión de federación OIDC

Enrutamiento de dominio

El enrutamiento de dominio redirige automáticamente a los usuarios al proveedor de identidad correcto según el dominio de su correo electrónico. Cuando un usuario ingresa su correo en la página de inicio de sesión, Authagonal verifica si la parte del dominio (por ejemplo, acme.com) coincide con alguna conexión SSO configurada. Si coincide, el usuario es redirigido de forma transparente al IdP de su organización.

El enrutamiento de dominio mapea dominios de correo electrónico a proveedores de identidad

Aprovisionamiento JIT

Por defecto, cuando un usuario inicia sesión a través de SSO por primera vez y no existe ya en tu inquilino, Authagonal crea su cuenta automáticamente (aprovisionamiento Just-In-Time). Esto se puede deshabilitar por conexión marcando Deshabilitar aprovisionamiento JIT al crear o editar la conexión.

Cuando el aprovisionamiento JIT está deshabilitado, solo los usuarios que han sido pre-aprovisionados — a través de SCIM, la página de Usuarios del portal o la API — pueden iniciar sesión a través de esa conexión. Los usuarios desconocidos reciben un error access_denied y son dirigidos a contactar a su administrador.

Usuarios

La página de Usuarios te permite gestionar todos los usuarios finales en tu inquilino. Puedes buscar usuarios, ver sus detalles, crear nuevas cuentas y ver cómo fue aprovisionado cada usuario.

Búsqueda y paginación

La barra de búsqueda admite filtrado por dirección de correo electrónico o ID de usuario. La búsqueda tiene un retardo de 300ms para que los resultados se actualicen mientras escribes sin sobrecargar la API. Los resultados están paginados a 50 usuarios por página — usa los controles de navegación en la parte inferior de la tabla para moverte entre páginas.

Tabla de usuarios

La tabla de usuarios muestra las siguientes columnas para cada usuario:

La lista de usuarios con barra de búsqueda y paginación

Crear usuarios

Haz clic en Crear usuario para añadir un nuevo usuario local. El formulario requiere:

Crear un nuevo usuario local

Idioma preferido

Cada usuario tiene un idioma preferido que controla tanto su interfaz alojada como los correos transaccionales que Authagonal le envía (verificación, restablecimiento de contraseña, bienvenida y más). Puedes definirlo al crear un usuario y cambiarlo en cualquier momento desde su página de detalle. Si un usuario no tiene un idioma preferido definido, Authagonal recurre al inglés. El selector ofrece todos los idiomas soportados: inglés, alemán, francés, español, portugués, vietnamita y chino simplificado.

Definir el idioma preferido de un usuario en su página de detalle

Detalle del usuario

Haz clic en cualquier fila de la lista de usuarios para abrir su página de detalle. Desde ahí puedes editar datos de perfil, gestionar roles, restablecer MFA, revisar atributos personalizados y eliminar al usuario.

Perfil

Edita correo electrónico, nombre/apellidos, teléfono, empresa, ID externo y el indicador de activo del usuario. Los cambios de correo deben permanecer únicos en el inquilino; la API devuelve email_in_use si ya está en uso.

Roles

Asigna y retira roles definidos en la página Roles. La pertenencia a roles se incluye en los tokens ID y de acceso cuando el cliente tiene activado includeRolesInTokens.

Autenticación multifactor

Consulta todas las credenciales MFA registradas para el usuario — aplicación autenticadora (TOTP), WebAuthn/passkeys y códigos de recuperación — cada una con marcas de tiempo de registro y último uso. Elimina credenciales individuales o restablece todo MFA. Restablecer obliga al usuario a volver a registrarse en el próximo inicio de sesión.

Atributos personalizados

Datos clave/valor arbitrarios asociados al usuario. Las claves deben ser únicas. Los atributos se exponen vía la API de perfil de usuario y SCIM, y pueden mapearse a reclamaciones del token de acceso configurando los userClaims de un ámbito personalizado.

Organización

La organización a la que pertenece este usuario. Es un identificador de texto libre propio, emitido como reclamación org_id en sus tokens y en /connect/userinfo bajo el ámbito profile. Authagonal nunca lo deriva: lo define tu aplicación de aprovisionamiento, el token SCIM que creó al usuario, o tú mismo a mano aquí.

El enlace junto al campo lista a todos los que comparten ese valor, y el mismo filtro está disponible en la API como GET /api/v1/users?organizationId=. Úsalo para saber quién pertenece a un cliente final concreto sin paginar todo el directorio.

Eliminar usuario

Elimina permanentemente al usuario y todas sus credenciales MFA. Escribe el correo del usuario para confirmar — no hay deshacer.

Grupos

Los grupos te permiten organizar usuarios e incluir la membresía de grupo en los tokens. Los grupos pueden crearse manualmente en el portal o aprovisionarse automáticamente a través de SCIM desde un proveedor de identidad externo.

Lista de grupos

La página de Grupos muestra todos los grupos en tu inquilino con la siguiente información:

Lista de grupos con indicadores de origen

Crear un grupo

Haz clic en Crear grupo e ingresa un displayName para el grupo. Los nombres de grupo deben ser descriptivos y únicos dentro de tu inquilino (por ejemplo, "Engineering", "Billing Admins", "Beta Testers").

Detalle del grupo y miembros

Haz clic en cualquier grupo para abrir la vista de detalle. Aquí puedes ver todos los miembros actuales y gestionar la membresía:

• Añadir miembros — Ingresa un ID de usuario para añadir un usuario al grupo.
• Eliminar miembros — Haz clic en el botón de eliminar junto a cualquier miembro para eliminarlo individualmente.

Gestionar la membresía del grupo en la vista de detalle

Grupos en tokens

Cuando includeGroupsInTokens está habilitado en un cliente, el token de ID incluye una reclamación groups que contiene las membresías de grupo del usuario. Cada entrada incluye el id y name del grupo:

{
  "sub": "user-123",
  "email": "[email protected]",
  "groups": [
    { "id": "grp-001", "name": "Engineering" },
    { "id": "grp-002", "name": "Beta Testers" }
  ]
}

Roles

Los roles soportan el control de acceso basado en roles (RBAC) en tu aplicación. Define roles en Authagonal, asígnalos a usuarios y usa la reclamación roles en los tokens para aplicar la autorización en la lógica de tu aplicación.

Gestionar roles

La página de Roles muestra una tabla con todos los roles definidos con edición en línea. Cada rol tiene:

Crear un rol

Haz clic en Crear rol y proporciona un nombre y una descripción. Los nombres de los roles deben ser concisos y seguir una convención de nomenclatura consistente en tu aplicación (por ejemplo, minúsculas con guiones: billing-admin).

Edición en línea

Los roles soportan edición en línea directamente en la tabla. Haz clic en el icono de lápiz en cualquier rol para entrar en modo de edición — los campos de nombre y descripción se vuelven editables. Modifica los valores y luego haz clic en el icono de marca de verificación para guardar. Los cambios entran en vigor inmediatamente.

Eliminar un rol

Haz clic en el icono de eliminar en cualquier rol para eliminarlo. Se te pedirá confirmar antes de que el rol sea eliminado permanentemente. Eliminar un rol no invalida retroactivamente los tokens existentes — el rol estará ausente de los nuevos tokens emitidos después de la eliminación.

Edición en línea de roles en la tabla de roles

Roles en tokens

Los roles asignados a un usuario se incluyen como una reclamación roles en el token de ID. Tu aplicación puede leer esta reclamación para tomar decisiones de autorización:

{
  "sub": "user-123",
  "email": "[email protected]",
  "roles": ["admin", "billing-admin"]
}

Aprovisionamiento SCIM

SCIM 2.0 (System for Cross-domain Identity Management) permite el aprovisionamiento automático de usuarios y grupos desde proveedores de identidad empresariales como Okta, Azure AD, OneLogin y JumpCloud. Una vez configurado, las cuentas de usuario y las membresías de grupo se sincronizan automáticamente desde el IdP ascendente a tu inquilino de Authagonal.

Sincronización del ciclo de vida de usuarios SCIM con aprovisionamiento descendente

Pasos de configuración

Sigue estos pasos para habilitar el aprovisionamiento SCIM para un cliente:

1. Selecciona la aplicación cliente — Elige el cliente OAuth con el que se asociará el aprovisionamiento SCIM.
2. Genera un token SCIM — Proporciona una descripción y un período de expiración en días, luego genera el token.
3. Copia el token inmediatamente — El valor del token sin procesar se muestra solo una vez. Cópialo antes de cerrar el diálogo.
4. Configura tu IdP — En la configuración SCIM de tu proveedor de identidad, ingresa la URL base y el token bearer.
5. Prueba la sincronización de usuarios — Activa una sincronización de prueba desde tu IdP y verifica que los usuarios aparezcan en el portal de Authagonal.

URL base de SCIM

Configura tu proveedor de identidad con la siguiente URL base:

https://{slug}.authagonal.io/scim/v2

Reemplaza {slug} con el slug de tu inquilino.

Página de configuración SCIM con generación de tokens

Gestión de tokens

Los tokens SCIM autentican las solicitudes de aprovisionamiento desde tu IdP. Puedes gestionar múltiples tokens por cliente:

Para revocar un token, haz clic en el botón Revocar junto a él. Los tokens revocados permanecen visibles en la lista con fines de auditoría pero dejan de aceptar solicitudes inmediatamente.

Gestión de tokens con indicadores de tokens activos y revocados

Probar la conectividad

Verifica que tu integración SCIM está funcionando consultando el endpoint ServiceProviderConfig:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://acme.authagonal.io/scim/v2/ServiceProviderConfig

Una respuesta exitosa devuelve un documento JSON que describe las funcionalidades SCIM soportadas, incluyendo operaciones masivas, filtrado y capacidad de cambio de contraseña.

Qué puede ver un token

Un token SCIM solo ve los usuarios y grupos que él mismo aprovisionó. Leer, actualizar o eliminar un usuario creado por otro conector responde 404, el listado devuelve solo los propios y la membresía de un grupo solo puede nombrar usuarios aprovisionados por ese mismo conector. Las cuentas creadas de cualquier otra forma, por un administrador, por registro de autoservicio o por aprovisionamiento justo a tiempo mediante SSO, son completamente invisibles para SCIM.

Ese límite es por cliente OAuth, no por token. Dos tokens emitidos sobre el mismo cliente OAuth son una sola identidad con dos secretos, y cada uno puede modificar lo que creó el otro. Da a cada conector que no confíe en los demás su propio cliente OAuth. externalId tiene el mismo alcance, así que dos conectores pueden usar cada uno ext-001 para personas distintas sin colisionar.

Desaprovisionamiento

DELETE /scim/v2/Users/{id} desactiva la cuenta y la marca como eliminada. El registro se conserva, tal como permite RFC 7644, pero responde 404 a cualquier operación posterior y se omite de los listados. Sus inscripciones MFA y sus membresías de grupo se purgan, su asignación de externalId se libera y todos los tokens emitidos se revocan, de modo que el acceso termina de inmediato y no en la siguiente expiración de token.

Si más adelante se vuelve a contratar a la misma persona y se crea de nuevo, recibe un nuevo ID de usuario. Los identificadores nunca se reutilizan: el ID es el sujeto de cada token que has emitido, así que reutilizarlo daría de forma silenciosa al nuevo empleado el historial del titular anterior en todas las aplicaciones que confían en él.

Etiquetar usuarios sincronizados con una organización

SCIM no ofrece a un conector ninguna forma de indicar cuál de tus clientes finales está sincronizando. El SCIM básico no define ningún atributo de organización, así que una creación de usuario simple te da el nombre y el correo de la persona y nada sobre a quién pertenece. Si varios clientes finales aprovisionan en tu inquilino, sus usuarios llegan indistinguibles.

Es el token el que lo responde, no la solicitud. Cuando creas un token SCIM, asigna a Organización un identificador propio. Cada usuario aprovisionado mediante ese token queda etiquetado con él, y a partir de entonces se emite como reclamación org_id en sus tokens. Emite un token por cada cliente final sobre el mismo cliente OAuth y sus usuarios sincronizados quedan correctamente atribuidos sin necesidad de registrar un cliente OAuth para cada uno. Déjalo en blanco y los usuarios quedan sin etiquetar, que es como se comportaba cada token antes de que esto existiera.

La etiqueta se aplica cuando se crea el usuario y nunca en una actualización posterior, de modo que una sincronización incremental rutinaria no puede mover de forma silenciosa una cuenta existente. Si además ejecutas una aplicación de aprovisionamiento, la etiqueta explícita del token prevalece: una respuesta de /try solo rellena una organización que todavía está vacía.

Esquemas soportados

Implementamos los esquemas básicos User y Group de SCIM 2.0 (RFC 7643). Los atributos de usuario soportados son userName, name.givenName, name.familyName, displayName, emails, active, externalId y preferredLanguage / locale.

La extensión enterprise user no está implementada, por lo que department, manager, employeeNumber, costCenter, division y organization se aceptan y se ignoran en lugar de almacenarse, tanto en la creación como en el reemplazo y en PATCH. Entra y Okta mapean algunos de ellos por defecto, así que no necesitas quitarlos de tu mapeo de atributos. Para atribuir un usuario a uno de tus clientes finales, define la organización en el token SCIM: el atributo enterprise organization lo afirma el proveedor de identidad de tu cliente final, y deliberadamente no se convierte en la org_id del usuario.

Ámbitos de OAuth

Los ámbitos permiten a los clientes solicitar porciones específicas de los datos o permisos de un usuario. Authagonal admite tanto los ámbitos estándar de OIDC como los ámbitos personalizados que definas para tus API.

Ámbitos integrados

Ámbitos personalizados

Define tus propios ámbitos en la página Ámbitos. Cada ámbito describe un permiso o recurso que un cliente puede solicitar (por ejemplo, billing.read, orders.write).

Reclamaciones personalizadas en los tokens

Las reclamaciones personalizadas tienen dos mitades. La fuente son los datos por usuario: cada AuthUser tiene un diccionario customAttributes que puedes poblar desde el Portal (Usuarios → usuario → Atributos personalizados), vía SCIM o mediante un hook de aprovisionamiento TCC. La liberación es por ámbito: la lista userClaims de cada ámbito nombra las claves que pueden salir del servidor.

Cuando un cliente solicita ámbitos, Authagonal recorre los ámbitos concedidos, une sus listas userClaims y emite solo esas claves de los customAttributes del usuario. Las claves desconocidas se descartan silenciosamente — un cliente no puede leer un atributo adivinando su nombre. Las reclamaciones OIDC estándar (sub, email, name, etc.) siguen la especificación y no están sujetas a la lista de permitidos.

# 1. On the user (Portal → Users → {user} → Custom Attributes)
department = "engineering"
employee_id = "E-1042"
seat_tier = "enterprise"

# 2. On a custom scope (Portal → Scopes → projects.read)
name        = "projects.read"
userClaims  = ["department", "seat_tier"]   # <-- whitelist

# 3. Client requests scope=openid projects.read
# Decoded access token (relevant fields only):
{
  "sub": "u-9b…",
  "scope": "openid projects.read",
  "department": "engineering",
  "seat_tier":  "enterprise"
  // employee_id is NOT emitted — it's not in the whitelist for any granted scope.
}

Asignar ámbitos a clientes

Añade los ámbitos permitidos en la pestaña Clientes → Ámbitos y Concesiones. Un cliente solo puede solicitar ámbitos que se le hayan concedido; los ámbitos desconocidos se rechazan con invalid_scope.

Marca

Personaliza la apariencia de las páginas de inicio de sesión de tu inquilino. La configuración de marca te permite hacer coincidir la experiencia de autenticación con la identidad visual de tu producto — desde logotipos y colores hasta personalizaciones avanzadas de CSS.

Apariencia

Configuración de apariencia con vista previa de color en vivo

Información de contacto

Controles de la página de inicio de sesión

Controla qué elementos aparecen en la página de inicio de sesión de tu inquilino:

Ejemplo de página de inicio de sesión con marca personalizada aplicada

CSS personalizado

Para un control total sobre la apariencia de la página de inicio de sesión, proporciona la URL de un archivo CSS en tus ajustes de marca. El archivo se carga después de los estilos por defecto, por lo que tus reglas tienen prioridad.

Modo oscuro

La app de inicio de sesión incluye temas claro, oscuro y del sistema. Los usuarios eligen desde un conmutador en la página de login; la elección se mantiene entre sesiones. Cuando está en system, la SPA sigue prefers-color-scheme en tiempo real.

Los valores claros se declaran en :root; las anulaciones oscuras están limitadas a .dark. El branding del inquilino mediante customCssUrl siempre prevalece — tus colores se mantienen sin importar el tema del usuario.

Configuración

Configura las políticas de seguridad, webhooks y configuración del entorno a nivel de inquilino. Estas configuraciones se aplican globalmente a todos los clientes a menos que se anulen a nivel de cliente.

Política de contraseñas

Define los requisitos de complejidad de contraseña para todos los usuarios en tu inquilino:

Configuración de la política de contraseñas

Política de MFA

La política de MFA a nivel de inquilino establece el comportamiento predeterminado de autenticación multifactor. Los clientes individuales pueden anular esta configuración.

Sesión y bloqueo

Controla la duración de la sesión y el comportamiento de bloqueo de cuenta:

Configuración de sesión y bloqueo

Webhooks

Los webhooks te permiten reaccionar a eventos de autenticación en tiempo real. Dos eventos (onUserAuthenticated, onTokenIssued) son aplicables — por defecto se disparan de forma asíncrona y no bloquean al usuario, pero puedes activar la aplicación por evento para que una respuesta no 2xx o un cuerpo {"allow": false} rechace la acción. El resto de eventos son notificaciones — siempre fire-and-forget, nunca bloquean.

Configuraciones adicionales de webhooks:

Configuración de eventos de webhook

Verificar webhooks

Una vez configurada cualquier URL de webhook, Authagonal genera un secreto de firma por inquilino (un valor whsec_… que se muestra en modo de solo lectura en Ajustes → Webhooks). Cada entrega saliente lleva una cabecera X-Authagonal-Signature: t=<unix>,v1=<hex>, donde v1 es HMAC-SHA256(secret, "{t}.{body}") calculado sobre el cuerpo crudo de la solicitud. Vuelve a calcularlo en tu endpoint y compáralo en tiempo constante para confirmar que la solicitud realmente provino de Authagonal y no fue manipulada — y rechaza las entregas cuyo t sea demasiado antiguo para bloquear repeticiones.

import crypto from 'node:crypto';

// rawBody MUST be the exact bytes Authagonal sent — verify before any JSON re-serialization.
function verifyAuthagonalWebhook(signatureHeader, rawBody, signingSecret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const { t, v1 } = parts;

  // Replay protection: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Ventana de mantenimiento

Establece una ventana de mantenimiento preferida para operaciones disruptivas como rotaciones de certificados y actualizaciones de infraestructura. Elige una hora UTC (0-23) — el portal también muestra la hora equivalente en tu zona horaria local para mayor comodidad.

Registro y acceso

Quién puede convertirse en usuario de tu inquilino, y en qué condiciones puede iniciar sesión.

Retención de usuarios inactivos

De forma opcional, desactiva y después elimina las cuentas que han dejado de usarse, para que un directorio no acumule identidades inactivas para siempre. Ambas están desactivadas mientras no las configures, y la eliminación es permanente.

Exportación de auditoría y copias de seguridad remotas

Dos formas de sacar tus datos de forma programada en lugar de bajo petición. La exportación de auditoría envía cada día completo de eventos de auditoría a una URL que tú indiques, firmada para que puedas verificar que viene de nosotros, para alimentar un SIEM o un archivo de cumplimiento. Las copias de seguridad remotas mandan copias de tus copias diarias y semanales a un destino que controlas tú, sin autenticación, con autenticación básica o con un token Bearer. Ambas se configuran en Configuración y son tuyas, independientes de las copias que guardamos nosotros.

Entorno sandbox

El entorno sandbox es un clon completo de tu inquilino de producción, disponible en una URL separada. Úsalo para probar cambios de configuración, integraciones SSO y endpoints de webhook sin afectar a los usuarios activos.

El sandbox es accesible en {slug}-sandbox.authagonal.io.

Controles del entorno sandbox

Facturación

Gestiona tu suscripción y facturación a través de la página de Facturación del portal. Esta página te ofrece un resumen de tu plan actual y proporciona acceso al portal de facturación de Stripe para gestionar métodos de pago, facturas y cambios de plan.

Información de suscripción

La página de facturación muestra los detalles de tu suscripción actual de un vistazo. Verás una insignia de estado indicando el estado de tu suscripción — active, trialing, past_due, canceled o unpaid — junto con el nombre de tu plan, el período de facturación actual (fechas de inicio y fin), y si tu suscripción está configurada para cancelarse al final del período actual.

Gestionar suscripción

Haz clic en el botón Gestionar suscripción para abrir el portal de facturación de Stripe en una nueva ventana. Desde ahí puedes actualizar tus métodos de pago, ver y descargar facturas, cambiar tu plan o cancelar tu suscripción.

Si aún no existe una suscripción, se muestra un botón de Configurar facturación en su lugar, que te guía a través de la selección de un plan y la introducción de datos de pago.

La página de facturación muestra los detalles de tu suscripción actual y proporciona acceso a Stripe

Dominios personalizados

Sirve tus páginas de autenticación desde tu propio dominio (por ejemplo, auth.tudominio.com) en lugar del predeterminado {slug}.authagonal.io. Los dominios personalizados brindan a tus usuarios una experiencia de autenticación fluida y con tu marca.

Añadir un dominio

Ingresa el nombre de host que deseas usar en el formulario de añadir dominio (por ejemplo, auth.tudominio.com). Una vez añadido, el dominio aparecerá en tu lista de dominios con un estado pending_verification.

Verificación DNS

Crea un registro CNAME apuntando tu dominio a {slug}.authagonal.io. Una vez que el registro DNS esté configurado, haz clic en Verificar para comprobar la propagación DNS.

auth.yourdomain.com.  CNAME  acme.authagonal.io.

Certificados TLS

Una vez que tu dominio esté verificado, necesitas un certificado TLS para que los usuarios puedan conectarse de forma segura a través de HTTPS. Authagonal soporta dos opciones:

Automático (cert-manager) — Authagonal aprovisiona y renueva certificados TLS automáticamente usando cert-manager. Esta es la opción recomendada para la mayoría de los usuarios. No se requiere configuración adicional.

Traer el propio (BYO) — Sube tu propio certificado y clave privada en formato PEM. Esta opción es útil si tu organización requiere certificados de una autoridad de certificación específica. Se hace seguimiento de la expiración del certificado para que puedas renovarlo antes de que caduque.

Estado del dominio

Cada dominio muestra una insignia de estado indicando su estado actual: pending_verification (DNS aún no confirmado), verified (DNS confirmado, TLS pendiente), active (totalmente operativo) o failed (problema de configuración detectado).

La lista de dominios muestra cada dominio personalizado y su estado actual

Sube tu propio certificado TLS y clave privada en formato PEM

Configuración de correo

Configura cómo tu inquilino envía correos transaccionales — verificación, restablecimiento de contraseña y notificaciones MFA. Elige entre el remitente compartido predeterminado, un dominio personalizado verificado mediante Resend o tu propio servidor SMTP.

Correos localizados

Los correos transaccionales se envían en el idioma preferido del destinatario. Los correos de verificación, restablecimiento de contraseña, cuenta existente, bienvenida, facturación e invitación de administrador están plantillados en siete idiomas: inglés, alemán, francés, español, portugués, vietnamita y chino simplificado. Cuando no existe una plantilla para el idioma del destinatario, el correo recurre al inglés.

El idioma se resuelve a partir de la preferencia almacenada del destinatario en el momento del envío. Esa preferencia puede provenir de varios lugares:

• Registro y alta — capturado del idioma que el usuario eligió en las pantallas de inicio de sesión alojadas.
• La página de Usuarios del portal — definida por un administrador al crear o editar un usuario.
• El aprovisionamiento SCIM — mapeado desde el preferredLanguage del IdP cuando los usuarios se sincronizan mediante SSO.
• La página de cuenta de autoservicio — elegida por el propio usuario en /login/account.

Proveedores de correo

Identidad del remitente

El correo y el nombre del remitente se comparten en todos los modos de proveedor. El correo del remitente es obligatorio; si el nombre está vacío, se usa el nombre del inquilino.

Dominio personalizado de Resend

Verifica tu dominio de envío con Resend una sola vez y úsalo como dirección de remitente para este inquilino. Los registros DNS TXT (SPF, DKIM) se proporcionan en la página de Dominios; Resend los valida automáticamente.

SMTP personalizado

Usa tu propio servidor SMTP — útil para relays internos, proveedores no cubiertos por Resend o fijación regulatoria.

Dominio de envío personalizado

Con el proveedor Resend puedes registrar tu propio dominio para que los correos provengan de tu marca (por ejemplo, [email protected]) en lugar de @authagonal.io.

1. Ve a Ajustes → Correo y selecciona el proveedor Dominio personalizado de Resend.
2. Introduce tu nombre de dominio y haz clic en Registrar.
3. Añade los registros DNS mostrados (DKIM, SPF y return path) al DNS de tu dominio.
4. Haz clic en Comprobar verificación — cuando el DNS se propague (normalmente 1–10 minutos), el estado del dominio cambiará a verificado.

Pruebas

Usa el botón Enviar correo de prueba en Ajustes → Correo para verificar tu configuración. Se enviará un correo de prueba a tu dirección de administrador usando los ajustes guardados.

Registro de auditoría

El Registro de auditoría proporciona un registro de solo lectura de todas las acciones administrativas realizadas en tu inquilino. Cada cambio realizado a través del portal o la API se captura con contexto completo, dándote un rastro completo para cumplimiento y resolución de problemas.

Columnas del registro

Acciones registradas

Las siguientes acciones administrativas se registran en el registro de auditoría:

El registro de auditoría proporciona un registro completo de todas las acciones administrativas

Copias de seguridad

Authagonal realiza copias de seguridad automáticas de los datos de tu inquilino cada hora. Las copias incluyen todos los usuarios, grupos, roles, clientes, conexiones SSO, tokens SCIM, marca y ajustes. Puedes ver el historial y descargar la última copia completa desde la página de Copias de seguridad.

Cómo funcionan las copias

• Una copia completa se ejecuta una vez al día, capturando todas las tablas del shard de almacenamiento de tu inquilino.
• Las copias incrementales se ejecutan cada hora, capturando solo las filas que cambiaron desde la última copia.
• Las copias se almacenan en Azure Blob Storage con la misma identidad administrada que usa tu inquilino.
• Los registros eliminados se rastrean mediante tombstones y se incluyen en las copias para completitud de auditoría.

Descargar copias

Haz clic en "Descargar última" para obtener un archivo ZIP con la copia completa más reciente fusionada con todas las copias incrementales posteriores. Cada tabla se exporta como un archivo JSONL (un objeto JSON por línea).

Aplicaciones de aprovisionamiento

Las aplicaciones de aprovisionamiento son tus propios servicios. Authagonal las llama cada vez que se crea un usuario, para que puedan crear una cuenta, asignar una licencia, decidir a qué organización pertenece el usuario o rechazar el registro por completo.

Cómo funciona

Cuando se crea un usuario, Authagonal llama a la URL de callback de tu aplicación de aprovisionamiento siguiendo el patrón TCC (Try/Confirm/Cancel). Todas las aplicaciones deben aceptar en la fase Try antes de confirmar ninguna, de modo que varios sistemas posteriores puedan ponerse de acuerdo, o uno pueda vetar, sin dejar cuentas a medio crear.

Cuándo se ejecuta el aprovisionamiento

El aprovisionamiento se ejecuta en todas las rutas que crean un usuario, no solo en el registro autoservicio. Las combinaciones de aplicación y usuario ya aprovisionadas se omiten, por lo que una aplicación ve cada usuario una sola vez.

La solicitud Try

Authagonal envía este JSON por POST a <code>{callbackUrl}/try</code>. Los campos sin valor se omiten en lugar de enviarse como null.

El caso habitual que conviene prever es el de un usuario que llega por SSO: todavía no tiene organización, y federated_connection te dice de cuál de tus clientes procede.

{
  "transactionId": "8f14e45fceea167a5a36dedd4bea2543",
  "userId": "0f6b1c8e-3d2a-4f51-9e77-2c1a4b5d6e7f",
  "email": "[email protected]",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "customAttributes": {
    "federated_connection": "acme-okta"
  }
}

La respuesta Try

Tu aplicación responde con un 200 y un cuerpo JSON. El cuerpo no es solo un acuse de recibo: es la forma en que una aplicación posterior asigna la organización y los atributos que acaban en los tokens del usuario.

{
  "approved": true,
  "organizationId": "org_acme",
  "customAttributes": { "org_role": "member" }
}

Etiquetar a los usuarios con la organización correcta

Decide la organización aquí, en un solo lugar, en vez de en cada ruta de creación. Un usuario de SSO lleva federated_connection, que identifica la conexión que lo autenticó y, por tanto, al cliente, y sigue siendo correcto cuando un mismo cliente federa varios dominios de correo. Un usuario invitado no tiene conexión, así que identifícalo por la invitación que emitiste. Ambas rutas llegan a /try antes de que el usuario exista, de modo que una sola lógica las cubre y no hay dos reglas que puedan divergir.

// POST {callbackUrl}/try
app.post('/provisioning/try', async (req, res) => {
  const { email, customAttributes } = req.body;

  // An SSO user carries the connection that vouched for them. That is the
  // customer, and it stays right when one customer has several domains.
  const connection = customAttributes?.federated_connection;

  const org = connection
    ? await orgByConnection(connection)
    : await orgByPendingInvite(email);

  if (!org) return res.json({ approved: false, reason: 'No organization for this user' });

  // Stamped on the user and emitted as org_id on every token from now on.
  res.json({ approved: true, organizationId: org.id });
});

Añadir una aplicación de aprovisionamiento

Para añadir una aplicación de aprovisionamiento, proporciona un nombre, una URL de callback y una clave API opcional. La clave API se envía como token Bearer en el encabezado Authorization de cada solicitud de webhook, permitiendo que tu aplicación autentique las solicitudes de Authagonal.

Pruebas

Haz clic en Probar junto a cualquier aplicación de aprovisionamiento para enviar una solicitud de prueba a tu URL de callback. Los resultados de la prueba muestran el código de estado HTTP y el cuerpo de la respuesta, ayudándote a verificar que tu aplicación está recibiendo y procesando webhooks correctamente.

Prueba las aplicaciones de aprovisionamiento para verificar la entrega y manejo de respuestas del webhook

Límites del plan

El número máximo de aplicaciones de aprovisionamiento es configurable por inquilino, con un límite predeterminado de 6. Este límite puede ser ajustado por un administrador si tu flujo de trabajo requiere objetivos de aprovisionamiento adicionales.

Equipo

La página de Equipo gestiona los administradores del portal — las personas que pueden acceder y configurar tu inquilino a través del portal de gestión. Todos los miembros del equipo tienen acceso administrativo completo a todos los aspectos de la configuración de tu inquilino.

Lista de administradores

La lista de administradores muestra el nombre, dirección de correo electrónico y la fecha en que fue añadido cada miembro del equipo. Un indicador "Tú" se muestra junto a la fila del usuario actual para que puedas identificar fácilmente tu propia cuenta.

Invitar administradores

Para invitar a un nuevo miembro del equipo, proporciona su dirección de correo electrónico, nombre y una contraseña temporal (mínimo 8 caracteres). El usuario invitado inicia sesión con la contraseña temporal y debe cambiarla en el primer inicio de sesión.

Campos de invitación

Las invitaciones de administrador crean un usuario totalmente aprovisionado — sin viaje de ida y vuelta por correo.

Eliminar administradores

Haz clic en Eliminar junto a cualquier miembro del equipo para revocar su acceso. Se muestra un diálogo de confirmación antes de que la eliminación se finalice. No puedes eliminarte a ti mismo — siempre debe haber al menos un administrador en el equipo.

Gestiona los administradores del portal desde la página de Equipo

Soporte

Abre un ticket de soporte con el equipo de Authagonal sin salir del portal. Cada ticket es una conversación con hilo, así que tú y nuestro equipo estáis siempre alineados, desde el primer reporte hasta la resolución.

Tus tickets

La página de soporte lista todos los tickets que has abierto, con la actividad más reciente primero. Usa la insignia de estado para ver de un vistazo qué está esperando por ti y qué está esperando por nosotros.

Tus tickets de soporte con asunto, estado, prioridad y última actividad

• Cada fila muestra el asunto, el estado actual (abierto, pendiente, resuelto o cerrado), la prioridad y la hora de la última actividad.
• Haz clic en Nuevo ticket para abrir uno y dale un asunto, una prioridad y tu primer mensaje.
• Las insignias de estado con código de color facilitan revisar la lista en busca de tickets que necesitan tu atención.

El hilo de un ticket

Al abrir un ticket se muestra la conversación completa. Las respuestas se publican en orden y los nuevos mensajes de nuestro equipo aparecen sin recargar la página.

El hilo de un ticket entre tú y el equipo de Authagonal

• Los mensajes con hilo entre tú y el equipo de Authagonal se muestran en orden cronológico.
• Responde en línea y adjunta archivos para compartir registros, capturas de pantalla o configuración.
• El hilo se actualiza en vivo, así que una respuesta de nuestro equipo aparece en cuanto se envía.
• Si en su lugar respondes al correo de notificación, tu mensaje se añade al hilo automáticamente.

Mesa de soporte para tus usuarios

Aparte del soporte que recibes de nosotros, Authagonal puede gestionar una mesa de soporte para tus usuarios finales. Ellos abren tickets desde las páginas de su cuenta en el host con la marca de tu propio inquilino, y tu equipo los responde desde el portal.

Existe porque las personas que no pueden iniciar sesión son justo las que no pueden llegar a una herramienta de soporte que exige iniciar sesión. La mesa está junto a las pantallas de inicio de sesión, así que un usuario bloqueado sigue teniendo una vía, y cada ticket llega ya vinculado a una cuenta real de tu directorio y no a la dirección que alguien haya escrito.

Cómo activarla

Abre Configuración en el portal y habilita el portal de soporte. Tus usuarios no ven nada hasta que lo hagas.

Qué ven tus usuarios

Los usuarios con sesión iniciada tienen un área de soporte en las páginas de su cuenta en el host de tu inquilino, con tu marca. Pueden abrir un ticket, ver todo lo que han abierto y responder en un hilo. Las respuestas de tu equipo también llegan por correo electrónico, así que el usuario no tiene que estar comprobándolo.

Con los tickets anónimos habilitados, alguien que no puede iniciar sesión todavía puede abrir uno. Indica una dirección de correo y su mensaje, y recibe a cambio un enlace privado a la conversación. Ese enlace es la única vía de entrada, así que trátalo como una credencial: es imposible de adivinar, y cualquiera que lo tenga puede leer ese hilo concreto y responder en él.

La bandeja de entrada del operador

Tu equipo responde desde Bandeja de soporte en el portal. Es un lugar distinto de tus propios tickets con nosotros, y está disponible para el rol tenant:support y superiores, así que puedes dar a un agente acceso a la mesa sin darle el resto del portal.

Los usuarios escriben en su propio idioma

Un ticket se almacena en el idioma en que lo escribió el usuario, y cada persona del hilo lo lee en el suyo. Tu agente ve el mensaje traducido al idioma de su portal, el usuario ve tu respuesta traducida al suyo, y el texto original se conserva siempre al lado. El idioma se detecta a partir del primer mensaje y queda fijado al ticket. Las traducciones se calculan una vez por idioma y se reutilizan, así que un hilo largo no se vuelve a traducir entero.

Zonas horarias

Un ticket registra la zona horaria desde la que lo abrió el usuario. Cada mensaje muestra entonces su hora local junto a la tuya, de modo que una respuesta a las 14:32 se lee como las 02:32 que en realidad eran para la persona que la esperaba. No se muestra nada cuando la zona es desconocida, por ejemplo en un ticket que llegó por correo, o cuando coincide con la tuya.

Webhooks

Configura una URL de webhook de soporte para recibir los eventos de tickets en el momento en que ocurren, para lanzar una alerta o replicar los tickets en tu propio sistema. Las cargas van firmadas para que puedas verificar que vienen de nosotros.

Importar y migrar

Migra un sistema de identidad existente a tu inquilino de Authagonal. Se admiten dos fuentes — Duende IdentityServer (una base de datos SQL Server) y Auth0 (la Management API). Cada una ejecuta una vista previa de solo lectura para que revises exactamente qué se copiará antes de confirmar.

Importación desde Duende IdentityServer

Migra clientes, ámbitos, usuarios y roles desde una base de datos SQL Server de Duende IdentityServer existente a tu inquilino de Authagonal. La importación se ejecuta en dos fases — vista previa y commit — para que puedas revisar lo que se copiará antes de realizar cualquier cambio.

Qué se importa

El importador lee de la ConfigurationDb de Duende y de las tablas de ASP.NET Identity y escribe las filas mapeadas en tu inquilino. Se omiten artefactos de corta duración como persisted grants, device codes y claves de firma.

Vista previa antes del commit

Pega tu cadena de conexión a ConfigurationDb / IdentityDb de Duende y haz clic en Ejecutar vista previa. La vista previa abre una conexión de solo lectura y cuenta cada fila que se importaría — no se escribe nada.

• Recuentos por entidad de clientes, ámbitos, usuarios, roles y asignaciones de roles.
• Avisos de sobrescritura cuando el inquilino de destino ya tiene clientes, roles o ámbitos coincidentes.
• Avisos de tablas desconocidas y columnas no mapeadas para que sepas qué se descartará.

Panel de vista previa con recuentos y avisos

Hashes de contraseña

Duende almacena contraseñas con ASP.NET Identity V3 (PBKDF2). El PasswordHasher de Authagonal verifica ese formato directamente y rehashea al formato nativo en el primer inicio de sesión exitoso — los usuarios conservan su contraseña sin flujo de restablecimiento.

Reconciliación de ID de usuario

Si un usuario que ya está en este inquilino tiene el mismo correo que un registro entrante, la importación rota el userId de esa cuenta al sub de origen antes de importar, de modo que los roles, inicios de sesión y reclamaciones importados se vinculan a la cuenta existente y las apps que ya referencian al usuario por su sub de origen siguen resolviéndose tras la migración. La contraseña y el perfil existentes de la cuenta se conservan; los roles de origen se fusionan encima. La vista previa enumera cada cuenta que se reconciliará antes de confirmar.

Ejecutar la importación

Haz clic en Iniciar importación tras revisar la vista previa. La fase de commit escribe clientes, ámbitos, usuarios, roles y referencias de inicio de sesión externo en los stores del inquilino. Las filas duplicadas de clientId, scope name, email y role name se omiten — el importador es seguro de re-ejecutar.

Qué no se importa

• Persisted grants, device codes, server-side sessions — de corta duración, se regeneran automáticamente.
• Claves de firma — Authagonal emite sus propias claves por tenant.
• Columnas y tablas personalizadas — cualquier cosa fuera del esquema estándar de Duende se emite como aviso para que sepas que los datos se descartaron.
• Clientes deshabilitados — se importan deshabilitados; reactívalos desde la página Clientes cuando estés listo.

Importar desde Auth0

Conecta Authagonal con la Management API de tu inquilino de Auth0 y trae tus aplicaciones, APIs, roles, usuarios y conexiones empresariales. Los IDs de usuario y aplicación importados se conservan, de modo que las referencias existentes a sub y client_id siguen resolviéndose tras el cambio.

Qué necesitarás

Crea una aplicación Machine-to-Machine en Auth0 autorizada para la Management API, con estos ámbitos de lectura: read:users, read:clients, read:resource_servers, read:roles, read:connections, read:client_grants. Pega su dominio, client ID y client secret en el formulario de importación — solo se usan para la importación.

Qué se importa

Contraseñas

La Management API de Auth0 nunca devuelve los hashes de contraseña. Si dispones de la exportación masiva de contraseñas asistida por soporte de Auth0 (NDJSON), proporciónala — los hashes bcrypt se importan tal cual y tus usuarios conservan sus contraseñas sin restablecimiento. Ese archivo también incluye el conjunto completo de usuarios, eliminando el límite de 1.000 usuarios del listado de la API de Auth0. Sin él, los usuarios se importan como perfiles y establecen una nueva contraseña en el primer inicio de sesión.

Referencia de API

Cada inquilino expone un servidor OIDC compatible con estándares en https://{slug}.authagonal.io. Todos los endpoints siguen las especificaciones OAuth 2.0 y OpenID Connect. Esta referencia cubre todos los endpoints con los que tu aplicación puede necesitar interactuar.

Flujo de código de autorización con PKCE

Descubrimiento OIDC y JWKS

El documento de descubrimiento permite que las bibliotecas de cliente OIDC se configuren automáticamente. No se requiere autenticación para ninguno de los endpoints.

GET /.well-known/openid-configuration

Devuelve el documento de configuración del proveedor OpenID. La respuesta incluye todos los metadatos que tu cliente necesita para interactuar con este inquilino.

GET /.well-known/openid-configuration/jwks

Devuelve el JSON Web Key Set utilizado para verificar las firmas de tokens. La respuesta contiene un array keys con claves públicas RSA, cada una incluyendo los campos kty, use, kid, alg, n y e.

curl https://acme.authagonal.io/.well-known/openid-configuration

Endpoint de autorización

GET /connect/authorize

Inicia un flujo de código de autorización. El usuario debe tener una sesión activa o será redirigido a la página de inicio de sesión. En caso de éxito, el usuario es redirigido de vuelta a tu aplicación con un código de autorización.

Respuesta exitosa: Redirección 302 a redirect_uri con los parámetros de consulta code y state.

Respuesta de error: Redirección 302 con los parámetros de consulta error, error_description y state.

Pushed Authorization Requests (PAR)

RFC 9126. En lugar de poner cada parámetro de autorización en la URL, tu cliente los envía por POST a /connect/par con autenticación normal y recibe una request_uri opaca y de corta duración. El navegador visita luego /connect/authorize?client_id=...&request_uri=... — nada más queda en el historial del navegador, los logs del servidor ni los encabezados Referer, y el servidor ya ha verificado la integridad de los parámetros bajo autenticación de cliente.

POST /connect/par

La autenticación de cliente es la misma que en /connect/token: HTTP Basic con client_id/client_secret o credenciales codificadas en el formulario. Los clientes públicos publican sin secreto. El cuerpo lleva los mismos parámetros que enviarías normalmente a /connect/authorize; request_uri en sí es rechazado (encadenar un PAR está prohibido por §2.1 de la especificación). Devuelve 201 Created.

Respuesta

En la llamada posterior GET /connect/authorize?client_id=…&request_uri=…, todos los demás parámetros se toman de la carga útil enviada y cualquier parámetro de consulta extra se ignora. El client_id en la llamada de autorización debe coincidir con el cliente que envió la solicitud. Una vez consumida (o cuando transcurre expires_in), la request_uri se elimina del almacén.

# 1. Push parameters (server returns request_uri + expires_in)
curl -X POST https://acme.authagonal.io/connect/par \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "response_type=code" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "scope=openid profile email" \
  -d "state=$(openssl rand -hex 16)" \
  -d "code_challenge=YOUR_CODE_CHALLENGE" \
  -d "code_challenge_method=S256"

# 2. Send the user to /authorize with only client_id + request_uri
# https://acme.authagonal.io/connect/authorize?client_id=my-app&request_uri=urn:ietf:params:oauth:request_uri:abc123...

Endpoint de token

POST /connect/token

Intercambia credenciales por tokens. Las solicitudes deben usar Content-Type: application/x-www-form-urlencoded. La autenticación del cliente puede proporcionarse a través de HTTP Basic auth (Authorization: Basic base64(client_id:client_secret)) o como parámetros del cuerpo del formulario (client_id + client_secret).

Concesión de código de autorización

Concesión de token de actualización

Concesión de credenciales de cliente

Concesión de código de dispositivo

Respuesta del token:

curl -X POST https://acme.authagonal.io/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "client_id=my-app" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

Endpoint UserInfo

GET /connect/userinfo

Devuelve reclamaciones sobre el usuario autenticado. Requiere un token de acceso válido con el alcance openid.

curl https://acme.authagonal.io/connect/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Introspección de token (RFC 7662)

POST /connect/introspect

Valida un token y devuelve sus metadatos. Requiere credenciales de cliente (autenticación Basic o parámetros del cuerpo del formulario).

Respuesta de token activo:

Respuesta de token inactivo: { "active": false }

curl -X POST https://acme.authagonal.io/connect/introspect \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN"

Revocación de token (RFC 7009)

POST /connect/revocation

Revoca un token emitido previamente. Requiere credenciales de cliente.

El endpoint siempre devuelve 200 OK, incluso para tokens inválidos o ya revocados, según la especificación RFC 7009.

Autorización de dispositivo (RFC 8628)

POST /connect/deviceauthorization

Inicia el flujo de autorización de dispositivo para dispositivos con restricciones de entrada (CLIs, smart TVs, dispositivos IoT). El dispositivo muestra un código al usuario, quien luego aprueba la solicitud en un dispositivo separado con navegador.

Respuesta:

Flujo de aprobación: El usuario visita la verification_uri, ingresa el user_code y aprueba la solicitud. Mientras tanto, el dispositivo consulta periódicamente el endpoint de token con el device_code.

Códigos de error de consulta periódica:

curl -X POST https://acme.authagonal.io/connect/deviceauthorization \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-cli" \
  -d "scope=openid profile email"

Cierre de sesión / Logout

GET POST /connect/endsession

Cierra la sesión del usuario actual, activa el cierre de sesión por canal trasero a todos los clientes con un BackChannelLogoutUri registrado, y revoca todas las concesiones.

Si se proporciona un post_logout_redirect_uri válido que coincida con una URI registrada, el usuario recibe una redirección 302. De lo contrario, una respuesta JSON confirma que la sesión ha sido finalizada.

Referencia de API SCIM 2.0

Authagonal soporta el protocolo SCIM 2.0 para el aprovisionamiento automatizado de usuarios y grupos. Los proveedores de identidad como Okta, Azure AD y OneLogin pueden usar esta API para mantener tu inquilino de Authagonal sincronizado con tu directorio corporativo.

URL base: https://{slug}.authagonal.io/scim/v2

Autenticación: Todas las solicitudes requieren un token Bearer. Genera un token SCIM en el portal bajo Settings > SCIM Provisioning.

Encabezados comunes:

Los endpoints de lista soportan paginación a través de los parámetros de consulta startIndex (basado en 1) y count (máx. 200), y filtrado a través del parámetro filter (por ejemplo, userName eq "[email protected]").

Usuarios

GET /scim/v2/Users — Lista usuarios con paginación y filtrado opcionales.

GET /scim/v2/Users/{id} — Obtiene un usuario individual por su ID de usuario de Authagonal.

POST /scim/v2/Users — Crea un nuevo usuario. Devuelve 201 Created.

PUT /scim/v2/Users/{id} — Reemplazo completo de un recurso de usuario. Todos los campos deben proporcionarse.

PATCH /scim/v2/Users/{id} — Actualización parcial usando SCIM PatchOp.

DELETE /scim/v2/Users/{id} — Eliminación suave del usuario (desactiva la cuenta y revoca todos los tokens). Devuelve 204 No Content.

curl -X POST https://acme.authagonal.io/scim/v2/Users \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[email protected]",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "displayName": "Jane Smith",
    "active": true,
    "externalId": "ext-12345"
  }'

Grupos

GET /scim/v2/Groups — Lista todos los grupos con paginación y filtrado opcionales.

GET /scim/v2/Groups/{id} — Obtiene un grupo individual por ID, incluyendo su lista de miembros.

POST /scim/v2/Groups — Crea un nuevo grupo. Devuelve 201 Created.

PUT /scim/v2/Groups/{id} — Reemplazo completo de un recurso de grupo (incluyendo su lista de miembros).

PATCH /scim/v2/Groups/{id} — Actualización parcial para añadir o eliminar miembros del grupo.

DELETE /scim/v2/Groups/{id} — Eliminación permanente del grupo. Devuelve 204 No Content.

curl -X PATCH https://acme.authagonal.io/scim/v2/Groups/GROUP_ID \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "add",
        "path": "members",
        "value": [
          { "value": "USER_ID_1" },
          { "value": "USER_ID_2" }
        ]
      }
    ]
  }'

API del portal (automatización)

La API del portal permite que tu propio backend automatice todo lo que puedes hacer en el portal — gestionar usuarios, clientes, grupos, roles, ámbitos, conexiones SSO y configuración — usando una credencial de máquina a máquina. Es la misma API que llama la interfaz del portal.

URL base: https://portal-api.<your-domain>/api/v1. Las solicitudes se autentican con un token de acceso Bearer; el inquilino se toma del token, no de la URL.

Crear una credencial de API

En el portal, abre Clients → Create API credential, elige un nivel de acceso y dale un nombre. Authagonal genera un cliente OAuth client_credentials configurado para la API del portal y devuelve un ID de cliente y un secreto.

Niveles de acceso

Obtener un token

Intercambia la credencial por un token de acceso en el endpoint de token de tu inquilino de administración — https://<your-tenant>.<your-domain>/connect/token — y luego envía el token como un encabezado Bearer a la API del portal. Los tokens son válidos durante una hora.

# 1. Exchange the credential for an access token (your tenant's token endpoint)
curl -X POST https://acme.authagonal.io/connect/token \
  -d grant_type=client_credentials \
  -d client_id=api-3f2a... \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=tenant:admin

# Response: { "access_token": "ey...", "token_type": "Bearer", "expires_in": 3600 }

# 2. Call the Portal API with the access token
curl https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoints

Todas las rutas son relativas a la URL base y requieren un token de acceso Bearer. El ámbito junto a cada grupo es el nivel de acceso mínimo que necesitan las credenciales. Los endpoints de listado aceptan los parámetros de consulta startIndex y count.

GET/api/v1/clients— Listar clientes OAuth.

GET/api/v1/clients/{id}— Obtener un cliente por su ID.

POST/api/v1/clients— Crear un cliente. Devuelve el ID del cliente y, para clientes confidenciales, un secreto de un solo uso.

PUT/api/v1/clients/{id}— Actualizar un cliente (URIs de redirección, tipos de concesión, duración de tokens, requisitos PKCE/PAR).

DELETE/api/v1/clients/{id}— Eliminar un cliente.

POST/api/v1/clients/api-credential— Generar una credencial de API del Portal de máquina a máquina.

GET/api/v1/users— Listar usuarios. Admite count, search (prefijo de correo o nombre), organizationId para filtrar por una organización y after para paginación por cursor.

GET/api/v1/users/count— Número total de usuarios del inquilino.

GET/api/v1/users/stats/mfa— Estadísticas de inscripción en MFA.

GET/api/v1/users/{id}— Obtener un usuario.

POST/api/v1/users— Crear un usuario con correo y contraseña.

PUT/api/v1/users/{id}— Actualizar un usuario (perfil, correo, estado activado/bloqueado, organizationId).

DELETE/api/v1/users/{id}— Eliminar un usuario.

GET/api/v1/users/{id}/mfa— Get a user's enrolled MFA methods.

DELETE/api/v1/users/{id}/mfa— Reset a user's MFA enrollment.

GET/api/v1/roles— Listar roles.

POST/api/v1/roles— Crear un rol.

DELETE/api/v1/roles/{id}— Eliminar un rol.

POST/api/v1/roles/assign— Asignar un rol a un usuario.

POST/api/v1/roles/unassign— Quitar un rol de un usuario.

GET/api/v1/groups— Listar grupos.

GET/api/v1/groups/{id}— Obtener un grupo con sus miembros.

POST/api/v1/groups— Crear un grupo.

POST/api/v1/groups/{id}/members— Agregar miembros a un grupo.

DELETE/api/v1/groups/{groupId}/members/{userId}— Eliminar un miembro de un grupo.

DELETE/api/v1/groups/{id}— Eliminar un grupo.

GET/api/v1/group-role-mappings— Listar las asignaciones de grupo a rol (roles concedidos al emitir el token según la pertenencia al grupo).

GET/api/v1/scopes— Listar ámbitos de API.

POST/api/v1/scopes— Crear un ámbito.

DELETE/api/v1/scopes/{name}— Eliminar un ámbito.

GET/api/v1/saml/connections— Listar conexiones SAML.

POST/api/v1/saml/connections— Crear una conexión SAML.

DELETE/api/v1/saml/connections/{id}— Eliminar una conexión SAML.

GET/api/v1/oidc/connections— Listar conexiones OIDC.

POST/api/v1/oidc/connections— Crear una conexión OIDC.

DELETE/api/v1/oidc/connections/{id}— Eliminar una conexión OIDC.

GET/api/v1/sso/domains— Listar los dominios enrutados a conexiones SSO (descubrimiento de dominio de origen).

GET/api/v1/branding— Obtener la personalización del inquilino (colores, logotipo, idiomas admitidos).

PUT/api/v1/branding— Actualizar la personalización del inquilino.

GET/api/v1/settings— Obtener la configuración del inquilino (webhooks, registro público, política de tokens).

PUT/api/v1/settings— Actualizar la configuración del inquilino.

POST/api/v1/settings/webhook-secret/regenerate— Rotar el secreto de firma del webhook.

POST/api/v1/settings/test-email— Enviar un correo de prueba con la configuración de correo actual.

GET/api/v1/custom-domains— Listar los dominios de inicio de sesión personalizados y su estado de verificación.

POST/api/v1/custom-domains— Agregar un dominio personalizado.

POST/api/v1/custom-domains/{domain}/verify— Iniciar la verificación DNS de un dominio personalizado.

DELETE/api/v1/custom-domains/{domain}— Eliminar un dominio personalizado.

GET/api/v1/email/domains— Listar los dominios de correo del remitente.

GET/api/v1/audit— Consultar el registro de auditoría del inquilino.

Ejemplo: crear un usuario

curl -X POST https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "S3cure-temp-passw0rd",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

# 200 OK
# { "userId": "8f3a...", "email": "[email protected]" }

Pantallas de inicio de sesión

Estas son las pantallas alojadas que tus usuarios finales ven en el servidor de autenticación de tu inquilino. Authagonal incluye todas las pantallas listas para usar, así que obtienes una experiencia de inicio de sesión completa y segura sin construir ninguna interfaz. Esta página recorre cada pantalla y muestra qué ajustes del portal la controlan.

Inicio de sesión

• Flujo de dos pasos, con el correo primero: el usuario introduce su correo y hace clic en Continuar, y entonces aparece el campo de contraseña.
• Los botones de inicio de sesión único «Continuar con {provider}» aparecen automáticamente cuando existen conexiones SSO.
• Enlaces de olvidé mi contraseña y crear cuenta, cada uno de los cuales se puede mostrar u ocultar.
• Captcha opcional de Cloudflare Turnstile para disuadir intentos de inicio de sesión automatizados.

Controlado en la administración del portal

• Marca define el logotipo, el color, el nombre de la aplicación, el correo de soporte y el CSS personalizado.
• Muestra u oculta los enlaces de olvidé mi contraseña y registro (Marca).
• Las conexiones SSO añaden los botones de inicio de sesión social (página SSO).
• Duración de la sesión y umbrales de bloqueo (Configuración → Seguridad).

Registro

• Recopila nombre y apellido (opcional), correo electrónico y una contraseña.
• Una lista de verificación de la política de contraseñas en vivo se actualiza a medida que el usuario escribe, así los requisitos quedan claros antes de enviar.
• Captcha opcional de Cloudflare Turnstile.
• Un enlace de «Iniciar sesión» para usuarios que ya tienen una cuenta.

Controlado en la administración del portal

• Muestra u oculta el enlace de registro (Marca).
• La política de contraseñas de tu inquilino controla la lista de verificación.
• Marca da estilo a toda la pantalla.

Olvidé mi contraseña

• El usuario introduce su correo y luego ve una confirmación neutral de «revisa tu correo».
• La pantalla nunca revela si una cuenta existe, lo que frustra los sondeos de enumeración de cuentas.
• Un enlace de «Volver al inicio de sesión» devuelve al usuario a la pantalla de inicio de sesión.

Controlado en la administración del portal

• Muestra u oculta el enlace de olvidé mi contraseña (Marca).
• La entrega de correo de tu inquilino envía el mensaje de restablecimiento.
• Marca da estilo a toda la pantalla.

Restablecer contraseña

• Campos de nueva contraseña y confirmar contraseña con una lista de verificación de requisitos por regla en vivo.
• Un estado claro de enlace no válido o caducado cuando el token de restablecimiento ya no es válido.
• Un estado de éxito que confirma que la contraseña se ha cambiado.

Controlado en la administración del portal

• La política de contraseñas de tu inquilino controla la lista de verificación.
• Marca da estilo a toda la pantalla.

Desafío MFA

• Un selector de método entre aplicación autenticadora, passkey y código de recuperación.
• Un campo TOTP de 6 dígitos que se envía automáticamente una vez introducidos todos los dígitos.
• Entrada de código de recuperación para usuarios que han perdido el acceso a su autenticador.
• Un botón de passkey para verificación respaldada por hardware.

Controlado en la administración del portal

• La política de MFA se configura por aplicación (Clientes → Seguridad).
• A cualquier usuario con un factor registrado siempre se le exige el desafío, independientemente de la política.

Configuración de MFA

• Muestra el estado de los métodos registrados para que el usuario sepa qué ya está configurado.
• Configuración del autenticador mediante código QR, una clave manual de respaldo y un paso de confirmación.
• Registro de passkey para autenticación respaldada por hardware.
• Generación de códigos de recuperación para recuperar la cuenta.
• Una opción de omitir cuando el MFA es de autoservicio en lugar de obligatorio.

Controlado en la administración del portal

• La política de MFA se configura por aplicación; Obligatorio fuerza la configuración al iniciar sesión (Clientes → Seguridad).
• Marca da estilo a toda la pantalla.

Autorización de dispositivo

• Un campo centrado de entrada del código de usuario para el código mostrado en el dispositivo.
• Un paso de aprobación para autorizar el dispositivo.
• Un interstitial de inicio de sesión cuando el usuario aún no está autenticado.
• Una confirmación de aprobación una vez que el dispositivo está autorizado.

Controlado en la administración del portal

• Habilita la concesión de código de dispositivo en la aplicación (Clientes → Tipos de concesión).
• Establece la duración del código de dispositivo (Clientes → Tokens).

Consentimiento

• Muestra el logotipo y nombre del cliente que hace la solicitud.
• Una lista por scope con etiquetas claras y legibles para cada permiso.
• Botones de Permitir y Denegar para conceder o rechazar el acceso.
• Un pie con una nota de consentimiento que explica lo que significa la decisión.

Controlado en la administración del portal

• Activa Requerir consentimiento por aplicación (Clientes → Seguridad).
• El logotipo, el nombre y la URL provienen de los propios metadatos de la aplicación.
• Marca pinta la tarjeta de consentimiento.

Aplicaciones conectadas (concesiones)

• Lista todas las apps que el usuario ha autorizado, con su nombre, ámbitos y fecha de concesión.
• Revoca el acceso a una app, con un paso de confirmación antes de que surta efecto.
• Un estado vacío amigable cuando el usuario no ha autorizado ninguna app.

Controlado en la administración del portal

• La lista se llena con las aplicaciones que requieren consentimiento.
• Marca da estilo a toda la pantalla.

Cuenta

Una página de cuenta de autoservicio alojada en /login/account donde los usuarios que han iniciado sesión gestionan su propio perfil e idioma preferido, sin necesidad de acceso al portal.

• Editar nombre y apellidos, empresa y teléfono; la dirección de correo se muestra en solo lectura.
• Elegir un idioma preferido entre los idiomas soportados; la interfaz previsualiza la elección al instante y la conserva al guardar.
• El idioma guardado controla la interfaz alojada del usuario y el idioma de los correos transaccionales que recibe.

Controlado en la administración del portal

• Branding da estilo a toda la pantalla.
• El mismo idioma preferido puede ser editado por un administrador en la página de Usuarios del portal.

Flujos de autenticación

Los flujos de autenticación cubren cómo los usuarios finales interactúan con tu inquilino de Authagonal — iniciar sesión, registrarse, restablecer contraseñas y configurar MFA. Estos endpoints son utilizados por la página de inicio de sesión alojada y pueden llamarse directamente si estás construyendo una interfaz de inicio de sesión personalizada.

Inicio de sesión

POST /api/auth/login

Autentica a un usuario con correo electrónico y contraseña. En caso de éxito, firma una cookie de sesión y devuelve el perfil del usuario. Si MFA está configurado, la respuesta indica que se requiere un segundo factor antes de que la sesión esté completamente establecida.

Cuerpo de la solicitud:

{
  "email": "[email protected]",
  "password": "correct-horse-battery-staple"
}

Respuesta exitosa:

Respuesta de MFA requerido: Cuando el usuario tiene MFA inscrito, la respuesta incluye mfaRequired: true junto con un challengeId y un array methods que lista los métodos MFA disponibles.

Respuesta de configuración de MFA requerida: Cuando el inquilino requiere MFA pero el usuario aún no se ha inscrito, la respuesta incluye mfaSetupRequired: true con un setupToken para el flujo de inscripción.

Respuestas de error:

Verificación SSO: Si el dominio de correo electrónico del usuario tiene una conexión SSO configurada, el endpoint de inicio de sesión devuelve sso_required con un redirectUrl. El cliente debe redirigir al usuario al proveedor SSO.

Bloqueo de cuenta: Después de maxFailedAttempts intentos consecutivos de inicio de sesión fallidos, la cuenta se bloquea durante lockoutDurationMinutes. Ambos valores son configurables en la configuración del inquilino.

Registro

POST /api/auth/register

Crea una nueva cuenta de usuario. Se envía un correo electrónico de verificación automáticamente — el usuario debe verificar su correo electrónico antes de poder iniciar sesión.

Cuerpo de la solicitud:

{
  "email": "[email protected]",
  "password": "a-strong-password-here",
  "firstName": "Jane",
  "lastName": "Smith"
}

Éxito: 201 Created con el userId de la nueva cuenta. Registrarse con un correo que ya existe también devuelve 201: nunca revelamos si un correo está registrado (para evitar la enumeración de cuentas) y, en su lugar, avisamos por correo al titular real de la cuenta.

Respuestas de error:

Restablecimiento de contraseña

POST /api/auth/forgot-password

Solicita un correo electrónico de restablecimiento de contraseña. El endpoint siempre devuelve una respuesta exitosa independientemente de si el correo electrónico existe, para prevenir la enumeración de correos electrónicos.

{
  "email": "[email protected]"
}

POST /api/auth/reset-password

Restablece la contraseña del usuario usando el token del enlace del correo electrónico.

{
  "token": "RESET_TOKEN_FROM_EMAIL",
  "newPassword": "new-strong-password"
}

Efectos secundarios de un restablecimiento de contraseña exitoso:

• El contador de intentos de inicio de sesión fallidos se reinicia a cero
• Todos los tokens de actualización existentes son revocados
• Se genera un nuevo sello de seguridad (invalidando todas las sesiones existentes)

Configuración y verificación de MFA

Authagonal soporta tres métodos MFA: TOTP (aplicaciones autenticadoras), WebAuthn (llaves de seguridad y biometría) y códigos de recuperación de un solo uso.

Configuración TOTP

POST /api/auth/mfa/totp/setup — Devuelve un URI de datos de código QR y una clave de entrada manual. El usuario escanea el código QR con su aplicación autenticadora (Google Authenticator, Authy, 1Password, etc.) y luego confirma la inscripción.

POST /api/auth/mfa/totp/confirm — Confirma la inscripción TOTP validando un código de 6 dígitos de la aplicación autenticadora.

{
  "code": "123456"
}

Configuración WebAuthn

POST /api/auth/mfa/webauthn/setup — Devuelve opciones de creación de credenciales para la API WebAuthn. El navegador llama a navigator.credentials.create() con estas opciones.

POST /api/auth/mfa/webauthn/confirm — Confirma la inscripción WebAuthn enviando la respuesta de atestación del navegador.

Códigos de recuperación

POST /api/auth/mfa/recovery/generate — Genera 10 códigos de recuperación de un solo uso de 8 caracteres. Cada código puede usarse exactamente una vez para omitir MFA.

Verificación MFA

POST /api/auth/mfa/verify — Completa el desafío MFA después de un inicio de sesión exitoso con contraseña.

Estado de MFA

GET /api/auth/mfa/status — Devuelve los métodos MFA actualmente inscritos del usuario.

Flujo de inicio de sesión SSO

Authagonal soporta tanto conexiones SSO basadas en SAML 2.0 como en OIDC. El enrutamiento basado en dominio detecta automáticamente qué proveedor SSO usar según la dirección de correo electrónico del usuario.

Verificación SSO

GET /api/auth/[email protected]

Flujo SAML

El usuario es redirigido a GET /saml/{connectionId}/login que envía una AuthnRequest SAML al proveedor de identidad. El IdP autentica al usuario y publica una respuesta SAML de vuelta al endpoint del Assertion Consumer Service (ACS). Authagonal valida la aserción, crea o actualiza al usuario y firma una cookie de sesión.

Los metadatos SAML para configurar tu IdP están disponibles en GET /saml/{connectionId}/metadata.

Flujo OIDC

El usuario es redirigido a GET /oidc/{connectionId}/login que redirige al proveedor de identidad ascendente con PKCE. Después de que el usuario se autentica, el callback en /oidc/callback intercambia el código de autorización, valida el token de ID y crea o actualiza al usuario.

Aprovisionamiento JIT: Tanto los flujos SAML como OIDC soportan aprovisionamiento just-in-time. Si el usuario no existe ya en el inquilino, se crea automáticamente a partir de las reclamaciones del proveedor de identidad. Si ya existe, sus atributos de perfil se actualizan para coincidir con los valores más recientes del proveedor.

Backend-for-Frontend (BFF)

Un BFF mantiene los tokens de OAuth completamente fuera del navegador. Tu aplicación de página única no guarda más que una cookie de sesión httpOnly, y un cliente confidencial en tu propio backend ejecuta el flujo de OpenID Connect y guarda los tokens en el servidor.

Todo lo que una aplicación de página única puede leer, el cross-site scripting lo puede robar, y eso incluye un token de acceso en memoria y un token de actualización en localStorage. Guardar tokens en el navegador también limita su duración, porque un token de actualización de larga vida al alcance de los scripts es un riesgo permanente. La mejor práctica actual del IETF OAuth 2.0 for Browser-Based Apps recomienda este patrón exactamente por esa razón.

A cambio obtienes una sesión que sobrevive a una recarga de página sin un solo token a la vista, la renovación resuelta por ti en el servidor, revocación inmediata mediante el cierre de sesión back-channel, y un proxy autenticado para que tu API nunca tenga que analizar un token que el navegador podría haber manipulado.

Crear el cliente

En el portal, abre Clientes y elige Crear app BFF. Indica la URL base desde la que se sirve tu aplicación, por ejemplo https://app.acme.com, y Authagonal registra por ti un cliente confidencial correctamente configurado en lugar de dejarte armarlo a mano:

Conéctalo a tu backend

Hay dos entornos de ejecución compatibles y se comportan igual: Authagonal.Bff para .NET y @authagonal/bff para Node, este último con adaptadores para Express y Next.js. Apunta cualquiera de los dos a los valores que el portal acaba de darte.

// dotnet add package Authagonal.Bff
builder.Services.AddAuthagonalBff(o =>
{
    o.Authority    = "https://acme.authagonal.io";       // your tenant auth host
    o.ClientId     = builder.Configuration["Bff:ClientId"]!;
    o.ClientSecret = builder.Configuration["Bff:ClientSecret"]!;
    o.Scope        = ["openid", "profile", "email", "offline_access"];
    o.PostLogoutRedirectUri = "https://app.acme.com/";
});

var app = builder.Build();

app.UseForwardedHeaders();   // required behind a proxy or ingress, see the note below
app.MapAuthagonalBff();
app.MapFallbackToFile("index.html");   // your SPA
app.Run();

// npm install @authagonal/bff
import express from 'express';
import { authagonalBff } from '@authagonal/bff/express';

const app = express();

app.use(authagonalBff({
  authority: 'https://acme.authagonal.io',
  clientId: process.env.BFF_CLIENT_ID,
  clientSecret: process.env.BFF_CLIENT_SECRET,
  scope: ['openid', 'profile', 'email', 'offline_access'],
  postLogoutRedirectUri: 'https://app.acme.com/',
}));

app.listen(8080);

Endpoints

Se montan bajo /bff de forma predeterminada. Deben servirse desde el mismo origen que tu SPA, porque la cookie de sesión es httpOnly y de mismo origen: ponlos detrás del mismo nombre de host y no en un dominio de API aparte.

Desde el navegador

Toda solicitud que no sea de navegación debe llevar una cabecera anti-falsificación estática. Protege frente a la falsificación de solicitudes entre sitios junto con el atributo SameSite de la cookie: el envío de un formulario entre sitios no puede establecer una cabecera personalizada, así que una solicitud que no la lleve se rechaza.

const me = await fetch('/bff/user', {
  headers: { 'X-Authagonal-Bff': '1' },
}).then(r => r.json());

if (!me.isAuthenticated) {
  // Navigate, do not fetch: this is a redirect to your identity provider.
  window.location.href = '/bff/login?returnUrl=' + encodeURIComponent(location.pathname);
}

Inicia y cierra sesión navegando, no con fetch: location.href = '/bff/login'. Esas rutas responden con una redirección a tu proveedor de identidad, y una cadena de redirecciones no es algo que fetch pueda seguir de forma útil.

Llamar a tu API

El BFF puede reenviar tu API bajo su propia ruta base y adjuntar el token de acceso de la sesión al pasar. El navegador envía una cookie, tu API recibe un token Bearer que valida de la forma habitual, y nada de ese token es visible para la página ni falsificable por ella. Registra un upstream y las solicitudes a /bff/api/** llegan a él autenticadas. Deja la lista vacía y el proxy queda deshabilitado por completo.

o.Upstreams.Add(new BffUpstream
{
    Prefix        = "/orders",                        // matches /bff/api/orders/**
    TargetBaseUrl = "https://api.internal.acme.com",
    StripPrefix   = false,                            // keep /orders in the forwarded path
});

WebSockets

Un handshake de WebSocket no puede llevar una cabecera personalizada ni un token Bearer, así que aquí no sirven ni la cabecera anti-falsificación ni el proxy. Habilita los tickets y la SPA podrá llamar a GET /bff/ws-ticket, poner en la URL de conexión el ticket de un solo uso y corta duración, y hacer que tu API lo canjee. Genera uno justo antes de cada conexión: se elimina en el primer uso y expira en segundos.

Entregar un token al navegador, a propósito

Todo el sentido de un BFF es que el navegador no guarda ningún token, así que esto es opcional y de alcance limitado. Existe para el único caso al que el modelo de cookie no llega: un servidor de recursos en otro origen, como una aplicación que incrustas en un iframe, al que hay que llamar con un token Bearer. Habilitado, GET /bff/token?resource=… devuelve un token intercambiado: el token de la sesión reducido a un único recurso de la lista de permitidos y vinculado a cualquier parámetro de contexto también permitido. El navegador nunca ve el token propio de la sesión, y lo que sí recibe es de corta duración y para una sola audiencia. Se rechaza toda solicitud que nombre un recurso fuera de la lista de permitidos, que es lo que impide que esto sea una fábrica de tokens de uso general.

Servir a varios inquilinos desde un solo BFF

Establece un parámetro de consulta de inquilino y un solo despliegue atiende a muchos inquilinos: /bff/login?slug=acme selecciona el inquilino, un resolutor aporta la authority y las credenciales de cliente de ese inquilino, la clave viaja en la cookie de correlación hasta la sesión, y el cierre de sesión back-channel resuelve el inquilino a partir del emisor del token. El resolutor predeterminado mantiene el comportamiento de inquilino único idéntico byte a byte, así que esto no te cuesta nada mientras no lo uses.

Opciones que conviene conocer

El conjunto completo. El paquete de Node los refleja en camelCase, así que BasePath es basePath y así sucesivamente.

Gestiona tu portal desde un asistente de IA

Conecta un asistente de IA a tu inquilino y pídele que haga lo que de otro modo harías a base de clics: encontrar a un usuario que no puede iniciar sesión, comprobar si todavía tiene un segundo factor, invitar a alguien, ver quién tiene un rol de administrador.

Es una conexión OAuth corriente, no una clave API. Cada persona inicia sesión como ella misma y aprueba el acceso, así que un asistente puede hacer exactamente lo que esa persona puede hacer en el portal y nada más. No se crea nada nuevo que pueda filtrarse, y revocar un asistente deja intactos a todos los demás.

Cómo activarlo

Abre Configuración y activa el acceso de asistentes de IA. Hasta que lo hagas está desactivado, y mientras está desactivado el endpoint no existe, en lugar de limitarse a rechazar. Una vez activado, el panel muestra la URL que hay que pegar en tu cliente de IA:

https://portal-api.authagonal.io/api/v1/mcp/{your-tenant}

Qué puede hacer un asistente

Exactamente lo que puede hacer la persona que lo conectó, decidido en cada llamada contra su propio token. Un agente con tenant:support obtiene las herramientas de diagnóstico y del día a día; las herramientas de administrador no solo están ocultas para él, se rechazan si las nombra directamente. Todo lo que está restringido dentro del portal sigue restringido: cambiar la dirección de correo de un usuario exige allí el rol de administrador, y aquí lo exige también.

Como es una concesión normal, la gestionas de la forma normal. Revócala y el asistente deja de funcionar de inmediato, en lugar de al expirar el siguiente token. Todo lo que hace un asistente queda escrito en tu registro de auditoría a nombre de la persona por la que actuó, así que el rastro es el mismo que ya lees.

Las herramientas

Veinte en esta versión. Tu cliente de IA decide cuáles habilitar, así que puedes darle a un asistente solo las herramientas de lectura si es todo lo que quieres que haga.

Qué no está incluido todavía

Eliminar usuarios, crear o editar conexiones SSO, la facturación, las copias de seguridad y los secretos de cliente están todos ausentes de esta versión. Eliminar pertenece a tu cola de borrado y no a un sitio contiguo; una conexión SSO pesa lo suficiente como para que una edición equivocada deje fuera a toda una plantilla, así que por ahora son de solo lectura; y una herramienta que devolviera un secreto de cliente lo dejaría en la transcripción de un asistente. Dinos cuáles de estas quieres y en qué orden.

Autenticación de servidores MCP

Si expones un servidor Model Context Protocol, Authagonal puede ser el servidor de autorización que hay detrás. Un asistente de IA se conecta, la persona que está detrás inicia sesión y concede el acceso, y tu servidor recibe un token bearer normal que validas como el de cualquier otra API.

La alternativa es una clave API pegada en la configuración de un asistente: una credencial sin ningún usuario detrás, sin caducidad, sin paso de consentimiento y sin forma de revocar un conector sin rotarla para todo el mundo. Hacerlo con OAuth significa que la concesión pertenece a una persona con nombre, es visible en tu registro de auditoría y se puede revocar desde el portal sin tocar nada más.

Cómo se produce la conexión

Todo el intercambio se basa en el descubrimiento, así que un cliente conforme no necesita más configuración que la URL de tu servidor.

Nada de esa secuencia es específico de Authagonal: es la especificación de autorización de MCP, construida sobre RFC 9728 para los metadatos del recurso, RFC 8414 para descubrir el servidor de autorización, RFC 7591 para el registro y RFC 8707 para nombrar el recurso. Un conector que sigue la especificación funciona sin tratarnos como un caso especial.

Deja que los conectores se registren solos

Un conector que nunca has visto no puede usar un cliente que hayas creado a mano, así que registra uno en tiempo de ejecución. Eso está desactivado por defecto. Activa el registro dinámico de clientes en Configuración y el endpoint de registro aparecerá en tu documento de descubrimiento; déjalo desactivado y el endpoint no se anuncia y rechaza las solicitudes. Activarlo abre el registro solo para tu inquilino, nunca para el de nadie más.

Qué implementa tu servidor MCP

Dos cosas pequeñas, y a partir de ahí es un servidor de recursos corriente. Primero, publica metadatos de recurso protegido que nombren a tu inquilino como servidor de autorización. Sírvelos en la ruta well-known y, si tu endpoint MCP está en una subruta, también en la forma con el sufijo de ruta, ya que los clientes prueban ambas.

GET https://your-app.example/.well-known/oauth-protected-resource

{
  "resource": "https://your-app.example/mcp",
  "authorization_servers": ["https://acme.authagonal.io"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp"]
}

Segundo, cuando llegue una llamada sin un token válido, responde 401 con un encabezado WWW-Authenticate que apunte a esos metadatos. Ese encabezado es lo que convierte un rechazo en una conexión: sin él el cliente no tiene forma de descubrir dónde autenticarse, y simplemente falla.

// Validate the connector's token like any other resource server.
builder.Services.AddAuthentication().AddJwtBearer("McpBearer", o =>
{
    o.Authority = "https://acme.authagonal.io";              // your tenant
    o.TokenValidationParameters.ValidAudience = "https://your-app.example/mcp";
});

// Unauthenticated? Point the connector at the metadata rather than just refusing.
http.Response.Headers.WWWAuthenticate =
    "Bearer resource_metadata=\"https://your-app.example/.well-known/oauth-protected-resource\"";
return Results.Unauthorized();

Ámbitos, planes y revocación

Define un ámbito para tu superficie MCP, añádelo a los ámbitos de registro permitidos y aparecerá en la pantalla de consentimiento para que el usuario vea qué está aprobando. El token lleva los roles del usuario y los claims que hayas configurado, de modo que tu servidor puede decidir qué puede hacer esta persona concreta en lugar de tratar a todos los conectores por igual.

Como es una concesión de OAuth corriente, la revocación funciona de la forma corriente: busca al usuario, revoca sus sesiones o la concesión, y el conector deja de funcionar de inmediato en lugar de al expirar el siguiente token. El registro de auditoría deja constancia del registro, del consentimiento y de la emisión, así que puedes ver qué asistente pidió qué y cuándo.

Crea una interfaz de inicio de sesión personalizada

Reemplaza las pantallas alojadas de inicio de sesión, registro, restablecimiento de contraseña y MFA de Authagonal por tu propia interfaz, mientras Authagonal sigue encargándose de la autenticación, MFA, SSO, sesiones y emisión de tokens. Dos vías: usar nuestra biblioteca de componentes de React, o llamar a la API de autenticación directamente desde cualquier framework. Es opcional — primero habilita Custom login UI en la configuración del inquilino.

Requisito previo: un dominio personalizado en tu raíz

La sesión de inicio de sesión es una cookie de origen propio (first-party), por lo que tu interfaz y el servidor de autenticación de Authagonal deben compartir un dominio registrable. Apunta un dominio de autenticación personalizado a Authagonal en la misma raíz donde se ejecuta tu app — p. ej. autenticación en login.acme.com, app en app.acme.com. La configuración Custom login UI permanece deshabilitada hasta que exista un dominio personalizado activo.

Agrega también el origen de tu interfaz (p. ej. https://app.acme.com) a los Allowed CORS origins de tu cliente OAuth — la misma lista que configuras para el intercambio de tokens.

React: @authagonal/login

npm i @authagonal/login incluye la lógica de autenticación y la interfaz en un solo paquete — el mismo sobre el que está construido el inicio de sesión alojado de Authagonal. Elige tu nivel:

• App completa — incorpora App y aplícale tu tema mediante la marca.
• Componer páginas — usa LoginPage, MfaChallengePage, ResetPasswordPage… dentro de tu propio diseño.
• Primitivas + lógica — crea tus propias pantallas con AuthLayout/Button/Input y el cliente de la API (login, mfaVerify, forgotPassword, …).

import { AuthLayout, Input, Button, login, ApiRequestError } from '@authagonal/login';

function MyLogin() {
  async function onSubmit(email: string, password: string) {
    try {
      const res = await login({ email, password });        // POST /login (sets the session cookie)
      if (res.mfaRequired) {/* render your MFA step → mfaVerify(...) */}
      else window.location.href = res.returnUrl;            // hand off to /connect/authorize
    } catch (e) {
      if (e instanceof ApiRequestError) {/* show e.message */}
    }
  }
  return <AuthLayout>{/* your own markup + <Input/> <Button/> */}</AuthLayout>;
}

Cualquier framework: llama a la API de autenticación

¿No usas React? Llama directamente a los endpoints del flujo de autenticación (bajo /api/auth) y luego entrega al flujo OIDC estándar /connect/authorize. Envía credentials: 'include' para que se almacene la cookie de sesión.

# 1. Authenticate (browser fetch — credentials:'include' so the session cookie is stored)
curl -i -X POST https://login.acme.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.acme.com" \
  --data '{"email":"[email protected]","password":"..."}'
# (handle {"mfaRequired":true} → POST /api/auth/mfa/verify, then continue)

# 2. Hand off to the OAuth flow — top-level navigation to the authorize endpoint with PKCE:
# https://login.acme.com/connect/authorize?client_id=my-app&redirect_uri=...&response_type=code
#   &scope=openid%20profile%20email&code_challenge=...&code_challenge_method=S256
# The session cookie (same-site) authenticates the user; you get back a code → exchange at /connect/token.

Planes y límites

Authagonal ofrece cuatro niveles de plan. Todos los planes incluyen todas las funcionalidades — la única diferencia es el límite de Usuarios Activos Mensuales (MAU) y el precio de excedentes.

Niveles de plan

Usuarios Activos Mensuales (MAU)

Un Usuario Activo Mensual es cualquier usuario único que se autentica exitosamente al menos una vez durante un mes de facturación. Los usuarios aprovisionados a través de SCIM pero que no han iniciado sesión no cuentan para tu total de MAU.

Excedentes — Si tu plan admite excedentes, los usuarios más allá del límite de MAU se facturan a la tarifa por usuario mostrada en la tabla de planes anterior. Puedes establecer un tope de excedente para limitar tu gasto máximo durante el período de facturación.

Aplicación — Si tu plan no admite excedentes (Starter), los usuarios más allá del límite de MAU no pueden iniciar sesión hasta el próximo período de facturación o hasta que actualices a un plan que admita excedentes.