Managing Single Sign-On

Configure VMware Cloud Services with Tanzu CloudHealth

Note - Effective Feb 2023, the VMware Cloud Services is a default authentication tool for all the new VMware Tanzu CloudHealth platform users. Using the VMware Cloud Services console, you can manage your entire VMware Cloud services portfolio across hybrid and native public clouds, and it provides you with easy access to the Tanzu CloudHealth platform and other VMware Cloud Services products.

Depending on whether you are a new Tanzu CloudHealth user or a new VMware Cloud Services user, there can be differences in the onboarding workflows.

Onboard a new Tanzu CloudHealth user
Onboard a new VMware Cloud Services user

You will receive an invitation email for both workflows with an onboarding link.

Sign up for the Tanzu CloudHealth Services Platform

As a New User with Non-federated Access

Prerequisite

An email with an onboarding link from the VMware Cloud Services platform.

Procedure

Log in to the VMware Cloud Services platform.
- If you are a new user of VMware products, by clicking the onboarding link provided in the invitation mail, you are redirected to the VMware Cloud Services login page. Create a VMware Cloud Services account. The first user who creates an Organization gets an Organization Owner role in the VMware Cloud Services platform. See Create VMware Cloud Services Account.
- If you already have a VMware account, then log in using your VMware account credentials.
Once the Organization is created, new users invited to join the Organization can have the role that the Organization Administrator or Organization Owner granted them. It is recommended to provide the Organization Member role to new users to limit the Organization access unless they need higher privileges within the Organization.
Select a VMware Cloud Services Organization.

Select an existing Organization or create a new Organization in which you want to onboard the Tanzu CloudHealth service.
- If you select the Organization which already exists, click Proceed to Service. You will be redirected to the Tanzu CloudHealth platform.
Each Organization comes with an Organization ID. If any of the existing Organizations were associated with the Tanzu CloudHealth platform service in the past, and the service was added again to the Organization, in that case, Tanzu CloudHealth automatically reactivates your old Tanzu CloudHealth account, and links it to the VMware Cloud Services Organization ID.

Note that, per the data retention policy, Tanzu CloudHealth retains customer data for 13 months. If the Organization ID is not available in the Tanzu CloudHealth database, Tanzu CloudHealth creates a new account for you and automatically links it to the VMware Cloud Services Organization ID.
- If you want to create a new organization,
a. Click Add Service to Another Org.

b. Click Create Organization.

c. Create your Organization Profile by providing an Organization Name and Address. d. Select Terms of Service and click Continue. e. Accept or Decline the Data Disclosure to Partners approval, click Continue.

You will be redirected to the Tanzu CloudHealth platform.

Users with Federated Access

Prerequisite

Enterprise Federation setup is ready.
The VMWare Cloud Services Organization must be activated for Identity Governance and Administration (IGA).
The Organization owner should set an auto entitlement policy in the VMware Cloud Services platform. See Configure auto entitlement policy. This policy is required to grant the Organization and service level role to anyone who logs in with a federated domain.

If you have an SSO federation setup, new Tanzu CloudHealth users from your company first need to log in to the VMware Cloud Services platform to access the Tanzu CloudHealth services. Once authenticated, they can access the Tanzu CloudHealth platform directly and get into their assigned Tanzu CloudHealth account.

Further, Organization Administrator or Organization Owner can change the user roles in the VMware Cloud Services platform, and the Tanzu CloudHealth administrator can change the Tanzu CloudHealth roles in the Tanzu CloudHealth platform if required.

Create a VMware Cloud Services Account

If you are a new user and do not have a VMware Cloud Services account, you need to create one to use Tanzu CloudHealth services. As part of the onboarding process, you will receive an Onboarding link in your mail id. Click the onboarding link and complete the following steps.

