Configurar proveedores de inicio de sesión
Las personas inician sesión en Excubius con la cuenta de su organización, de Microsoft Entra ID o de Google. Excubius nunca guarda una contraseña de directorio: recibe un token firmado del proveedor, lo valida y guarda la cuenta como el proveedor más el identificador de la persona en él, nunca solo como una dirección de correo electrónico. Esta guía muestra cómo registrar Excubius en cada proveedor y cómo decidir quién obtiene una cuenta.
Antes de empezar
- Conoce la dirección pública del servidor,
https://<primary name>. Todas las direcciones de redirección de esta guía empiezan por ella. A quien abre Excubius a través de un alias se le envía al nombre principal para iniciar sesión, así que basta con una dirección de redirección por proveedor. Consulta Configurar nombres y TLS. - Usa HTTPS. Microsoft Entra ID solo acepta
httpparalocalhost. - Necesitas acceso al archivo de configuración del servidor,
/opt/excubius/.env, o al instalador:sudo ./install.sh --reconfigurevuelve a pedir los valores de Entra ID. - Para activar o desactivar el inicio de sesión con Google necesitas el rol Superadministrador. Para elegir quién obtiene una cuenta en una entidad necesitas el rol Administrador de entidad en ella.
Cómo se decide un primer inicio de sesión
Los roles solo se asignan cuando se crea la cuenta o se acepta una invitación. Una cuenta existente inicia sesión con los roles que tiene, así que un rol que un administrador quitó no se vuelve a asignar en el siguiente inicio de sesión.
Registrar Excubius en Microsoft Entra ID
El inicio de sesión con Microsoft Entra ID forma parte de los planes Core, Pro y Enterprise.
Crea un registro de aplicación por instalación, para un solo inquilino. Los registros multiinquilino (common u organizations) no son compatibles.
- En el Microsoft Entra admin center, abre App registrations y selecciona New registration.
- Name: lo que las personas verán en la solicitud de consentimiento, por ejemplo el nombre con el que conocen el monitoreo.
- Supported account types: Accounts in this organizational directory only (single tenant).
- Redirect URI: plataforma Web,
https://<primary name>/api/v1/auth/entra/callback.
- En Overview, copia el Directory (tenant) ID y el Application (client) ID.
- En Certificates & secrets › Client secrets, selecciona New client secret y copia su Value, no su ID. Solo se muestra una vez. Anota la fecha de vencimiento: el inicio de sesión deja de funcionar cuando el secreto vence, así que crea el siguiente antes y reemplaza el valor.
- En Authentication, deja desactivados Access tokens e ID tokens para los flujos implícitos e híbridos, y deja vacío Front-channel logout URL. Excubius usa el flujo de código de autorización con PKCE.
- En API permissions, conserva los permisos delegados de Microsoft Graph
openid,profileyemail.User.Read, que se agrega de forma predeterminada, no causa problemas. Concede el consentimiento de administrador si tu inquilino no permite que los usuarios den su consentimiento. - En Token configuration, selecciona Add optional claim, tipo de token ID, notificación
email, y acepta el aviso que agrega el permisoemailde Graph. Sin ella, Excubius usapreferred_username, lo que funciona bien cuando los nombres principales de usuario son direcciones de correo electrónico. - Si quieres asignar roles a grupos del directorio, selecciona Add groups claim en Token configuration:
- Elige Groups assigned to the application y luego asigna los grupos en Enterprise applications › tu aplicación › Users and groups. Así los tokens son pequeños y solo llevan los grupos que asignas. Security groups también funciona.
- Para el token ID, elige Group ID. Excubius compara los ID de objeto de los grupos; los nombres no coinciden.
- Un token lleva como máximo 200 grupos. Por encima de esa cantidad, Entra ID no envía ningún grupo, y Excubius trata a la persona como si no tuviera ningún grupo del directorio.
- Si quieres, en Enterprise applications › tu aplicación › Properties, establece Assignment required? en Yes. Así, solo los usuarios y grupos asignados a la aplicación pueden iniciar sesión, antes de que Excubius aplique sus propias reglas.
Ahora entrega los valores a Excubius:
-
Conéctate al servidor, cambia a la cuenta de servicio con
sudo -iu excubiusy agrega los tres valores a/opt/excubius/.env:ENTRA_TENANT_ID=8f6a1c2e-4b3d-4e5f-9a8b-7c6d5e4f3a2bENTRA_CLIENT_ID=11111111-2222-3333-4444-555555555555ENTRA_CLIENT_SECRET=<the secret value> -
Reinicia la plataforma:
export XDG_RUNTIME_DIR=/run/user/$(id -u)systemctl --user restart excubius.service
La página de inicio de sesión muestra Iniciar sesión con Microsoft cuando los tres valores están configurados. El secreto de cliente solo se lee del archivo de configuración: nunca se escribe en la base de datos, nunca lo devuelve la API y nunca se registra.
Registrar Excubius en Google
- En la Google Cloud console, abre Google Auth Platform.
- Audience: Internal cuando todos tienen una cuenta de Google Workspace de tu organización; External en caso contrario. Publica la aplicación, o agrega usuarios de prueba mientras pruebas.
- Data access: los ámbitos
openid,.../auth/userinfo.emaily.../auth/userinfo.profile.
- En Clients, selecciona Create client, tipo Web application, y agrega el URI de redirección autorizado
https://<primary name>/api/v1/auth/google/callback. No necesitas orígenes de JavaScript. - Copia el Client ID y el Client secret en
/opt/excubius/.envcomoGOOGLE_CLIENT_IDyGOOGLE_CLIENT_SECRET, y reinicia la plataforma como en los pasos de Entra ID. - Comprueba que la función
access.google_loginesté activada en Configuración › Instancia. Está activada de forma predeterminada.
La página de inicio de sesión muestra Iniciar sesión con Google. Mientras access.google_login está desactivada, el inicio de sesión con Google se rechaza, no solo se oculta.
Cualquiera puede crear una cuenta personal de Google con cualquier dirección de correo electrónico en la que reciba correo. Por eso, un inicio de sesión con Google solo cuenta para un dominio permitido cuando Google es la autoridad de la dirección: una cuenta de Google Workspace de ese mismo dominio, con una dirección verificada. Las cuentas personales de Google siempre necesitan una invitación, y para una invitación Google debe indicar que la dirección está verificada.
Elegir quién obtiene una cuenta
Cada entidad tiene un modo de registro que se aplica a ella y a todo lo que está debajo, hasta que una entidad inferior configura el suyo.
| Modo | Un primer inicio de sesión sin invitación | Rol asignado |
|---|---|---|
| Por invitación (el predeterminado) | Se rechaza | — |
| Dominios permitidos | Se acepta cuando el dominio de la dirección de correo electrónico está en la lista. La coincidencia es exacta; los subdominios no cuentan | El Rol predeterminado (Lector salvo que elijas otro; nunca Superadministrador) en la entidad que configura el registro, heredado hacia abajo como cualquier rol |
Para configurarlo:
- Abre Configuración › Usuarios y roles y elige la entidad en el selector, por ejemplo Ciguapa Inc..
- Selecciona la pestaña Registro. La página indica de dónde viene la configuración actual: de esta entidad, de una entidad superior o de la instalación.
- Elige Por invitación o Dominios permitidos.
- Para Dominios permitidos, escribe los Dominios, separados por comas o espacios (hasta 50), por ejemplo
ciguapa.example, y elige el Rol predeterminado. - Selecciona Guardar.
Para que una entidad inferior vuelva a seguir a su padre, selecciona Volver a heredar.
- Una persona cuyo dominio está permitido en varias entidades obtiene el rol predeterminado de cada una.
- En la entidad raíz, la configuración
ALLOWED_SIGNUP_DOMAINSde la instalación se aplica hasta que se guarda un registro allí. Equivale a Dominios permitidos con esos dominios y el rol Lector en la raíz. Guardar el registro de la raíz, aunque sea como Por invitación, la reemplaza. - Una entidad configurada como Por invitación deja de asignar roles por dominio ella misma, pero no puede quitar un rol heredado del registro de un ancestro.
- Para impedir el acceso a alguien, desactiva a la persona. Quitar el dominio no afecta a las cuentas existentes. Consulta Administrar usuarios y roles.
Invitaciones e inicio de sesión
Una invitación es un enlace, https://<primary name>/invite/<token>, que un administrador de entidad crea para una dirección de correo electrónico, un rol y una entidad; consulta Invitar a alguien. Cuando la persona lo abre:
- La página muestra la entidad, el rol, quién la invitó y una dirección enmascarada, y luego los botones de inicio de sesión. Se pide al proveedor que preseleccione la dirección invitada.
- La dirección de la cuenta con la que inicia sesión debe ser la invitada, sin distinguir mayúsculas de minúsculas.
- Se crea la cuenta, o se vincula una cuenta existente del mismo proveedor, y se asigna el rol en la entidad invitada. Si allí ya tenía un rol inferior, se eleva; uno superior se conserva.
- Si vuelve a abrir el enlace más adelante, simplemente inicia sesión.
Cuando se rechaza el inicio de sesión
El navegador vuelve a la página de inicio de sesión con una explicación sencilla, y cada rechazo se escribe en el registro de auditoría como login.failed con su motivo.
| Código | Significado | Qué hacer |
|---|---|---|
not_invited | No hay invitación y ninguna entidad acepta el registro por dominio; o el enlace de invitación es desconocido | Invita a la persona o permite su dominio |
domain_not_allowed | Existe registro por dominio, pero no para este dominio, o el proveedor no es la autoridad de ese dominio, como ocurre con una cuenta personal de Google | Agrega el dominio o invita a la persona |
account_disabled | La cuenta existe y está desactivada | Actívala en Usuarios y roles |
email_mismatch | La dirección de la cuenta no es la invitada, o Google no la verificó | Inicia sesión con la cuenta invitada, o invita a la dirección correcta |
invite_expired | La invitación venció, u otra persona ya la usó | Envía una invitación nueva |
invalid_state | El inicio de sesión tardó más de 10 minutos, se empezó en otro navegador o pestaña, o la respuesta no coincidía con la solicitud | Empieza de nuevo desde la página de inicio de sesión |
provider_error | El proveedor rechazó la solicitud (consentimiento denegado o cancelado), no está configurado o está desactivado, o su respuesta no pasó la validación | Revisa la configuración del proveedor descrita más arriba y la entrada auth.login_refused del registro del backend |
Cerrar la sesión de Excubius no cierra la sesión de la persona en Microsoft ni en Google.