Set up sign-in providers
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
httponly forlocalhost. - You need access to the server's configuration file,
/opt/excubius/.env, or to the installer:sudo ./install.sh --reconfigureasks 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
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.
- 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.
- On Overview, copy the Directory (tenant) ID and the Application (client) ID.
- 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.
- 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.
- Under API permissions, keep the Microsoft Graph delegated permissions
openid,profileandemail.User.Read, added by default, does no harm. Grant admin consent if your tenant does not let users consent themselves. - Under Token configuration, select Add optional claim, token type ID, claim
email, and accept the prompt that adds the Graphemailpermission. Without it Excubius usespreferred_username, which is fine when user principal names are e-mail addresses. - 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.
- 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:
-
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-7c6d5e4f3a2bENTRA_CLIENT_ID=11111111-2222-3333-4444-555555555555ENTRA_CLIENT_SECRET=<the secret value> -
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
- 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.emailand.../auth/userinfo.profile.
- 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. - Copy the Client ID and the Client secret into
/opt/excubius/.envasGOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRET, then restart the platform as in the Entra ID steps. - Check that the feature
access.google_loginis 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.
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.
| Mode | A first sign-in without an invitation | Role given |
|---|---|---|
| By invitation (the default) | Refused | — |
| Allowed domains | Accepted when the e-mail address's domain is in the list. The match is exact; subdomains do not count | The 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:
- Open Settings › Users and roles and choose the entity in the picker, for example Ciguapa Inc..
- Select the Registration tab. The page says where the current setting comes from: this entity, an entity above it, or the installation.
- Choose By invitation or Allowed domains.
- For Allowed domains, enter the Domains, separated by commas or spaces (up to 50), for example
ciguapa.example, and choose the Default role. - 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_DOMAINSsetting 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.
| Code | Meaning | What to do |
|---|---|---|
not_invited | No invitation, and no entity accepts sign-up by domain; or the invitation link is unknown | Invite the person, or allow their domain |
domain_not_allowed | Sign-up by domain exists, but not for this domain, or the provider is not authoritative for it, as with a personal Google account | Add the domain, or invite the person |
account_disabled | The account exists and is deactivated | Activate it in Users and roles |
email_mismatch | The account's address is not the invited one, or Google did not verify it | Sign in with the invited account, or invite the right address |
invite_expired | The invitation expired, or someone else already used it | Send a new invitation |
invalid_state | The sign-in took more than 10 minutes, was started in another browser or tab, or the answer did not match the request | Start again from the sign-in page |
provider_error | The provider refused (consent denied or cancelled), is not configured or is switched off, or its answer failed validation | Check 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.