What is SAML SSO? 

Using the SAML 2.0 protocol, Mailjet allows you to integrate with your Identity Provider to authenticate users via single sign-on, also known as SSO. Theoretically, as long as your current Identity Provider supports the SAML 2.0 protocol (Okta, Azure AD, Auth0, Onelogin, etc), then you should be able to use your provider with Mailjet. 

Requirements to enable SAML SSO on Mailjet

In order to set up SAML, you will need to verify that you own your corporate domain (the domain being used in the SAML configuration to log in). Currently, the Mailjet platform uses TXT records for domain verification. 

Mailjet can generate a unique TXT record for you to add to your corporate domain’s DNS that will allow us to verify you own this domain. In order to use this method, head to the SAML Setup page ( Settings > Details in the left-hand nav and then scroll down to the Authentication section, and in the SAML Auth sub-section, click on Setup SAML SSO) enter your corporate domain in the Domain Name field under Domain TXT Record Generation, and hit Generate. Copy the TXT record from the modal and add that to the DNS records for your domain.

Make sure all user account domains are verified before trying to set up SAML on Mailjet. For example, if the domains are mailjet.com and mailgun.com, these actions must be performed for each one of them.

Identity Provider details

You’ll need to provide the following to Mailjet from your Identity Provider:

• IdP Entity ID (Also known as Identity Provider Issuer)
• Single Sign-on URL
• X509 Certificate

Service Provider details

You’ll need to provide the following SAML Provider details to your Identity Provider from Mailjet:

• Entity ID
• Assertion Consumer Service URL
• Single Logout Service URL

Accessing and enabling SAML SSO on Mailjet

In order to access the SAML configuration on Mailjet, click on Account Settings > SAML Auth (SSO) on the Account Information page:

Once there, you will find the relevant Service Provider details, as well as the form you’ll need to complete:

In order to enable your configuration, all the required fields have to be filled with the identity provider details.

Disabling SAML SSO

In order to disable SAML SSO on your account, click on Account Settings > SAML Auth (SSO) on the Account Information page. Once there, click on the cog icon and then click on Deactivate SAML.

 

Identity providers

Different Identity Providers can be used: Okta, Azure AD, Auth0, Onelogin, etc. This article explains how to do it with Okta and Azure.

Setting up SAML SSO using Okta

First, you’ll need an Okta account. If you already have one, great! If not, you can register at https://developer.okta.com and follow the instructions to get a free developer account.

Once you have an Okta account, navigate to 'Applications'.

Once there click on 'Create App Integration'. When the modal pops up, select 'SAML 2.0' as the Sign-on method and click on Next.

Give your app a descriptive name, and a logo, if you wish. You can ignore the App visibility options and then click on Next.

Enter your:

• Single sign-on URL (this is referred to as 'Assertion Consumer Service URL' in your Mailjet Dashboard)
  • Leave the Use this for Recipient URL and Destination URL checkbox checked
• Audience URI (Entity ID in your Mailjet Dashboard)
• Leave Default RelayState blank
• Name ID format should be set to `EmailAddress`
• Application username should be set to `email`.
• Leave Update application username on as default.

Leave the Attribute Statements section empty and click on Next.

On the next page, choose 'I’m an Okta customer adding an internal app', and click on Finish.

You’ll land on the Sign On tab on the application you’ve just configured.

Look for the 'View Setup Instructions' button and click on it to display the actual data you need to add on Mailjet. It should look like this:

Copy the data into the SAML Auth (SSO) page in Mailjet and submit the form. If everything is correct, you should be good to go.

Setting up SAML SSO using Azure

To set up SAML, you will need first to verify that you own your corporate domain (the domain being used in the SAML configuration to log in) on both platforms (Mailjet and Azure).

Verifying a domain on Azure Active Directory

Go to your 'Azure Active Directory' and select 'Custom domain names'.

Click on 'Add custom domain' and follow the procedure.

