⚠️ Requirements:

 Microsoft Active Directory Federation Services (AD FS) 2.0 RTW running on Microsoft Windows Server 2012 R2 or later.

1. Open the AD FS Management console (under Control Panel > System and Security > Administrative Tasks).

2. Under the Actions pane (on the right side), click Add Relying Party Trust...

3. On the Select Data Source page, select Enter data about the relying party manually and click Next.

4. On the Specify Display Name page, type Valimail Enforce in the Display Name field and click Next.

5. On the Choose Profile page, select AD FS Profile and click Next.

6. On the Configure Certificate page, click Next.

7. On the Configure URL page, check Enable support for the SAML 2.0 WebSSO protocol. In the Relying party SAML 2.0 SSO service URL, type https://app.valimail.com/sso/consume/

8. On the Configure Identifiers page, in the Relying party trust identifier field, type https://app.valimail.com and click Add, then click Next.

9. On the Configure Multi-factor Authentication page, select the option appropriate for your organization.

Note: Valimail supports multi-factor authentication within the Account Settings user interface, if you choose to enable it there instead of in ADFS.

10. On the Choose Issuance Authorization Rules page, select Permit all users to access this relying party. User access to the application should be controlled via the user account listing in the Valimail Account Settings page.

11. On the Finish page, check the Open the Edit Claims Rules dialog..., and click Close. The Edit Claims Rules window will open.

12. On the Issuance Transform Rules tab, click Add Rule.

13. On the Choose Rule Type page, select Send LDAP Attributes as Claims and click Next.

14. For Claim rule name, type Valimail-1, for Attribute store, select Active Directory, and add the three (3) claims listed below in the LDAP Mapping table:

        On the left-side select E-Mail-Addresses; on the right-side type Email

        On the left-side select Given-Name; on the right-side type FirstName

        On the left-side select Surname; on the right-side type LastName

Then click Finish.

15. Click Add Rule again, and select Transform an Incoming Claim, then click Next.

16. For Claim rule name, type Valimail-2, for Incoming claim type type Email (this must exactly match the claim name from Step 14. For Outgoing claim type select Name ID, and for Outgoing name ID format select Email. Select Pass through all claim values and click OK. 

17. Your Issuance Transform Rules tab should look exactly as below (the order of the Rules is important). Click OK.

18. Return to the AD FS Management console, expand the Service folder, and click the Certificates folder. Then locate the certificate which you'll use under the Token-signing section, and click View Certificate... in the Actions pane (on the right-side).

19. Click the Details tab in the Certificate dialog, then click the Copy to File... button.

20. In the Certificate Export Wizard, click Next, then select Base-64 encoded X.509 (.CER), and click Next. Enter a path to save the file to, then click Next, then click Finish, then click OK.

21. Now, go into the Active Directory Users and Computers console and ensure the users you intend to test with are active users in your domain's Active Directory. If not, now is the time to create them.

Set things up in the Valimail platform

1. Be sure to add any users who should have access SSO access to Valimail, including the administrator user with which you are currently logged in.

⚠️SSO testing will fail unless you add your user during this step and also ensure the user has already been added as a user in the Valimail Product under Account Settings.

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

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

4. In the Account Security section, click Setup.

5. You'll need to fill out the Single Sign-on Configuration form. 

• Open the .cer file saved in a previous step, copy its contents, and paste the contents in the x.509 Certificate field.
• In the Identity Provider Entity ID, type your AD FS server Entity ID.
  • Example: https://[your-adfs-domain.com]/adfs/services/trust
• In the SAML 2.0 Endpointfield, type the URL to your AD FS server's SAML 2.0 endpoint. 
  • Example: https://[your-adfs-domain.com]/adfs/ls
  • If your AD FS server is https://sso.vmcs1.com, then type https://sso.vmcs1.com/adfs/ls/ (you're appending the /adfs/ls/ to your server's URL).

Before making these updates confirm your AD FS server's Issuer URL, since some will send http://your-adfs-domain.com instead of https://your-adfs-domain.com.

6. Click Enable.

Test it Out

1. Testing IdP-initiated SSO: Open up a private/incognito window in your browser and go to the Microsoft portal, login with your Microsoft credentials. If SSO was successful, you'll arrive at the Valimail home page for your account.

2. Testing SP-initiated SSO: Open up a private/incognito window in your browser and go to https://app.valimail.com and enter your Microsoft AD username (which is usually an email address). The password field will become disabled and you can click Log In with SSO. You will then be taken to the Microsoft login screen and the IdP-initiated login flow. If SSO was successful, you'll arrive at the Valimail home page for your account.