On the VMware Cloud Services sign in page, click Sign in using another account.
Fill in the following details in the account creation form.
- Name and Phone number.
- Email address Make sure you enter the same email address on which you received the invite. Create a password.
- Business name and Address details.
Select the terms of user agreement and click Continue.
Click Send Verification Code. Copy and paste the verification code from your registered email address to the VMware Cloud Services platform. Complete the email verification and log in using your registered VMware account credentials.
Click Create VMware Account. You will be redirected to the VMware Cloud Services sign in page.
Log in to the VMware Cloud Services platform using the newly created credentials. Once authenticated, you can directly log in to the Tanzu CloudHealth platform.

After creating a VMware Cloud Services account, the first user who creates an Organization gets an Organization owner role in the VMware Cloud Services platform.

Add New Users to the Organization in the VMware Cloud Services Platform

Pre-requisite

You must have either Organization Owner or Organization Administrator role to invite users to your Organization. For more information, see How do I manage users in my Organization.
You have at least one Organization created in the VMware Cloud Services platform.

As an Organization owner, you can invite users to your Organization in the VMware Cloud Services platform and grant them access to the Tanzu CloudHealth services platform.

To add new users to the Organization 1. In the Tanzu CloudHealth platform, click the profile name at the top-right corner, and select View Organization. You will be redirected to the Organization page in the VMware Cloud Services platform. 2. From the left menu, click Identity & Access Management > Active Users.

CSP Active Users

Click Add Users. On the Add New Users page, provide the account name of the user or the email address of the user you want to add to your Organization. Make sure the account name of the user is a real email address.
Assign Roles. As an administrator in the VMware Cloud Services platform, you must assign two roles to the users you invite to the Tanzu CloudHealth platform - an Organization Role in the VMware Cloud Services platform and a Service Role for the Tanzu CloudHealth platform. A user can have the same or different roles in both platforms. For example- An administrator in VMware Cloud Services will not necessarily be an Administrator in the Tanzu CloudHealth platform, and vice versa.

Organization Roles The following Organization roles are available in the VMware Cloud Services platform.

Mandatory Roles	Additional Roles
Organization Administrator	Access Log Auditor
Organization Member	Billing Read-Only
Organization Owner	Developer
	Project Administrator
	Software Installer
	Support User

To know more about the VMware Cloud Services Organization and roles, see Before you start with VMware Cloud services.

Service Roles To assign a Service Role, you first need to select a service and then the service- related role.

For Tanzu CloudHealth service, you can assign either a Tanzu CloudHealth Administrator role or A role Managed by Tanzu CloudHealth. In Role Managed by Tanzu CloudHealth, the user will assume a Tanzu CloudHealth role assigned by the Tanzu CloudHealth administrator in the Tanzu CloudHealth platform.

To know more about the roles in the Tanzu CloudHealth platform, see What are Tanzu CloudHealth Roles.

Click Add to send an invitation to the user.

Invite Redemption

New users should accept the invitation using the invite link and create a VMware Cloud Services account or log in to the VMware Cloud Services platform using their active VMware account credentials.

After the user has successfully logged in to the VMware Cloud Services platform,

On the Services > Organization page, click Launch Service to go to the Tanzu CloudHealth platform.
Select the Tanzu CloudHealth terms of service and click Next.

After redeeming the invitation, the user name will be added to the Tanzu CloudHealth platform.

Add Users to the User Group in the Tanzu CloudHealth Platform

See, how to add Users to a User group in the Tanzu CloudHealth platform.

Configure Auto Entitlement Policy

As an Organization owner, you need to link your Organization to your identity provider to grant federated access to all users from your domain.

Pre-requisite

A domain has been set up in the VMware Cloud Services platform.
The domain setup is not attached to a specific Organization in the VMware Cloud Services platform.

Procedure

Step 1 – Link the domain name with your Organization

From the left pane, click Organization > Details.
Scroll down to the Domains Linked to Identity Provider and click Link Identity Provider.
Click Link to link your Organization and click Continue.