Once the domain has been added, it will be shown on your 'Custom domain names' page. The status of the domain should be 'Verified' for the SSO to work.

Verifying a domain on Mailjet App

Follow the procedure described here. 

Once your domain is verified on both sides, let's start setting up SSO authentication between Azure and Mailjet.

SSO configuration on Azure

Enter your Azure account and navigate to 'Azure Active Directory'.

Once there, click on 'Enterprise applications'.

Select 'New application' on top of the screen.

Then click on 'Create your own application' and follow the configuration steps.

Once you have created your application, click on it...

...and select the second option ‘Set up a single sign on”.

Choose 'SAML' method for the SSO configuration.

On the next page, you will find the relevant Identity Provider details and the forms you will need to complete.

On the first step 'Basic SAML Configuration', you will need to take the relevant Service Provider details from Mailjet, and fill out the marked sections below.

Provide Mailjet information to Azure

Jump to the third step 'SAML Configuration' and select 'Sign SAML response and assertion' from the dropdown menu under 'Signing option'. The 'Signing Algorithm' field should be left as it is (SHA-256).

Don't forget to download the Base64 certificate as you will need it later for the Mailjet configuration.

When you have completed steps 1 and 3, you will need to do the same on the Mailjet side.

To access the SAML configuration on Mailjet, click on Account Settings --> SAML Auth (SSO) on the Account Information page.

Select 'Setup SAML Auth'.

You will then find the form you will need to complete.

In order to enable the SSO configuration, all the required fields must be filled with the identity provider details from Azure.

Provide Azure information to Mailjet

Mailjet

Azure

Comment

Users' management

Mailjet

Our SAML-based SSO feature can provide your end-users with access to the Mailjet application through an identity provider (IdP). All users you have given shared access to your account will be listed in the 'Users' section.

Note: The single sign-on feature will be disabled by default for all users. Only active users with an Associated domain in the SAML configuration will be able to log in to your account via SSO.

You can enable SSO functionality for all users at once, by clicking the 'Enable SAML for all' button...

... or manually choose to enable or disable access for individual users one by one via the cog icon.  

Identity provider (Okta) 

Once you have activated your end-users within the Mailjet application you will also need to add them to your identity provider (IdP), in this case Okta.

Open your Okta account, go to Directory --> People and click on 'Add person'.

Once you have entered all the required information, select 'Save'.

Note: If you want to immediately notify the new user and send him an activation email, check the box 'Send user activation email now'. The user will then be prompted to click on a link to activate his Okta account.

Next step will be to visit the Applications page and select the application to which you want to assign the newly added user.

Select 'Assign to people' from the Assign drop-down menu.

Click 'Assign' on the user you previously added.

Note: Only unassigned users will be displayed.

You will then be redirected to the People page to find all users added to your Okta account and their current status.

If all the steps mentioned above have been followed correctly, end-users with access to your Mailjet application should have no problem logging in via SSO.

Identity provider (Azure) 

Once you have activated your end-users within the Mailjet application you will also need to add them to your identity provider (IdP), in this case Azure.

Open your Azure account, go to Azure Active Directory --> Users and click on 'New user'.

Follow all the steps and add the new user, which will be displayed on the 'Users' page.

Note: Enter the email address in lowercase letters as it is case-sensitive.

Now you need to assign the newly created user to the Mailjet application you created earlier.

Go to the application and select 'Assign users and groups'. 

Then click on 'add user/group'...

...and select the user you want to give SSO access to from the list.

Once selected and assigned, the user will be displayed under the 'Users and groups' page. All users displayed on this page will have SSO access to your application.

If all the steps mentioned above have been followed correctly, end-users with access to your Mailjet application should have no problem logging in via SSO.

Sign in with SSO 

To sign in, click on the 'Sign in with SSO' button on the Mailjet login page.

A new window will then appear with a single input form for your email.

Once you enter your email and click on the 'Sign in' button, you will be redirected to your account dashboard.