Configuring Single Sign-On for End User Applications using a 3rd Party Identity Provider

Document created by user.oxriBaJeN4 Employee on Dec 14, 2015Last modified by user.oxriBaJeN4 Employee on Jul 25, 2017
Version 18Show Document
  • View in full screen mode

This guide explains how to configure Single Sign-On for the End User Applications using a 3rd party Identity provider.

Single Sign-On is supported in the following Mimecast End User Applications:

 

  • Mimecast for Outlook 6.1 and later
  • Mimecast Mobile 3.1 and later
  • Mimecast for Mac 2.4 and later

 

Please ensure you view the Understanding Enforce SAML Authentication for End User Applications guide to learn about the impact of enabling this setting.

Working with your Identity Provider

 

Provide information to your Identity Provider

Before you can configure the Mimecast Single Sign-On settings you must work with your Identity Provider to add support for Mimecast. Some providers, for example, OneLogin, Okta, or Centrify may have Mimecast apps in their application catalogues, however Mimecast is not able to provide support for these as their implementation is out of Mimecast's control. Please consult directly with your Identity Provider if you need any assistance.

 

The following information may be useful for your Identity Provider:

 

FieldDescription
SAML VersionMimecast only supports SAML 2.0. Your Identity Provider must also support this.
Service Provider Initiated Request: Binding TypeService Provider Initiated SAML requests from Mimecast use a POST binding.
Service Provider Initiated Request: Issuer

The <saml:Issuer> value in a Service Provider Initiated SAML request from Mimecast will be different depending on the Mimecast grid that your organization's Mimecast account is hosted. Below are the expected values for each grid:

  • Europe - eu-api.mimecast.com.ACCOUNTCODE
  • United States - us-api.mimecast.com.ACCOUNTCODE
  • South Africa - za-api.mimecast.com.ACCOUNTCODE
  • Australia - au-api.mimecast.com.ACCOUNTCODE
  • Offshore - jer-api.mimecast.com.ACCOUNTCODE

 

Where ACCOUNTCODE is your unique Mimecast account code as specified in the Administration | Account | Account Settings page of the Administration Console.

Service Provider Initiated Request: AssertionConsumerUrl

The AssertionConsumerServiceURL value in a Service Provider Initiated SAML request from Mimecast will be different depending on the Mimecast grid that your organization's Mimecast account is hosted. Below are the expected values for each grid:

Service Provider Initiated Request: RequestedAuthnContext

Mimecast supports the RequestedAuthnContext features in a Service Provider Initiated SAML request. Depending on your Mimecast configuration these values can be empty or:

<samlp:RequestedAuthnContext xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                         Comparison="exact"
                         >

    <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
        urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
        </saml:AuthnContextClassRef>
    <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
        urn:federation:authentication:windows
        </saml:AuthnContextClassRef>
</samlp:RequestedAuthnContext>

It is also possible for the request to only include one <saml:AuthnContextClassRef>.

SAML Response: Destination

The Destination URL's for Service Provider Initiated SAML authentication attempts will be different depending on the Mimecast grid that your organization's Mimecast account is hosted. Below are the expected values for each grid:

SAML Response: IssuerThe issuer element must be present and contain the value provided by your Identity Provider. This value is also set in the Mimecast configuration in a later step and the value found in the SAML response must match the value stored in your Mimecast settings.
SAML Response: Audience

The SAML response must contain an AudienceRestriction element with a child element called Audience. The value of this element must be set based on the region where your Mimecast account is hosted. Please see the table below for the expected values for each grid:

  • Europe - eu-api.mimecast.com.ACCOUNTCODE
  • United States - us-api.mimecast.com.ACCOUNTCODE
  • South Africa - za-api.mimecast.com.ACCOUNTCODE
  • Australia - au-api.mimecast.com.ACCOUNTCODE
  • Offshore - jer-api.mimecast.com.ACCOUNTCODE

 

