vCloud Director 9: SAML2 Federation for System Administrators

In the past in vCloud Director 8.20 (and older versions) system admins (the provider context) could use local, LDAP and vSphere SSO accounts. vCloud Director 9.0 now replaces vSphere SSO accounts with more generic SAML2 accounts which means you can have the same IdP mechanism in the tenant and system context.

This change however breaks the previous vSphere SSO federation which was as simple as entering the vSphere Lookup Service URL and enabling the vSphere Single Sign-On with a check box (which in vCloud Director 9.0 is no longer there).

Here is the procedure how to enable vSphere Single Sign-On in vCloud Director 9.0.

  1. Login to vCloud Director as system admin and from administration>System Settings/Federation download the metadata document (spring_saml_metadata.xml) from the link provided (../cloud/org/System/saml/metadata/alias/vcd). Make sure the certificate (below) is valid.
  2. Login to vSphere Web Client as SSO admin and go to Administration/Single Sign-On/Configuration/SAML Service Providers
  3. Import the metadata from step #1
  4. Download the vsphere.local.xml metadata from the link below.
  5. Go back to VCD, check use SAML Identity Provider and upload metadata from #4.

Note that Import Users/Group source now changes from vSphere SSO to SAML.

vCloud Director 8.20
vCloud Director 9.0
Advertisements

Configure Active Directory Federation for vCloud Director Organization

Configure Active Directory Federation for vCloud Director Organization

vCloud Director tenants can federate their on-premises identity source with vCloud Director to simplify user management in their vCloud organization. I have already wrote blog post about this topic in the past; this time I will provide step by step instructions how to federate Active Directory with Active Directory Federation Services (AD FS).

