If your organization defines a SAML identity provider in its OrgFederationSettings, you cannot import the users or groups as you can from an LDAP service. Instead, you must map the SAML-defined roles of those users and groups to roles defined in your organization.

Unlike imports from an LDAP service, imports from a SAML identity provider do not actually import information from an external database. Instead, the operation creates a mapping between a user or group name in your organization's database and a user or group name defined by your organization's SAML provider. The vCloud Director database stores these mappings, but does not store any data retrieved from the SAML provider.

When you import a user from a SAML identity provider, you must include the domain name, such as user@domain.com. When you import a group from a SAML identity provider, you must use its fully distinguished name.

When a user login presents a SAML token to the organization, user and group names in the token are evaluated using the mappings established by the import operation. This evaluation process can be summarized as follows:

If the SAML token includes an attribute named UserName, try to match the value of that attribute to the value of the name attribute of the User.

If the SAML token does not include an attribute named UserName, try to match the value of the NameId element to the value of the name attribute of the User.

If the SAML token includes an attribute named Groups, assume that the value of that attribute is a list of group names, and try to match each value in the list to the value of the name attribute of a Group in the organization.

If the SAML token does not include an attribute named Groups, assume that the user is not a member of any group.

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

Verify that your organization has defined a SAML identity provider in its OrgFederationSettings.

1

Create a User or Group element that identifies a user or group defined by your organization's SAML provider.

2

Include the following line in the User or Group element.

<ProviderType>SAML</ProviderType>
3

POST the element to the organization's users or groups URL.

This example imports a user from the SAML identity provider defined by the organization. This example is identical to the one shown in Example: Import a User from an LDAP Database, but includes a ProviderType element that specifies the source as the organization's SAML identity provider. It also omits the IsExternal element, which is required when importing from LDAP but is ignored when importing from SAML.

The response is a User element, most of which is not shown in the example. The response includes a link that an administrator can use to edit user metadata, and additional elements, such as IsDefaultCached and StoredVmQuota, inherited from organization defaults. It also includes a NameInSource element, which contains the user's name in the encoding used by the identity provider.

Request:

POST https://vcloud.example.com/api/admin/org/26/users
Content-Type: application/vnd.vmware.admin.user+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<User
   xmlns="http://www.vmware.com/vcloud/v1.5"
   name="user@example.com"
   type="application/vnd.vmware.admin.user+xml">
   <IsEnabled>true</IsEnabled>
   <ProviderType>SAML</ProviderType>
    <Role
      type="application/vnd.vmware.admin.role+xml"
      href="https://vcloud.example.com/api/admin/role/105" />
</User>

Response:

201 Created
Content-Type: application/vnd.vmware.admin.user+xml
...
<User
   xmlns="http://www.vmware.com/vcloud/v1.5"
   name="user@example.com"
   id="urn:vcloud:user:85"
   type="application/vnd.vmware.admin.user+xml"
   href="https://vcloud.example.com/api/admin/user/85">
   <Link
      rel="edit"
      type="application/vnd.vmware.admin.user+xml"
      href="https://vcloud.example.com/api/admin/user/85" />
   <FullName>Imported User Full Name</FullName>
   <EmailAddress>user@example.com</EmailAddress>
   <IsEnabled>true</IsEnabled>
   <ProviderType>SAML</ProviderType>
   <NameInSource>\F4\D3\42\8E\6A\BC\D3</NameInSource>
   <IsAlertEnabled>false</IsAlertEnabled>
   <IsDefaultCached>false</IsDefaultCached>
   <StoredVmQuota>0</StoredVmQuota>
   <DeployedVmQuota>0</DeployedVmQuota>
   <Role
      type="application/vnd.vmware.admin.role+xml"
      href="https://vcloud.example.com/api/admin/role/105" />
   <GroupReferences />
</User>