SSO Configuration Guide: SAML 2.0 and OIDC

Single sign-on (SSO) lets your team sign in to Mailzzy with the same work account they use for your company's other apps. Mailzzy works with any identity provider (IdP) that supports SAML 2.0 or OpenID Connect (OIDC), including Okta, Microsoft Entra ID (formerly Azure AD), Google Workspace, OneLogin, Ping Identity, JumpCloud, and Auth0.

The setup is the same for every provider — only the names of the fields in your IdP's admin console differ. This guide lists the common names side by side so you can follow along whichever provider you use.

Before You Begin

Make sure you have the following:

• Enterprise SSO on your Mailzzy plan. If the Enterprise SSO tab shows "Enterprise SSO isn't included in your plan," contact support@mailzzy.com before continuing.

• A Mailzzy administrator account. The Enterprise SSO tab is only visible to administrators.

• An administrator for your identity provider who can create app integrations and assign users to them.

• The email domains your team signs in with, such as acme.com. Mailzzy decides who is sent to SSO by matching the domain of the email address a user signs in with, so use domains your organization owns.

Each Mailzzy account can have one SAML 2.0 connector and one OIDC connector.

Choosing Between SAML 2.0 and OIDC

Both protocols give your users the same sign-in experience. Choose the one your identity provider and IT team prefer:

• SAML 2.0 — the most widely supported enterprise option. Choose it if your IdP offers SAML apps or your security team standardizes on SAML.

• OIDC / OAuth 2.0 — a modern protocol built on OAuth 2.0. Choose it if your IdP favors OIDC apps, such as app registrations in Microsoft Entra ID or OAuth clients in Google Cloud.

If you're unsure, start with SAML 2.0 — every major identity provider supports it.

Step 1: Create an SSO Connector in Mailzzy

1. In the top-right corner of Mailzzy, click the dropdown arrow next to your profile name and email, then select Security.
2. Open the Enterprise SSO tab and click Add Connector. The Add SSO Configuration dialog opens with three steps: Name & domains, Configure your IdP, and Submit IdP details.
3. Under Protocol, choose SAML 2.0 or OIDC / OAuth 2.0.
4. Optionally enter a Connector name — a friendly label such as acme-okta. If you leave it blank, Mailzzy creates one for you. The name can't be changed later.
5. In Email Domains, type each domain that should use this connector and press Enter. You can add more than one.
6. Leave Require SSO for users on these domains turned off for now. You'll turn it on after testing, in Step 5.
7. Keep Send login hint turned on so your IdP's sign-in page is pre-filled with the user's email.
8. To create Mailzzy accounts automatically the first time new users sign in, turn on Automatically onboard new SSO users and choose a Default role for new users.
9. Click Reserve connector.

Mailzzy reserves the connector and shows the values you'll need in your identity provider. The connector is listed as Setup incomplete and won't accept sign-ins until you finish Step 3.

Step 2: Set Up the App in Your Identity Provider

In your identity provider's admin console, create a new application — a SAML 2.0 app, or for OIDC, a Web application that uses the Authorization Code flow. Then copy the values from the Mailzzy dialog into it. Each value has its own Copy button.

For SAML 2.0

• If your IdP can import service provider metadata, you can give it the SP Entity ID / Audience URI / Metadata URL value instead of entering each field by hand.

• Mailzzy identifies users by email address, so the NameID (subject) your IdP sends must be the user's email.

• Mailzzy signs requests with RSA-SHA256. If your IdP requires signed requests or single logout, download the SP Signing Certificate from the dialog (Download .crt or Download .pem) and upload it to your IdP.

• You can also send first name, last name, display name, and phone number as attributes. See Map User Attributes below.

For OIDC / OAuth 2.0

• Use the Authorization Code grant type, and allow the openid, email, and profile scopes.

• Copy the Client ID and Client Secret your IdP generates. You'll need them in Step 3, and some IdPs only show the secret once.

• If your IdP allows only one shared Initiate Login URI for all apps, use the shared URI shown below the RP values in Mailzzy instead. It works as long as the same issuer isn't used by another connector on your Mailzzy account.

Assign users

Assign the new app to the users or groups who should have access to Mailzzy. Only assigned users can sign in through SSO. Assigning a user doesn't create their Mailzzy account on its own — see User Provisioning and Roles below.