Where ACCOUNTCODE is your unique Mimecast account code as specified in the Administration | Account | Account Settings page of the Administration Console.

SAML Response: NameIDThe SAML response must contain the NameID element as a child of the Subject element. The value of this element must be the requesting user's primary email address.
SAML Response: NotBefore / NotAfterThe SAML response must contain the NotBefore and NotAfter attributes in a Conditions element. The values of these attributes must be within a 1 minute margin of error to the current time otherwise the request will be rejected for security reasons.
SAML Response: Token Signing CertificateThe SAML response must contain the metadata of your Identity Provider's certificate. This value is also set in the Mimecast configuration in a later step and the value found in the SAML response must match the value stored in your Mimecast settings.

 

Example Service Provider (Mimecast) Initiated Request

 

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                    ID="_64642038fbe3183a186d3341a82c7ae5"
                    Version="2.0"
                    IssueInstant="2015-12-15T11:38:55Z"
                    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                    AssertionConsumerServiceURL="
https://xx-api.mimecast.com/login/saml
"


                    >

    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">xx-api.mimecast.com.ACCOUNTCODE</saml:Issuer>
    <samlp:RequestedAuthnContext xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                                 Comparison="exact"
                                 >

        <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
            urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
            </saml:AuthnContextClassRef>
        <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
            urn:federation:authentication:windows
            </saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

 

Where ACCOUNTCODE is your unique Mimecast account code as specified in the Administration | Account | Account Settings page of the Administration Console.

 

Example SAML Response

 

<samlp:Response ID="_233d5c0c-1349-4c2b-b9d7-ea81a372c0e1"
                Version="2.0"
                IssueInstant="2015-12-10T10:43:01.236Z"
                Destination="
https://xx-api.mimecast.com/login/saml
"


                Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"
                xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                >

    <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">{issuer}</Issuer>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
    </samlp:Status>
    <Assertion ID="_4979d114-89a0-4444-b511-49873d0d822e"
               IssueInstant="2015-12-10T10:43:01.236Z"
               Version="2.0"
               xmlns="urn:oasis:names:tc:SAML:2.0:assertion"
               >

        <Issuer>{issuer}</Issuer>
        <ds:Signature xmlns:ds="
http://www.w3.org/2000/09/xmldsig#
"
>


            <ds:SignedInfo>
                <ds:CanonicalizationMethod Algorithm="
http://www.w3.org/2001/10/xml-exc-c14n#
"
/>


                <ds:SignatureMethod Algorithm="
http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
"
/>


                <ds:Reference URI="#_4979d114-89a0-4444-b511-49863d0d822e">
                    <ds:Transforms>
                        <ds:Transform Algorithm="
http://www.w3.org/2000/09/xmldsig#enveloped-signature
"
/>


                        <ds:Transform Algorithm="
http://www.w3.org/2001/10/xml-exc-c14n#
"
/>


                    </ds:Transforms>
                    <ds:DigestMethod Algorithm="
http://www.w3.org/2001/04/xmlenc#sha256
"
/>


                    <ds:DigestValue>jXxm9YqN2re9PxvH1fnc1nCr3mn97OdFrfQfDcqYjeU=
                        </ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue>JG++KMDC+AzrFNTbO7STsWz1kpvQ8q+05d8wUi5sb9uZE0XC6mdO
                cjHwQqyEKAHTUgY/dFdCGckfkz+pRC6Rrd2LEDBGyiAoAslJCUWFaELLlzCV4Vt1ZjTmM
                o4p6pM+k33hqlzOHV/gpqYFKnVVRVTTvdJ4sqxheF4D4RJcdo9YH7x65F1U9FX+DtkBS
                paBvzYwFxQ2KBW4oTmlAlZ4B0/dEvJ2w92psywaRLtgVBvO5571xkpVBL7t6UYDfflopL
                VFhq4+j4UVQdmnWPEA4aUTtVEo3vh/U59mCzNVgpYIaT/AfYhXggeiN4me2i0/MnikEVzA
                4PioOmRpYdySOw==
                </ds:SignatureValue>
            <KeyInfo xmlns="
