Configure Okta SSO with Tanzu CloudHealth

Configure Okta SSO to authenticate users into the Tanzu CloudHealth platform

Prerequisites

Okta is set up and functional within your domain.
An Okta administrator has been created with permission to create a SAML 2.0 application.
Okta groups corresponding to each Tanzu CloudHealth role are configured within your Tanzu CloudHealth account.
SAML app has been created in the Okta console. For help creating a SAML app, see the Okta help.

Note

Tanzu CloudHealth does not support mixed-mode authentication. After you configure SAML SSO through an identity provider (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

Use the information in this section to configure the SAML app you created. For more details about items in the configure SAML settings menu, visit the Okta help.

In these examples, replace the variable <domain-com> in these examples with the connection name that you are using. For example, if the domain name was mydomain.com, the corresponding connection name would be mydomain-com.

Single sign on URL:

https://cloudhealthtech.auth0.com/login/callback?connection=<domain-com>

Audience URI:
```
urn:auth0:cloudhealthtech:<domain-com>
```
Attribute Statements
- First row
  - Name: name
  - Format: Unspecified
  - Value: user.firstName + " " + user.lastName
- Second row
  - Name: email
  - Format: Unspecified
  - Value: user.email
Group Attribute Statements
- For Classic Organization:
  - Name: roles
  - Format: Unspecified
  - Filter: Starts With
  - Value: cloudhealth-
- For FlexOrg:
  - Name: roles
  - Format: Unspecified
  - Filter: Matches Regex
  - Value: .*

The Group Attribute Statements will pass all groups in Okta to which a member belongs. If you want to limit the scope of the groups, you can change the Regular Expression value from .* to a pattern that matches the groups you wish to share with the Tanzu CloudHealth platform.

If the group names start with the same value, you can use the Starts With filter instead of filtering by prefix defined in the Value section.

Step 2: Set Up Groups

Configure groups that will pass your Tanzu CloudHealth roles via SSO. For instructions on how to create groups, see the Okta help.

Create three Okta groups to map to the default Tanzu CloudHealth roles using exactly the name and spelling below:

cloudhealth-standard
cloudhealth-power
cloudhealth-administrator

Also create Okta groups for any additional custom roles you have configured in Tanzu CloudHealth. To add custom roles, add cloudhealth- before the IDP role name. You can find the IDP name for a custom role by going to https://apps.cloudhealthtech.com/roles. For example, for an IDP named tech-support, the corresponding group name in Okta is cloudhealth-tech-support.

Step 3: Get SAML Credentials

Get the following SAML credentials from your IDP.

X.509 Certificate
SAML 2.0 Endpoint

Step 4: 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. 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.
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 5: 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 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 will have access to the Tanzu CloudHealth platform. Users cannot sign into the Tanzu CloudHealth platform using their existing credentials.

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 6: 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, the best practice is to 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.
Click Update Company Profile.