We're experiencing difficulty. Our engineers are on it. Please check status.mailgun.com for real-time updates.

Azure SAML Setup Guide

Table Of Contents
Quick Overview
General Configuration
    Verify The SAML Domain
    Enabling SAML SSO
    Disabling SAML SSO
Azure Configuration
Got Questions?

Quick Overview

Note: SAML SSO is available on Scale and higher plans (i.e. Contract and Enterprise). See our plan comparison here.

Using the SAML 2.0 protocol, Mailgun 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, Auth0, Onelogin, Azure AD, etc), then you should be able to use your provider with Mailgun. 

Mailgun supports just-in-time (JiT) provisioning, so that when a user logs into Mailgun using our SSO integration, that user automatically becomes a user under your Mailgun account.

In short, this setup process requires the exchange of information between the two systems:

  • Provide Mailgun With The Information Below From Your Identity Provider
    • IdP Entity ID (also known as Identity Provider Issuer)
    • Single Sign-on URL
    • X509 Certificate
  • Provide Your Identity Provider With The Information Below From Mailgun
    • Entity ID
    • Assertion Consumer Service URL
    • Single Logout Service URL

^ Top Of Page

General Configuration

Verify The SAML Domain

In order to set up SAML, you will need to verify that you own your corporate domain (the domain to be configured with SAML login). There are two methods for verifying your domain on the Mailgun platform:

  • Verified sending domain - If the domain you wish to configure with SAML is already a verified sending domain on your account, no further action is required for this bullet point. Otherwise, you will need to add the domain and configure the SPF and DKIM records to verify the domain. This domain must match the FQDN in the corporate email addresses that will be used to authenticate using SAML.
  • TXT record - Mailgun can generate a unique TXT record for you to add to your domain’s DNS that will allow us to verify you own this domain. In order to use this method:
    • Navigate to the SAML Configuration settings page (see the "Enabling SAML SSO" section below)
    • Enter your domain in the Domain Name field under the Domain TXT Record Generation section
    • Click the Generate button
    • Finally, copy the TXT record from the modal, and add it to your DNS hosting provider for your domain.

Screen Shot 2022-11-08 at 3.45.12 PM.png          Screen Shot 2022-11-08 at 3.45.36 PM.png

Enabling SAML SSO

Note: Only Admin users have access to enable/disable SAML on an account.

As for enabling SAML SSO, we'll show you how to do this below:

  1. First, log in to the Mailgun Control Panel (if you have not already done so).
  2. Then, at the top-right corner of the page, click the Profile drop-down menu to expand its list of options.
  3. Next, click the Account option. Alternatively, you can use this direct link
  4. On the resulting page and in the Authentication section, click the Setup button for the SAML Auth setting.

Screen Shot 2022-11-08 at 3.46.23 PM.png

Once there, you will find the relevant SAML Provider (SP) Details [i.e. Mailgun details that you provide to your Identity Provider], as well as the Identity Provider (IdP) Details [i.e. Identity Provider details that you provide to Mailgun]. This article goes over the specific information and additional steps needed in the relevant Identity Provider sections (i.e. Okta, Azure, OneLogin, etc.). You will also have the option to Manage Custom Configuration , which allows you to set your User Name Attribute Settings. 

Screen Shot 2022-11-08 at 3.23.12 PM.png Screen

Disabling SAML SSO

Note: Only Admin users have access to enable/disable SAML on an account.

As for disabling SAML SSO, we'll show you how to do this below:

  1. First, log in to the Mailgun Control Panel (if you have not already done so).
  2. Then, at the top-right corner of the page, click the Profile drop-down menu to expand its list of options.
  3. Next, click the Account option. Alternatively, you can use this direct link
  4. On the resulting page and in the Authentication section, and by the SAML Auth setting, click the Disable button.

Screen Shot 2022-11-08 at 3.45.59 PM.png

Of Special Note: 

^ Top Of Page

Azure Configuration

Create An Azure Account (If Needed)

First, you’ll need an Azure Active Directory account and one of the following roles: Global Administrator, Cloud Application Administrator, or Application Administrator.

If you already have one, great! If not, you can register at https://azure.microsoft.com/en-us/free/ and follow the instructions to open an account.

Once you have activated your users within the Mailgun application, you will need to add them to Azure, your identity provider (IdP).

