Configuración SSO OAuth/OIDC

Scale Plan

Configura OAuth 2.0 u OpenID Connect (OIDC) para el inicio de sesión único. Una alternativa moderna a SAML para proveedores de identidad nativos en la nube.

SAML vs OAuth/OIDC

Característica	SAML	OAuth/OIDC
Protocolo	Basado en XML	JSON/REST
Formato de token	Aserción XML	JWT
Ideal para	IdPs empresariales	Aplicaciones en la nube
Complejidad de configuración	Mayor	Menor

Proveedores soportados

Proveedor	Protocolo
Microsoft Entra ID (Azure AD)	OIDC
Okta	OIDC
Auth0	OIDC
Keycloak	OIDC
Personalizado	OAuth 2.0 / OIDC

Configuración OAuth/OIDC de Zenovay

Redirect URI

Tu proveedor de identidad necesitará esta URI de redirección:

Configuración	Valor
Redirect URI / Callback URL	https://auth.zenovay.com/api/sso/oauth/callback

Puedes copiar este valor (y los equivalentes SAML) directamente desde Configuración → Seguridad → SSO, bajo Detalles del proveedor de servicios.

Scopes requeridos

Zenovay requiere estos scopes:

openid
email
profile

Elección entre OAuth 2.0 y OpenID Connect

Característica	OAuth 2.0	OpenID Connect
Verificación del token de identidad	No aplicable	Automática via JWKS
Campos requeridos	Client ID, Client Secret, Issuer, Authorization URL, Token URL, Userinfo URL	Client ID, Client Secret, Issuer, Metadata URL
Ideal para	IdPs sin soporte OIDC	IdPs modernos (Okta, Entra ID, Auth0, Keycloak)

Con OIDC proporcionas la URL de metadatos (el documento .well-known/openid-configuration de tu IdP) y Zenovay lee los puntos finales de autorización, token, userinfo y JWKS de él. Con OAuth 2.0 puro ingresas cada URL de punto final tú mismo.

Configuración Microsoft Entra ID OIDC

Paso 1: Registrar la aplicación

1. Inicia sesión en el centro de administración de Microsoft Entra
2. Ve a Identidad → Aplicaciones → Registros de aplicaciones
3. Haz clic en Nuevo registro
4. Configura:

Campo Entra ID	Valor
Nombre	Zenovay
Tipos de cuenta admitidos	Solo cuentas en este directorio de organización
Redirect URI	Web — https://auth.zenovay.com/api/sso/oauth/callback

5. Haz clic en Registrar

Paso 2: Crear secret de cliente

1. Ve a Certificados y secretos
2. Haz clic en Nuevo secreto de cliente
3. Establece descripción y expiración
4. Copia el valor secreto inmediatamente (no se mostrará de nuevo)

Paso 3: Anotar detalles de la aplicación

Registra estos valores:

• ID de aplicación (ID de cliente) — de la página Descripción general
• Client Secret — del paso 2
• Tenant ID — de la página Descripción general

Paso 4: Permisos de API

1. Ve a Permisos de API
2. Verifica que Microsoft Graph → User.Read (delegado) esté listado
3. Si no, haz clic en Agregar un permiso → Microsoft Graph → Permisos delegados → User.Read

Paso 5: Configurar en Zenovay

1. En Zenovay, ve a Configuración → Seguridad → SSO
2. Haz clic en Añadir proveedor y elige OpenID Connect
3. Ingresa:
   • Nombre del proveedor: por ejemplo, "Microsoft Entra ID"
   • Client ID: el ID de aplicación (ID de cliente) del paso 3
   • Client Secret: el valor secreto del paso 2
   • Issuer: https://login.microsoftonline.com/{tu-id-tenant}/v2.0
   • Metadata URL: https://login.microsoftonline.com/{tu-id-tenant}/v2.0/.well-known/openid-configuration
4. Haz clic en Crear
5. Añade y verifica tu dominio de correo electrónico
6. Prueba la conexión

Configuración Okta OIDC

Paso 1: Crear aplicación

1. Ve a la consola de administrador de Okta → Aplicaciones
2. Haz clic en Crear integración de aplicación
3. Selecciona OIDC - OpenID Connect
4. Selecciona Aplicación web
5. Haz clic en Siguiente

Paso 2: Configurar la aplicación

