Skip to main content
Version: 0.4 · current

Set up sign-in providers

How-to guideReviewed October 11, 2026
Applies to:Excubius 0.4Roles: Installer (Linux administrator), Super admin, Entity admin
PlansFree · Core · Pro · EnterpriseDeploymentSelf-hosted

People sign in to Excubius with their organisation's account, from Microsoft Entra ID or Google. Excubius never stores a directory password: it receives a signed token from the provider, checks it, and keeps the account as the provider plus the person's identifier there, never as an e-mail address alone. This guide shows how to register Excubius with each provider and how to decide who gets an account.

Before you begin​

  • Know the server's public address, https://<primary name>. Every redirect address below starts with it. People who open Excubius through an alias are sent to the primary name to sign in, so one redirect address per provider is enough. See Set up names and TLS.
  • Use HTTPS. Microsoft Entra ID accepts http only for localhost.
  • You need access to the server's configuration file, /opt/excubius/.env, or to the installer: sudo ./install.sh --reconfigure asks the Entra ID values again.
  • To switch Google sign-in on or off you need the Super admin role. To choose who gets an account on an entity you need Entity admin on it.

How a first sign-in is decided​

Roles are given only when the account is created or an invitation is accepted. An existing account signs in with the roles it has, so a role an administrator removed is not given back at the next sign-in.

Register Excubius in Microsoft Entra ID​

Plan

Sign-in with Microsoft Entra ID is part of the Core, Pro and Enterprise plans.

Create one app registration per installation, for a single tenant. Multi-tenant registrations (common or organizations) are not supported.

  1. In the Microsoft Entra admin center, open App registrations and select New registration.
    • Name: what people will see on the consent prompt, for example the name they know the monitoring by.
    • Supported account types: Accounts in this organizational directory only (single tenant).
    • Redirect URI: platform Web, https://<primary name>/api/v1/auth/entra/callback.
  2. On Overview, copy the Directory (tenant) ID and the Application (client) ID.
  3. Under Certificates & secrets › Client secrets, select New client secret and copy its Value, not its ID. It is shown only once. Note the expiry date: sign-in stops when the secret expires, so create the next one before then and replace the value.
  4. Under Authentication, leave Access tokens and ID tokens for implicit and hybrid flows off, and leave Front-channel logout URL empty. Excubius uses the authorization code flow with PKCE.
  5. Under API permissions, keep the Microsoft Graph delegated permissions openid, profile and email. User.Read, added by default, does no harm. Grant admin consent if your tenant does not let users consent themselves.
  6. Under Token configuration, select Add optional claim, token type ID, claim email, and accept the prompt that adds the Graph email permission. Without it Excubius uses preferred_username, which is fine when user principal names are e-mail addresses.
  7. Optionally, to give roles to directory groups, select Add groups claim under Token configuration:
    • Choose Groups assigned to the application, then assign the groups under Enterprise applications › your app › Users and groups. This keeps tokens small and carries only the groups you map. Security groups also works.
    • For the ID token, choose Group ID. Excubius matches group object IDs; names do not match.
    • A token carries at most 200 groups. Beyond that Entra ID sends no groups, and Excubius treats the person as having no directory groups at all.
  8. Optionally, under Enterprise applications › your app › Properties, set Assignment required? to Yes. Then only users and groups assigned to the application can sign in, before Excubius applies its own rules.

Now give the values to Excubius:

  1. Connect to the server, become the service account with sudo -iu excubius, and add the three values to /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. Restart the platform:

    export XDG_RUNTIME_DIR=/run/user/$(id -u)
    systemctl --user restart excubius.service

The sign-in page shows Sign in with Microsoft once all three values are set. The client secret is read only from the configuration file: it is never written to the database, never returned by the API and never logged.

