Enable SAML SSO for Classic Organizations

Explains how to enable SAML SSO through your IDP provider. This is an alternative to username-password-based authentication.

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

What is SAML SSO

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 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.

Note
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.

Step 1: Configure SAML Settings in IdP

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

Before you begin, review the users that are listed in your IDP. After configuring SSO, all users in the IDP will have access to Tanzu CloudHealth.

Configure SSO Credentials

Provide the single sign-on URL, also called an SSO callback, where your domain is company.com.
```
https://cloudhealthtech.auth0.com/login/callback?connection=company-com
```
Provide the audience URI, where your domain is company.com.
```
urn:auth0:cloudhealthtech:company-com
```

Add User Role to IdP Assertion

Roles in the Tanzu CloudHealth platform manage the level of access and visibility that users have after they are authenticated.

Configure your IDP to include a roles attribute with each assertion sent to the Tanzu CloudHealth platform. When a user logs in, Tanzu CloudHealth looks for the roles attribute in the assertion:

If the attribute is found, Tanzu CloudHealth approves the login and assigns the user the specified role.
If the attribute is found to include multiple roles, Tanzu CloudHealth approves the login and assigns the user only the first role in the sequence.
If the attribute is not found, Tanzu CloudHealth rejects the login.

Tanzu CloudHealth does not recognize any attribute name other than roles. If you name the attribute Roles or role, Tanzu CloudHealth rejects those user logins.

Assign one of these default roles as a string. Attribute values are case-sensitive.

Roles Attribute Value	Tanzu CloudHealth Role
`cloudhealth-administrator`	Administrator
`cloudhealth-power`	Power user
`cloudhealth-standard`	Standard user

You can locate the attribute value of a specific custom role in the Tanzu CloudHealth platform.

Log into the Tanzu CloudHealth platform. From the left menu, select Setup > Admin > Roles.
Click the View icon for a custom role.
In the Details pane, locate the IDP Name field.

Note

Newly created tenants cannot view the attributes of a role created earlier than the tenant.

Add User Organization to IDP Assertion (Optional)

Only supported if you are already using Tanzu CloudHealth organizations. Contact Tanzu CloudHealth to enable this capability.

Organizations allow you to manage the visibility of data to users of the Tanzu CloudHealth platform. Using organizations, you can grant multiple stakeholders access to the Tanzu CloudHealth platform without providing them access to data you do not want them to see. For example, you might want to ensure that the Marketing Department can only see the cloud infrastructure that it is using.

You can configure your IDP to include an organization attribute with each assertion to the Tanzu CloudHealth platform. Configure this attribute for all users. When a user logs in, Tanzu CloudHealth looks for the organization attribute in the assertion.

If the attribute is found, Tanzu CloudHealth assigns the user to the specified organization.
If the attribute is not found, Tanzu CloudHealth rejects the login.

The value of the organization attribute is the organization ID, which is derived from the lowercased form of the organization name. Any spaces in the organization name are replaced with hyphens. Mixed case portions in the organization name are separated by underscores.

The following examples show how organization IDs are generated in the Tanzu CloudHealth platform:

Organization Name in Tanzu CloudHealth	Organization ID
Finance	chtorg-finance
Sales and Marketing	chtorg-sales-and-marketing
EngDept	chtorg-eng_dept

You can locate the attribute value of a specific organization in the Tanzu CloudHealth platform.

Log into the Tanzu CloudHealth platform. From the left menu, select Setup > Admin > Organizations.
Click the View icon for an organization.
In the Details pane, locate the IDP Name field.

Some IDPs require the organization ID to begin with the prefix chtorg-. Contact support for more information regarding your IDP requirements.

Get SAML Credentials

Get the following SAML credentials from your IdP.

X.509 Certificate
SAML 2.0 Endpoint

Step 2: Configure SAML SSO in Tanzu CloudHealth Platform

In the Tanzu CloudHealth platform, from the left menu, select Setup > Admin > SSO Configuration.
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.
- 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.
Click Update SSO Configuration. Tanzu CloudHealth generates a DNS token for each domain you provided during SAML SSO configuration. The domains are placed under Pending status.

Step 3: Validate Pending SSO Domains

In the Tanzu CloudHealth platform, from the left menu, select Setup > Admin > SSO Domains.
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.
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.
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.

Step 4: 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.

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