Enable SAML SSO for FlexOrgs

If you are using FlexOrgs to manage your organizations, follow this procedure to enable SAML SSO. To enable SAML SSO for classic organizations, see Enable SAML SSO for Classic Organizations.

What Is SAML SSO

VMware Tanzu CloudHealth allows single sign-on (SSO) as an alternative to username-password-based authentication. If you have in-house identity management or use a different identity provider (IDP), you can authenticate your users using the Security Assertion Markup Language (SAML) protocol.

SAML is an XML-based, open-standard data format for exchanging authentication and authorization data between parties, particularly between an IDP such as Okta, Ping, Azure AD, or ADFS and a service provider such as Auth0 or Tanzu CloudHealth.

An IDP is a software that is built around managing user access. When configured, an IDP sends SAML data to the Tanzu CloudHealth platform. This data is called an assertion, and it must contain the attributes email, name, and roles. The attributes in the assertion allow you to authenticate users in the Tanzu CloudHealth platform. You can authenticate multiple domains with Tanzu CloudHealth through the same IDP.

Tanzu CloudHealth does not support mixed-mode authentication. After you configure SAML SSO through an IDP in the Tanzu CloudHealth platform, you can only invite users through that IDP. You will no longer be able to send user invitations through the Tanzu CloudHealth platform.

How Dynamic Mapping Works

In FlexOrgs, you can dynamically map users to user groups based on SSO attributes. You specify the attributes in your Identity Provider (IDP).

This capability allows you to centrally manage users in your IDP. When you change their attributes, users are mapped to different user groups with new permissions.

Note

If you do not want to map users to user groups dynamically, you can invite users manually.

Step 1: Specify SSO Attributes in User Group Definition

Before you attach attributes for mapping users in your IDP, specify the key-value pair that the user group should look for in the IDP assertion.

1. In the Tanzu CloudHealth Platform, from the left menu, select Setup > Admin > User Groups > New User Group.
2. In the Details tab, provide the following information:
   • Name
   • Description for the user group (optional)
   • Key-value pairs attached as IDP assertions to user profiles that are associated with this user group. If multiple SSO values are defined for an SSO key, the users are mapped to the user group if they match either value.
3. In the Members tab, click Add Members. Select the users to include in the user group. Skip this step if you are using SSO key-value pairs to map users to user groups.
4. In the Assignment tab, add one or more role documents to the user group. For each role document, select the OU in which it is applicable. Multiple role documents can be assigned to a single OU, creating an overlapping tapestry of permissions.

Step 2: Configure SAML Settings in IDP

Perform these steps in the IDP of your choice that supports SAML SSO.

1. Provide the single sign-on URL, or SSO callback, where your domain is company.com:

   https://cloudhealthtech.auth0.com/login/callback?connection=company-com
   

2. Provide the audience URI, where your domain is company.com:

   urn:auth0:cloudhealthtech:company-com
   

3. Locate the following SAML credentials from your IDP:

   • X.509 Certificate
   • SAML 2.0 Endpoint

Step 3: Configure SAML SSO in the Tanzu CloudHealth Platform

1. In the Tanzu CloudHealth platform, from the left menu, select Setup > Admin > Single Sign-On > Configuration.
2. From the SSO Provider dropdown, select SAML and provide the following information:
   • Domains for SSO: Enter domain names in company.com format. Make sure to enter a space after the domain name.
   • Sign In Endpoint: Enter the SAML 2.0 Endpoint from your IDP.
   • Signing Certificate: Paste the contents of the X.509 certificate from your IDP. Please ensure that you include the BEGIN CERTIFICATE and END CERTIFICATE portions of the Certificate.
   • User-Organization Association: Check this option if the IDP does not support passing the organization that the user should be assigned to.
   • Default Organization: From the dropdown, select the organization to which all new users should be assigned.
3. Click Update SSO Configuration. Tanzu CloudHealth generates a DNS token for each domain you provided during SAML SSO configuration. The domains are placed in a Pending status.

Step 4: Validate Pending SSO Domains

1. In the Tanzu CloudHealth platform, from the left menu, select Setup > Admin > SSO Domains.
2. In the Pending Domains section, copy the value of the DNS Token for the domain you want to validate. Paste the token into a text file and prepend the string cloudhealth= to it.
3. Go to your domain provider, and add the modified DNS token as a TXT token to the domain. Tanzu CloudHealth uses the TXT token to validate the domain. This process can take up to 72 hours. Validated tokens appear in the Claimed Domains section.
4. After the domain is validated, all users who are listed in the IDP have access to the Tanzu CloudHealth platform. Users cannot sign into the Tanzu CloudHealth platform using their existing credentials.

Note

When your SSO configuration uses more than one domain, ensure that the TXT record is present for all the domains before validating. Because once a domain is validated, only users from the Claimed Domains will be able to sign in via SSO.

Step 5: Configure Session Length for Users (Optional)

You can configure the session length for your users in the Tanzu CloudHealth platform. The default session length is Until the browser closes. However, it is recommended that you specify a shorter length, which is measured from the time the user was last active, not from the time the user last logged in.

1. In the Tanzu CloudHealth platform, select Setup > Admin > Settings.
2. On the Edit Customer tab, go to the Settings pane.
3. Select a session length from the dropdown menu.