browse
Overview
This article explains how to configure SAML between Cisco Umbrella and Active Directory Federation Services (ADFS), version 3.0. Configuring SAML with ADFS differs from our other SAML integrations as it's not a one or two click process in the wizard, but requires changes in ADFS to work correctly.
Below are detailed modifications you will need to make in order to get SAML and ADFS working together. The primary steps are to first disable encryption between your ADFS environment and Cisco Umbrella, and then add some Issuance Transform Custom Claim Rules to Umbrella relaying party setting.
Prerequisites
Only perform these steps with an existing, working ADFS set up. We are unable to provide assistance or support in helping configure ADFS in a particular environment.
Only ADFS version 3.0 is supported (Windows Server 2012 R2) by these instructions at this time. It is possible earlier (2.0 or 2.1) or later (4.0) versions of ADFS will work with the Umbrella SAML integration, but this has not been tested or proven. If you have a different version of ADFS and would be interested in working with our Support and Product teams to integrate, please contact us.
You can find the prerequisites for the initial SAML setup here: Identity Integrations: Prerequisites. Once you complete those steps, you can continue using the ADFS specific instructions below to complete the configuration.
The steps in the article mention that you will need to upload your SAML (ADFS) metadata to Umbrella. You can access your metadata by navigating to the following URL and then uploading the XML file.
https://{your-ADFS-domain-name}/federationmetadata/2007-06/federationmetadata.xml
Disable Encryption
- Open AD FS Management. Expand Trust Relationships and click Relying Party Trusts.
- Right-click the Umbrella relying party (or whatever you may have called it) and select Properties.
- Click the Encryption tab.
- Click Remove to remove the certificate for encryption.
- Hit OK to close the screen.
Adding new Issuance Transform Claim Rules
- Open AD FS Management. Expand Trust Relationships and click Relaying Party Trusts.
- Right-click the Umbrella relaying party (or whatever you may have called it) and select Edit Claim Rules.
- Click Add Rule under Issuance Transform Rules.
- Choose Send Claims Using a Custom Rule.
See below for the list of rules you will be adding, once you've added each of these rules, the integration should begin to work.
Transform Rules
Note: These rules were tested and working in our ADFS lab environment as well as in a few customer production environments. Please modify them to fit your environment.
userPrincipalName to Email Address
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"), query = ";userPrincipalName;{0}", param = c.Value);
Email to NameID
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType,
Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"]
= "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");
Appendix: Login with 'mail' attribute
By default ADFS authenticates users by their UPN (User Principal Name). If your user's e-mail address (eg. Umbrella account name) does not match their UPN then additional steps are required. Please see the following Knowledge Base article:
How do I configure AD FS in the Cisco Umbrella Dashboard to allow logins with an e-mail address?