An organization that defines an external identity provider that it shares with other applications or enterprises is said to be federated with those applications or enterprises.

An organization can define a SAML identity provider that it shares with other applications or enterprises. Users that authenticate to the identity provider obtain a token that they can then use to log in to the organization. Such a strategy can enable an enterprise to provide access to multiple, unrelated services, including vCloud Director with a single set of credentials, an arrangement often referred to as single sign-on. An organization that wants to participate in a federated identity scheme must include an OrgFederationSettings element that contains SAML metadata retrieved from the federation's identity provider. By default, this element is empty.

Note

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.

Verify that you are logged in to the vCloud API as an organization administrator or system administrator.

Download the appropriate SAML metadata in XML format from your identity provider. The SAML metadata must provide mappings for the user attributes shown in this XML fragment:

<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"/>

1

Retrieve the list of organization settings elements.

Use a request like this one:

GET https://vcloud.example.com/api/admin/org/26/settings

The response is an OrgSettings element.

2

Examine the OrgSettings element to find the link to the OrgFederationSettings.

3

Retrieve the OrgFederationSettings.

Make a GET request to the URL in the element's href attribute value.

4

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 Example: Update Organization Federation Settings

5

Update the OrgFederationSettings with your modifications.

Find the Link element in the settings element where rel="edit". 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 Example: Update Organization Federation Settings.

This example updates the OrgFederationSettings of the organization created in Example: Create an Organization. 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/26/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>
   <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/26/settings"
      type="application/vnd.vmware.admin.organization+xml"/>
   <Link
      rel="edit"
      href="https://vcloud.example.com/api/admin/org/26/settings/federation"
      type="application/vnd.vmware.admin.organizationFederationSettings+xml"/>
   <Link
      rel="federation:regenerateFederationCertificate"
      href="https://vcloud.example.com/api/admin/org/26/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>
   <Enabled>true</Enabled>
</OrgFederationSettings>