Conectar un proveedor OpenID Connect

Usa esta guía cuando tu proveedor de identidad hable OpenID Connect en lugar de SAML. Funciona cualquier emisor con certificación OIDC —Pocket ID, Keycloak, Auth0, Zitadel, Google Workspace y compañía siguen los mismos pasos—; lo único que cambia es el lugar donde tu proveedor muestra los valores.

Requisitos previos

• un proveedor OIDC en el que puedas crear un cliente —anota su ID de cliente y su URL del emisor (la base bajo la que vive el documento .well-known/openid-configuration), además de su secreto de cliente cuando el cliente sea de tipo confidencial (los clientes públicos con PKCE no tienen ninguno),
• un servidor de Control Center que administres (el propietario del servidor).

Pasos

1. Abre Ajustes → Servidor → Inicio de sesión único y cambia a OpenID Connect.
2. Completa la URL del emisor, el ID de cliente y el Secreto del cliente (opcional) cuando el proveedor haya emitido uno. Control Center descubre los endpoints a partir del documento de descubrimiento estándar del emisor: no hace falta configuración por proveedor.
3. En el proveedor, registra la redirección https://<your-server>/oidc/callback en ese cliente.
4. Si tus grupos viven bajo un claim distinto de groups, especifica el nombre en Claim de grupos; asigna grupos a roles si quieres (SSO nunca puede otorgar el rol de propietario).
5. Elige la política de pertenencia (agregar automáticamente a cada espacio de trabajo o requerir invitaciones por espacio de trabajo), activa Usar OpenID Connect para iniciar sesión y presiona Guardar conexión.
6. Presiona Probar conexión: el servidor obtiene el documento de descubrimiento del emisor y confirma sus endpoints, así que una notificación verde significa que todo funciona salvo el recorrido de ida y vuelta por el navegador. Para comprobar también el registro del cliente, usa el verificador de abajo.
7. Inicia sesión: la pantalla de conexión web muestra Iniciar sesión con OpenID Connect, o abre https://<your-server>/oidc/login directamente.

Los claims (correo electrónico, nombre, grupos) los lee tu servidor del endpoint de tokens del emisor a través de TLS: el navegador nunca los proporciona, así que no hay ninguna verificación local de la firma del JWT. El cliente debe tener permitido solicitar el scope openid profile email, que es exactamente lo que pide Control Center.

Como ese canal TLS es lo único que autentica los claims, la URL del emisor debe ser https: un emisor en texto plano permitiría a cualquier atacante en la ruta falsificar identidades en masa. http solo se acepta para emisores de loopback (localhost, 127.0.0.1, ::1), para desarrollo local.

¿Cliente público o cliente confidencial?

La forma predeterminada —y recomendada— es un cliente público que usa el flujo de código de autorización con PKCE (RFC 7636): el verificador de código de un solo uso que guarda el servidor sustituye al secreto, y el intercambio de tokens queda vinculado a la solicitud de autorización que lo inició. No hay ningún secreto que se pueda filtrar, y un código de autorización robado es inútil sin el verificador. Algunos proveedores llaman “SPA” o “nativo” a este tipo de cliente cuando lo creas.

Si tu proveedor te emitió un cliente confidencial, marca el cliente como público en el proveedor (PKCE se mantiene de cualquier forma) o pega el secreto de cliente en el campo Secreto del cliente (opcional) de la conexión. El secreto se guarda en el archivo de secretos del servidor con permisos 0600 (nunca en la base de datos), se envía al endpoint de tokens como client_secret_post y nunca se devuelve por RPC; si dejas el campo en blanco al guardar, se conserva el secreto almacenado. Cuando un inicio de sesión falla en el intercambio de tokens, el registro del servidor indica el error propio del proveedor (invalid_client casi siempre significa que el secreto falta o es incorrecto).

Alcanzabilidad

El inicio de sesión en sí está mediado por el navegador: el emisor solo redirige el navegador del usuario de vuelta a /oidc/callback, y tu servidor hace una llamada HTTPS saliente al endpoint de tokens —no hace falta ninguna conexión entrante desde el emisor—, así que un servidor detrás de NAT funciona siempre que los navegadores de los usuarios puedan alcanzarlo (LAN, VPN, Tailscale o un túnel). El aprovisionamiento SCIM es la excepción: el IdP llama directamente a tu servidor, lo que requiere un túnel o una URL pública; consulta aprovisionar usuarios con SCIM.

Verifica tu configuración desde esta página

El verificador de abajo se ejecuta en tu navegador. Obtiene directamente el documento de descubrimiento de tu emisor, así que este sitio nunca lo ve, y aplica las reglas del servidor: un emisor https que coincida con el documento, endpoints en el propio origen del emisor, PKCE S256 y el método de autenticación de tokens que necesita tu tipo de cliente. Con un ID de cliente y la dirección del servidor, puede abrir un inicio de sesión de prueba que muestra si el cliente y su URI de redirección están registrados. Nunca pide el secreto de cliente.

Runs in your browserYour browser fetches the discovery document straight from your issuer. Add a server address and it also asks that server which sign-in methods it offers. This site never receives what you type.

Issuer URL

Client ID (optional)

Needed for the test sign-in.

Groups claim (optional)

Client type

Public, PKCE only Confidential, has a client secret

Never paste the secret here. The check only needs to know whether one exists.

Server address (optional)

The address your users open. Adds a reachability check and a test sign-in.

Paste the discovery document instead

Discovery document JSON

For providers that block other sites from reading it.

Check issuer