Saltar al contenido principal
Versión: 0.4 · actual

Configurar proveedores de inicio de sesión

Guía paso a pasoRevisada el 11 de octubre de 2026
Se aplica a:Excubius 0.4Roles: Instalador (administrador de Linux), Superadministrador, Administrador de entidad
PlanesFree · Core · Pro · EnterpriseImplementaciónEn tus servidores

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 http para localhost.
  • Necesitas acceso al archivo de configuración del servidor, /opt/excubius/.env, o al instalador: sudo ./install.sh --reconfigure vuelve 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​

Plan

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.

  1. 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.
  2. En Overview, copia el Directory (tenant) ID y el Application (client) ID.
  3. 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.
  4. 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.
  5. En API permissions, conserva los permisos delegados de Microsoft Graph openid, profile y email. 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.
  6. En Token configuration, selecciona Add optional claim, tipo de token ID, notificación email, y acepta el aviso que agrega el permiso email de Graph. Sin ella, Excubius usa preferred_username, lo que funciona bien cuando los nombres principales de usuario son direcciones de correo electrónico.
  7. 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.
  8. 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:

  1. Conéctate al servidor, cambia a la cuenta de servicio con sudo -iu excubius y agrega los tres valores a /opt/excubius/.env:

    ENTRA_TENANT_ID=8f6a1c2e-4b3d-4e5f-9a8b-7c6d5e4f3a2b
    ENTRA_CLIENT_ID=11111111-2222-3333-4444-555555555555
    ENTRA_CLIENT_SECRET=<the secret value>
  2. 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​

  1. 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.email y .../auth/userinfo.profile.
  2. 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.
  3. Copia el Client ID y el Client secret en /opt/excubius/.env como GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET, y reinicia la plataforma como en los pasos de Entra ID.
  4. Comprueba que la función access.google_login esté 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.

Google y los dominios permitidos

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.

ModoUn primer inicio de sesión sin invitaciónRol asignado
Por invitación (el predeterminado)Se rechaza—
Dominios permitidosSe acepta cuando el dominio de la dirección de correo electrónico está en la lista. La coincidencia es exacta; los subdominios no cuentanEl Rol predeterminado (Lector salvo que elijas otro; nunca Superadministrador) en la entidad que configura el registro, heredado hacia abajo como cualquier rol

Para configurarlo:

  1. Abre Configuración › Usuarios y roles y elige la entidad en el selector, por ejemplo Ciguapa Inc..
  2. 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.
  3. Elige Por invitación o Dominios permitidos.
  4. Para Dominios permitidos, escribe los Dominios, separados por comas o espacios (hasta 50), por ejemplo ciguapa.example, y elige el Rol predeterminado.
  5. 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_DOMAINS de 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ódigoSignificadoQué hacer
not_invitedNo hay invitación y ninguna entidad acepta el registro por dominio; o el enlace de invitación es desconocidoInvita a la persona o permite su dominio
domain_not_allowedExiste 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 GoogleAgrega el dominio o invita a la persona
account_disabledLa cuenta existe y está desactivadaActívala en Usuarios y roles
email_mismatchLa 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_expiredLa invitación venció, u otra persona ya la usóEnvía una invitación nueva
invalid_stateEl 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 solicitudEmpieza de nuevo desde la página de inicio de sesión
provider_errorEl proveedor rechazó la solicitud (consentimiento denegado o cancelado), no está configurado o está desactivado, o su respuesta no pasó la validaciónRevisa 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.