Step 2 – Configure a domain policy

From the left pane, navigate to Identity and Access Management > Governance.
In the Requests tab, click Settings.
On the Request Settings page, click Add Domain Policy.
Provide the following information-
- Name – Name of new domain policy.
- Description – Description of new domain policy.
- Domains – List of domain names separated by a comma or new line to which the new policy is applicable.
- Scopes- Assign Organization and Service roles.
Click Save. The domain policy appears in the Grant default roles section.

The domain policy becomes effective immediately after you save the policy, and any user with the saved domain name can log in to the VMware Cloud Services platform using their credentials.

By default, all the users from the configured domain will be assigned an Organization member role. Later Organization Owner can edit the role if required.

Select the policy name in the Grant default roles section to edit the domain policy details and click Edit.

Manage Your VMware Cloud Services Account Profile

Using the VMware Cloud Services console, you can manage your entire VMware Cloud services portfolio across hybrid and native public clouds, and it provides you with easy access to the Tanzu CloudHealth platform and other VMware Cloud Services products.

In the VMware Cloud Services platform, click your profile name at the top right corner. In this pane, you can see your Organization ID and can change your Organization and User Settings.

Organization Settings View Organization – Click to view the setting of your current Organization. You will be redirected to the VMware Cloud Services > Organization > Details page.
User Settings
- My Account – View your account details in the VMware Cloud Services platform.
- Set Default Organization- If you are added to more than one Organization, you can set a default Organization.
- Tanzu CloudHealth Profile

To view all the VMware Cloud services you have access to, click the 9-dot menu at the top right corner. Click the service name to switch to a different service.

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.

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.

In the Tanzu CloudHealth Platform, from the left menu, select Setup > Admin > User Groups > New User Group.
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.
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.
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.

Provide the single sign-on URL, or 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
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

In the Tanzu CloudHealth platform, from the left menu, select Setup > Admin > Single Sign-On > 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 in a Pending status.

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

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.

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.

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.

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.

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.

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)

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.

Enable Active Directory Federation Services (ADFS) SSO with Tanzu CloudHealth

Provide an AD FS Token Signing Certificate in Base-64 PEM Format and AD FS SSO Sign-In Endpoint to Tanzu CloudHealth.

In order to start authenticating via Active Directory Federation Services (AD FS), provide an AD FS Token Signing Certificate in Base-64 PEM Format and AD FS SSO Sign-In Endpoint to Tanzu CloudHealth.

Tanzu CloudHealth will generate an SSO endpoint and contact you to activate and test the connection.

Tanzu CloudHealth does not support mixed-mode authentication. Once 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: Get Token Signing Certificate

In AD FS Management, from the left menu, select Service > Certificates.
Right-click the Token-signing certificate and select View Certificate.
In the Certificate dialog box, select the Details tab and click Copy to File. Then click OK.
Complete the Certificate Export Wizard as follows. a. On the Export File Format page, select Base-64 encoded X.509 (.CER). b. On the File to Export page, specify a filename. c. Confirm the export options and click Finish.

Step 2: Get SSO Sign-In Endpoint for AD FS

In AD FS Management, from the left menu, select Service > Endpoints.
Verify the endpoint structure, which should resemble https://_<yourdomainname>_.com/adfs/ls.

Step 3: Send Information to Tanzu CloudHealth

Reach out to the Tanzu CloudHealth Support team (mailto:[email protected]) to create a ticket and provide the following information:

Your customer tenant name.
Contact for AD FS setup within your organization.
Open the exported token signing certificate in a text editor. Copy and paste this PEM formatted certificate into the body of the ticket email.
Your SSO sign-in endpoint.

Step 4: Complete Setup and Test Connection

After receiving your ticket, Tanzu CloudHealth Support will provide you an activated metadata URL that contains information for completing the setup.

