# Conexiones

Permita el inicio de sesión con un proveedor de identidad externo (OIDC, SAML, Microsoft Entra, social), con vinculación de cuentas y creación JIT.

> **Nota sobre el plan:** Los proveedores sociales (como Google, Apple, GitHub y muchos más) forman parte de todos los planes. Los proveedores empresariales (OIDC/SAML genérico, Microsoft Entra, Okta, Auth0, Ping Identity, Keycloak, OneLogin, JumpCloud, DATEV, los agregadores de identificación electrónica Criipto y Signicat, y el eID alemán) requieren la función **enterprise identity brokering**, incluida en el plan Advanced y superiores (y en Trial).

Una **conexión** permite que sus usuarios inicien sesión con un Identity Provider *externo*, una opción «Iniciar sesión con…» en la pantalla de inicio de sesión. La plataforma delega la autenticación en el proveedor, recibe de vuelta el perfil del usuario y lo vincula a una cuenta existente o crea una nueva. En términos de protocolo, la plataforma actúa como Relying Party (OIDC) o Service Provider (SAML); el proveedor externo es el Identity Provider.

Las conexiones se gestionan en la Admin Console, en **Integraciones → Conexiones**.

## Proveedores disponibles

Las conexiones se agrupan en tres categorías.

**Genéricas** (basadas en estándares, configurables más de una vez):

| Proveedor | Protocolo | Uso habitual |
|---|---|---|
| **OpenID Connect (generic)** | OIDC | Cualquier Identity Provider OIDC conforme al estándar. |
| **SAML 2.0 (generic)** | SAML | Cualquier Identity Provider SAML 2.0. |

**Empresariales:**

| Proveedor | Protocolo | Uso habitual |
|---|---|---|
| **Microsoft Entra** | OIDC | Inicio de sesión con un tenant de Microsoft Entra (profesional o educativo). |
| **Okta** | OIDC | Inicio de sesión con una org de Okta Workforce. Necesita su dominio de Okta. |
| **Auth0** | OIDC | Inicio de sesión con un tenant de Auth0. Necesita su dominio de Auth0. |
| **Ping Identity (PingOne)** | OIDC | Inicio de sesión con un entorno de PingOne. Necesita el host de PingOne y el ID de entorno. |
| **Keycloak** | OIDC | Inicio de sesión con un realm de Keycloak. Necesita la URL del servidor y el realm. |
| **OneLogin** | OIDC | Inicio de sesión con una cuenta de OneLogin. Necesita su dominio de OneLogin. |
| **JumpCloud** | OIDC | Inicio de sesión con una cuenta de JumpCloud. |
| **DATEV** | OIDC | Inicio de sesión con una cuenta de DATEV (asesores fiscales y sus clientes). |
| **Criipto** | OIDC | Identificaciones electrónicas europeas (MitID, BankID, itsme y más) a través de una única conexión con su tenant de Criipto. |
| **Signicat** | OIDC | Identificaciones electrónicas europeas a través de una única conexión con su cuenta de Signicat. |
| **German eID (Online-Ausweis)** | OIDC | Inicio de sesión con el documento de identidad alemán mediante AusweisIDent. |

**Sociales y de consumo** (cada uno se configura una sola vez): Amazon, Apple, Basecamp, Bitbucket, Box, DigitalOcean, Discord, Docusign, Dropbox, Facebook, Figma, Fitbit, FreshBooks, GitHub, GitLab, Google, Hugging Face, Intuit (QuickBooks), Kakao, Klarna, LINE, LinkedIn, Microsoft account, netID, PayPal, Salesforce, Slack, SoundCloud, Spotify, Strava, TikTok, Twitch, Vimeo, WordPress.com, X, Xero e Yahoo.

Las conexiones OIDC y SAML genéricas pueden configurarse más de una vez (para varios proveedores distintos); cada proveedor con nombre se configura una sola vez. Con el tiempo se añaden nuevos proveedores, así que la pantalla de creación es la lista autorizada.

