Enable your VMware Cloud Director organization to use a Security Assertion Markup Language (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.

When you import users and groups, the system extracts a list of attributes from the SAML token, if available, and uses 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"

    You can configure the attributes in the Tenant Portal under the Attribute Mapping tab when you edit the SAML configuration.

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 groups. A user might belong to multiple groups, and 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 by using the 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 does not have any rights to perform any activities.

You can use the Edit SAML Configuration dialog box to change the SAML settings.

Prerequisites

  • Verify that you are logged in as an organization administrator or a role with equivalent set of rights.

  • Verify that you have access to an SAML 2.0 compliant identity provider.
  • Verify that you receive the required metadata from your SAML identity provider. You must import the metadata to VMware Cloud Director either manually or as an XML file. The metadata must include the following information:
    • 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 a SAML provider, see the documentation for your SAML identity provider.

Procedure

  1. In the top navigation bar, click Administration.
  2. Under Identity Providers, click SAML.
  3. Click Edit.
  4. On the Service Provider tab, enter the Entity ID.
    The Entity ID is the unique identifier of your organization to your identity provider. You can use the name of your organization, or any other string that satisfies the requirements of your SAML identity provider.
    Important: Once you specify an Entity ID, you cannot delete it. To change the entity ID, you must do a full SAML reconfiguration for your organization. For information about Entity IDs, see Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) 2.0.
  5. To download the SAML metadata for your organization, click Retrieve Metadata.
    Your browser downloads the SAML metadata, an XML file which you must provide as-is to your identity provider.
  6. Review the certificate expiration date and, optionally, click Regenerate to regenerate the certificate used to sign federation messages.
    You can provide your own certificates for SAML signing by uploading them to the certificate library in the UI and then, passing a reference to them in the SAML configuration API.
    The certificate is included in the SAML metadata, and is used for both encryption and signing. Either or both encryption and signing might be required depending on how trust is established between your organization and your SAML identity provider.
  7. On the Identity Provider tab, turn on the Use SAML Identity Provider toggle.
  8. Copy and paste the SAML metadata you received from your identity provider to the text box, or click Upload to browse to and upload the metadata from an XML file.
  9. For VMware Cloud Director 10.5.1 and later, if you want to customize the Sign in with SAML button label that appears on the VMware Cloud Director login page, enter a new custom button text.

    You can enter up to 24 symbols. You can use special characters and accented letters. If you want to revert to the default text, delete the custom label. The default button label is localized, and depending on your browser language settings, the text might appear in a different language. Custom labels always appear as you enter them.

  10. Click Save.

What to do next

  • Configure your SAML provider with VMware Cloud Director metadata. See your SAML identity provider documentation and the VMware Cloud Director Installation, Configuration, and Upgrade Guide.
  • Import users and groups from your SAML identity provider. See Managing Users, Groups and Roles in VMware Cloud Director.