SAML Single Sign-On

SAML Single Sign-On lets your team log into Mittr using the same account they use for the rest of your company’s tools. You configure it once in your Identity Provider (IdP: Okta, Azure AD, Google Workspace, OneLogin, Auth0, etc.), and every employee in the designated group gets access without ever creating a Mittr password.

Mittr supports SP-initiated (user clicks “Continue with your IdP” on the Mittr login page) and IdP-initiated (user launches Mittr from their IdP’s app dashboard) flows out of the box.

• Scale plan or above. SAML SSO is gated on the Scale plan; the Settings tab surfaces a 503 hint if your plan doesn’t include it.
• Admin access in Mittr and in your IdP. In Mittr this means the admin role on your workspace.
• A verified email domain you want to gate access with (optional but recommended: see Email-domain discovery).

Setting up SAML is a two-side handshake:

1. Mittr side: create a new SAML connection. Mittr generates a fresh signing keypair and a set of URLs specific to your workspace.
2. IdP side: create a new SAML 2.0 application using the URLs and the public certificate Mittr gave you.
3. Back to Mittr: paste your IdP’s metadata (URL or XML) into the Mittr connection so it can verify assertions signed by your IdP.
4. Test: click the Login URL. If everything is wired up you land on the dashboard logged in as a real user.

The rest of this guide walks through each step in detail, with vendor-specific notes for Okta, Azure AD, and Google Workspace.

1. Sign into your Mittr workspace.
2. Open Settings → SSO (the tab has a lock icon).
3. Click New SAML connection.
4. Fill in:
   • Connection name: any label you like (Okta Production, Azure AD: Staging). Shown only to admins.
   • Slug: URL-safe identifier (okta-prod, azure-staging). Becomes part of your SAML callback URL. Cannot be changed later without re-registering in your IdP.
   • Default role: what newly-provisioned users get when the IdP doesn’t specify a group. viewer is the safe default.
   • IdP metadata: you’ll fill this in after Step 2.
5. Save. Mittr generates the SP keypair and opens a Register these in your IdP panel with four values:
   • SP Metadata URL
   • ACS URL (Reply URL)
   • SP Entity ID (Audience)
   • Login URL (for SP-initiated flows: this is what you’ll eventually put behind your Mittr login link)

Keep this panel open: you’ll copy from it in Step 2.

Pick your IdP below. The field names differ slightly by vendor but the four values are universal.

1. In Okta, go to Applications → Create App Integration.

2. Pick SAML 2.0 and click Next.

3. On the General Settings step, pick a name and logo (shown to your users on the Okta dashboard).

4. On the Configure SAML step, set these values (copy from the Mittr Register these in your IdP panel):

   Okta field	Paste from Mittr
   Single sign-on URL	ACS URL
   Audience URI (SP Entity ID)	SP Entity ID
   Name ID format	EmailAddress
   Application username	Email

5. Under Attribute Statements, add at least three mappings:

   Name	Value
   email	user.email
   firstName	user.firstName
   lastName	user.lastName

6. Under Group Attribute Statements (optional but recommended for role mapping), add groups with filter Matches regex .*.

7. Finish the wizard. In the app’s Sign On tab, click View SAML setup instructions to get your Identity Provider metadata URL; that’s what you’ll paste into Mittr in Step 3.

8. Under the app’s Assignments tab, add the users or groups that should have Mittr access.

1. Go to Enterprise applications → New application → Create your own application.

2. Pick Integrate any other application you don’t find in the gallery (Non-gallery). Give it a name.

3. Open Single sign-on → SAML.

4. Click Edit on Basic SAML Configuration and paste:

   Azure AD field	Paste from Mittr
   Identifier (Entity ID)	SP Entity ID
   Reply URL (Assertion Consumer Service)	ACS URL
   Sign on URL (SP-initiated only)	Login URL

5. Under User Attributes & Claims, verify the defaults include emailaddress, givenname, and surname.

6. Under SAML Certificates, copy the App Federation Metadata URL. That’s what you’ll paste into Mittr.

7. Under Users and groups, assign the group that should access Mittr.

1. In the Google Admin console, go to Apps → Web and mobile apps → Add app → Add custom SAML app.

2. Pick a name, upload an icon, click Continue.

3. On the Google Identity Provider details page, download the IdP metadata XML. You’ll paste this into Mittr in Step 3; Google doesn’t expose a public URL for it.

4. On the Service provider details page, paste:

   Google field	Paste from Mittr
   ACS URL	ACS URL
   Entity ID	SP Entity ID
   Name ID format	EMAIL

5. Under Attribute mapping:

   Google directory field	Mittr attribute name
   Primary email	email
   First name	firstName
   Last name	lastName

6. Finish. On the app page click User access and turn the service On for everyone (or for a specific org unit).

Any SAML 2.0-conformant IdP works. The four universal fields map straight across:

Standard SAML term	Mittr dashboard label
Assertion Consumer URL	ACS URL
Audience / Entity ID	SP Entity ID
Sign-on URL (SP-initiated)	Login URL
Metadata URL (SP)	SP Metadata URL

