Recently I needed to integrate a vRA environment with Active Directory Federated Services (ADFS) so the same Single Sign On experience could be delivered across various products for the customer. This required a good cooperation with the AD team in order to set it up correctly.
Below an overview how to get it working and the steps we went through 🙂
A good point to start are the VMware resources regarding the setup of Active Directory Federated Services with vRA:
- vRA 7.5 – https://docs.vmware.com/en/vRealize-Automation/7.5/com.vmware.vra.prepare.use.doc/GUID-1733E9D9-1FC5-4B14-BA04-F4F73CDD22DF.html
- vRA 7.6 – https://docs.vmware.com/en/vRealize-Automation/7.6/com.vmware.vra.prepare.use.doc/GUID-1733E9D9-1FC5-4B14-BA04-F4F73CDD22DF.html
Next to knowing what needs to be done on the vRA side, you need to know how the ADFS side is set up.
- In our case ADFS SSO was configured to use the e-mail address for authentication, hence we need to map the E-Mail address LDAP attribute to the outgoing claiming type used. Example:
- LDAP: E-Mail address – Outgoing: E-Mail Address
- In your specific use case / environment it might very well be that another LDAP attribute needs to be mapped to the ‘E-Mail address’ outgoing type (e.g. LDAP: SAM – Outgoing: E-Mail Address).
- ADFS SSO Identity Provider Metadata XML
- vRA SAML Metadata XML, these are always Tenant specific and of the following format:
- E.g.: https://<YOUR-VRA-FQDN>/SAAS/t/<Tenant_Name>/API/1.0/GET/metadata/sp.xml
- Can be found via: Log on to your vRA Tenant, go to ‘Administration‘ followed by ‘Directories Management‘ and you select ‘Identity Providers‘. Afterwards Click on ‘Add Identity Provider‘ and choose ‘Create Third Party IdP‘, scroll all the way to the bottom and you’ll see your vRA Tenant’s Metadata XML Link:
- Make sure to allow 443 communication between your vRA environment & ADFS in order to be able to add & resolve the MetaData XML URLs. Another option is to just copy-paste the content of the MetaData XML or save the file(s).
- An Active Directory configured in vRA
ADFS Side Setup
Set up Relying Party Trust
First we need to setup a Relying Party Trust on the ADFS environment. To do this you can basically follow the procedure outlined by Microsoft for this and keep everything at default except modifying the ‘Data Source’ to your needs:
Below a short overview:
- Go to ‘Server Manager’ – ‘Tools‘ – ‘AD FS Management‘
- Under ‘Actions‘ select ‘Add Relying Party Trust’
- Follow the wizard, leave everything as default
- Under ‘Select Data Source‘ add your vRA Tenant’s MetaData XML URL or provide the file.
This URL can be found in the ‘Prerequisites‘ section earlier in this blogpost.
- Complete the wizard
Set up Claim Rules
Next up is setting up the Claim Rules in order to issue a set of tokens. According to the Microsoft documentation, the Role of Claim Rules can be defined as follows:
The overall function of the Federation Service in Active Directory Federation Services (AD FS) is to issue a token that contains a set of claims. The decision regarding what claims AD FS accepts and then issues is governed by claim rules.
For vRA we will be setting up 2 Rules. Let’s start!
- Click ‘Add Rule‘
- Choose the following template: ‘LDAP Attributes as Claims template‘
- Give the Claim Rule a name and set the Attribute Store to ‘Active Directory‘.
- Make sure to setup the correct mapping for your environment. In our use case the following was required: ‘LDAP Attribute – E-Mail-Addresses | Outgoing Claim Type – E-Mail Address‘. An example can be found below
- Click ‘Add Rule‘
- Choose the following template: ‘Send Claims Using a Custom Rule‘
- Give the Claim Rule a name to your likings / standards and paste the following entry in the ‘Custom Rule‘ field*:
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", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"] = "vmwareidentity.domain.com");
- Make sure to change the ‘vmwareidentity.domain.com‘ to the FQDN of your vRA environment. E.g.
- Save your Claim Rule by clicking ‘Finish‘ and let’s configure vRA now! 🙂
*Note: The latest version of the Custom Rule entry can be found on the VMware KB pages provided in the ‘Resources’ section of this blog post.
The vRA Side Setup!
The all-in-one screenshot:
The written version:
- Logon to your vRA environment in a tenant of your choice
- Go to ‘Administration‘
- Select ‘Directories Management‘
- Select ‘Identity Providers‘
- Add an ‘Create Third Party IdP‘
- Give your Identity Provider a descriptive name. E.g.: ‘ADFS’
- Decide your SAML Request Binding. E.g.: ‘HTTP Redirect‘
- Enter your ADFS environment’s MetaData XML URL in the ‘Identity Provider Metadata URL or XML’ field. E.g.: https://<ADFS-SSO-FQDN.yourdomain.example>/FederationMetadata/2007-06/FederationMetadata.xml
- Click ‘Process IdP Metadata‘. This will automatically populate the Name ID Formatting From SAML Response fields below.
- Edit / Remove / Modify the fields so it looks like the all-in-one screenshot above.
E.g.: ‘urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress’ mapped to ’emails’
- Set the Name ID Policy in SAML Request to ‘unspecified‘ as shown in the all-in-one screenshot above.
- Under ‘User’s select your vRA AD Directory to use this ADFS integration with
- Modify the Network Ranges to your likings
- And set the ‘Authentication Method‘ to: urn:oasis:name:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
- Click ‘Save‘ & your good to go!
In order to test it, you need to modify your access policy in vRA to use this Identity Provider.
- Under the ‘Directories Management’ menu select ‘Policies‘
- Here you can add or modify your access policies
- !!! WARNING: Make sure that you can still access your vRA environment by your last known working Identity Provider in some way! For example only configure the ADFS Identity Provider for a specific network range or a specific application. In case something is wrong with your ADFS Identity Provider, you can still log on via your other Identity Provider(s). !!!
- Modify for example your default_access_policy and set the access from a specific network range or application type to use the ADFS Identity Provider.
E.g.: Web browser, macOs, …. to use ADFS IdP and the others to use another IdP of which you are sure you can still access it.
- Click ‘OK‘
- And click ‘Save‘ to apply your changes!
Let’s test it out!
- Browse to your Tenant vRA FQDN of which you’ve configured ADFS for and from a device which will be using the ADFS IdP as configured in your access_policy.
- If all goes well, you should land on your ADFS SSO sign in page
- Log in with credentials that have access to the vRA Tenant environment
- If all goes well you’ll be redirected back to vRA after login!
- A good start for troubleshooting issues with the setup is using a SAML plugin for your browser of choice in order to investigate the SAML Requests & Responses.
- Horizon.log file is a good place to investigate issues!
- E.g.: If you’ve mapped the wrong LDAP Attribute to the E-Mail Address on the ADFS Side within the Claim Rule we’ve setup, you might see what exactly ADFS is sending back to vRA. In combination with checking the ‘horizon.log’ file on your vRA environment, you might be able to see what exactly goes wrong (example: Invalid SAML response, cannot translate / decode response into format ’email address’).
Good luck! Hopefully it could be of any assistance 🙂