For example, for a customer called smidgetswidgets.com sample endpoint data is formatted as follows: - Connection Name - smidgetswidgets-com - Callback URL - https://cloudhealthtech.com/auth0.com/login/callback?connection=smidgetswidgets-com - Audience URI - urn:auth0:cloudhealthtech:smidgetswidgets-com - Metadata - https://cloudhealthtech.auth0.com/samlp/metadata?connection=smidgetswidgets-com

Add Relying Party Trust

Complete the Add Relying Party Trust wizard as follows:

In the AD FS Management console, click Add Relying Party Trust.
On the Select Data Source page, select Import data about the relying party published online or on a local network. Then paste the Metadata URL that you received from Tanzu CloudHealth.
Specify your display name.
Retain the default option to not configure multi-factor authentication.
On the Choose Issuance Authorization Rules page, select Permit all users to access this relying party.
On the Ready to Add Trust page, navigate to the Identifiers tab. Confirm that the Audience URI that you received from Tanzu CloudHealth appears in the Relying party identifiers field. Then, navigate to the Endpoints tab and confirm that the endpoints you received from Tanzu CloudHealth appear there.
Select the option to edit claim rules and click Close. The wizard closes and the Edit Claim Rules dialog box appears.

Edit Claim Rules

Claim rules pass information from AD to Tanzu CloudHealth. Complete the Edit Claim Rules wizard as follows:

Click Add Rule.
From the Claim rule template dropdown, select Send LDAP Attributes as Claims. This rule allows fields from AD to be sent to Tanzu CloudHealth. Configure this rule to send user email and display name for login.
On the rule configuration page, name the rule and populate the fields as follows:
- E-Mail-Addresses: email
- Display-Name: name Fields are case sensitive. Do not select the prepopulated E-mail Address option.
In the Edit Claim Rules dialog box, click Add Rule to create roles claim rules. Rules pass Tanzu CloudHealth roles for the users. Ensure that there exist three security groups in AD for each user type: Admin, Power, and Standard.
From the Claim rule template dropdown, select Send Group Membership as Claim.
On the rule configuration page, name the rule and browse for the cht-admin group, then select a group. Ensure that your outgoing claim type is roles (all lowercase).
Repeat steps 4 through 6 for the two other groups: cloudhealth-power and cloudhealth-standard.

Result: SSO is active in your account. Users are controlled completely outside of Tanzu CloudHealth via AD security groups.

Enable Azure Active Directory SSO

Configure Tanzu CloudHealth to authenticate your users via Azure Active Directory.

As an alternative to username-password-based authentication, Tanzu CloudHealth allows single sign-on (SSO). You can authenticate your users via Azure Active Directory.

There are two procedures depending on whether you are using FlexOrgs to manage your organizations:

Tanzu CloudHealth does not support mixed-mode authentication. Once you configure Azure AD SSO 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.

Prerequisite

You are assigned a Global Administrator role in the Active Directory that you want to use for authenticating your users.

Enable Azure AD SSO for FlexOrgs

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.

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.

In the Tanzu CloudHealth Platform, from the left menu, select Setup > Admin > User Groups > New User Group.
In the Details tab, provide the following information:
- Name
- (Optional) Description for the user group
- Key-value pairs attached as IDP assertions to user profiles that are associated with this user group. Note: If multiple SSO values are defined for an SSO key, the users are mapped to the user group if they match either value.
Specify the SSO Key as groups. Specify SSO Values as the Azure AD group names that you want to associate with the User Group.
In the Members tab, click Add Members. Select the users to include in the user group. Note: Skip this step if you are using SSO key-value pairs to map users to user groups.
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: Create Group and Assign Users in Azure Portal

Create a group and add members in Azure Active Directory. For help creating a group and adding members, see the Microsoft Azure Active Directory documentation.
When creating the new group, complete the New Group form as follows:
- Group Type: Select Security from the dropdown.
- Group Name: Enter the SSO value that was entered in the previous step.
- Group Description: Enter a role description.
- Membership Type: Select Assigned from the dropdown.