Mittr accepts any NameID format that carries an email address. It requires email in the assertion; without it the ACS rejects the login as SAML_MISSING_EMAIL.

Return to the Mittr SSO connection you opened in Step 1. Fill in the IdP metadata field with whichever form your IdP gave you:

• Metadata URL (preferred, when available): Mittr will refetch with TTL caching so cert rotations at your IdP are picked up automatically.
• Metadata XML: paste the raw XML blob. You’ll need to re-paste on cert rotation.

Hit Save. Mittr probes the metadata, extracts the IdP entity ID, and the connection flips to Active.

From an incognito window:

1. Go to yourdomain.com/login.
2. Enter your work email (e.g. [email protected]). If you configured email-domain discovery, a Continue with <IdP> button appears; click it.
3. Without discovery, paste the Login URL from the Mittr SSO panel directly into your browser.
4. You’re redirected to your IdP. Authenticate as usual.
5. The IdP redirects you back to yourdomain.com/auth/sso/saml/…/acs.
6. Mittr verifies the signed assertion, creates a session cookie, and lands you on the dashboard.

First-time users are JIT-provisioned at the connection’s default role (or a mapped role if you configured role mapping).

Drive Mittr roles from IdP group membership:

1. In your IdP, make sure the SAML app pushes a groups attribute (Okta: Group Attribute Statement; Azure AD: User Attributes & Claims → Group Claims; Google: configure via directory API).

2. In Mittr’s connection editor, open Role mapping and add the IdP group names that should promote members to admin or editor. Example mapping:

   • engineering becomes editor
   • admins becomes admin
   • read-only becomes viewer

3. On login, Mittr scans the assertion’s groups in order; the first match wins. Unmapped users fall back to the connection’s Default role.

Group priority is admin over editor over viewer. If a user is in multiple mapped groups, the highest-privilege role applies.

Instead of asking users to hunt for the “Continue with Okta” button, you can map your email domain to your tenant so the login page auto-offers SSO when the user types a recognised email.

1. In Mittr, go to Settings → SSO → Email domains.
2. Add your domain (acme.com). Mittr normalises it (@ stripped, lowercase, no trailing slash).
3. On the login page, when a user types an email whose domain matches, a Continue with <IdP name> button appears.

Notes:

• Domains are globally unique. If another tenant has claimed acme.com, you’ll get a 409; contact support to resolve.
• The /auth/sso/discover endpoint returns 404 for unknown domains (no enumeration leak: attackers can’t find out which tenants exist by guessing emails).

By default, SAML JIT creates users at the connection’s default role. If you want specific users at specific roles before they’ve logged in even once:

1. Go to Settings → Team → Invite member.
2. Enter their email and pick their Mittr role.
3. Send the invite (or skip the invite email: the row exists either way).

When that user eventually signs in via SAML with the same email, the invite-consumption path kicks in: Mittr flips their status from invited to active, attaches the SSO identity to the existing row, and preserves the role you chose. The default role is not applied.

The SP (Mittr side) cert + private key live encrypted at rest. You can rotate them from the connection editor:

1. Open the connection.
2. Click Rotate SP key. Confirm.
3. Copy the new SP Metadata URL / Entity ID / cert and update your IdP’s SAML app.

Until you update the IdP, it will still be signing responses against the old cert and assertions will fail. Plan rotations during a low- traffic window.

Your IdP isn’t including an email in the assertion. In Okta, check Attribute Statements → email. In Azure AD, check User Attributes & Claims → emailaddress. In Google, verify the NameID format is EMAIL.

The first path segment in the URL (/auth/sso/saml/<here>/…) doesn’t match any clients.slug. Check:

• You copied the URL from the current Register these in your IdP panel (if you renamed your workspace slug after registering with your IdP, the old URL still works: Mittr accepts either slug or UUID: but double-check the connection name matches).
• The workspace isn’t deleted.

The connection has been deactivated. Re-enable it in Settings → SSO (toggle the Active switch on the row).

The IdP’s cert in the metadata doesn’t match the cert the assertion was signed with. Most common cause: you rotated the cert at the IdP but Mittr is still caching the old metadata. If you used a Metadata URL, wait for the TTL to expire (~15 minutes) or click Refresh metadata in the connection editor. If you pasted XML, paste the new XML from your IdP.

Mittr stores every consumed assertion ID and rejects re-use. This usually means: the user clicked Back and re-POSTed the same SAMLResponse from their browser history. Ask them to start a fresh login flow.

The Issuer in the SAMLResponse doesn’t match the IdP entity ID we cached when you pasted the metadata. Can happen if your IdP renamed their entity ID. Re-paste their metadata into the connection.

The session cookie wasn’t set or wasn’t sent to /auth/session on the dashboard hydration fetch. Check:

• Your deployment is behind HTTPS in production (Secure cookie flag requires TLS).
• No reverse proxy is stripping Set-Cookie.
• Browser cookie policy isn’t blocking third-party cookies for your domain.

• Automate user lifecycle: pair SAML with SCIM v2 provisioning so HR-driven adds and removes flow into Mittr without manual invites.
• Restrict by IP: pair SAML auth with IP whitelisting to require that logins come from your office network.