Okta SSO Configuration Guide for Mailzzy

This guide shows Okta administrators how to set up Okta SSO for Mailzzy using the Mailzzy app in the Okta Integration Network (OIN). You add the app from the Okta catalog, enter one value from Mailzzy, and Okta fills in every sign-in URL for you. The app supports both OpenID Connect (OIDC) and SAML 2.0. Okta recommends OIDC, and this guide covers both.

If you use a different identity provider, or want to build a custom Okta app instead of using the catalog app, follow the SSO Configuration Guide.

Read This Before You Enable SSO

Setting up SSO doesn't change how anyone signs in until you choose to require it. When you turn on Require SSO for users on these domains in Mailzzy, everyone with an email address on your connector's domains must sign in through Okta, and password sign-in is blocked for them.

• Mailzzy keeps one password-fallback user (a break-glass account) who can still sign in with a password if Okta is unavailable. Protect that account with two-factor authentication.

• There's no separate backup sign-in URL. If Okta is unavailable, the password-fallback user can sign in with a password and pause the connector on the Enterprise SSO tab, or you can email support@mailzzy.com to disable SSO for your account.

• Test sign-in fully, as described in Step 6, before you require SSO.

Supported Features

The Okta Mailzzy integration supports:

• SP-initiated SSO: users start at the Mailzzy sign-in page and are sent to Okta to authenticate.

• IdP-initiated SSO: users click the Mailzzy tile on their Okta End-User Dashboard.

• Just-In-Time (JIT) provisioning: Mailzzy creates an account the first time an assigned user signs in, when Automatically onboard new SSO users is turned on.

• Sign out of Okta when signing out of Mailzzy (OIDC only): when a user who signed in with OIDC signs out of Mailzzy, Mailzzy also ends their Okta session, then returns them to the Mailzzy sign-in page. This uses the post-logout redirect URI the catalog app registers in Okta.

Both OIDC and SAML 2.0 support SP-initiated SSO, IdP-initiated SSO, and JIT provisioning. Only one connector can be live on a Mailzzy account at a time, so pick one protocol.

Current limitations:

• SCIM provisioning isn't supported. Unassigning or deactivating a user in Okta stops them from signing in through SSO, but it doesn't deactivate their Mailzzy account. Deactivate them in Mailzzy as well. See How to Manage Team Members or Sub-Accounts.

• Okta group membership isn't mapped to Mailzzy roles. New users get the default role set on the connector, and you can change it in Mailzzy afterward.

• Sign-out from Okta is supported for OIDC only. With SAML 2.0, signing out of Mailzzy ends the Mailzzy session but not the Okta session.

• Signing out of Okta, or ending a user's Okta session, doesn't sign them out of Mailzzy. Universal Logout isn't supported.

Prerequisites

Before you begin, make sure you have:

• A Mailzzy plan that includes Enterprise SSO. If the Enterprise SSO tab shows "Enterprise SSO isn't included in your plan," contact support@mailzzy.com first.

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

• An Okta account with the Super Administrator or Application Administrator role, so you can add apps from the OIN catalog and assign users to them.

• The email domains your team signs in with, such as acme.com. Mailzzy matches the domain of the email address a user signs in with to decide who is sent to Okta.

• User email addresses in Okta that match the addresses your team uses in Mailzzy. Mailzzy identifies users by email.

Step 1: Reserve an SSO Connector in Mailzzy

1. Sign in to Mailzzy as an administrator. In the top-right corner, click the dropdown arrow next to your profile name and email, then select Security.
2. Open the Enterprise SSO tab and click Add Connector.
3. Under Protocol, choose OIDC / OAuth 2.0 (recommended) or SAML 2.0. Make a note of your choice, because you'll pick the same one in Okta in Step 3.
4. Optionally enter a Connector name, such as acme-okta.
5. In Email Domains, type each domain that should sign in with Okta and press Enter.
6. Leave Require SSO for users on these domains turned off for now.
7. To create Mailzzy accounts for new users on their first sign-in, turn on Automatically onboard new SSO users and choose a Default role for new users.
8. Click Reserve connector.
9. Find and copy the connector's Registration ID, using one of the three options below.

How to Find Your Registration ID

The Registration ID is the unique identifier Mailzzy gives your connector when you click Reserve connector. It's the connector name, then a hyphen, then 32 letters and numbers. For example: acme-okta-3f9a1c7e5b2d4e8f9a0b1c2d3e4f5a6b. Copy the whole value, including the connector name at the start. All three options below show the same value.

Option 1: From the URL Mailzzy shows right after you reserve the connector

1. After you click Reserve connector, Mailzzy shows the sign-in URLs for your protocol under Configure these values in your IdP.
2. For OIDC, find Redirect URI / Callback URL. For SAML 2.0, find ACS URL / Reply URL / Single Sign-On URL.
3. Look at the end of that URL. The Registration ID is everything after the last forward slash (/). For OIDC the URL ends in /login/oauth2/code/ followed by the Registration ID. For SAML 2.0 it ends in /login/saml2/sso/ followed by the Registration ID.
4. Copy only that last part. Don't copy the https:// address or the path in front of it.

