Enable your organization to use a SAML identity provider, also called single sign-on, to import users and groups from a SAML identity provider and allow imported users to sign on to the organization with the credentials established in the SAML identity provider.

Prerequisites

  • This operation requires the rights included in the predefined Organization Administrator role or an equivalent set of rights.

  • Verify that you have access to an OpenAM or Active Directory Federation Services SAML identity provider.

  • Verify that your system has updated JCE unlimited strength jurisdiction policy files. See "Install Java Cryptography Extension Unlimited Strength Jurisdiction Policy Files" in the vCloud Director Administrator's Guide.

  • Create an XML file with the following metadata from your SAML identity provider.

    • The location of the single sign-on service

    • The location of the single logout service

    • The location of the service's X.509 certificate

    For information on configuring and acquiring metadata from an OpenAM or Active Directory Federation Services SAML provider, consult the documentation for your SAML provider.

  • The system will extract these attributes from the SAML token (if available) and use them for interpreting the corresponding pieces of information about the user attempting to log in.

    • email address = "EmailAddress"

    • user name = "UserName"

    • full name = "FullName"

    • user's groups = "Groups"

    • user's roles = "Roles" (this attribute is configurable)

    Group information is necessary if the user is not directly imported but is expected to be able to log in by virtue of membership in imported group(s). A user may belong to multiple groups and hence can have multiple roles during a session.

    If an imported user or group is assigned the Defer to Identity Provider role, the roles are assigned based on the information gathered from the Roles attribute in the token. If a different attribute is used, this attribute name can be configured via API only and only the Roles attribute is configurable. If the Defer to Identity Provider role is used, but no role information can be extracted, the user can log in but not have any rights to perform any activities.

Procedure

  1. Click Administration.
  2. In the left pane, select Settings > Federation.
  3. Enter an Entity Id for the Service Provider.

    The Entity Id uniquely identifies your organization to your Identity Provider. Previously, the system generated an Entity Id for you. To ensure backward compatibility and continued functionality, the system will continue to use this generated value, but it is strongly recommended that organization(s) use their own Entity Id specific to their identity provider.

    Once an Entity Id is set, it cannot be deleted, but can be changed. Any changes to the Entity Id will require a full SAML reconfiguration in order for it to continue functioning correctly. For more information on Entity Ids, see Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) 2.0.

  4. Review the Certificate Expiration date and If necessary, click Regenerate to regenerate the certificate used to sign federation messages.

    The certificate is included in the SP (vCloud Director) metadata. This certificate is used for both encryption and signing. Either or both of these may be required depending on how trust is established between SP and IDP and parameters that are agreed upon as a part of this trust establishment.

  5. Click the Metadata link to download the Service Provider metadata.

    This must be provided to your IDP as a part of trust establishment between your organization and your IDP. You can review the document to understand the SP parameters included as part of this process, but do not edit this document as it will interfere with correct SAML behavior.

  6. Select Use SAML Identity Provider.
  7. Copy and paste the IDP SAML provider metadata XML into the text box or click Browse to upload the metadata XML file.
  8. Click Apply.

What to do next

  • Configure your SAML provider with vCloud Director metadata. See your SAML provider's documentation and the vCloud Director Installation and Upgrade Guide.

  • Import users and groups from your SAML provider.