Esta página es una traducción automática de la página en inglés, que es la versión de referencia. Leer la página en inglés
Proveedores de inicio de sesión externos
Un proveedor de inicio de sesión externo permite a los usuarios iniciar sesión con una cuenta que tienen en otro lugar: un proveedor OpenID Connect
(Google Workspace, Microsoft Entra ID, Keycloak y similares), GitHub, Discord o un servidor de Mastodon.
Configuras los proveedores con el comando my login-provider en un host que tenga la configuración del servidor, o mediante la
API de administración (/api/v1/admin/login_providers) con el permiso manage_login_providers, que solo tiene el rol integrado
admin. El comando funciona antes de que ningún administrador pueda iniciar sesión, así que puedes usarlo para la primera configuración.
En el cliente web, los administradores con ese permiso usan «Proveedores de inicio de sesión» en el menú de administración. La lista
muestra el tipo de cada proveedor, su estado, cuántos usuarios están vinculados y si se permite el registro, bajo un resumen del
límite a los proveedores de inicio de sesión mientras está activado; «Añadir un proveedor de inicio de sesión» abre el formulario que
crea uno. Al elegir un proveedor se abre su página, que muestra su URL de callback con un botón que la copia, y donde
cambias sus ajustes, lo activas o desactivas y le das un secreto de cliente nuevo, todo guardado con un solo botón, y lo eliminas, lo que
pide escribir su nombre.
Qué hace el inicio de sesión externo
Sección titulada «Qué hace el inicio de sesión externo»- Un proveedor solo demuestra quién es alguien en ese proveedor. Una cuenta nunca se vincula a un usuario por su dirección de correo electrónico: un usuario vincula una cuenta en «Cuentas vinculadas» de la configuración, o se registra con ella como usuario nuevo. Una dirección de correo electrónico que coincide con la de un usuario existente nunca vincula a ese usuario.
- Un usuario vinculado sigue introduciendo el código de dos factores (TOTP) tras iniciar sesión con un proveedor, y un usuario cuya cuenta no está activa no puede iniciar sesión.
- Los usuarios nuevos pueden registrarse con un proveedor solo cuando lo permites para ese proveedor (
-allow-signup) y el modo de registro les deja registrarse; el código de invitación, el CAPTCHA, los bloqueos de registro y el límite de red se aplican igual que en el formulario de contraseña. Quien se registra así no tiene contraseña e inicia sesión solo con el proveedor. El diagrama de las vías de registro muestra ambas formas de registrarse lado a lado.
| Tipo | -issuer |
Condiciones |
|---|---|---|
oidc |
La URL del emisor (https), exactamente como la nombran los tokens de ID del proveedor, como https://accounts.google.com |
-claim <claim>=<value>: solo los usuarios cuyo token de ID tiene la reclamación con uno de los valores indicados para ella |
github |
Ninguno: el servidor conoce los endpoints de github.com | -org <organization>: solo los miembros de una de las organizaciones (añade -scope read:org) |
discord |
Ninguno: el servidor conoce los endpoints de discord.com | -guild <server ID>: solo los miembros de uno de los servidores de Discord (guilds); si no se indica ninguno, entra cualquier usuario de Discord |
mastodon |
El dominio web del servidor, como mastodon.example (Mastodon 4.3 o posterior) |
Ninguna |
Para Google Workspace, limita los usuarios a tu organización con -claim hd=<your domain>. No te fíes del dominio de la
dirección de correo electrónico.
Ejemplos
Sección titulada «Ejemplos»En la consola de Google Cloud, crea un cliente OAuth de tipo «Web application». Para limitarlo a tu organización, establece el
tipo de usuario de la pantalla de consentimiento de OAuth en «Internal» (disponible cuando el proyecto pertenece a una organización
de Google Workspace), y añade también la condición hd: el tipo de usuario restringe a quién deja entrar Google, y la condición hace que este
servidor compruebe la reclamación hd de cada token de ID.
printf '%s\n' "$CLIENT_SECRET" | my login-provider create -kind oidc -name Google \ -issuer https://accounts.google.com -client-id 123.apps.googleusercontent.com -claim hd=example.comKeycloak y otros proveedores OpenID Connect
Sección titulada «Keycloak y otros proveedores OpenID Connect»El emisor es la URL del realm, como https://sso.example.com/realms/main, exactamente como la nombran los tokens de ID del proveedor.
Crea un cliente confidencial con el flujo estándar y los ámbitos openid, email y profile. Si el proveedor
está en una red privada, inclúyelo en login_provider_allowed_destinations (más abajo).
Usa -claim para exigir una reclamación, como una reclamación de grupo, con uno de los valores indicados.
Discord
Sección titulada «Discord»Crea una aplicación en el Portal de desarrolladores de Discord, abre «OAuth2» y
entrega al servidor el ID de cliente y el secreto de cliente. El servidor pide los ámbitos identify y email, y también
guilds cuando indicas servidores con -guild. Un usuario se identifica por su ID numérico de Discord; el nombre de usuario y el nombre visible
solo sugieren el nombre de usuario en el formulario de registro. La dirección de correo electrónico se considera verificada solo cuando Discord dice que está
verificada; de lo contrario, el usuario la confirma por correo como cualquier otra dirección.
Con -guild, el servidor comprueba en cada inicio de sesión, registro y vinculación que el usuario pertenece a uno de los servidores indicados
y, si no, lo rechaza. Sin él, cualquier usuario de Discord puede iniciar sesión. Un ID de guild es un número de hasta 20 dígitos: en
Discord, activa el «Developer Mode» (User Settings, Advanced), luego haz clic con el botón derecho en el icono del servidor y elige «Copy Server
ID».
printf '%s\n' "$DISCORD_SECRET" | my login-provider create -kind discord -name Discord \ -client-id 123456789012345678 -guild 987654321098765432Añade la URL de retorno en «OAuth2», «Redirects» de la aplicación, después de que add la muestre.
Crea una OAuth App (Settings, Developer settings, OAuth Apps) y entrégale el ID de cliente y el secreto. El servidor pide
el ámbito user:email, y también read:org cuando indicas organizaciones con -org. Con -org, el servidor comprueba
en cada inicio de sesión que el usuario pertenece a una de las organizaciones, de modo que los miembros de otras organizaciones son rechazados.
Configurar un proveedor
Sección titulada «Configurar un proveedor»El URI de redirección que necesita el proveedor es la URL de retorno del proveedor, https://<host>/auth/external/<id>/callback,
que contiene el ID que el servidor asigna al proveedor. Por tanto:
- Registra un cliente OAuth en el proveedor (una «OAuth App» en GitHub) con cualquier URI de redirección por ahora, y anota el ID de cliente y el secreto de cliente que te dé.
- Ejecuta
my login-provider createcon ellos. Muestra la URL de retorno. - Cambia el URI de redirección del cliente en el proveedor a esa URL de retorno.
# The client secret is read from standard input, or prompted for in a terminal.printf '%s\n' "$CLIENT_SECRET" | my login-provider create -kind oidc -name "Example SSO" \ -issuer https://sso.example.com -client-id my-client-id -claim hd=example.comprintf '%s\n' "$GITHUB_SECRET" | my login-provider create -kind github -name GitHub \ -client-id Iv1.0123456789abcdef -org example-org -scope read:orgMastodon
Sección titulada «Mastodon»Un proveedor mastodon es un servidor de Mastodon que tú nombras; los usuarios de otros servidores no pueden iniciar sesión con él. El servidor
debe ser Mastodon 4.3 o posterior: add lee los metadatos de su servidor de autorización
(/.well-known/oauth-authorization-server) y rechaza un servidor que no los tenga. Sin -client-id, add registra un cliente
en el propio servidor, con la URL de retorno y el ámbito profile, y guarda el ID de cliente y el secreto que obtiene, de modo que
no hay nada que hacer en el servidor:
my login-provider create -kind mastodon -name mastodon.example -issuer mastodon.exampleSi el servidor no deja que otros registren clientes, add falla. En ese caso, crea una aplicación con el ámbito profile y la
URL de retorno en las configuraciones de desarrollo del servidor, y entrega su ID de cliente y su secreto como para los demás tipos
(la URL de retorno contiene el ID del proveedor, así que sigue los tres pasos anteriores).
Los usuarios inician sesión solo con el ámbito profile, que lee su cuenta y nada más. Mastodon no entrega ninguna dirección de correo electrónico,
así que quien se registra con él confirma la dirección por correo. El formulario de registro sugiere el nombre de usuario de la cuenta.
Mientras el dominio del servidor, o un dominio superior, tenga una acción de dominio (acciones de dominio), su botón desaparece y
nadie inicia sesión, se registra ni vincula una cuenta con él. El servidor de un proveedor no cambia; configura un proveedor nuevo
para otro servidor.
El secreto de cliente se guarda cifrado con la clave de cifrado de claves (gestión de claves) y nunca se vuelve a mostrar, ni con el comando ni con la API de administración.
Un proveedor nuevo está activado. Por defecto, los usuarios pueden vincular su cuenta existente a él (-allow-link), pero nadie puede registrarse
con él: añade -allow-signup para que los usuarios nuevos puedan registrarse con él, algo que el modo de registro sigue limitando
(registro).
Cambiar, rotar, desactivar y eliminar
Sección titulada «Cambiar, rotar, desactivar y eliminar»my login-provider list # every provider with its callback URL and linked usersmy login-provider set -name "Corp SSO" <id> # changes only the settings it namesmy login-provider set -claim '' <id> # '' removes every -claim (or -scope, -org)my login-provider rotate-secret <id> # reads the new client secret like addmy login-provider disable <id>my login-provider enable <id>my login-provider delete <id>setcambia solo las configuraciones que nombra.-scope,-claimy-orgreemplazan la lista entera. El tipo de un proveedor no cambia; configura un proveedor nuevo en su lugar.rotate-secretreemplaza el secreto de cliente por el que introduzcas. Rótalo primero en el proveedor y luego aquí.disableconserva el proveedor y las cuentas vinculadas a él, pero nadie inicia sesión, se registra ni vincula con él, y la página de inicio de sesión no lo muestra, hasta que ejecutesenable.disableydeletemuestran cuántos usuarios vinculados ya no pueden iniciar sesión con el proveedor y qué hace ahora la limitación a proveedores de inicio de sesión mientras su configuración está activada.deleteelimina el proveedor definitivamente.
Usuarios que inician sesión solo mediante un proveedor
Sección titulada «Usuarios que inician sesión solo mediante un proveedor»Desactivar o eliminar un proveedor no afecta a los usuarios. Un usuario que tiene una contraseña o una passkey, o tiene otra cuenta
vinculada, inicia sesión de ese modo, salvo que el inicio de sesión esté limitado a proveedores de inicio de sesión y otro
proveedor siga activado. Un usuario que no tiene nada de esto ya no puede iniciar sesión en absoluto: disable y delete muestran cuántos
usuarios vinculados pierden el proveedor, y el cliente web muestra el número en la confirmación. enable restablece a los
usuarios de un proveedor desactivado; un proveedor eliminado no puede volver.
Para recuperar a un usuario así, emite un enlace de restablecimiento de contraseña en la página de Gestión de la cuenta en las pantallas de administración, o con
my admin account password-reset-link @alice, y entrégaselo al usuario (registro).
Después, el usuario inicia sesión con la nueva contraseña.
Cada cambio se registra en el registro de auditoría con el nombre visible del proveedor, como la CLI o como el administrador que lo hizo mediante la API de administración.
Limitar el inicio de sesión a proveedores de inicio de sesión
Sección titulada «Limitar el inicio de sesión a proveedores de inicio de sesión»La configuración de instancia login_providers_only (desactivada por defecto) hace que los proveedores sean la única forma de iniciar sesión y registrarse,
mientras haya al menos un proveedor activado. Actívalo en la página «Registro» de «Configuración del servidor» del cliente web, o con la CLI:
my instance set login_providers_only trueLa confirmación del cliente web y la salida del comando indican cuántos usuarios locales activos no tienen vínculo con un proveedor activado. El cliente web indica también cuándo eso te incluye a ti. Avisa y no rechaza: decides tú.
Mientras la limitación se aplica:
- Las contraseñas y las passkeys no permiten iniciar sesión a nadie, y la página de inicio de sesión muestra solo los proveedores. También se rechaza un inicio de sesión que hubiera empezado con una contraseña o una passkey y esté esperando su código de dos factores.
- Nadie se registra con una contraseña. La página de registro muestra los proveedores que permiten registros (
-allow-signup), según el modo de registro como de costumbre. Si no hay ningún proveedor así, el registro figura comoclosed, también para los clientes y en NodeInfo. - Nadie solicita ni usa un enlace de restablecimiento de contraseña. Los enlaces siguen siendo válidos hasta que caducan y funcionan si la limitación termina a tiempo.
- Los usuarios no pueden establecer ni cambiar una contraseña, ni añadir una passkey, porque ninguna permitiría iniciar sesión. Sí pueden eliminarlas.
my admin account password-reset-linky las pantallas de administración siguen emitiendo un enlace, e indican que no funciona hasta que la limitación termine.my admin createsigue creando un administrador y avisa de que la contraseña no permite iniciar sesión.- Un usuario no puede desvincular su última cuenta de un proveedor activado.
Lo que sigue funcionando:
- Las sesiones, los tokens de acceso de aplicaciones y los tokens de actualización siguen siendo válidos. La limitación no termina ninguno.
- Una contraseña o una passkey siguen confirmando operaciones dentro de una sesión. Así es como un usuario existente pasa a un proveedor: con la sesión iniciada, abre «Cuentas vinculadas» en la configuración, confirma con la contraseña o la passkey e inicia sesión en el proveedor.
- El inicio de sesión, el registro y la vinculación en un proveedor, y el código de dos factores tras el inicio de sesión de un proveedor.
Cada rechazo se redacta igual sea cual sea la dirección de correo electrónico, la contraseña o el token enviados, por lo que no dice nada sobre ninguna cuenta.
Los usuarios sin vínculo no pueden iniciar sesión cuando sus sesiones terminan, hasta que actúes. Una cuenta nunca se vincula por la dirección de correo electrónico,
así que el inicio de sesión de un proveedor tampoco los encuentra. Pídeles que vinculen una cuenta mientras tienen la sesión iniciada. Un usuario que
perdió su sesión necesita que termines la limitación durante un tiempo, o que lo mantengas fuera. Esto incluye a un usuario con disable_login,
suspend o ban, que sin vínculo no tiene página de inicio de sesión desde la que apelar.
Vincular también requiere que el navegador tenga la sesión iniciada en las páginas de inicio de sesión: un usuario cuya aplicación sigue con la sesión iniciada, pero cuya sesión
de navegador terminó, no puede vincular mientras la limitación se aplica y tiene que esperar a que actúes. Anuncia el cambio a tus usuarios antes de
activar la limitación, para que vinculen una cuenta mientras sus sesiones duran.
Terminar la limitación
Sección titulada «Terminar la limitación»La limitación sigue a la configuración y a los proveedores de una petición a la siguiente, sin reiniciar.
-
Un administrador que se ha quedado fuera ejecuta esto en un host que tenga la configuración del servidor:
Ventana de terminal my instance set login_providers_only false -
Cuando no hay ningún proveedor activado, la limitación no se aplica: desactivar o eliminar el último proveedor vuelve a abrir el inicio de sesión con contraseña y passkey, diga lo que diga la configuración. Los usuarios sin contraseña ni passkey siguen necesitando un enlace de restablecimiento.
-
Con la configuración activada y ningún proveedor activado, configurar o activar un proveedor inicia la limitación de inmediato; un proveedor nuevo está activado en cuanto se configura. El cliente web avisa antes, con cuántos usuarios activos no tienen vínculo con ese proveedor y si eso te incluye a ti. Avisa solo ante la acción que iniciaría la limitación.
my login-provider create,enable,disableydeletemuestran qué hace ahora la limitación mientras la configuración está activada. -
Cuando una caída del proveedor deja fuera a todos, usa el mismo comando.
Reautenticación
Sección titulada «Reautenticación»Las operaciones que piden la contraseña o una passkey (establecer una contraseña, añadir una passkey, eliminar o mover la cuenta,
vincular otra cuenta) piden a un usuario que no tiene ninguna de las dos que vuelva a iniciar sesión en un proveedor vinculado (registro).
A un proveedor OpenID Connect se le pide que autentique de nuevo al usuario (max_age=0 y prompt=login) y el servidor
rechaza una autenticación anterior; a un servidor de Mastodon se le pide con force_login=true. GitHub y Discord no tienen forma de
pedir un inicio de sesión reciente, así que un usuario que sigue con la sesión iniciada allí queda confirmado sin introducir nada. El servidor sigue comprobando
que la cuenta es la vinculada, pero es una prueba más débil de que la persona está frente al teclado. Prefiere un proveedor OpenID
Connect, o haz que los usuarios conserven una contraseña o una passkey, cuando esto importe.
Proveedores en una red interna
Sección titulada «Proveedores en una red interna»El servidor llega a los proveedores a través de su protección de HTTP saliente, que rechaza las direcciones de bucle local y privadas. Para usar un
proveedor de tu propia red, como un Keycloak junto al servidor, incluye su host o rango de direcciones en
login_provider_allowed_destinations.
Para LLM y agentes de programación:llms.txt,llms-full.txt, llms-small.txt