For example, if your Redirect URI ends in /login/oauth2/code/acme-okta-3f9a1c7e5b2d4e8f9a0b1c2d3e4f5a6b, your Registration ID is acme-okta-3f9a1c7e5b2d4e8f9a0b1c2d3e4f5a6b.

Option 2: From the Enterprise SSO tab

1. In Mailzzy, open Security and go to the Enterprise SSO tab.
2. Find your connector in the list. In the Connector column, the connector name is in bold, and the Registration ID is in smaller gray text directly below it.
3. Select the Registration ID text and copy it. If the text looks cut off, use Option 1 or Option 3 to see the full value.

Option 3: From the setup information dialog

1. On the Enterprise SSO tab, click the ⋮ (more actions) button at the end of your connector's row.
2. Select RP Setup Info for an OIDC connector, or SP Setup Info for a SAML 2.0 connector.
3. The dialog title shows RP Setup Info or SP Setup Info, a dash, and then the Registration ID. Copy the Registration ID from the title. The URLs listed in the dialog end with the same value.

You don't need to copy any of the URLs Mailzzy shows into Okta. The Okta catalog app builds them from your Registration ID.

Step 2: Add Mailzzy from the Okta Integration Network

1. Sign in to the Okta Admin Console.
2. Go to Applications → Applications and click Browse App Catalog.
3. Search for Mailzzy and select it.
4. Click Add Integration.
5. On General Settings, keep or change the Application label. This is the name users see on their Okta dashboard.
6. In Registration Id, paste the full Registration ID you copied in Step 1, including the connector name at the start, such as acme-okta-3f9a1c7e5b2d4e8f9a0b1c2d3e4f5a6b. It must match exactly, with no spaces before or after it. If you're not sure where to find it, see How to Find Your Registration ID in Step 1.
7. Click Done.

For more on adding catalog apps, see Okta's help article Add existing app integrations.

Step 3: Choose the Sign-On Method in Okta

Open the Mailzzy app's Sign On tab and follow the steps for the protocol you chose in Step 1.

If you chose OIDC

1. On the Sign On tab, click Edit and select OpenID Connect.
2. Set Application username format to Email.
3. Click Save.
4. Copy the Client ID and Client secret shown on the Sign On tab. You'll paste them into Mailzzy in Step 5.
5. Note your Okta org URL, such as https://acme.okta.com. This is your issuer URL.

If you chose SAML 2.0

1. On the Sign On tab, click Edit and select SAML 2.0.
2. Set Application username format to Email.
3. Click Save.
4. Under Metadata details, copy the Metadata URL. You'll paste it into Mailzzy in Step 5.

Okta sends the user's email address as the SAML NameID, which is all Mailzzy needs to sign a user in. The app doesn't send any other attribute statements.

Step 4: Assign Users and Groups

1. Open the Mailzzy app's Assignments tab.
2. Click Assign, then choose Assign to People or Assign to Groups.
3. Click Assign next to each person or group who needs Mailzzy, then click Done.

Only assigned users can sign in to Mailzzy through Okta.

Step 5: Enter Your Okta Details in Mailzzy and Activate SSO

Return to Mailzzy and click Continue to IdP details. If you closed the dialog, open the connector's ⋮ menu on the Enterprise SSO tab and select Complete setup. Then enter the details for your protocol.

For OIDC

• IdP Configuration: choose Issuer URL and paste your Okta org URL, such as https://acme.okta.com. Mailzzy finds the rest of Okta's endpoints automatically.

• Client ID and Client Secret: paste the values from the Okta Sign On tab.

• Client Authentication Method: leave it as Client Secret Basic (HTTP Basic header).

• Use PKCE: leave it on.

• Scopes: keep openid, email, and profile.

• End Session Endpoint: leave it blank. Mailzzy finds Okta's sign-out endpoint from the issuer URL, which is what signs users out of Okta when they sign out of Mailzzy.

For SAML 2.0

• IdP Configuration: choose Metadata URL and paste the Okta metadata URL into IdP Metadata URL. Mailzzy reads Okta's issuer, sign-in URL, and signing certificate from it.

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

Step 6: Test Okta Sign-In

Test in a private or incognito browser window so an existing session doesn't hide a problem.

• From Mailzzy (SP-initiated): follow the steps in SP-Initiated SSO below as an assigned user.

• From Okta (IdP-initiated): sign in to the Okta End-User Dashboard as an assigned user and click the Mailzzy tile. You should land in Mailzzy signed in.

• New user (JIT): if you turned on automatic onboarding, sign in as an assigned user who doesn't have a Mailzzy account yet and confirm that one is created.

• From the Enterprise SSO tab: open the connector's ⋮ menu and select Test SSO.

• Sign-out (OIDC): sign out of Mailzzy. You should return to the Mailzzy sign-in page, and opening the Okta End-User Dashboard should ask you to sign in to Okta again.

Step 7: Require SSO (Optional)

After testing, you can require Okta sign-in 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).
4. Click Save Changes.

SP-Initiated SSO

To sign in to Mailzzy from the Mailzzy sign-in page:

1. Go to https://send.mailzzy.com/.
2. Click Sign in with SSO.
3. Enter your work email address and click Continue with SSO.
4. Sign in to Okta if prompted. You're returned to Mailzzy, signed in.

Troubleshooting

Contact Support

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