La lista de conexiones muestra un aviso cuando alcanza el límite de conexiones de su plan; vacíe o elimine una conexión para poder añadir otra.

[Image: La lista de conexiones con tres Identity Providers configurados]

## Añadir una conexión

1. En la página Conexiones, elija **Crear conexión** y seleccione un proveedor.
2. Revise los **requisitos previos** que muestra la conexión, por ejemplo registrar una aplicación en el proveedor externo para obtener un client ID y un secret, y confirme.
3. Complete el formulario de configuración (véase más abajo).
4. Guarde. Las conexiones nuevas se crean en estado **Nunca**; actívelas cuando quiera que aparezcan en la pantalla de inicio de sesión.

### Campos de configuración

Cada conexión necesita un **Nombre** y un **Directorio** de destino, el directorio en el que se colocan los usuarios nuevos creados a través de esta conexión. Consulte [Directorios de usuarios](https://dts-identity.com/es/docs/directories/user-directories.md).

Los campos específicos de cada protocolo son:

- **OIDC genérico**: la URL de discovery (configuración) del proveedor, un client ID, un client secret y los scopes que se solicitan (de forma predeterminada `openid profile email`). La URL de discovery se lee cada vez, de modo que la conexión recoge los endpoints y las claves del proveedor sin que tenga que volver a introducirlos.
- **Microsoft Entra**: un client ID, un client secret y el **tenant ID** (o `common` para multi-tenant). Los endpoints del proveedor proceden del documento de discovery de Microsoft para ese tenant.
- **Okta**: un client ID, un client secret y su **dominio de Okta** (por ejemplo `acme.okta.com`, una org de preview o un dominio personalizado). Cree una OIDC Web Application en la Okta Admin Console y asígnela a los usuarios que deban iniciar sesión.
- **Auth0**: un client ID, un client secret y su **dominio de Auth0** (por ejemplo `acme.eu.auth0.com`, o un dominio personalizado). Cree una Regular Web Application en el Auth0 Dashboard.
- **Ping Identity (PingOne)**: un client ID, un client secret, el **host de PingOne** (el host regional, como `auth.pingone.com` o `auth.pingone.eu`, o un dominio personalizado) y el **ID de entorno**.
- **Keycloak**: un client ID, un client secret, la **URL del servidor** y el **realm**. En Keycloak 16 y anteriores, incluya la ruta base `/auth` en la URL del servidor. Active la autenticación de cliente para que el cliente sea confidencial.
- **OneLogin**: un client ID, un client secret y su **dominio de OneLogin** (por ejemplo `acme.onelogin.com`). Establezca el método de autenticación del endpoint de token de la aplicación en **POST**.
- **JumpCloud**: un client ID y un client secret de una aplicación OIDC personalizada. Establezca su tipo de autenticación de cliente en **Client Secret Post**.
- **DATEV**: un client ID y un client secret de una app del DATEV Developer Portal, suscrita al producto «Login with DATEV». El acceso a producción se concede tras una revisión técnica.
- **Criipto**: el dominio de su tenant de Criipto (por ejemplo `acme.criipto.id` o un dominio personalizado), un client ID, un client secret y la identificación electrónica que se va a usar. Como la identificación electrónica es fija por conexión, añada una conexión por cada identificación electrónica que quiera ofrecer.
- **Signicat**: el dominio de su cuenta de Signicat (por ejemplo `acme.signicat.com`), un client ID, un client secret y la identificación electrónica que se va a usar. Añada una conexión por identificación electrónica.
- **German eID (Online-Ausweis)**: el entorno (producción o referencia) y un client ID y un client secret de AusweisIDent. AusweisIDent opera el servidor eID y custodia el certificado de autorización, de modo que la integración se realiza mediante OIDC estándar.
- **Kakao**: una clave de REST API (client ID) y un client secret. En la consola de Kakao Developers, habilite Kakao Login, active OpenID Connect en los ajustes avanzados (necesario para recibir un token de ID) y configure los elementos de consentimiento. El acceso a la dirección de correo electrónico requiere una Kakao Business App.
- **netID**: un client ID y un client secret de un servicio que registre en el portal para desarrolladores de netID. Un servicio nuevo empieza en un entorno aislado para usuarios de prueba autorizados; solicite su liberación para uso productivo.
- **Intuit (QuickBooks)**: un client ID y un client secret de una app del portal Intuit Developer. Las claves de producción se emiten después de que Intuit complete su evaluación de la app.
- **La mayoría de los proveedores sociales**: un client ID (a veces con otro nombre, por ejemplo el client ID de Slack, la key de Bitbucket, el application ID de GitLab o la integration key de Docusign) y un secret correspondiente. Siga la guía de configuración de cada proveedor para conocer los nombres exactos de los campos.
- **Proveedores con host o región**: Salesforce, GitLab y Docusign añaden un campo **host** (por ejemplo un My Domain de Salesforce, una instancia autogestionada de GitLab o el host de producción frente al de desarrollo de Docusign) para que la conexión apunte a la instancia correcta.
- **Apple**: un Services ID (el client ID), su team ID, el key ID y el contenido de la clave privada `.p8` que descarga de Apple. La clave privada se almacena cifrada y nunca se vuelve a mostrar; el client secret que exige Apple se genera automáticamente a partir de ella.
- **SAML genérico**: la URL de entrada (inicio de sesión) del proveedor, su Entity ID y su certificado de firma en formato PEM, introducidos directamente. La propia URL de retorno (ACS) y el Entity ID de la plataforma se muestran en la guía de configuración de la conexión para que los registre en el lado del proveedor.

Los secretos y las claves privadas se introducen en campos que permanecen vacíos al editar una conexión existente: deje vacío un campo de secreto para conservar el valor almacenado. Los secretos nunca se vuelven a mostrar en texto claro ni se escriben en los registros.

Al configurar la conexión, cada guía muestra además la **URL de retorno** que hay que registrar en el proveedor para que este dirija la respuesta de inicio de sesión de vuelta a esta plataforma.

### Enrutado por dominio de correo (Home Realm Discovery)

Active **Home realm discovery** en una conexión e introduzca uno o varios **Dominios de correo**. Cuando un usuario introduce una dirección de correo cuyo dominio coincide, se le envía directamente a ese proveedor en lugar de a la pantalla de contraseña, de modo que nadie tiene que elegir el botón «Iniciar sesión con…» correcto. Introduzca los dominios como una lista separada por comas (por ejemplo `acme.com, acme.co.uk`).

- Una conexión con dominios de correo definidos **no se muestra como botón** en la página de inicio de sesión; solo se llega a ella mediante el enrutado por dominio (o un enlace directo a la conexión). Así la pantalla de inicio de sesión se mantiene despejada cuando hay varios proveedores empresariales configurados.
- Un dominio puede asignarse a **una sola** conexión; guardar una segunda conexión con el mismo dominio se rechaza.
- Los usuarios cuyo dominio de correo no está enrutado, y los que inician sesión con un nombre de usuario, continúan hacia la pantalla de contraseña habitual.
- El correo se transmite a un proveedor OIDC como `login_hint`, de modo que el proveedor puede rellenarlo previamente y el usuario no tiene que introducirlo por segunda vez. Los proveedores SAML no lo reciben (una SAML Request de inicio de sesión no puede transportarlo de forma fiable).
- Cuando una aplicación inicia el inicio de sesión con una dirección de correo conocida (un `login_hint` de OIDC) en un dominio enrutado, el usuario se envía directamente al proveedor, sin ver antes la pantalla de inicio de sesión.
- Desactivar Home realm discovery (o vaciar sus dominios) devuelve el botón de la conexión a la página de inicio de sesión.

Si un proveedor enrutado está mal configurado temporalmente y necesita llegar a la pantalla de contraseña para una cuenta de ese dominio, añada `?noHrd=1` a la URL de inicio de sesión para omitir el enrutado en esa visita.

### Por qué se registra una app propia en el proveedor

Para cada conexión (un proveedor social como GitHub o LinkedIn, o uno empresarial como Okta o Microsoft Entra) se registra una aplicación OAuth *en el proveedor* y se indican aquí su client ID y su secret, en lugar de utilizar unos compartidos. Es algo deliberado:

- La pantalla de consentimiento muestra **su** nombre y **su** logotipo, no uno genérico.
- La app solicita exactamente los **scopes que usted necesita**.
- El retorno se dirige a **su propio dominio**, de modo que el cierre de sesión y el step-up de MFA se comportan correctamente.

La pantalla de requisitos previos de la conexión enumera lo que hay que registrar antes de empezar.

## Vinculación de cuentas

Cuando un usuario vuelve a través de una conexión, la plataforma lo reconoce por el identificador estable que proporciona el proveedor (no por el correo electrónico) y lo autentica en su cuenta vinculada, actualizando su nombre y su imagen a partir del proveedor.

Para evitar la apropiación de cuentas, si el proveedor comunica una dirección de correo que ya pertenece a **otra** cuenta no vinculada a esta conexión, el inicio de sesión se **rechaza** en lugar de fusionar ambas en silencio: no existe un paso de administración para «fusionar cuentas», y un correo entrante (especialmente si no está verificado) nunca se apodera de una cuenta existente. El correo de la conexión solo se adopta en una cuenta cuando la conexión es **de confianza**, el proveedor afirma que el correo está verificado y el dominio del correo no está reservado por otro directorio (véase la reserva de dominios de correo en [Directorios de usuarios](https://dts-identity.com/es/docs/directories/user-directories.md)).

## Creación de usuarios just-in-time

Cuando alguien inicia sesión por primera vez a través de una conexión y no existe ninguna cuenta que coincida, la plataforma crea una **just in time**:

- El nuevo usuario se coloca en el **Directorio** configurado en la conexión.
- Su perfil (nombre, correo, imagen) se toma del proveedor.
- No tiene contraseña y solo inicia sesión a través de esa misma conexión.

Cómo se activa la cuenta nueva depende de la opción **Fuente de confianza**:

- Si la conexión está marcada como de confianza *y* el proveedor afirma que el correo está verificado, la cuenta se activa de inmediato.
- En caso contrario, el usuario recibe un correo de activación y debe verificar su dirección antes de que la cuenta pase a estar activa.

Los proveedores sociales son de confianza de forma predeterminada; las conexiones OIDC y SAML genéricas no lo son, porque solo debería confiar en un claim de correo procedente de un proveedor que controle o haya verificado.

### Proveedores sin dirección de correo

Algunos proveedores no facilitan una dirección de correo (por ejemplo X, Strava, Fitbit, SoundCloud, Vimeo y TikTok). Las conexiones de identificación electrónica (Criipto, Signicat y el eID alemán) también devuelven un nombre verificado y un identificador nacional en lugar de un correo. Iniciar sesión con uno de ellos sigue funcionando y sigue creando una cuenta, pero esa cuenta no tiene correo: no se envía ningún correo de activación y no puede emparejarse por correo con una cuenta existente. El usuario puede añadir y verificar un correo más adelante en su portal de cuenta, lo que también habilita la recuperación por correo y cualquier opción multifactor basada en correo.

Unos pocos proveedores devuelven un correo que no verifican (Spotify, por ejemplo). Ese correo se almacena en la cuenta nueva, pero se trata como no verificado y nunca se adopta en otra cuenta existente, de modo que la cuenta sigue sus reglas de verificación habituales.

### Apple

Apple devuelve el nombre del usuario **solo en el primer inicio de sesión**, así que un usuario de Apple que regresa conserva el nombre capturado entonces. Los usuarios que eligen la opción **Hide My Email** de Apple inician sesión con una dirección de retransmisión privada, lo que funciona con normalidad. La clave privada `.p8` que introduce se almacena cifrada y solo se utiliza para generar el client secret de corta duración que exige Apple.

## Ajustes por conexión

| Ajuste | Efecto |
|---|---|
| **Nombre** | La etiqueta que se muestra en la Admin Console y en el registro de auditoría. |
| **Directorio** | Dónde se crean los usuarios just-in-time. |
| **Home realm discovery** | Cuando está activo, los dominios de correo enrutados a esta conexión. Un usuario que introduzca un correo con uno de esos dominios se envía directamente a este proveedor, y la conexión no se muestra como botón en la página de inicio de sesión. Un dominio solo puede pertenecer a una conexión. |
| **Fuente de confianza** | Controla la activación automática y si se adopta el correo del proveedor. |
| **Activado** | Solo las conexiones activadas aparecen en la pantalla de inicio de sesión. |

Puede desactivar una conexión para retirarla de la pantalla de inicio de sesión sin eliminarla, o eliminarla por completo. Ambas acciones piden confirmación escribiendo el nombre de la conexión.

## Referencia

| Término | Significado |
|---|---|
| Conexión | Una delegación del inicio de sesión en un Identity Provider externo. |
| Vinculación de cuentas | El emparejamiento de una identidad federada que regresa con una cuenta existente. |
| Creación just-in-time (JIT) | La creación de una cuenta nueva en el primer inicio de sesión federado de un usuario. |
| Fuente de confianza | Una conexión cuyo claim de correo verificado la plataforma acepta para la activación automática. |
| Home Realm Discovery | El enrutado automático de un inicio de sesión hacia una conexión según el dominio de correo que introduce el usuario. |

## Solución de problemas

- **El proveedor devuelve un error en el retorno.** La causa más habitual es una URL de redirección (retorno) que no está registrada en el proveedor externo, o un client ID o secret que no coinciden. Registre la URL de retorno exacta que se mostró al crear la conexión y vuelva a comprobar las credenciales.
- **El intercambio de tokens falla con un error `invalid_client`.** Algunos proveedores (por ejemplo OneLogin y JumpCloud) fijan de forma predeterminada el método de autenticación del endpoint de token de la aplicación en Basic. Establézcalo en **POST** (client secret post) en los ajustes de la aplicación en el proveedor.
- **Los usuarios de un determinado dominio de correo se envían directamente a un proveedor externo.** Ese dominio está asignado a los dominios de correo de una conexión, lo que activa el enrutado por dominio (Home Realm Discovery). Quite el dominio de la conexión para dejar de enrutarlo. Para llegar una vez a la pantalla de contraseña (por ejemplo cuando el proveedor está mal configurado), añada `?noHrd=1` a la URL de inicio de sesión.
- **El inicio de sesión con Kakao falla o no devuelve ningún token de ID.** Kakao solo emite un token de ID cuando OpenID Connect está activado en los ajustes avanzados de Kakao Login de la app. Un elemento de consentimiento que falte también aborta el inicio de sesión; configure los elementos de consentimiento solicitados (apodo, imagen de perfil) en la consola de Kakao.
- **Un usuario que regresa aterriza en una cuenta nueva y vacía.** La vinculación de cuentas empareja una identidad federada con una cuenta existente por el correo verificado. Si el proveedor no devuelve un correo verificado, o el correo difiere del almacenado, no se encuentra ninguna coincidencia y se crea una cuenta aparte. Confirme que el proveedor facilita un claim de correo verificado.
- **El primer inicio de sesión a través de una conexión se rechaza con un error de dominio.** El dominio del correo está reservado por otro directorio. Un dominio incluido en un directorio no puede reclamarse desde usuarios creados en otro sitio, incluido el inicio de sesión federado just-in-time. Traslade la reserva o utilice una dirección de un dominio no reservado.
- **Se crea un usuario federado, pero permanece inactivo.** Las cuentas nuevas se activan automáticamente solo en una conexión de confianza que devuelva un correo verificado. En las demás conexiones, la cuenta sigue sus reglas habituales de verificación y de ciclo de vida.

Consulte también el [glosario](https://dts-identity.com/es/docs/reference/glossary.md).
