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.

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.

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

3

Update the OrgFederationSettings with your modifications.

a

Find the Link element in the settings element where rel="edit".

b

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 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>
   <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>
   <Enabled>true</Enabled>
</OrgFederationSettings>