Step 3: Configure Azure AD SSO in Tanzu CloudHealth Platform

In the Tanzu CloudHealth Platform, select Setup > Admin > SSO Configuration.
From the SSO Provider dropdown, select Azure AD and provide the following information:
- Role Passing: Select how roles are passed to Tanzu CloudHealth.
- Default Organization: Select the organization to which all new users should be assigned.

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

Enable Azure AD SSO for Classic Organizations

Step 1: Identify Tanzu CloudHealth Roles

By default, Tanzu CloudHealth provides three roles for Active Directory SSO:

Standard User
Power User
Administrator

To review the privileges assigned to each role, go to Setup > Admin > Roles in the Tanzu CloudHealth Platform and click the View icon for each role.

If your organization has users whose role does not match any of the default roles, create a custom role as follows:

In the Tanzu CloudHealth platform, from the left menu, select Setup > Admin > Roles > New Role.
Name the role and assign the privileges it provides.

Result: Tanzu CloudHealth generates an IDP Name for the role.

The IDP Name varies depending on the string you enter in the Name field for the Role. For example:

Role Name	IDP Name
Finance	`cloudhealth-finance`
Sales and Marketing	`cloudhealth-sales-and-marketing`
EngDept	`cloudhealth-eng_dept`

Step 2: Create Group and Assign Users in Azure Portal

Create a group and add members in Azure Active Directory. For help creating a group and adding members, see the Microsoft Azure Active Directory documentation.
When creating the new group, complete the New Group form as follows:
- Group Type: Select Security from the dropdown.
- Group Name: Enter the IDP name Tanzu CloudHealth generated in the previous step.
- Group Description: Enter a role description.
- Membership Type: Select Assigned from the dropdown.

Step 3: Configure Azure AD SSO in Tanzu CloudHealth Platform

In the Tanzu CloudHealth Platform, select Setup > Admin > SSO Configuration.
From the SSO Provider dropdown, select Azure AD and provide the following information:
- Role Passing: Select how roles are passed to Tanzu CloudHealth.
- Default Organization: Select the organization to which all new users should be assigned.

Step 4: Configure Session Length for Users (Optional)

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.

Configure Google Apps SSO for Tanzu CloudHealth

Configure Tanzu CloudHealth to allow your Google Apps users to log in using their Google Apps account

If your company uses Google Apps, you can configure Tanzu CloudHealth to allow your Google Apps users to log in using their Google Apps account. Tanzu CloudHealth connects to Google Apps via the OAuth protocol. For more information, refer to Using OAuth 2.0 to Access Google APIs.

Tanzu CloudHealth does not support mixed-mode authentication. Once you configure SSO through Google Apps 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 Google Apps Domain

Enable Admin API access for your domain and create Google Groups for each Tanzu CloudHealth role.

Log in to the Google Apps admin control panel (cPanel) using an account that has super admin privileges. The cPanel for your domain can be accessed via https://admin.google.com
Navigate to the Security page and click API Reference.
Within the API Access section, enable Admin APIs by selecting the checkbox for Enable API access.
Navigate to the Groups page. Add a group for each of the default Tanzu CloudHealth roles (Administrator, Power User, Standard).

The group names are case-sensitive and must match those listed here.
- cloudhealth-administrator
- cloudhealth-power
- cloudhealth-standard Once these groups have been created, you can dynamically add and remove users from Tanzu CloudHealth roles by adding or removing them from these groups.

A user should only be a member of one Tanzu CloudHealth group. Users that do no belong to a group cannot access the Tanzu CloudHealth Platform. Group membership changes take up to 24 hours to propagate through Google Apps.

Step 2: Create Google Groups for each Custom Tanzu CloudHealth Role

Within Tanzu CloudHealth, custom roles can be defined. Each custom role within
Tanzu CloudHealth is assigned an IDP name. The IDP Name is used when creating

