# Configure Single Sign On (SSO) with Mailosaur and Okta ## Before you get started Mailosaur's Okta integration supports authentication via SAML, OpenID Connect (OIDC) and SCIM provisioning (depending on plan level). Before beginning, ensure that you have: - A Mailosaur account with SSO enabled. SSO is available on the Enterprise plan, and as an optional bolt-on to the Core plan. - Access with the role of Account Administrator. ## Supported Features - SP-initiated SSO - JIT (Just-In-Time) provisioning - SCIM provisioning (Enterprise plan only) ## SAML ### Configuration Steps Follow these steps if you wish to integrate Okta and Mailosaur using SAML. Alternatively, you can configure using OpenID Connect (OIDC). ### 1. Configuration within Okta 1. Log in to your Okta administrative portal. 2. Click **Applications** in the left-hand sidebar, and then **Browse App Catalog** near the top of the resulting page. 3. Search for "mailosaur" in the search bar, and then click the Mailosaur integration from the results. 4. Click the **Add Integration** button to add the Mailosaur integration to your Okta instance. 5. When the app integration is added to your Okta instance, you will be redirected to the applications assignments page. Click on the **Sign On** tab then copy the **Metadata URL** value, you will need this later. ### 2. Verify your company domain in Mailosaur So that your users can be automatically redirected to Okta if they try to log in via the Mailosaur login page, you need to verify that you own the domain in their email address (for example, if your users used `some.person@example.com`, you would verify ownership of `example.com`). To do this: 1. Log in to the Mailosaur Dashboard. 2. Click **Account settings** at the bottom of the left-hand navigation, then select **Domains & addresses** > **Domains**. 3. Click **Add domain** and type in the domain that you wish to verify (e.g. `example.com`). 4. Leave all other options unchanged, and click **Add Domain**. 5. Follow the on-screen instructions to verify that you own this domain (contact our support team if you're unsure how to do this). ### 3. Set up SSO within Mailosaur 1. If you are not already logged in, then log in to the Mailosaur Dashboard. 2. Click **Account settings** at the bottom of the left-hand navigation, then select **Security** > **Single sign-on**. 3. Select your verified domain from the list of domains (see step above if you haven't verified a domain yet). 4. From the list of Identity providers, choose **Okta**. 5. Now fill in the **Identity provider (IdP) metadata URL** field. The value for this is what you copied above and can be found on the **Sign On** tab within the Okta administrative portal. 6. Paste in this value and click **Save**. SSO is now configured on your account. You can optionally choose to enable JIT (Just-In-Time) Provisioning, which will automatically add any new users to your account when they first log in to Mailosaur. You can also make SSO mandatory (however, you must first log in with Okta before you can do this). Users can now log in via the URL shown on-screen e.g. `https://mailosaur.com/sso/{company}` ### 4. Configure a tile to allow users to log in via the Okta Dashboard Mailosaur only supports Service Provider Initiated (SP-initiated) logins. Because of this, users are unable to click on the application tile provided by Okta. Instead, you should hide this default tile, and create an [Okta Bookmark App](https://support.okta.com/help/s/article/create-a-bookmark-app) tile: 1. Log in to Okta as an administrator. 2. Open the configuration for the Mailosaur application, and ensure you have hidden its default tile by checking **Do not display application icon to users** under **General Settings** > **Application Visibility**. 3. Select **Applications** in the left drop-down menu. 4. Select **Browse App Catalog**. 5. Select **Bookmark App** and then **Add**. 6. Type in your desired name for the Mailosaur tile. 7. Enter `https://mailosaur.com/sso/{company}` into the URL box. 8. Save your bookmark. 9. Your users can now log in to Mailosaur by clicking this tile. ## OpenID Connect (OIDC) ### Configuration Steps Follow these steps if you wish to integrate Okta and Mailosaur using OpenID Connect (OIDC). Alternatively, you can configure using SAML. ### 1. Configuration within Okta 1. Log in to your Okta administrative portal. 2. Click **Applications** in the left-hand sidebar, and then **Browse App Catalog** near the top of the resulting page. 3. Search for "mailosaur" in the search bar, and then click the Mailosaur integration from the results. 4. Click the **Add Integration** button to add the Mailosaur integration to your Okta instance. 5. When the app integration is added to your Okta instance, you will be redirected to the applications assignments page. 6. On the **General** tab, make a note of the **Client ID** that is shown. 7. Click on the **Sign On** tab then make a note of the **Issuer** URL. 8. Contact support with the **Client ID** and **Issuer URL** noted above, so that our team can complete OIDC configuration on our side. 9. Our team will provide you information on how your users can login. 10. Configure tiles for your users, using an **Okta Bookmark App**. #### Configure a tile to allow users to log in via the Okta Dashboard Mailosaur only supports Service Provider Initiated (SP-initiated) logins. Because of this, users are unable to click on the application tile provided by Okta. Instead, you should hide this default tile, and create an [Okta Bookmark App](https://support.okta.com/help/s/article/create-a-bookmark-app) tile: 1. Log in to Okta as an administrator. 2. Open the configuration for the Mailosaur application, and ensure you have hidden its default tile by checking **Do not display application icon to users** under **General Settings** > **Application Visibility**. 3. Select **Applications** in the left drop-down menu. 4. Select **Browse App Catalog**. 5. Select **Bookmark App** and then **Add**. 6. Type in your desired name for the Mailosaur tile. 7. Enter `https://mailosaur.com/sso/{company}` into the URL box. 8. Save your bookmark. 9. Your users can now log in to Mailosaur by clicking this tile. ## SCIM ### Supported Features - Create users - Update user attributes - Deactivate users - Push groups For more information on the features listed above, we recommend visiting [this glossary from Okta](https://help.okta.com/en/prod/Content/Topics/Reference/glossary.htm). ### Configuration Steps ### 1. Generate a token for use with SCIM 1. Log in to the Mailosaur Dashboard. 2. Click **Account settings** at the bottom of the left-hand navigation, then select **Integrations** > **API Keys**. 3. Click **Create standard key**, name the new key `SCIM` and click **Create**. 4. Find the newly-created key and click **Reveal Key**, copy the revealed value for use later (below). ### 2. Configuring provisioning in Okta 1. Log in to your Okta administrative portal. 2. Click **Applications** in the left-hand sidebar, and navigate into the Mailosaur application that you already have configured (see configuration steps for SAML or OIDC above). 3. Select the **Provisioning** tab and check the **Configure API Integration** box. 4. Check the **Enable API integration** checkbox. 5. Paste in the API key that you created in the steps above. 6. Click **Test API Credentials** - a success message should appear. 7. Click **Save**. 8. Select **To App** in the left panel then click **Edit**. 9. Enable **Create users**, **Update User Attributes** and **Deactivate Users**, then click **Save**. ### 3. Select users to be provisioned - The **Assignments** tab will let you provision your Okta users to Mailosaur. #### Sync groups On the **Push Groups** tab: - Select **Push Groups**, then **Find groups by name**. - Enter the name of your group. - Click **Save & Add Another**. ## Known Issues / Troubleshooting Please contact our team at support@mailosaur.com if you encounter any issues. #### See also - [SSO with Microsoft Entra](/docs/managing-your-account/sso-mailosaur-microsoft-entra)