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

Azure SAML SSO Setup Guide

Article Preview


    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


    General configuration


    Verifying 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: 


    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).


    Setting up SAML SSO

    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).


    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 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.

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


    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).


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


    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




    Provide Azure Information To Mailgun

    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



    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.


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

    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.




    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.
    2. IdP Attribute name will be UserGroup
    3. Set the IdP Attributes Value to the Object ID of the Azure AD Group

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


    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.


    Need Support?

    Our Support Team here at Sinch Mailgun is happy to help! Reach out to us in the Support section of your Mailgun Control Panel, and we'll be with you shortly!