All help articles

One sign-in for everything (single sign-on)

Webmail, the team manager at /manage and the admin panel all sign in with a Zappocity account: one email and password (at zappo.city) for every Zappocity product. Zappocity is a standard OpenID Connect provider, so later products (xi.ht) sign in the same way.

Turning it on

In the admin panel, Settings → Single sign-on → Connect to Zappocity (sudo corpsuite sso connect). That:

1. registers Mailocity with the Zappocity on the same server (under Products → Single sign-on applications), with its return addresses on every webmail, sign-in, team manager and admin host;
2. gives every mailbox and every staff member a Zappocity account with the same email and password, already confirmed, so nobody has to do anything (new mailboxes and staff get one within a minute);
3. turns single sign-on on. From then on, passwords sign in nowhere else: the sign-in pages show only Sign in with Zappocity, and mail apps need app passwords (see below). Tell people before you connect.

Run Connect again after adding a host name, so its return address is registered.

What people see

• Webmail and the team manager: Sign in with Zappocity goes to zappo.city's sign-in (or straight through when already signed in there) and back into their mailbox. Two-step sign-in belongs to the Zappocity account: a sign-in there with a code (or security key) needs nothing more. A mailbox's own two-step sign-in from before is not asked for: turn two-step sign-in on for the Zappocity account instead.
• The admin panel: staff sign in the same way. Their first sign-in through Zappocity links the staff member to the Zappocity account with their staff email; after that, that account signs them in even if its email changes (their staff email follows it), and another account that later has the old email does not. A staff member who makes a new Zappocity account is removed and added again.
• Mail apps (IMAP, SMTP, ManageSieve, CalDAV/CardDAV, JMAP apps) cannot use single sign-on: they sign in with an app password, made in webmail under Settings → App passwords. The mailbox password no longer works in them, and an app still signed in with it is signed out within a minute.

A Zappocity account opens a mailbox only once its email is confirmed. If someone signed up at Zappocity with a mailbox's address and never confirmed it, the mailbox's owner takes that account over at the next sync (with the mailbox's password) and whoever made it is signed out.

New accounts

While single sign-on is on, new accounts are made through zappo.city: the signup page and teams' join pages send people there to sign in, or to create their Zappocity account (with a confirmed email), and then they choose their address. The new mailbox has no password of its own and is linked to that Zappocity account. See Plans and signup and letting people join a team.

Mailboxes that team admins or staff add by hand still get the password they set, and a Zappocity account with it at the next sync, as before; the person signs in with it at zappo.city and can change it there.

Signing out

Signing out anywhere signs out everywhere that sign-in reached:

• Sign out in webmail, the team manager or the admin panel, after signing in with Zappocity, also signs out of zappo.city, and so out of every other product and help desk signed in to from that zappo.city session.
• Sign out on the account page (or on a help desk's own address) ends the zappo.city session and every webmail, panel and help desk session that came from it.
• Other sessions (another browser, another device) stay signed in; Sign out everywhere else on the account page ends those.
• Other apps that sign in with Zappocity can send people to https://zappo.city/oauth/logout (the discovery document's end_session_endpoint) to sign them out, with client_id and a post_logout_redirect_uri on the same site as one of the app's return addresses to come back to; anything else ends on the account page. ID tokens carry the session's sid.

Settings live in Zappocity

For a mailbox that signs in with Zappocity, webmail's Settings show mail settings only (mail apps, app passwords, addresses, plus addresses, signatures, spam, filters, import and the like), with a card linking to the Zappocity account for the password, two-step sign-in (codes, security keys and passkeys), where you are signed in, security alerts, recent sign-ins and invitations. Signing out everywhere there ends webmail sessions too.

Passwords while it is on

While single sign-on is on, everyone signs in through zappo.city:

• webmail, the team manager and the admin panel refuse passwords (their password forms are gone);
• mail apps take app passwords only, and the mailbox password is refused with "Sign in with an app password" (whether or not it was right);
• webmail refuses changing or resetting the mailbox password, a recovery address and the mailbox's two-step sign-in: those are the Zappocity account's, on its account page.

Making an app password asks you to confirm it's you on zappo.city (your password, and your code when two-step sign-in is on) unless you signed in there in the last 10 minutes: Confirm on Zappocity, then Make app password again. You stay signed in throughout.

There is no setting to open passwords again while single sign-on is on. Turning single sign-on off opens them (and if Zappocity cannot be reached, the command line on the server still works: sudo corpsuite sso set enabled:=false).

Good to know

• Turn on two-step sign-in for the Zappocity account (on the account page), especially for staff: it then protects every product signed in to through it. Webmail's Settings → Two-step sign-in links there for anyone who signs in with Zappocity; app passwords for mail apps stay in webmail.
• The mailbox password is not used while single sign-on is on: the Zappocity password is the one that counts.
• Other apps that sign in with Zappocity can ask for a fresh sign-in with prompt=login or max_age: zappo.city then asks the person to confirm it's them, in the session they have, and the ID token's auth_time is when they did.
• The provider uses the authorization code flow with PKCE (required), RS256 ID tokens, and single-use codes that expire after a minute (a code used twice revokes what it was exchanged for). Discovery is at https://zappo.city/.well-known/openid-configuration.
• Mailocity's return addresses (webmail's and the panels' sign-in callbacks on every host name that serves them) are registered when you connect, and kept up to date afterwards: setting or changing a portal host name (webmail, sign-in, either panel, Zappocity) registers it at once, and the server checks again each time it starts.
• "This sign-in link is not valid: the return address ... is not registered" means the page was opened on an address Zappocity does not know, such as a host name not set in Settings → Host names and HTTPS, or a different port. Open the page at its usual address, or add the host name to the settings. The server log names the address it refused.
• Applications outside this server register under Products → Single sign-on applications (corpsuite zappocity sso client add) with their exact return addresses; their secret is shown once.