When you're done in your IdP, return to Mailzzy and click I've configured my IdP. If you closed the dialog, you can pick up where you left off from the connector's ⋮ menu by selecting Complete setup.

Step 3: Enter Your IdP Details and Activate SSO

Enter the details your identity provider generated. For both protocols, the recommended option reads everything Mailzzy needs from a single URL.

For SAML 2.0

• Metadata URL (recommended): paste your IdP's metadata URL into IdP Metadata URL. Mailzzy reads the issuer, sign-in URL, and signing certificate from it.

• Manual entry: enter the IdP Entity ID / Issuer, IdP SSO URL, and IdP Signing Certificate (PEM), plus the IdP Single Logout URL if you use single logout. Use this option if your IdP doesn't publish a metadata URL.

For OIDC / OAuth 2.0

• Issuer URL (recommended): paste your IdP's issuer URL. Mailzzy discovers the authorization, token, user info, and JWK Set endpoints automatically.

• Manual entry: enter the Authorization Endpoint, Token Endpoint, User Info Endpoint, and JWK Set Endpoint individually.

• End Session Endpoint (optional): add it if signing out of Mailzzy should also sign the user out of your IdP.

• Client ID and Client Secret: from the app you created in Step 2.

• Client Authentication Method: defaults to Client Secret Basic (HTTP Basic header). Choose Client Secret Post (form body) if your IdP app is set up that way.

• Use PKCE (recommended): leave this on unless your IdP doesn't support PKCE.

• Scopes: openid, email, and profile are included by default. Add any other scopes your IdP requires.

Advanced options

Most setups don't need these. Expand Advanced at the bottom of the form to:

• SAML: set a custom Email Attribute if your IdP sends the email address in a non-standard attribute, override the SP Entity ID, or supply your own SP signing certificate and key. Mailzzy generates a signing key pair for each connector automatically, so you only need your own for a specific reason.

• OIDC: set an Email Claim (override) if the email arrives in a non-standard claim, or use ACR Values, Prompt, and Max Age to control how your IdP authenticates users.

Click Activate SSO. The connector's status changes from Setup incomplete to Live.

Step 4: Test Single Sign-On

Test SSO before you require it, while password sign-in still works as a fallback:

• From the Enterprise SSO tab: open the connector's ⋮ menu and select Test SSO. This option is available once the connector is Live.

• From the Mailzzy sign-in page: click Sign in with SSO, enter a work email on one of your connector's domains, and click Continue with SSO. You should be sent to your IdP and returned to Mailzzy signed in.

• From your identity provider: open your IdP's user dashboard, such as the Okta End-User Dashboard or Microsoft My Apps, and click the Mailzzy app tile.

• New user onboarding: if you turned on Automatically onboard new SSO users, sign in as an assigned user who doesn't have a Mailzzy account yet and confirm that one is created.

• Sign-out: if you set up single logout, sign out of Mailzzy and confirm your IdP session ends too.

Step 5: Require SSO for Your Domain

Once SSO works, you can require it for everyone on your domains:

1. On the Enterprise SSO tab, open the connector's ⋮ menu and select Edit.
2. Turn on Require SSO for users on these domains.
3. Choose a Password-fallback user (break-glass account). This one user can still sign in with a password if your IdP is ever unavailable. It defaults to the person who set up SSO.
4. Click Save Changes.

From now on, everyone else with an email address on the connector's domains must sign in through your identity provider.

Tips for Popular Identity Providers

Menu names in identity providers change from time to time. If a label below doesn't match what you see, search your IdP's documentation for the equivalent SAML or OIDC setting.

Okta

• SAML: in the Admin Console, go to Applications → Applications → Create App Integration and choose SAML 2.0. After saving, copy the Metadata URL from the app's Sign On tab.

