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 you create an organization, it receives 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 can make this request without authentication.

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. Verify that you are logged in to the vCloud Air Compute Service as an Account Administrator.

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. To add your identity provider's SAML metadata as the value of the SAMLMetadata element, modify the retrieved OrgFederationSettings 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 appears.

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 you specify a SAML identity provider, you must retrieve the SAMLMetadata element from a GET request to the endpoint and include the Enabled, SamlSPEntityId, and SamlAttributeMapping elements in the update request. If you do not, the request fails without changing the OrgFederationSettings.

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>