Campo Okta	Valor
Nombre de integración de la aplicación	Zenovay
Tipo de concesión	Authorization Code
URIs de redirección de inicio de sesión	https://auth.zenovay.com/api/sso/oauth/callback

Paso 3: Asignar usuarios

1. Ve a la pestaña Asignaciones
2. Asigna usuarios o grupos
3. Guardar

Paso 4: Obtener credenciales

De la pestaña General, anota:

• Client ID
• Client Secret

Paso 5: Obtener Issuer y URLs de metadatos

1. Ve a Seguridad → API en la consola de administrador de Okta
2. Encuentra tu servidor de autorización (normalmente "default")
3. El Issuer URI se verá como: https://tu-org.okta.com/oauth2/default
4. La URL de metadatos correspondiente es el Issuer URI más /.well-known/openid-configuration, por ejemplo: https://tu-org.okta.com/oauth2/default/.well-known/openid-configuration

Paso 6: Configurar en Zenovay

1. Ve a Configuración → Seguridad → SSO
2. Haz clic en Añadir proveedor y elige OpenID Connect
3. Ingresa:
   • Nombre del proveedor: por ejemplo, "Okta"
   • Client ID: del paso 4
   • Client Secret: del paso 4
   • Issuer: el Issuer URI del paso 5
   • Metadata URL: la URL de descubrimiento del paso 5
4. Haz clic en Crear
5. Añade y verifica tu dominio de correo electrónico
6. Prueba la conexión

Configuración Auth0

Paso 1: Crear aplicación

1. Ve al panel de Auth0
2. Ve a Aplicaciones → Crear aplicación
3. Elige Aplicaciones web ordinarias
4. Haz clic en Crear

Paso 2: Configurar ajustes

En la pestaña Configuración:

Campo Auth0	Valor
URLs de devolución de llamada permitidas	https://auth.zenovay.com/api/sso/oauth/callback

Haz clic en Guardar cambios.

Paso 3: Obtener credenciales

De la pestaña Configuración, anota:

• Dominio (por ejemplo, tu-tenant.us.auth0.com)
• Client ID
• Client Secret

Paso 4: Configurar en Zenovay

1. Ve a Configuración → Seguridad → SSO
2. Haz clic en Añadir proveedor y elige OpenID Connect
3. Ingresa:
   • Nombre del proveedor: por ejemplo, "Auth0"
   • Client ID: del paso 3
   • Client Secret: del paso 3
   • Issuer: https://tu-tenant.us.auth0.com/ (incluye la barra diagonal final)
   • Metadata URL: https://tu-tenant.us.auth0.com/.well-known/openid-configuration
4. Haz clic en Crear
5. Añade y verifica tu dominio de correo electrónico
6. Prueba la conexión

Google Workspace

Si específicamente necesitas OIDC con Google, puedes crear credenciales OAuth en la consola de Google Cloud:

1. Ve a Google Cloud Console → APIs & Services → Credenciales
2. Haz clic en Crear credenciales → ID cliente OAuth
3. Selecciona Aplicación web e ingresa https://auth.zenovay.com/api/sso/oauth/callback como URI de redirección
4. Anota el Client ID y el Client Secret
5. En Zenovay, añade un proveedor OpenID Connect con Issuer https://accounts.google.com y Metadata URL https://accounts.google.com/.well-known/openid-configuration

Proveedor OIDC personalizado

Si tu proveedor de identidad soporta el descubrimiento de OpenID Connect:

