Tutorial: Integrating Defend with a SAML 2.0 SSO Provider


Valimail Defend supports integration with Identity Providers (IdP) that support the XML-based Security Assertion Markup Language (SAML) 2.0 protocol.


For IdPs where Defend doesn't appear in the app catalog or those without app catalogs, but support SAML 2.0, Valimail can be implemented using the following instructions.


Configuring Defend with an IdP is a two-step process. Step 1 involves working within the IdP to configure Defend as an app. Step 2 involves working within Defend.


Step 1: IdP Configuration

A SAML 2.0 compliant IdP will typically require, at a minimum, the following data to configure an app:

Attribute NameValue
SAML Assertion Consumer Service (ACS) URLhttps://defend.valimail.com/sso/consume
Recipient URLhttps://defend.valimail.com/sso/consume
Destinationhttps://defend.valimail.com/users/sign_in
Audience URI (SP Entity ID)https://defend.valimail.com
Default RelayStateleave blank
Name ID FormatThis should be in the form of an email address.


Name ID: Some IdPs may need to know what format in which to send the Name ID to Valimail. The IdP should send in the format of an email address.


Additional Attributes: Defend expects some additional user information to be passed by the IdP, these are:

Attribute NameName FormatValue
FirstNameUnspecifiedThe user's first name as it appears in the IdP.
LastNameUnspecifiedThe user's last name as it appears in the IdP.


⚠️ Note: the attribute names above are case-sensitive and should appear in the IdP configuration exactly as they do here.


Step 2: Valimail Defend Configuration

1. Obtain the IdP Metadata file from your SSO provider. Some providers make this available through their user interface or online help, while others may require you to contact their Support Team. You will need this before continuing with setup.


⚠️SSO testing will fail unless you have also added to Valimail Defend any users who should have access. Ensure users have already been added in Valimail Enforce under Account Settings.


2. In a new browser tab/window, go to https://defend.valimail.com and login to Valimail with your username and password.


3. Click on your account name and click Account Settings.


4. In the Authentication section, click the Setup button.


5. In the Single Sign-on Configuration section, scroll down to the IDP Metadata File section and click the Choose File button. Locate the XML file you saved in Step 16 and upload it.

6. Then clickat the bottom of the page.


7. Testing IdP-initiated SSO: Open up a private/incognito window in your browser and go to your SSO provider's login portal, login with your SSO credentials, locate and then launch the Valimail Enforce app. If SSO was successful, you'll arrive at the Valimail Enforce home page for your account.


8. Testing SP-initiated SSO: Open up a private/incognito window in your browser and go to https://defend.valimail.com and enter your SSO username (email address). You will see the following message -- clickSign in with SSO. You will then be taken to your SSO provider's login screen and the IdP-initiated login flow. If SSO was successful, you'll arrive at the Valimail Defend home page for your account.