Single sign-on
Your identity provider signs your team in to Trotta Mail, by SAML or OpenID Connect. Okta, Microsoft Entra ID, Google Workspace, JumpCloud and OneLogin each work with one or the other. Single sign-on is part of Enterprise.
#Before you start
- A domain you verified under Domains, such as
trotta.io. Single sign-on signs in addresses on the domains you bind to it, and no others. - The owner sets it up. Admins can read the settings and run a test. API keys cannot touch it.
- An authenticator app on the owner's account. Adding a connection, turning one on, or changing what it trusts takes a code from it.
#How your team signs in
On the sign-in page, a human chooses Continue with SSO and types their work address. Trotta Mail sends them to your identity provider and signs them in when it vouches for them.
- A human whose address is already one of your mailboxes signs in to that account.
- An address with an open invitation takes the invitation up.
- Any other address on a bound domain joins as a member, with a mailbox at that address, if a seat is free. With no free seat, nothing is created.
- An account in another organization is never linked or taken over, and an agent inbox never becomes a human's.
- The owner never signs in this way. The owner uses their password and an authenticator code.
- An admin signs in this way only with an authenticator app set up in Trotta Mail. To add an admin, invite them as a member, have them set one up, then make them an admin.
- Anyone with an authenticator app in Trotta Mail enters its code after your identity provider.
For members without one, your identity provider is responsible for the second factor. A single sign-on session lasts 12 hours at most, and ends at once when its connection is turned off or removed.
#Set up SAML
- In Single sign-on, choose New connection, then SAML. Give it a name, pick your domains, and save.
- Copy the Entity ID and the ACS URL into a new SAML app at your identity provider, or give it the metadata file. Send the email address as the Name ID, or as an
emailattribute. - Assign the app to the humans who should use it.
- Copy your identity provider's entity ID (issuer), sign-in URL and signing certificate back into the connection with Edit.
- Choose Test sign-in and sign in at your identity provider.
Sign the assertion, the response, or both, with SHA-256. Leave assertion encryption off. Sign-ins started from your identity provider's app launcher are not accepted: humans start at the Trotta Mail sign-in page.
#Set up OpenID Connect
- At your identity provider, create a web app with a client secret. Add the sign-in redirect URI shown in New connection. It asks for the
openid,emailandprofilescopes. - Assign the app to the humans who should use it.
- In Single sign-on, choose New connection, then OpenID Connect. Paste the issuer URL, the client ID and the client secret, and pick your domains.
- Choose Test sign-in and sign in at your identity provider.
Your identity provider must send a verified email address. The client secret is kept encrypted and is never shown again.
#Notes for your identity provider
#Okta
- Go to Applications and Resources, then Applications, and choose Create App Integration. For SAML, pick SAML 2.0. Paste the ACS URL into Single sign-on URL and the Entity ID into Audience URI (SP Entity ID). Set Name ID format to EmailAddress and Application username to Email.
- After saving, the Sign On tab has the metadata and the details to copy back: the sign-in URL, the issuer and the signing certificate.
- For OpenID Connect, pick OIDC - OpenID Connect and Web Application, and add the redirect URI under Sign-in redirect URIs. The Client ID and client secret are on the General tab, under Client Credentials. The issuer is your Okta address, such as
https://your-org.okta.com.
#Microsoft Entra ID
- Use SAML. Entra ID's OpenID Connect tokens do not say whether an email address is verified, and a sign-in needs that.
- Go to Entra ID, then Enterprise apps, then All applications, then New application, and choose Create your own application. Under Single sign-on, choose SAML. In Basic SAML Configuration, paste the Entity ID into Identifier (Entity ID) and the ACS URL into Reply URL (Assertion Consumer Service URL).
- Under Attributes & Claims, make the email address the unique user identifier if your sign-in names and email addresses differ.
- From SAML Certificates, download the Base64 certificate. From the Set up section, copy the Login URL and the Microsoft Entra Identifier.
#Google Workspace
- In the Admin console, go to Apps, then Web and mobile apps, then Add App, then Add custom SAML app. Copy the SSO URL, the Entity ID and the certificate from Google Identity Provider details.
- In Service provider details, paste the ACS URL and the Entity ID, and set the Name ID format to EMAIL with the primary email as Name ID.
- Under User access, turn the app on for the humans who use Trotta Mail.
- OpenID Connect works too, with the issuer
https://accounts.google.com. Only accounts your Google Workspace manages on the bound domain are signed in.
#JumpCloud and OneLogin
Both work with a custom SAML app or OpenID Connect, set up as above. JumpCloud signs the response by default, which works. In OneLogin, choose SHA-256 for the signature.
#Require single sign-on
Once a test sign-in has worked, the owner can turn on Require single sign-on. Then:
- Everyone but the owner signs in through your identity provider. Their passwords stop working.
- Their password sessions end at once. Their single sign-on sessions and your agents are not affected.
- The API keys and connected apps that anyone but the owner made stop working. The console says how many before you confirm.
- The owner keeps a way in if your identity provider is ever down: their password together with a code from their authenticator app. While single sign-on is required, that app stays on.
Every change to single sign-on asks the owner for a fresh authenticator code, and is written to the audit trail, as is every sign-in and every refusal.
#When a sign-in does not work
| What the sign-in page says | What to check |
|---|---|
| The answer could not be trusted | The certificate, the issuer, and that the Entity ID and ACS URL match the connection. |
| Your address is not on a domain this sign-in covers | The address your identity provider sends, and the connection's domains. |
| Your identity provider did not vouch for your email address | That it sends a verified email address. |
| There is no free seat | Seats on your plan, under Plan and usage. |
| Started in another browser, or ran out | Start again from the Trotta Mail sign-in page. |
| The owner signs in with a password | The owner uses their password and authenticator code, not single sign-on. |
| An admin needs an authenticator app | Make them a member, have them set one up under Security, then make them an admin. |
The audit trail has the exact reason for each refusal. The routes are in the API reference.