Import a User or Group from a SAML Identity Provider

If your organization defines a SAML identity provider in its OrgFederationSettings, you must import users individually or as members of groups from the identity provider before they can log in to the organization.

Unlike imports from an LDAP service, imports from a SAML identity provider do not 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 that your organization's SAML provider defines. The VMware Cloud Director database stores these mappings, but does not store data retrieved from the SAML provider.

When you import a user from a SAML identity provider, you must include the domain name, such as [email protected]. 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. If you defined custom user and group attributes, the evaluation process uses the values of the UserNameAttributeName and GroupNameAttributeName elements from the SamlAttributeMapping element in the organization OrgFederationSettings. The evaluation process includes the following:

If the SAML token includes an attribute matching the value of the UserNameAttributeName element or an attribute named UserName, tries to match the value of that attribute to the value of the name attribute of the User. If the SAML token does not include such an attribute, tries 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 matching the value of GroupNameAttributeName or an attribute named Groups, assumes that the value of that attribute is a list of group names, and tries 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 such an attribute, assumes that the user is not a member of any group.

Prerequisites

This operation requires the rights included in the predefined Organization Administrator role or an equivalent set of rights.
Verify that your organization has defined a SAML identity provider in its OrgFederationSettings. See Configuring and Managing Federation with SAML.

Procedure

Create a User or Group element that identifies a user or group that your organization's SAML provider defines.
Include the following line in the User or Group element.
```
<ProviderType>SAML</ProviderType>
```
POST the element to the organization's users or groups URL.

Example: Import a User from a SAML Identity Provider

This example imports a user from the SAML identity provider that the organization defines. This example is identical to the one shown in Import a User from an LDAP Database, but includes a ProviderType element that specifies the source as the organization's SAML identity provider. This example 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 that the identity provider uses.

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="[email protected]"
   type="application/vnd.vmware.admin.user+xml">
   <IsEnabled>true</IsEnabled>
   <ProviderType>SAML</ProviderType>
   <Role
      href="https://vcloud.example.com/api/admin/org/26/role/13a69c14-e64c-409f-800f-0ecc470ea42d" />
</User>

Response:

201 Created
Content-Type: application/vnd.vmware.admin.user+xml
...
<User
   xmlns="http://www.vmware.com/vcloud/v1.5"
   name="[email protected]"
   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>[email protected]</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"
      name="vApp Author"
      href="https://vcloud.example.com/api/admin/org/26/role/13a69c14-e64c-409f-800f-0ecc470ea42d" />
   <GroupReferences />
</User>