Configuring and Managing Federation with SAML

An organization can define an external identity provider that supports the Security Assertion Markup Language (SAML) 2.0 standard. All organizations participating in a SAML-based federated identity scheme must include an OrgFederationSettings element that contains SAML metadata retrieved from the same identity provider.

When an organization is created, it is provided with a self-signed certificate for use when establishing trust with an identity provider. This certificate expires after one year. You can regenerate this certificate by making a request of the following form. 
POST https://vcloud.example.com/api/admin/org/id/settings/federation/action/regenerateCertificate
You can retrieve this certificate with a request of the following form, where name is the name of the organization. 
GET https://vcloud.example.com/cloud/org/name/saml/metadata/alias/vcd
You do not have to be authenticated to make this request.

You can also add your own certificate chain and private key by including a SamlSPKeyAndCertificate element in your OrgFederationSettings update.

Prerequisites

This operation requires the rights included in the predefined Organization Administrator role or an equivalent set of rights.

Download the appropriate SAML metadata in XML format from your identity provider. The SAML metadata must provide mappings for the default or custom user attributes. The following example XML fragment shows mappings to the default user attributes. Optionally, you can define custom user attributes by using the SamlAttributeMapping element in your organization OrgFederationSettings as shown in Update Organization Federation Settings. 
<saml:Attribute
   FriendlyName="Groups"
   Name="http://rsa.com/schemas/attr-names/2009/01/GroupIdentity"
   NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
<saml:Attribute
   FriendlyName="givenName"
   Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
   NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
<saml:Attribute
   FriendlyName="surname"
   Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
   NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
<saml:Attribute
   FriendlyName="Subject Type"
   Name="http://vmware.com/schemas/attr-names/2011/07/isSolution"
   NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
<saml:Attribute
   FriendlyName="userPrincipalName"
   Name="http://schemas.xmlsoap.org/claims/UPN"
   NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
<saml:Attribute
   FriendlyName="email"
   Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
   NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>

Procedure

  1. Retrieve the OrgFederationSettings.
    Use a request like this one: 
    GET https://vcloud.example.com/api/admin/org/40/settings/federation
  2. Modify the retrieved OrgFederationSettings element to add your identity provider's SAML metadata as the value of the SAMLMetadata element.
    XML entities must be encoded, as shown in Update Organization Federation Settings
  3. Update the OrgFederationSettings with your modifications.
    1. Find the Link element in the settings element where rel="edit".
    2. Make a PUT request to the URL in that link's href attribute value, and supply the modified section as the request body. See the request portion of Update Organization Federation Settings.

Example: Update Organization Federation Settings

This example updates the OrgFederationSettings of an organization whose URL is https://vcloud.example.com/api/admin/org/40/. The update adds SAML metadata retrieved from an identity provider, and enables federation by setting Enabled to true. Only a subset of the SAML metadata is shown.

Request: 
PUT https://vcloud.example.com/api/admin/org/40/settings/federation
Content-Type: application/vnd.vmware.admin.organizationFederationSettings+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<OrgFederationSettings
   type="application/vnd.vmware.admin.organizationFederationSettings+xml">
   <SAMLMetadata>
      &lt;EntitiesDescriptor
      xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
      xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" .... &gt;
      ...
      &lt;/EntitiesDescriptor&gt;</SAMLMetadata>
   <SamlAttributeMapping>
     <EmailAttributeName>email</EmailAttributeName>
     <UserNameAttributeName>userPrincipalName</UserNameAttributeName>
     <FirstNameAttributeName>givenName</FirstNameAttributeName>
     <SurnameAttributeName>surname</SurnameAttributeName>
     <FullNameAttributeName>name</FullNameAttributeName>
     <GroupAttributeName>Groups</GroupAttributeName>
     <RoleAttributeName>Roles</RoleAttributeName>
   </SamlAttributeMapping>
   <Enabled>true</Enabled>
</OrgFederationSettings>
Note: To update or remove OrgFederationSettings after a SAML identity provider is specified, you must include an empty SAMLMetadata element in the update request. If you do not, the request fails and the OrgFederationSettings are not changed.

The response contains information extracted from the request, and includes Link elements that the server creates.

Response: 
200 OK
Content-Type: application/vnd.vmware.admin.organizationFederationSettings+xml
...
<OrgFederationSettings ...
   type="application/vnd.vmware.admin.organizationFederationSettings+xml">
   <Link
      rel="up"
      href="https://vcloud.example.com/api/admin/org/40/settings"
      type="application/vnd.vmware.admin.organization+xml"/>
   <Link
      rel="edit"
      href="https://vcloud.example.com/api/admin/org/40/settings/federation"
      type="application/vnd.vmware.admin.organizationFederationSettings+xml"/>
   <Link
      rel="federation:regenerateFederationCertificate"
      href="https://vcloud.example.com/api/admin/org/40/settings/federation/action/regenerateFederationCertificate"/>
   <SAMLMetadata>&lt;EntitiesDescriptor
      xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
      xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" .... &gt;
      ...
      &lt;/EntitiesDescriptor&gt; </SAMLMetadata>
   <SamlAttributeMapping>
     <EmailAttributeName>email</EmailAttributeName>
     <UserNameAttributeName>userPrincipalName</UserNameAttributeName>
     <FirstNameAttributeName>givenName</FirstNameAttributeName>
     <SurnameAttributeName>surname</SurnameAttributeName>
     <FullNameAttributeName>name</FullNameAttributeName>
     <GroupAttributeName>Groups</GroupAttributeName>
     <RoleAttributeName>Roles</RoleAttributeName>
   </SamlAttributeMapping><Enabled>true</Enabled>
</OrgFederationSettings>