^ Top Of Page

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 (Mailgun and Azure).

^ Top Of Page

Verifying A Domain On Azure Active Directory

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

SSO_Azure_EN_24.PNG

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

SSO_Azure_EN_25.5.png

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.

SSO_Azure_EN_25.PNG

^ Top Of Page

Verifying A Domain In Mailgun

Follow the procedure described here

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

^ Top Of Page

SSO Configuration On Azure

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

SSO_Azure_EN_4.PNG

Once there, click on 'Enterprise applications'.

SSO_Azure_EN_5.PNG

Select 'New application' on top of the screen.

SSO_Azure_EN_6.PNG

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

SSO_Azure_EN_7.PNG

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

SSO_Azure_EN_26.PNG

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

SSO_Azure_EN_8.PNG

Choose 'SAML' method for the SSO configuration.

SSO_Azure_EN_9.PNG

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 Mailgun, and fill out the marked sections below.

SSO_Azure_EN_12.PNG

Provide Mailgun information to Azure

Azure Mailgun
Identifier (Entity ID) Entity ID
Reply URL (Assertion Consumer Service URL) Assertion Consumer Service URL
Logout Url (Optional) Single Logout Service

 

Go to '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).

SSO_Azure_EN_13.PNG

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

SSO_Azure_EN_27.PNG

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

 

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

Azure Groups & Group Claims

Note: See also Microsoft's documentation if needed.

1. Click on “+ Add a Group Claim”

pic 1.png

 

2. Group Claims Assertion Configuration

  1. For “Which groups associated with the user should be returned in the claim?”, select “Security Group”,
  2. next set “Source Attribute” to “Group ID”,
  3. expand “Advanced Options” and check “Customize the name of the group claim”,
  4. set “Name” to “UserGroup”
  5. Save.

pic 2.png

 

3. Click on “+ Add new claim”

pic 3.png

  1. Set “Name” to “FirstAndLastName”

  2. Set “Source” to “Attribute”

  3. Set “Source Attribute” to “user.displayname”

  4. Save

pic 4.png

4. In the “Additional Claims” section, delete “user.givenname” and “user.surname”

    1. To delete, click the “…” and select “delete”
      pic 5.png

5. Create the appropriate groups your organization will be using. These can be named anything but you will need to be sure the users will later be appropriately mapped to Mailgun’s roles.

    1. Navigate to Users and Groups → + Add user/group
      pic 6.png

    2. Select a group (Note the Object ID, this will be used during role mapping later)
      pic 7.png

    3. Assign appropriate users to the group
      pic 8.png

image-20230411-195828.png

 

 

^ Top Of Page

Provide Azure Information To Mailgun

Mailgun
Azure
Comment
Associated domain(s) - The custom domain name must be added and verified in Azure and Mailjet
IdP Entity ID

Azure AD Identifier

 
Request signing preference SAML Signing Certificate section > Edit > Signing option Should be Sign SAML response and assertion
Single Sign-On URL Login URL  
Single Logout Service URL

Logout URL

 
X.509 certificate Certificate (Base64) Must be downloaded as Base64 and opened in a text editor before so the value can be copied in the required format

 

 

USERS MANAGEMENT

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

SSO_Azure_EN_15.PNG

SSO_Azure_EN_16.5.png

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

SSO_Azure_EN_16.PNG

Now you need to assign the newly created user to the Mailgun application.

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

SSO_Azure_EN_17.PNG

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

SSO_Azure_EN_18.5.png

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

SSO_Azure_EN_19.PNG

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.

SSO_Azure_EN_18.PNG

^ Top Of Page

Rolemapping In Azure

Only map the Roles that will be assigned to the Groups accessing the application.

  1. Click the cog wheel icon to edit each role mapping section.
    saml1.png
  2. IdP Attribute name will be UserGroup
  3. Set the IdP Attributes Value to the Object ID of the Azure AD Group
    saml2.png
    saml3.png

  4. Submit, the role mapping should look similar as below.
    saml4.png

 

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

^ Top Of Page

Got Questions?

Sinch Mailgun has answers! If you have any concerns or questions, please send us a Support ticket using the Support page within your Mailgun Control Panel.  Our Support Team will be happy to assist!

^ Top Of Page