• OIDC: choose OIDC - OpenID Connect with the Web Application type. Your issuer URL is your Okta domain (for example, https://your-org.okta.com) or the URL of your custom authorization server (for example, https://your-org.okta.com/oauth2/default).

• Assigned users see the Mailzzy tile on their Okta End-User Dashboard automatically.

Microsoft Entra ID

• SAML: go to Enterprise applications → New application → Create your own application and choose the non-gallery option. Open Single sign-on, select SAML, and enter the Mailzzy values under Basic SAML Configuration. Then copy the App Federation Metadata Url from the SAML Certificates section.

• OIDC: go to App registrations → New registration and add the Redirect URI under the Web platform. Create a client secret under Certificates & secrets and copy its Value (not the Secret ID). Your issuer URL is https://login.microsoftonline.com/your-tenant-id/v2.0.

• Make sure your users have an email address in Entra ID. If the email isn't returned when using OIDC, add the email optional claim under Token configuration.

• Assign users and groups on the enterprise application's Users and groups page.

Google Workspace

• SAML: in the Admin console, go to Apps → Web and mobile apps → Add app → Add custom SAML app. Google shows its own details (SSO URL, Entity ID, and certificate) first. Google doesn't provide a metadata URL, so use Manual entry in Mailzzy.

• Custom SAML apps are off by default. Under User access, turn the app on for everyone or for the organizational units that need Mailzzy.

• OIDC: in the Google Cloud console, go to APIs & Services → Credentials, create an OAuth client ID of type Web application, and add the Redirect URI under Authorized redirect URIs. Your issuer URL is https://accounts.google.com. Set the OAuth consent screen to Internal so only users in your organization can sign in, and leave End Session Endpoint blank in Mailzzy — Google doesn't offer one.

OneLogin

• SAML: add the SAML Custom Connector (Advanced) app and enter the Mailzzy values on its Configuration tab. OneLogin also asks for an ACS (Consumer) URL Validator — a regular expression that matches the ACS URL. Then copy the Issuer URL (your metadata URL) from the SSO tab.

• OIDC: add the OpenId Connect (OIDC) app. Enter the Login Url, Redirect URI's, and Post Logout Redirect URI on the Configuration tab, then copy the Client ID and Client Secret from the SSO tab. Set the token endpoint authentication method to match the Client Authentication Method in Mailzzy. Your issuer URL is https://your-subdomain.onelogin.com/oidc/2.

Other identity providers

Ping Identity, JumpCloud, Auth0, Keycloak, and any other standards-based IdP work the same way. Create a SAML 2.0 or OIDC web application, paste in the Mailzzy values from Step 2, make sure the user's email address is sent as the NameID (SAML) or email claim (OIDC), and bring the metadata URL or issuer URL back to Mailzzy.

User Provisioning and Roles

• Automatic onboarding: with Automatically onboard new SSO users turned on, Mailzzy creates an account the first time an assigned user on your domain signs in through SSO. With it off, only people who already have a Mailzzy account can sign in through SSO.

• Default role: new users get the Default role for new users set on the connector. You can change a user's role in Mailzzy afterward. Mapping IdP groups to Mailzzy roles is coming soon.

• Removing access: unassigning or deactivating a user in your IdP stops them from signing in through SSO, but it doesn't deactivate their Mailzzy account. If SSO isn't required on your domain and they have a Mailzzy password, they could still sign in with it. When someone leaves, always deactivate them in Mailzzy as well — see How to Manage Team Members or Sub-Accounts.

• Mailzzy doesn't support SCIM provisioning at this time.

Map User Attributes

An email address is all Mailzzy needs to sign a user in. To fill in more profile details, open the connector's ⋮ menu, select Attribute mapping, and map the attribute (SAML) or claim (OIDC) names your IdP sends to these Mailzzy fields:

• Email — used to find or create the user. It must be an email address.

• Display name — takes precedence over first and last name.

• First name and Last name

• Phone — values longer than 25 characters are truncated.

Manage, Pause, or Delete a Connector

Each connector on the Enterprise SSO tab shows its status — Setup incomplete, Live, or Paused — and has a ⋮ menu with these options:

• SP Setup Info (SAML) or RP Setup Info (OIDC) — view and copy the values to enter in your IdP.

• Test SSO — run a test sign-in. Available for Live connectors.

• Edit (or Complete setup while setup is incomplete) — update domains, IdP details, and sign-in settings. The connector name and protocol can't be changed.

• Attribute mapping — map profile fields from your IdP.

• Delete — remove the connector.

To pause SSO without losing your configuration, open Edit, switch Active off, and save. The connector shows as Paused until you switch it back on.

Troubleshooting

Need Help?

If you get stuck, email support@mailzzy.com with your connector name, the protocol you're using, your identity provider, and the approximate time of a failed sign-in. Never send client secrets, private keys, or passwords.