1. Ve a Configuración → Seguridad → SSO
2. Haz clic en Añadir proveedor y elige OpenID Connect
3. Ingresa:
   • Nombre del proveedor: el nombre de tu proveedor
   • Client ID: de tu IdP
   • Client Secret: de tu IdP
   • Issuer: la URL del issuer de tu IdP (por ejemplo, https://tu-idp.com)
   • Metadata URL: tu documento de descubrimiento de IdP, generalmente la URL del issuer más /.well-known/openid-configuration
4. Haz clic en Crear

Zenovay lee automáticamente los puntos finales de autorización, token, userinfo y JWKS de tu IdP desde el documento de metadatos, por lo que no tienes que ingresar cada uno individualmente.

Proveedor OAuth 2.0 personalizado

Si tu proveedor de identidad no soporta el descubrimiento automático OIDC, usa OAuth 2.0 con configuración manual de puntos finales:

1. Ve a Configuración → Seguridad → SSO
2. Haz clic en Añadir proveedor y elige OAuth 2.0
3. Ingresa:
   • Nombre del proveedor: el nombre de tu proveedor
   • Client ID: de tu IdP
   • Client Secret: de tu IdP
   • Authorization URL: el punto final de autorización de tu IdP
   • Token URL: el punto final de token de tu IdP
   • Userinfo URL: el punto final de información de usuario de tu IdP
4. Haz clic en Crear

Finalización de la configuración

Verificar dominio

Después de guardar tu proveedor SSO, vincula los dominios de correo electrónico con los que se conecta tu equipo para que Zenovay sepa dirigirlos a través de SSO:

1. En la sección Verificación de dominio, ingresa tu dominio de correo electrónico (por ejemplo, empresa.com) y haz clic en Verificar dominio
2. Zenovay devuelve un registro TXT de DNS (host y valor) — agrégalo en tu proveedor de DNS
3. Haz clic en Verificar DNS una vez que el registro se haya propagado
4. Una vez verificado, los usuarios con ese dominio de correo electrónico serán dirigidos a SSO

Probar la conexión

Puedes ejecutar una verificación rápida antes de habilitar el proveedor:

1. Abre el menú de acciones del proveedor (el botón ⋯ en la fila del proveedor)
2. Haz clic en Probar conexión
3. Un toast de éxito confirma que Zenovay puede alcanzar tu IdP con las credenciales configuradas

También puedes confirmar el flujo de extremo a extremo manualmente:

1. Abre una ventana de navegador incógnito/privado
2. Ve a auth.zenovay.com
3. Elige Iniciar sesión con SSO e ingresa un correo electrónico de tu dominio verificado
4. Autentica con tu IdP
5. Verifica que regresas al panel de Zenovay

Habilitar y aplicar SSO

1. En la fila del proveedor, cambia el interruptor activado para habilitar el proveedor
2. Para requerir SSO para todos en el espacio de trabajo, abre el menú de acciones del proveedor (⋯) y elige Aplicar SSO, luego confirma

Mapeo de atributos de usuario

Claims estándar

Claim OIDC	Campo Zenovay
email	Dirección de correo electrónico
given_name	Nombre
family_name	Apellido
sub	Identificador único

Aprovisionamiento Just-In-Time

Los nuevos usuarios se crean automáticamente en su primer inicio de sesión SSO exitoso:

• Creación automática de cuenta desde el dominio de correo electrónico verificado
• No se requiere invitación

Características de seguridad

Zenovay aplica automáticamente estas medidas de seguridad para OAuth/OIDC:

• PKCE (Proof Key for Code Exchange) — protege el intercambio del código de autorización
• Parámetro de estado — previene ataques CSRF
• Validación de Nonce (OIDC) — previene ataques de repetición de token
• Verificación del token de identidad (OIDC) — valida tokens usando el punto final JWKS del IdP

Solución de problemas

Errores comunes

Error	Causa	Solución
Invalid redirect_uri	Discordancia de URL	Asegúrate de que la URI de redirección sea exactamente https://auth.zenovay.com/api/sso/oauth/callback
Invalid client_id	Credencial incorrecta	Verifica el ID de cliente en tu panel de IdP
Invalid grant	Código expirado	Intenta de nuevo — los códigos de autorización tienen corta duración
Token verification failed	Fallo de firma	Verifica que el punto final JWKS sea accesible
State parameter mismatch	Problema de sesión	Borra cookies e intenta en una ventana incógnito
OIDC discovery failed	Problema de URL de metadatos	Abre {metadata-url} en tu navegador y confirma que devuelve el documento .well-known/openid-configuration

Problemas de certificado

Si JWKS falla:

• Verifica que la URL de JWKS sea accesible
• Asegúrate de que el certificado SSL sea válido
• Verifica bloqueos de firewall

Consideraciones de seguridad

Gestión de secretos

• Almacena el secreto del cliente de forma segura
• Rota los secretos antes de que expiren
• Nunca expongas secretos en código del lado del cliente

Limitaciones de scopes

Solicita scopes mínimos:

• Solo openid, email, profile
• No solicites acceso innecesario

Validación de URI de redirección

• Usa validación de coincidencia exacta en tu IdP
• No uses caracteres generales
• Se requiere HTTPS

Próximos pasos

• Aplicar MFA para todos los usuarios
• Configurar registro de auditoría
• Políticas de contraseña personalizadas