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

Procedure

Retrieve the OrgFederationSettings.

Use a request like this one:

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

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

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.

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>