When configuring Ops Manager for VMware Pivotal Container Service (PKS) from an Authentication standpoint, you can either chose local authentication or use an external identity provider. The former means you are managing local users that reside within the User Account and Authentication (UAA) component of Ops Manager, which may be okay for a lab or proof of concept environment. However, for a Production deployment, most customers prefer to use their enterprise directory services which is typically Microsoft Active Directory.
Ops Manager can integrate with a number of external identity providers as long as it can speak SAML. For VMware customers, the preferred identity provider solution is VMware Identity Manager (vIDM) which not only supports Active Directory, but can also support a number of other directory service integrations like Active Directory Federation Services (ADFS) as example. Since vIDM supports SAML-based authentication, we can configure Ops Manager to use vIDM which also means we benefit from all of the enterprise Single Sign-On capabilities that vIDM delivers, including things like multi-factor authentication which can provide an additional layer of security when connecting to your PKS infrastructure.
Since there is currently no documentation on how to set this up, with the help of my colleague Blair Fritz and Assaf from the vIDM Engineering team, we have documented the process below which outline the required steps to integrate Ops Manager with vIDM.
Step 1 - Download and deploy vIDM. In my setup, I am using the latest release which is 3.2.0 and if you would like to follow a detailed step by step instructions, please take a look at the vIDM documentation here. As part of the vIDM setup, I will also assume you have also configured and synchronized with your Active Directory instance.
Step 2 - Next, we need to retrieve vIDM's Identity Provider (IdP) XML Metadata which will then be used to configure Ops Manager to use an external identity provider. Login to the vIDM Admin Console and navigate to Catalog->Web Apps and click on the Settings
Select the SAML Metdata from the left hand side and then click on the Identity Provider (IdP) metadata link which will open up a new window.
Copy the contents of the XML (make sure you do not copy the very top line that starts with This XML file does not ....) into your copy buffer which will be used in the next step.
Step 3 - Now, login to the Ops Manager UI via a browser. The following steps is for a brand new Ops Manager deployment, however, the process is similiar for an existing deployment that was configured with internal authentication. Please refer to the Existing Ops Manager Deployment section as the very bottom of this post for the specific details.
Select "Use an Identity Provider" to begin the configuration
Take the IdP XML metadata that was copied from Step 2 and past that into the first box as shown in the screenshot below. Next, we need to provide our SAML group/attributes names which are simply labels that we need to define within vIDM. You need to use two different values, to ensure you do not make a mistake, I have highlighted my example with two different colors which you can refer throughout the article. In my example, I am using the following:
- SAML Group Name: pks-admins
- SAML Group Attribute: pks-users
Next, provide the decryption password as well as selecting the "Provision an admin client in the BOSH UAA" and click the "Setup Authentication" button to begin.
This will take a few minutes and once it has completed, you should see the following screen. Do not worry, this is expected and we can move onto the next step.
Step 4 - Next, we need to retrieve Ops Manager's Service Provider (SP) XML metadata by going to following URL: https://[OPS-MANAGER-HOSTNAME-OR-IP]/uaa/saml/metadata which we will save to our desktop. Open the XML and copy it into your copy buffer for the next section as shown in the screenshot below.
Step 5 - Return back to your vIDM Admin Console to create the Ops Manager Web App. Under Catalog->Web Apps, click on the New button.
In the Definition section, you just need to provide a name for the web app, which we are using "Ops Manager". You can also add other pieces of information such as a description or icon, then click Next.
Step 5 - In the Configuration section, we now paste the Ops Manager's Service Provider (SP) XML metadata which we retrieved from Step 4 into the URL/XML box. Next, we need to expand the "Advanced Properties" to define our custom attribute mapping. This is the SAML group name and attributes that we had defined in Step 3 and in the next step, is where we associate the AD Group/Users within vIDM. Think of these as labels that are passed to Ops Manager for processing, you can use any name and they have nothing to do with the actual AD Group/Users, just make sure it matches what you have defined in Step 3.
Again, I have highlighted the parameters to the colors that match Step 3 so you can easily reference the values. In my example, I have the following:
- Name: pks-users
- Namespace: pks-admins
- Value: pks-admins
For the Format, select unspecified and then click Next to continue.
Step 6 - You can keep the default Access Policies and in the Summary section, click on the "Save & Assign" button, so that we can also assign the list of AD Group/Users mapped to the SAML group name that we had defined earlier.
Step 7 - Here is where we associate our actual AD Group/Users to the SAML group (pks-admins) that we had defined earlier. You can add as many groups and/or users that you wish to provide Ops Manager access. In my example, I have an AD group called "primp-admins" and one of the users in the group is named primp. Click next to complete the Ops Manager web app configuration.
At this point, we have completed all the configurations and we just need to test that it works.
Step 8 - Open a new incognito browser window (to prevent caching) and connect to Ops Manager. You should that it will automatically re-direct to our vIDM instance for authentication. Go ahead and select the domain and enter the credentials of a user that is in the AD Group that you had defined in Step 7 and then click login.
If everything was configured correctly, you should now be logged into Ops Manager using your AD account! As you can see in the screenshot below, the username here is primp which is what I had used to login to vIDM with.
Existing Ops Manager Deployment
If you have already deployed an existing Ops Manager, you can actually reconfigure the Authentication Method. To do so, simply login to Ops Manager with a local account and then in the upper right hand corner, click on the user name and select "Settings". Navigate to the Authentication Method section and simply fill out the exact same section as outline in Step 3. The only difference here is that you will provide your existing decryption passphrase which you had initially configured during Ops Manager setup. Once you click on "Setup SAML", you can return back to Step 4 and follow the exact sample procedure.
Role-Base Access Control (RBAC)
Ops Manager does support RBAC by using the UAA CLI, however you would need to create an additional web app within vIDM to scope the the specific AD Group/Users. For example, we could have the following two web apps:
- Ops Manager - Admin
- Ops Manager - Read Only
We have already defined the "Admin" app above. For the read only, we could define the following SAML group name/attribute mapping:
- SAML Attributes: pks-users
- Namespace: pks-viewers
- Value: pks-viewers
You would login with a user that has Ops Manager admin privileges as outlined in the documentation here and then assign the SAML Group Name you defined above to have a restrictive role such as opsman.restricted_view (for all roles, see here) which means you would have to run the following UAAC command:
uaac group map 'pks-viewers' --name 'opsman.restricted_view' --origin 'external-saml-provider'
Once that is done, you can open a new incognito browser and try to login to Ops Manager using one of the users that you have mapped in the read only group and you should only be able to "view" Ops Manager configuration and not make any changes.
Eric K. says
great post by the way.
I'm wondering if the procedure can be applied using the embeddede vIDM in vRA (7.6) as I would like to provide Container as a Server and Kubernetes cluster as a Service.
it would be great not being forced to double the configuration effort of the Identity Management.