http://www.w3.org/2000/09/xmldsig#
"
>


                <ds:X509Data>
                    <ds:X509Certificate>{certificate metadata}</ds:X509Certificate>
                </ds:X509Data>
            </KeyInfo>
        </ds:Signature>
        <Subject>
            <NameID>{emailAddress}</NameID>
            <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <SubjectConfirmationData NotOnOrAfter="2015-12-10T10:48:01.236Z"
                                         Recipient="
https://xx-api.mimecast.com/login/saml
"


                                         />

            </SubjectConfirmation>
        </Subject>
        <Conditions NotBefore="2015-12-10T10:43:01.236Z"
                    NotOnOrAfter="2015-12-10T11:43:01.236Z"
                    >

            <AudienceRestriction>
                <Audience>{audience}</Audience>
            </AudienceRestriction>
        </Conditions>
        <AuthnStatement AuthnInstant="2015-12-10T10:42:48.779Z"
                        SessionIndex="_4979d114-89a0-4444-b511-49863d0d822e"
                        >

            <AuthnContext>
                <AuthnContextClassRef>
                    urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
                    </AuthnContextClassRef>
            </AuthnContext>
        </AuthnStatement>
    </Assertion>
</samlp:Response>

 

Collect information from your Identity Provider

 

Before configuring any Mimecast settings you must gather the following information from your Identity Provider.

 

FieldDescription
SAML VersionMimecast only supports SAML 2.0. Your Identity Provider must also support this.
Federation Metadata URLMimecast can import the SAML Issuer, Login URL and Token Signing Certificate from a URL if your Identity Provider publishes this information in the standard XML format.
SAML IssuerA unique URL that identifies your Identity Provider. SAML responses sent to Mimecast must match this value exactly in the <saml:Issuer> attribute of the SAML response.
Login URLThe URL where Mimecast should redirect the user to in order to start the authentication attempt.
Logout URLThe URL where Mimecast should redirect the user to to when they logout. Mimecast only supports basic redirects here.
Supported Authentication Contexts

How users with authenticate against the Identity Provider and what Authentication classes the Identity Provider supports.

 

Mimecast supports the RequestedAuthnContext features in a Service Provider Initiated SAML request. Depending on your Mimecast configuration these values can be empty or:

<samlp:RequestedAuthnContext xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                         Comparison="exact"
                         >

    <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
        urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
        </saml:AuthnContextClassRef>
    <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
        urn:federation:authentication:windows
        </saml:AuthnContextClassRef>
</samlp:RequestedAuthnContext>

It is also possible for the request to only include one <saml:AuthnContextClassRef>.

Token Signing Certificate MetadataThe Metadata of the certificate issued by your identity provider.

 

Configuring Mimecast Settings

 

Once your Identity Provider is set up to support Mimecast SAML authentication requests and responses, you need to configure a Mimecast Authentication profile. This profile is applied to the users that you want to use Single Sign-on using the Applications Settings feature.

 