Register Excubius with Google​

  1. In the Google Cloud console, open Google Auth Platform.
    • Audience: Internal when everyone has a Google Workspace account of your organisation; External otherwise. Publish the app, or add test users while you test.
    • Data access: the scopes openid, .../auth/userinfo.email and .../auth/userinfo.profile.
  2. Under Clients, select Create client, type Web application, and add the authorized redirect URI https://<primary name>/api/v1/auth/google/callback. You do not need JavaScript origins.
  3. Copy the Client ID and the Client secret into /opt/excubius/.env as GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, then restart the platform as in the Entra ID steps.
  4. Check that the feature access.google_login is on in Settings › Instance. It is on by default.

The sign-in page shows Sign in with Google. While access.google_login is off, Google sign-in is refused, not only hidden.

Google and allowed domains

Anyone can create a personal Google account with any e-mail address they receive mail at. A Google sign-in therefore counts for an allowed domain only when Google is authoritative for the address: a Google Workspace account of that very domain, with a verified address. Personal Google accounts always need an invitation, and for an invitation Google must report the address as verified.

Choose who gets an account​

Each entity has a registration mode that applies to it and to everything below it, until a lower entity sets its own.

ModeA first sign-in without an invitationRole given
By invitation (the default)Refused—
Allowed domainsAccepted when the e-mail address's domain is in the list. The match is exact; subdomains do not countThe Default role (Viewer unless you choose another; never Super admin) on the entity that sets the registration, inherited below it like any role

To set it:

  1. Open Settings › Users and roles and choose the entity in the picker, for example Ciguapa Inc..
  2. Select the Registration tab. The page says where the current setting comes from: this entity, an entity above it, or the installation.
  3. Choose By invitation or Allowed domains.
  4. For Allowed domains, enter the Domains, separated by commas or spaces (up to 50), for example ciguapa.example, and choose the Default role.
  5. Select Save.

To make a lower entity follow its parent again, select Inherit from above again.

  • A person whose domain is allowed on several entities gets the default role of each.
  • On the root entity, the installation's ALLOWED_SIGNUP_DOMAINS setting applies until a registration is saved there. It means Allowed domains with those domains and the Viewer role on the root. Saving the root's registration, even as By invitation, replaces it.
  • An entity set to By invitation stops granting roles by domain itself, but it cannot take away a role inherited from an ancestor's registration.
  • To shut someone out, deactivate the person. Removing the domain does not affect existing accounts. See Manage users and roles.

Invitations and sign-in​

An invitation is a link, https://<primary name>/invite/<token>, that an entity administrator creates for one e-mail address, a role and an entity; see Invite someone. When the person opens it:

  • The page shows the entity, the role, who invited them and a masked address, then the sign-in buttons. The provider is asked to preselect the invited address.
  • The address of the account they sign in with must be the invited one, compared without regard to case.
  • The account is created, or an existing account of the same provider is linked, and the role is given on the invited entity. An existing lower role there is raised; a higher one is kept.
  • Opening the link again later simply signs that person in.

When sign-in is refused​

The browser returns to the sign-in page with a plain explanation, and every refusal is written to the audit log as login.failed with its reason.

CodeMeaningWhat to do
not_invitedNo invitation, and no entity accepts sign-up by domain; or the invitation link is unknownInvite the person, or allow their domain
domain_not_allowedSign-up by domain exists, but not for this domain, or the provider is not authoritative for it, as with a personal Google accountAdd the domain, or invite the person
account_disabledThe account exists and is deactivatedActivate it in Users and roles
email_mismatchThe account's address is not the invited one, or Google did not verify itSign in with the invited account, or invite the right address
invite_expiredThe invitation expired, or someone else already used itSend a new invitation
invalid_stateThe sign-in took more than 10 minutes, was started in another browser or tab, or the answer did not match the requestStart again from the sign-in page
provider_errorThe provider refused (consent denied or cancelled), is not configured or is switched off, or its answer failed validationCheck the provider settings above and the backend log entry auth.login_refused

Signing out of Excubius does not sign the person out of Microsoft or Google.