- Part 1 – Setting up the ADFS Server
- Part 2 – Configuring VIO to consume ADFS
- Part 3 – Multi group mappings
VMware Integrated OpenStack (VIO) is not one of the VMware solutions that I work with on a regular basis, at least not in comparison to vRA and vRO. Recently however, I’ve been working with another VMware PSO Consultant on a VIO delivery. We have been coming across some more advanced requirements, including using ADFS to auto create users in VIO. This series of posts highlights some of the configuration we implemented, which isn’t always covered in great detail within the official documentation.
Credit to my amazing colleague from the USA Adam Robinson (www.v-punk.com @omgitsadam) who figured out the JSON format needed to allow group based mappings which is crucial to the final solution.
This first part of the series covers setting up the ADFS server to allow VIO to relay requests to it, and the initial configuration on VIO to set the ADFS parameters for use.
Background
For this particular VIO engagement the customer wanted to be able to use a single identity source (ADFS) as the location for the user account information. They didn’t want to have to manage a separate set of accounts within VIO, which is the default configuration the product provides. They also wanted to be able to auto assign users to projects within VIO based on Active Directory security group membership, so that ADFS could again be used as the single source of truth for all access and authentication requests.
Specifically we had to meet the following requirements:
- Users should be able to belong to more than one security group. Where this occurs the user should be granted access to all matching projects within VIO
- Users who do not belong to any in scope security groups should be prevented from logging in by VIO when using their AD credentials
- Users and Projects should be auto created within VIO i.e. when the user logs for the first time VIO should create a project (if the named project does not already exist), create a user account of type ADFS and assign the account to the Member role within the new project
- The ADFS configuration on VIO should enforce the use of SSL i.e. it must validate the SSL certificate (including the full certificate chain) of the ADFS server
- The configuration should allow additional groups, users and projects to be added in the future
Having never previously configured ADFS with VIO our starting point was the VMware documentation, which covers the basic configuration steps. There was no mention or examples of using groups rather than users for authentication, or how you could assign a role to the users though. Widening the search, the open source OpenStack documentation contains more examples around the assignment of roles and the use of groups, still there wasn’t an exact match for our setup so it looked like a bit of trial and error would be needed. Let’s dive into the solution.
ADFS Server Configuration
The first part of the solution to configure is the ADFS server. In order to allow the Keystone component of VIO to relay requests for user authentication to the ADFS server successfully you must create/configure the following components on the ADFS server:
- A relaying party trust for VIO
- Claim rule(s) for the AD security groups you want to use with VIO
It’s important to note here that when you configure the relaying party the name you use in the url value for the endpoint url and the identity provider url must match the value you enter when setting the ADFS configuration on VIO. When VIO relays the authentication request to ADFS it will append the name you specify onto the end of the url. If the same url is not present on the ADFS server the task to reconfigure the VIO deployment will succeed, and you will receive an error message when you try to log in using ADFS credentials. This has been logged as a bug on the VMware documentation, which does not show matching values being used within its example.
The steps to perform this configuration for user UPN based matches are listed in the VMware documentation so I won’t recreate them here. To enable matching based on AD groups additional claim rules are required once the UPN configuration has been completed.
Within the ADFS administration console browse to the Trust Relationships>Relaying Party Trusts section and select the trust created for VIO. On the right of the screen select Edit Claim Rules
When the Edit Claim Rules box appears select Add Rule. From the Claim rule template drop down box select ‘Send Group Membership as a Claim’ and click Next.
The name of the rule can be set to any value you like, for simplicity we have used the name of the group the rule will be used for. When the number of rules starts to increase this will provide an easy method to identify the purpose of each rule.
Click the Browse button next to User’s group and enter the name of the AD security group you are creating a rule for.
Under Outgoing claim type select ‘Group’ and in the last box Outgoing claim value enter the name of the AD security group again. Click Finish to create the claim rule.
Repeat this process for each of the AD security groups you will be using to map users within VIO.
ADFS Server SSL Certificates
For this solution we had a requirement to use trusted SSL connections. Within the customer environment the VIO and ADFS servers were located in different domains and did not have a shared Root CA server. This meant that VIO did not automatically trust the ADFS server, and we needed to install the full certificate chain before implementing the ADFS configuration on the VIO servers.
Unfortunately the official VMware documentation is not entirely clear on how to achieve this. There are no notes in the section around configuring the SAML federation to guide you on how or where to place the certificates. There is however a clue under the viocli command reference section where there is a page covering certificates. The exact solution needed a bit of trial and error in a lab environment and the assistance of VMware GSS technicians to work out.
Installing the Certificates
Download the ADFS Server certificate and both the Root and Issuing CA Certificates (if applicable) from the ADFS Server. Alternatively grab the CA certificates from the CA servers themselves. The ADFS Server certificate needs to be in .pem format, while the Issuing and Root CA files will need to be in .crt format.
Either copy the ADFS server certificate file onto the VIO OMS nodes, or copy and paste the file contents into a new file using vi for example on the OMS nodes.
Run the command below to import the ADFS server certificate into VIO. When the import completes you will be prompted to run service oms restart to restart the OMS service. Restart the service and then repeat the process on the other OMS nodes.
sudo viocli certificate add --cert <path to .pem> --cert-name <subject field from cert>
The next step will vary slightly depending on the configuration of your environment. If the ADFS server certificate chain consists of both an issuing Intermediate CA and a Root CA, then these certificates must be combined into a single .crt file before they can be imported. The format used must be the Root CA certificate listed first, followed by the Issuing CA certificate. The file needs to be copied/created on the VIO controller nodes and not the OMS nodes.
On the first controller node add the combined .crt file to /etc/ssl/certs/ and run the command
sudo update-ca-certificates
It should show that one certificate was added. Check the contents of the /usr/local/share/ca-certificates directory. This should now have a copy of the certificate file that was imported. Repeat this process on the other controller nodes.
Now everything is setup on the ADFS server side of the solution and VIO trusts the ADFS server certificates. Part 2 of this series will cover how the ADFS parameters should be configured on the VIO OMS nodes.