Installation and configuration of AD FS is out of scope for this article as there are already very good and detailed guides on the internet.

  1. Download AD FS SAML2 metadata from your AD FS server (https://adfs.acme.com/FederationMetadata/2007-06/FederationMetadata.xml)
  2. As Org Administrator log into vCloud Director and in Administration > Settings > Federation check Use SAML Identity Provider checkbox and upload FederationMetadata file from #1.
  3. Still on the same page fill in Entity ID (must be unique for given IdP) and regenerate certificate. It will be valid for 1 year after which it must be regenerated again.
    Note: Entity ID is available only in vCloud Director 8.10 and newer.
  4. Click Apply.
  5. Download SAML metadata file from https://<vcd_url>/cloud/org/<org-name>/saml/medatadata/alias/vcd.
    Note: vCloud Director 8.10 provides link to the file just above the Certificate Expiration button.
    vcd-config-saml
  6. In Administration > Memebers > Users import SSO users from the SAML source. As user name use email address. Assign a vCloud role.
  7. It is also possible to import SSO groups from the SAML source. However, Groups menu might be missing under Users until you refresh the page (Groups menu got enabled by the step #2). For group import simply use AD group name (without domain).
    Note: If you get log out before setting up AD FS you can always go back to native authentication dialog by entering the following URL: https://<vcd_url>/cloud/org/<org-name>/login.jsp
    groups
  8. That’s all for vCloud Director configuration. The rest must be done in AD FS. Open AD FS Management Console and in Actions menu cling on Add Relying Party Trust. Go through the wizzard and import the SAML metadata file from step #5.
  9. Next we need to Edit claim rules. Under Issuance Transform Rules, using Send LDAP Atributes as Claims template create LDAP claim rule that uses Active Directory as Attribute Store and maps E-Mail-Addresses to E-Mail Address and Token-Groups – Unqualified Names to Groups.
    claim1
  10. Add another transform rule from Transform an Incoming Claim template that transforms E-Mail Address to Name ID.claim2
  11. Last thing that needs to be done is changing Relying Party Trust hashing algorithm from SHA-256 to SHA-1 (can be found in Properties > Advanced).

That’s all, now depending how your browser is configured, when you enter vCloud Director Organization URL you will be redirected to authentication dialog (either native browser or at the AD FS website). Enter AD credentials and if the user had been properly imported into vCloud Director (as individual user or member of a group) you should be logged into vCloud Director UI.

 

Edit 11/24/2016: My faithful readers (thank you Julius) have provided additional links for federations with other IdP solutions:

SafeNet Authentication Service: Integration Guide

RSA SecureID: blog post

vCloud Director – vCenter Single Sign-On Integration Troubleshooting

The access to vCloud Director provider context (system administrator accounts) can be federated with vCenter Single Sign-On. This means that when vCloud system administrator wants to log into the vCloud Director (http://vCloud-FQDN/cloud) he is redirected to vSphere Web Client where he needs to authenticate and then redirected back to vCloud Director.

VCD_SSO_Federation

Here follows collection of topics that might be useful when dealing when troubleshooting the federation:

1. When the SSO federation is enabled the end-user is always redirected to vSphere Web client. If you want to use local authentication use http://vCloud-FQDN/cloud/login.jsp and type local or LDAP account (if LDAP is configured).

2. If you enabled SSO federation and the vCenter SSO is no longer available, you cannot unregister its lookup service. To do this go to vCloud database and in dbo.config table clear the lookupservice.url value.

3. In case you are using self-signed untrusted certificate on the vSphere web client some browsers (Firefox) might not display the Add Security Exception button when being redirected. Therefore open first the vSphere web client page directly, create the security exception and then the redirection from vCloud website should work.

4. HTTP ERROR 500. Problem accessing /cloud/saml/HoKSSO/alias/vcd. Reason: Error determining metadata contracts
….
Metadata for issuer https://xxx:7444/STS wasn’t found

This error might appear after the vSphere web client SSO authentication when the user is redirected back to vCloud portal. To understand this error let’s first talk about what is going on in the background. When the SSO federation is enabled, vCloud Director establishes trust with vCenter SSO. The trust is needed so the identity provider (SSO) knows that the request for authentication is not malicious (phishing) and also the service provider (vCloud Director) needs to be sure the reply comes from the right identity provider.

The trust is established when the federation is configured with metadata exchange that contains keys and some information about the other party. The SSO metadata can be seen in vCloud Director database in the dbo.saml_id_provider_settings table. Now during the actual authentication process if for some reason the security token reply comes from different source than the one expected based on the identity provider metadata, you will get this error.

This issue might happen for example if the vCenter SSO hostname has been changed. In this particular case which I encountered it happened on vCenter Server Appliance 5.1. The SSO has been initiated before the hostname was set. So the identity provider response came with metadata containing the issuer’s IP address instead FQDN which the service provider (VCD) expected based on the SSO endpoint address. The issuer information did not get updated after the hostname change.

The VCSA 5.1 the issuer information is stored in SSO PostgreSQL DB. These are the steps to change it:

  1. Get the SSO DB instance name, user and password

cat /usr/lib/vmware-sso/webapps/lookupservice/WEB-INF/classes/config.properties

db.type=postgres
db.url=jdbc:postgresql://localhost:5432/ssodb
db.user=ssod
db.pass=rTjsz9PRPLOFswBkJTCNAAVp
`

  1. Connect to the DB with the password retrieved from the previous step (db.pass=…)

/opt/vmware/vpostgres/1.0/bin/psql ssodb -U ssod

Retrieve the STS issuer:

ssodb=> select issuer from ims_sts_config;

If the issuer is really incorrect update it with following command:

ssodb=> update ims_sts_config SET issuer='https://FQDN:7444/STS'

Note: I need to credit William Lam for helping me where to find the SSO DB password.

vCloud Director and Single-Sign-On (SAML)

In December last year i wrote a blog post about vCloud Director and SSPI Authentication. In the post I stated that besides using SSPI – which is Microsoft proprietary interface on top of Active Directory, the tenants can use Security Assertion Markup Language (SAML) standard to integrate with their identity provider. VMware has tested SAML2 integration with OpenAM (described in detail in vCloud Architecture Toolkit Implementation Examples) and Active Directory Federation Services (ADFS). However just recently there appeared another supported identity provider – our own VMware Horizon Workspace. The following whitepaper describes the integration in detail: Using VMware Horizon Workspace to Enable SSO in VMware vCloud Director 5.1.

In this post I will provide short step-by-step description of all the necessary steps that you as the vCloud Organization Administrator must take. The assumption is that you have on premise Horizon Workspace integrated with company Active Directory and want to use it for connecting private or public vCloud Director organizations.

  1. Download Horizon Identity provider metadata XML file from: https://<horizon_workspace_URL>/SAAS/API/1.0/GET/metadata/idp.xml
  2. In the target cloud go to Administration > Settings > Federation menu and check Use SAML Identity Provider and upload the idp.xml file
  3. Still on the same page regenerate the certificate and click apply
  4. Download the certificate from the url: https://<vcloud_URL>/cloud/org/<orgname>/saml/metadata/alias/vcd
  5. Log out from the cloud
  6. Log back in, you will need to change the URL to go directly to the local authentication: https://<vcloud_URL>/cloud/org/<orgname>/login.jsp
  7. In the Administration > Members > Users (or Groups) import Users (or Groups) by clicking the icon with arrow. Change the Source to SAML and type the user names or group names.
  8. Back in Horizon Workspace admin interface create a new Web Application in the catalog
  9. Fill in the following data:
    • Authentication Profile: SAML 2.0 POST profile
    • Login Redirection URL: https://<vcloud_URL>/cloud/org/<orgname>/
    • Check: Include Destination
    • Check: Sign Response
    • Check: Sign the Assertion
    • Configure via Metadata XML
    • Paste the certificate from point 4 into the Meta-data XML box
    • Add Attribute Mapping as seen in the screenshot
      Attribute Mapping
    • Save the page
  10. Edit the newly created Web Application and assign Entitlements (either specific users or a group). These should be the same users as in step 7.
  11. Now log into the Horizon as the entitled user and click the application icon. You should now get direct access into the vCloud Director.

Horizon Workspace

 

Edit 2 July 2013: In order to get SAML Groups working following is needed.

In step 9 create also group mapping. The group name must be hardcoded, but that should not be such a problem as a different web application in Horizon Workspace can be created for each group/role mapping. I have created hardcoded mapping to group name OrgAdministrators.

Attribute Mapping with Group

 

Then in step 7 the group can be imported and the correct role assigned.

SAML Group Import