Documentation
Aether
Connect Aether, the Scala Studios mail server, to Halo for sign-in, give its members roles from Halo groups, and optionally let Halo suspend and provision Aether accounts.
The examples use https://auth.example.com for Halo and https://mail.example.com for Aether.
Register Aether in Halo
-
In the console, open Applications and choose Add application.
-
Choose OpenID Connect and Continue.
-
Choose Web application and the Aether template, then Continue.
-
Enter the Aether address, the address people open Aether at, and the Provider slug Aether will use for Halo,
haloby default. The slug may contain lowercase letters, digits and hyphens. Halo builds the redirect URI and the post-logout URI from them:https://mail.example.com/api/v1/auth/oidc/halo/callback https://mail.example.com/loginThe template also sets the scopes Aether asks for:
openid,profile,emailandgroups. -
Choose Create application, and copy the client ID and the client secret. Halo shows the secret only once.
-
Choose Open application, go to Users & groups, choose Assign group, and pick the groups whose members may use Aether. Halo refuses to sign in anyone who is not assigned.
The application page in the console lists the values below with your issuer URL, slug and client ID filled in, under View setup guide right after creation and on the application's overview.
Connect it in Aether
-
In Aether, open Administration → Identity providers and choose Connect Halo.
-
Enter the values from Halo:
Field in Aether Value Issuer URL https://auth.example.comSlug halo, the provider slug you entered in HaloClient ID The client ID from Halo Client secret The client secret Halo showed once Aether fetches
https://auth.example.com/.well-known/openid-configurationand shows whether PKCE S256 and thegroupsclaim are available. Halo offers both. -
Optionally turn on Auto-provision, so Aether creates an account the first time someone signs in. If the person's verified email address belongs to a verified Aether domain, Aether also creates that mailbox and adds them to the domain's organization.
Aether matches a sign-in to an existing link for the provider and the person's sub first, then to an account with the same verified email address, and otherwise creates an account when auto-provisioning is on. Without a match, sign-in fails with not_provisioned.
Map groups to roles
Halo's groups claim lists the names of all of the person's groups. Aether has no other source of roles from Halo, so it maps group names:
- Administrator group: members of this Halo group become platform administrators in Aether.
- Group mappings: members of a Halo group get the mapped role, owner, admin or member, in an Aether organization.
Use the group names exactly as they appear in Halo's console. Mappings only grant or upgrade roles and never remove one. To take access away, change the role in Aether, or suspend the person in Halo.
Suspend accounts right away
Halo refuses tokens for suspended and deprovisioned people, so they cannot start a new Aether session, but a session they already have lasts up to 12 hours. To end it at once, send Halo's events to Aether:
-
In Halo, open Webhooks and choose Add endpoint, with the Webhook URL from the provider in Aether:
https://mail.example.com/api/v1/hooks/identity-providers/halo -
Choose the events
user.suspend,user.restore,scim.user.suspend,scim.user.deprovision,scim.user.restoreandsession.revoke. The setup guide in Halo suggests the familiesuser.*,scim.*andsession.*instead, which cover the same events and any added to those families later. -
Save, and paste the signing secret into Webhook signing secret on the provider in Aether.
Aether checks the Halo-Signature header and ignores repeated event ids. A suspend or deprovision event suspends the linked account, which ends its web sessions and stops its app passwords. A restore event restores the account only when Halo was what suspended it. session.revoke signs the account out everywhere. Halo has to reach Aether over the network, so an Aether on localhost cannot receive these events. Webhooks describes the deliveries and retries.
Provision accounts over SCIM
With SCIM, people have an Aether account before their first sign-in and lose it when they lose access, instead of waiting for them to sign in:
-
In Aether, open Administration → Identity providers, choose the people icon on the Halo provider, then Turn on SCIM. Copy the base URL and the bearer token; Aether shows the token once:
https://mail.example.com/api/v1/scim/halo -
In Halo, open Provisioning, find Aether under outbound provisioning and choose Set up. Enter the base URL and the token, turn on Push changes every 2 minutes, save, and choose Test.
-
Choose Sync now to push everyone assigned to the application right away.
Aether creates an account for each person, and the mailbox too when the address is on a verified domain, suspends the account when Halo deactivates it, and restores it when Halo activates it again, unless an Aether administrator suspended it. Groups are not provisioned; the group mappings above still apply when people sign in. Outbound SCIM describes what Halo pushes and when.
Check it
Open Aether's sign-in page and choose Halo. Aether opens signed in, and the sign-in appears in Halo's console under Sign-in logs. For errors, see troubleshooting.