SAML Settings

 

  1. Login to the Administration Console.
  2. Navigate to the Administration | Services | Applications menu.
  3. Select the Authentication Profiles button.
    Authentication_Profiles_Button.png
  4. Select an existing Authentication Profile to update or select the New Authentication Profile button to create a new one.
  5. Enter a Description for the new profile.
  6. Select Enforce SAML Authentication for End User Applications.

    Authentication Profile End User Apps.png
  7. The screen expands to reveal the SAML Settings:

    Authentication Profile End User Apps Other.png

  8. Select your Identity Provider from the Provider drop down list to see help text specific to that provider. If your provider is not listed choose Other.
  9. If your Identity Provider supports it, enter the Federation Metadata URL of your Identity Provider and select Import to automatically populate all of the required settings.
    • If Mimecast cannot reach this URL, or if your Identity Provider does not support this function, you can enter the Issuer, Login URL and Identity Provider Certificate Metdata values manually.
    • When populating the Identity Provider Certificate you must trim the Begin and End tags from the certificate metadata.
  10. Optionally select Monitor Metadata URL. This option requires a valid Metadata URL and will check that your Authentication Profile contains the current Identity Provider certificate and settings. The feature is designed to prevent unexpected issues when these settings change at the Identity Provider.

    Checks are made a maximum of once per day and are initiated when a user logs in. If a user with this Authentication Profile applied does not login on a given day the metadata will not be checked.

  11. Optionally specify the Logout URL. Mimecast only supports basic URL redirect logout methods.
  12. Optionally define which Authentication Context to use. By default both password protected and integrated contexts are used.

    These settings define the AuthnContextClass that is used in the SAML request provided by Mimecast and sent to your Identity Provider. Mimecast supports the Password Protected Transport and Windows Integrated contexts, a combination of both, or no context.

Optionally Define Permitted IP Ranges

 

To add an additional layer of security Mimecast provides optional Permitted IP Range settings for the Administration Console, End User Applications, and Gateway authentication attempts.

 

To configure Permitted IP ranges for the Administration Console:

  1. Login to the Administration Console.
  2. Navigate to the Administration | Account | Settings menu.
  3. Open the User Access and Permissions section.
  4. In the Admin IP Ranges text box, enter the public IP address ranges you want to restrict access to in CIDR format, one range per line.

 

To configure Permitted IP Ranges for End User Applications:

  1. Select the check box to enable Permitted Application Login IP Ranges.
  2. In the Permitted Application Login IP Ranges text box enter the public IP address ranges you want to restrict access to in CIDR format, one range per line.
  3. Select Save and Exit to apply the new settings.

 

To configure Permitted IP Ranges for Gateway authentication using SMTP or POP:

  1. Select the check box to enable Permitted Gateway Login IP Ranges.
  2. In the Permitted Gateway Login IP Ranges text box enter the public IP address ranges you want to restrict access to in CIDR format, one range per line.
  3. Select Save and Exit to apply the new settings.

 

Other Options

 

An Authentication Profile is applied to a group of users and a user can only have one effective profile at a given time. Consequently you may want to add additional authentication options to your Authentication Profile. Please see the Authentication Options space for information on other authentication methods.

 

Apply the Authentication Profile to an Application Setting

 

Once your Authentication Profile is complete, you need to reference it in an Application Setting in order for it to be applied. To do this:

  1. Login to the Administration Console.
  2. Navigate to the Administration | Services | Applications menu
  3. Select the Application Setting that you want to use.
  4. Use the Lookup button to find the Authentication Profile you want to reference and click the Select link on the lookup page.
    Application_Settings_select_Authentication_Profile.png
  5. Select Save and Exit to apply the change.

 

Next Steps

 

To test your configuration and verify that your Authentication Profile has been configured correctly,

 

Mimecast for Outlook

 

  1. Open Outlook
  2. Open the Account Options dialogue from the Mimecast ribbon or by clicking the Status Panel in the bottom left of the Outlook window.
  3. You should see the Single Sign-On button available to be selected.
  4. Click the Single Sign-On button followed by the Login button and you should be redirected to your Identity Provider.
  5. Once successfully authenticated you should be returned to the Account Options page and see that the status is Validated.

 

Mimecast Mobile / Mimecast for Mac

 

Applies to Mimecast Mobile v3.1 and later and Mimecast for Mac v2.4 and later

  1. Open the application.
  2. Enter your email address and select next.
  3. You should be redirected to your Identity Provider login URL.
  4. Once successfully authenticated with Identity Provider you should be granted access to the Mimecast application.

Attachments

    Outcomes