groups that map to roles in your identity provider. For more information on custom roles, see Creating Custom Role.

Log in to the Google Apps admin control panel (cPanel) using an account that has super admin privileges. The cPanel for your domain can be accessed via https://admin.google.com
Navigate to the Groups page
Add a group for each of the custom Tanzu CloudHealth roles that you have defined. Please note that the name of the Google Group needs to be of the format cloudhealth-<IDP NAME>.

Step 3: Configure Google Apps SSO in Tanzu CloudHealth Platform

In the Tanzu CloudHealth Platform, select Setup > Admin > SSO Configuration.
From the SSO Provider dropdown, select Google Apps and provide the following information:
- Domains for SSO: Enter domain names in company.com format.
- Default Organization: From the dropdown, select the organization to which all new users should be assigned.
Click Update SSO Configuration. Click the link in the message to grant Tanzu CloudHealth access to your company directory.

Step 4: Configure Session Length for Users (Optional)

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.

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.

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
- Name: roles
- Format: Unspecified
- Filter: Starts With
- Value: cloudhealth-

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

Step 6: Configure Session Length for Users (Optional)

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.

Configure OneLogin SSO for Tanzu CloudHealth

Configure OneLogin single sign-on to authenticate users into the Tanzu CloudHealth Platform

Prerequisites

OneLogin set up and functional within the customer’s domain
A OneLogin admin with permission to create a SAML 2.0 application during the setup call
OneLogin groups corresponding to each Tanzu CloudHealth role configured within the customer’s Tanzu CloudHealth account.

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: Create Tanzu CloudHealth Application in OneLogin

Create a Tanzu CloudHealth application in OneLogin by creating a SAML Test Connector (IdP w/attr) app in OneLogin. For help setting up the SAML test connector, see the OneLogin documentation.

Step 2: Configure SAML Settings

Next, configure the application you just made using the following settings:

Configuration Section

Replace the variable <domain-com> in these examples with the connection name that you are using. For example, if the domain name were company.com, the corresponding connection name would be company-com.

Audience: urn:auth0:cloudhealthtech:<domain-com>
ACS (Consumer) URL Validator: https://cloudhealthtech.auth0.com/samlp/metadata?connection=<domain-com>
ACS (Consumer) URL: https://cloudhealthtech.auth0.com/login/callback?connection=<domain-com>

Parameters Section

Keep the default attributes.
Add two additional parameters by clicking Add Parameter.
Field name: roles
Flags: Enable Include in SAML assertion
Click Save. Open the new field from the list of parameters.
For Value, select User Roles and click Save.
Field name: name
Flags: Enable Include in SAML assertion
Click Save. Then reopen it from the list of parameters.
For Value, select User Roles and click Save.

Ensure you have the following parameters:

SAML Test Connector (IdP w/attr) Field	Value
E-mail (attribute)	Email
Email (SAML NameID)	Email
First Name (Attribute)	First Name
Last Name (Attribute)	Last Name
Member of (Groups) (Attribute)	MemberOf
PersonImmutableID	- No default -
roles	User Roles

SSO

Get the following SAML credentials from your IdP:

X.509 Certificate
SAML 2.0 Endpoint.

Step 3: Set Up Groups

Configure the OneLogin roles that will pass your Tanzu CloudHealth roles via SSO.

Select Users > Roles.
Create three new roles (case-sensitive):
cloudhealth-standard
cloudhealth-power
cloudhealth-administrator
Add the recently created Tanzu CloudHealth OneLogin App to each role.
Assign these roles to users who need access at each one of these levels within the Tanzu CloudHealth platform. Only assign one Tanzu CloudHealth-based OneLogin role per user.

OneLogin groups for custom Tanzu CloudHealth roles also begin with cloudhealth-, with the IdP name of the custom role being entered after the -. The IdP name for the custom role can be found by viewing the role in Tanzu CloudHealth at https://apps.cloudhealthtech.com/roles.

