- Part 1 – Setting up the ADFS Server
- Part 2 – Configuring VIO to consume ADFS
- Part 3 – Multi group mappings
In part 1 of this series the focus was on configuring the ADFS server ready for consumption by VMware Integrated Openstack (VIO), and on ensuring VIO trusted the ADFS server certificates.
This post will focus on the steps required to configure VIO to consume the ADFS instance, using the UPN attribute of a user account and the user’s security group membership.
Attribute and Mapping JSON Files
Looking at the documentation we can see that the process to configure VIO involves running a viocli command, responding to prompts with details about the ADFS server and providing two JSON files attribute.json and mapping.json. So let’s start by taking a look at the purpose of these files.
attribute.json
The attribute.json file contains the ADFS Claim Rule Descriptions that VIO will consume. These are not the claim rules that we created in part 1, they are the schema provided by ADFS for a type of claim rule e.g. UPN. The details to use within this file are found within the ADFS administrative console under the Service>Claim Descriptions section.
Taking the example provided in the VMware documentation we can see an entry consists of a name and an id value.
[
{
"name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
"id": "upn"
}
]
Comparing these values with the UPN Claim Description entry in the ADFS administrative console we can see that the id value in the json file maps to the Short Name value and the name value maps to the Claim Type value.
Looking at the Claim Description entry for Group leads to the following base structure for the json file
"name": "http://schemas.xmlsoap.org/claims/Group",
"id": "group"To ensure VIO consumes both claim types we need to combine the values for UPN and group into a single json file. Since the structure of the file is a single array (indicated by the [ ] at the start and end of the file) with each entry contained within the { } the combined file looks like this:
[
{
"name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
"id": "upn"
},
{
"name": "http://schemas.xmlsoap.org/claims/Group",
"id": "group"
}
]
This file needs to be created/copied to each of the OMS nodes.
mapping.json
The mapping.json file provides the schema for VIO to map the ADFS users and groups to domains, projects and roles within VIO. The way VIO works means that any domain or project specified within this file will be automatically created if it does not exist, and updated if it does already exist. The role specified however must already exist within VIO.
The OpenStack documentation provides an overview of how the file is structured, I strongly suggest you read the documentation before trying to change any example files.
The example provided in the VMware documentation shows how to use the UPN of a user account to map a user to a new domain called adfs-users and a new group called Federated Users. The example does not map the users to any roles or projects though.
The local section of the file sets out the values used within VIO, while the remote section sets out the values to map to within ADFS. The use of the {0} for the name attribute within the local section tells VIO to use the first value specified within the remote section i.e. the UPN value from AD.
Using the OpenStack documentation as a reference, we can see from the Auto Provisioning section that there is an attribute named Projects which can be added within the local section of the file to enable the automatic creation of new projects within VIO for the federated users. Within the Projects attribute there is then a sub attribute named Roles which can be used to map the federated users to a particular role within the new project. Exactly what we needed to do.
The final mapping.json file used is shown below. VIO-Projectx is used as the name of the AD group as well as the name of the Project within VIO for simplicity, however this is not mandatory. The any_one_of attribute is used to allow additional AD backed groups to be added in the future to a single project if required. Again this file needs to be created/copied to each of the OMS nodes.
[{
"local": [{
"user": {
"name": "{0}"
},
"group": {
"domain": {
"name": "adfs-users"
},
"name": "Federated Users"
},
"projects": [{
"name": "VIO-Project1",
"roles": [{
"name": "member"
}]
}]
}],
"remote": [{
"type": "upn"
},
{
"type": "group",
"any_one_of": ["VIO-Project1"]
}
]
},
{
"local": [{
"user": {
"name": "{0}"
},
"group": {
"domain": {
"name": "adfs-users"
},
"name": "Federated Users"
},
"projects": [{
"name": "VIO-Project2",
"roles": [{
"name": "member"
}]
}]
}],
"remote": [{
"type": "upn"
},
{
"type": "group",
"any_one_of": ["VIO-Project2"]
}
]
}
]
Adding a Federation Identity Provider to VIO
With all of the configuration files and certificates ready it is now possible to finally run the commands to add a Federation Identity Provider to VIO. The steps listed in the VMware documentation can be followed to complete this process with the following important things to note when running the sudo viocli federation identity-provider add –type saml2 command:
- The command should be run on each OMS node in turn. Complete the process on the first node before continuing to the remaining nodes.
- The value entered for the Identity provider name must match the value used when setting up the relaying party trust in ADFS. The value entered here is passed as part of the url to ADFS, and if it does not match the configuration in ADFS an error will be returned to VIO and the user will not be able to log in.
- The value entered for the Identity provider display name is shown to users on the VIO login page as a value in a drop down box. This is the only prompt the users see for ADFS, there is no description field or mouse over text to tell them that it relates to their AD credentials until the screen that appears after selecting the ADFS option.
- When prompted if you want to verify the TLS/SSL certificates remember that the question being asked is a negative, so answering True will tell VIO to ignore certificates, False will tell VIO to ensure certificates verify without errors.
- When asked if VIO should use a static file or a template file for the two json files answer static to allow the use of the custom .json files.
- The value of the domain to associate federated users to is the name entered in the mapping.json file e.g. adfs-users.
- The value of the group to associate federated users to is the name entered in the mapping.json file e.g. Federated Users.
When prompted run the sudo viocli identity configure command to apply the configuration. This can take up to 15 minutes or more to complete and does not report any progress onscreen. You can monitor the progress via the /var/log/syslog file on the OMS node you are performing the task on.
If the configure command completes successfully you have now configured ADFS Federation with VIO and the solution is ready for testing.
Any user who belongs to a security group listed within the ADFS claim rules and within the mapping.json file should now be able to log in using their AD credentials and be automatically mapped to the specified project and role.
The VIO Horizon log in page will now display a drop down box to allow users to select whether to use the ADFS based login or the local OpenStack authentication.
Upon selecting the ADFS based authentication a new login screen will load to prompt the user to enter their AD credentials. Notice the AD Domain name is shown on the top of this page but the drop down box on the previous page only showed the name provided during the setup of the Identity Provider.
After entering their credentials for the first time VIO will automatically create a user account for them, create the project to which they belong (if it does not already exist) and assign the account to the specified role within the project. This means the first log in for each user via ADFS can take a few minutes to complete. Once logged in you will see that the user name in the top right of the screen is set to the UPN value from the AD account, and the project shown in the top left is set to Federated and the name of the project from the mapping.json file.
Logging in as the vioadmin account in a separate incognito window after the user has completed logging in via ADFS, you will see the projects and users created via the federation mappings. Notice how the Domain Name associated with the auto created projects is listed as adfs-users in this example, the name provided in the mapping.json file. Viewing the membership of a project shows the role mappings assigned to the users.
The final part of this series will cover the extra use case of allowing users to be mapped to multiple projects via ADFS federation.
Troubleshooting failures
If the configure task fails check the syslog file for information on the cause. If you see an error similar to the extract below the import of the SSL certificates has not been completed successfully. Retrace your steps and ensure the complete chain has been imported to the correct locations on the correct nodes.
2019-07-30 13:19:51,910 column.plugins.callback.progress Started TASK [keystone : fetch IdP metadata XMLs]
2019-07-30 13:19:53,673 p=1564 u=jarvis | fatal: [192.168.110.200 -> 192.168.110.200]: FAILED! => {"changed": false, "failed": true, "msg": "HTTPSConnectionPool(host='controlcenter.corp.local', port=443): Max retries exceeded with url: /federationmetadata/2007-06/federationmetadata.xml (Caused by SSLError(SSLError(1, u'[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:590)'),))", "url": "https://controlcenter.corp.local/federationmetadata/2007-06/federationmetadata.xml"}
After resolving the issue list the identity providers using the command
sudo viocli federation identity-provider list
A single result should be returned with an id value of 1. Now edit the identity provider by running the command
sudo viocli federation identity-provider edit --id 1
This reruns the command to configure the identity provider and you will need to answer the prompts again (most of the prompts can be left to just accept the previous answers by pressing enter). You will then need to run the sudo viocli identity configure command again to apply the updated configuration.
Do not use the sudo viocli federation identity-provider remove command unless you no longer require the provider. There is a bug with VIO 5.x (and possibly other versions) where the identity provider is not removed from the Keystone database when this command is run. If you then try to add a new provider with the same name VIO will report an error when you run the sudo viocli identity configure command similar to ‘Conflict occurred attempting to store identity_provider – Duplicate remote id‘. In this case you must remove the identity provider from VIO, reconfigure the deployment and manually delete any remaining entries from the Keystone database. This step should not be performed without first contacting VMware Support to confirm you are experiencing the issue reported in the bug, and the manual deletion from the database is the correct resolution.
1 thought on “Setting up ADFS Federation with VMware Integrated Openstack – Part 2”