Step 4: Configure SAML SSO in Tanzu CloudHealth Platform

In the Tanzu CloudHealth Platform, 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.
- 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 5: Validate Pending SSO Domains

In the Tanzu CloudHealth Platform, select Setup > Admin > SSO Domains.
In the Pending Domains section, copy the value of the DNS Token for the domain you want to validate.
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.

Step 6: Configure Session Length for Users (Optional)

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.

Troubleshooting SSO Issues

This section lists common SSO errors, and how to resolve them.

Error Message: Your user has not been assigned a role If you get the error Your user has not been assigned a role, it may be due to an incorrectly configured role. Cause: For a user in classic orgs or roles, the user is not passing a role that matches the IDP name of a role found in Tanzu CloudHealth under Setup > Admin > Roles. For a user in FlexOrgs or role documents, the user is not passing a role that matches a key/value pair defined against a user group. Resolution: There are two different resolutions depending on whether you are using classic organizations or FlexOrgs.

Classic Organizations or Roles

The user should verify from their identity provider that they are passing across a value that matches the IdP name of a configured role.

For example, the pre-configured Administrator role requires a role value in the user’s assertion that matches the Administrator’s role name of Tanzu CloudHealth-administrator.

The way a role is passed differs based on the identity provider:

Active Directory Federation Services (ADFS) - Each role claim is tied to a security group in Active Directory. Ensure that the user belongs to the group associated with the role claim in Active Directory to ensure they are passing the correct role value.
Azure Active Directory (AD) - Each group the user belongs to in Azure AD is passed as the role value. Ensure that the user belongs to the group associated with that role. For example, the cloudhealth-administrators group in Azure AD corresponds to the Administrator role in Tanzu CloudHealth.
Okta - Groups starting with the prefix cloudhealth- are passed as roles in the user’s assertion when signing in through SSO. Confirm the user’s group membership in Okta, and ensure that they belong to the correct cloudhealth- group.

FlexOrgs or Role Documents

The key/value pair is set by the user. To confirm that the user is passing the correct value, from Tanzu CloudHealth, go to Setup > Admin > User Groups and open the user group the user should be assigned to. Check that the SSO key/value section under the Details tab matches the expected value.

For example, UserGroup A has the following SSO key and SSO value pair in Tanzu CloudHealth: Department - Finance. Within the IdP, open the user’s account and confirm that the value found under the Department field matches the value in the Details tab for the user group.

Users can also be manually assigned to user groups or automatically assigned through SSO. You can manually assign a user when the correct values are not being passed from the IdP.

To manually assign a user, go to Setup > Admin > User Groups in Tanzu CloudHealth and open the user group the user should be assigned to. From the Members tab, select Add members. The next time the user signs in, they are assigned to the user group, given a role document, and access to Flex Orgs as defined in the user group’s Assignment tab.

Error Message: Your user has not been assigned an organization If you get the error Your user has not been assigned an organization, it may be due to a mismatched value between the identity provider and Tanzu CloudHealth. Cause: The User-Organization Association setting has not been configured under Setup > Admin > Single Sign On. Resolution: When the User-Organization Association setting is disabled, the identity provider is expected to pass a value in the Organization attribute that matches the IdP name of an Organization found in Tanzu CloudHealth under Setup > Admin > Organizations. Ensure that the values match on both the IdP and Tanzu CloudHealth. If the attribute has not been configured, enable this setting so new users are added to the Default Organization. You can then add and remove users as needed.
User Cannot Sign In If your user previously used the same email address with a different tenant in Tanzu CloudHealth, they may be unable to sign in. Cause: User records within Tanzu CloudHealth remain even after removing a user from an SSO configuration or tenant. Resolution: Contact Tanzu CloudHealth Support to confirm that a duplicate user record exists, and archive the duplicate so the user can access the new tenant.