Understanding FlexOrgs

Upgrade Existing Organizations to FlexOrgs

This procedure will help you upgrade a classic VMware Tanzu CloudHealth organization into a FlexOrg. FlexOrgs help you build organizations in Tanzu CloudHealth that closely reflect your business. You can assign a user to one, many, or all FlexOrgs in the hierarchy. FlexOrgs also give you more power over a user’s permissions. For example, a user might have edit access to their primary organization but view-only for their other organizations.

You can upgrade to FlexOrgs from your current Tanzu CloudHealth organizations within the Tanzu CloudHealth platform using the Upgrade Organization feature.

During the upgrade, the organization and the following content types for all clouds and hypervisors are migrated:

• Saved reports
• Subscriptions
• Policies
• Budgets
• (Optional) Users and user roles

Upgrading organizations cannot be undone. After upgrading, the new organization can only be accessed as a FlexOrg.

Preparing your classic organization for upgrade

There are a few things to consider to ensure that your upgrade goes smoothly.

Define your organization’s structure

Before you move to FlexOrgs, examine your existing organization structure and decide if there are any organizational changes you’d like to make. After upgrading organizations to FlexOrgs, parent organizations cannot be moved to another parent organization, so ensure your hierarchy is correct before you proceed.

For best practices around structuring organizations, see Best Practices for Planning FlexOrgs.

Define the new user workflow

Decide what should happen when a new user joins your organization. There are a few options depending on whether you use standard authentication or single sign-on (SSO):

• New users are manually added to Tanzu CloudHealth and directly placed into the appropriate user group.
• New users are added to Tanzu CloudHealth through SSO, then manually placed into the appropriate user group.
  • When adding new users this way, we recommend configuring a user group without a role document or organization assigned, and assigning all users to this user group through SSO. Then, manually add the user to their long-term user group.
• New users are added to Tanzu CloudHealth into a specific user group using SSO.

Limitations and other considerations

There are a few limitations of FlexOrgs to be aware of before you upgrade:

• FlexOrgs does not support sharing accounts between sub-orgs at the same level. Consider moving to a parent-child relationship for organizations with shared accounts.
• FlexOrgs does not currently support Oracle Cloud.

Upgrading a classic organization to a FlexOrg

When upgrading organizations to FlexOrgs, start with organizations at the top of your organizational hierarchy.

1. In the left navigation select Setup > Admin > FlexOrgs.
2. Select your top-level organization, click the Classic Organizations tab in the right pane. All of your current classic organizations are displayed.
3. Identify the organization you want to upgrade. Click on the ellipsis next to the your classic organization name, and click Upgrade.
4. In the User settings section, select whether to upgrade user settings.
5. Select a Parent Organization.
6. Resolve any conflicts, if present.
   • An account can only be in one organizational unit per level of the hierarchy, and any overlapping organization unit conflicts must be resolved before the upgrade can continue.
   • To resolve the conflict, change the parent organization or unassign the conflicting accounts from the new FlexOrg.
7. Review the summary of content to be migrated to the FlexOrg.
8. Repeat as required to upgrade your remaining organizations to FlexOrgs.
9. If you are using SSO, configure SSO as described in Dynamically Map Users to User Groups using SSO Attributes.

Create and Manage FlexOrgs in Tanzu CloudHealth

FlexOrgs are made up of organizational units (OU), users, user groups, and role documents.

Step 1 - Create Organizational Hierarchy using Organizational Units

Organizations are composed of one or more Organizational Units (OUs) arranged in a hierarchy.

OUs are aligned around AWS account, Azure subscription, and GCP project boundaries, so building a hierarchy involves grouping the accounts, subscriptions, or projects you have configured in Tanzu CloudHealth into OUs.

If the OUs you want to create cannot be clearly demarcated along AWS account, Azure subscription, or GCP project boundaries (for example, if two or more OUs share the same AWS accounts) contact your Tanzu CloudHealth Account Manager for tips on building a hierarchy.

For more information about organizational units, see Use Organizational Units to Define Organizational Hierarchy.

1. In the Tanzu CloudHealth Platform, from the left menu, select Setup > Admin > FlexOrgs. Click Add Organization. Initially, all AWS accounts, Azure subscriptions, and GCP projects that you have configured in the Tanzu CloudHealth Platform are allocated to the Top-Level Organization Unit (TLOU).
2. In the Add Organization dialog box, provide a Name and optionally, a Description for the Organization. Click Save to create the Organization.
3. From the list of Organizations, select the newly created Organization and switch to Accounts tab. Click on Assign Accounts.
4. In the pop-up window for Assign Accounts, click on the drop down for Provider and choose from Accounts, Subscriptions, or Project. Select the accounts you want to allocate to the Organization and click Assign.
5. Repeat this process until all accounts, subscriptions, or projects are assigned to an Organization. At the end of the process, you have the first level of OUs defined in your hierarchy. Here’s an example.

6. In order to create additional levels, switch into the OU under which you want to create the next level. Use the Organization Switcher at the bottom left-hand corner of the Tanzu CloudHealth Platform to switch.

   After switching into an OU, repeat steps 1 through 4 to create sub-organizations. At each level, fewer accounts, subscriptions, or projects are available for allocating to OUs. The organization tree on the FlexOrgs page reflects the hierarchy as you build. Here is a view of the hierarchy as viewed from the TLOU.

Step 2 - Create Role Documents

A Role Document defines the permissions granted to a user, thereby determining which Platform features a user has access to. For example, an administrator role document may grant full read/edit permissions, while an end user role document may grant limited read permissions. Multiple role documents can be assigned to a single OU, creating an overlapping tapestry of permissions.

For more information, see Use Role Documents to Define Permissions.

1. In the Tanzu CloudHealth Platform, from the left menu, select Setup > Admin > Role Documents. You can copy one of the built-in role documents (Standard User, Administrator, or Power User) and modify the copy to create your own. You can also create a new role document by selecitng New Role Document.
2. Click one of the the built-in role documents to understand its structure. Then decide if you want to customize an existing role document or build a new one. Here is the structure of the Standard User role document. A role document is a set of privileges (read, write, update, delete) for various operations in the Tanzu CloudHealth Platform.

Step 3 - Create User Groups

A User Group is a collection of users that all require the same level of access to content in one or more OUs. For example, a user group might be defined as employees belonging to the same team. User groups define the relationship between users, OUs, and Role Documents.

For more information, see Create User Groups to Define FlexOrgs Relationships.

1. In the Tanzu CloudHealth Platform, from the left menu, select Setup > Admin > User Groups. Then click New User Group.
2. In the Details tab, provide a Name and optionally, a Description for the User Group. If you are using SSO for FlexOrgs, provide the key value pairs attached as assertions to user profiles associated with this User Group.
3. In the Members tab, click Add Members. In the Add Members dialog box, locate the users that you want to include in the User Group. Then click Confirm.
4. In the Assignment tab, add one or more Role Documents that are applicable 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. Click Save.

Invite Users into a User Group and an Organization in FlexOrgs

Send an email invite to users and specify their user group and the Organization to which they have access

Prerequisites

Before you invite a user, make sure you have taken the following actions in the Tanzu CloudHealth Platform.

• You have created and identified a FlexOrgs organization or sub-organization for the user. See Create Organizational Hierarchy.
• You have created and identified a User Group for the user. See Create User Groups.

How to Invite Users

1. In the Tanzu CloudHealth Platform, from the left menu, select Setup > Admin > Users. Click Invite User.
2. Enter the name and email address of the user.
3. In the Organization dropdown, scroll to a FlexOrgs organization and select the organization to which the user has access. FlexOrgs organizations are visually distinguished from classic organizations by their expanding tree structure, which allows you to view their hierarchy.
4. In the User Group dropdown, select a User Group to which this user should be assigned when they log in.
5. Click Invite User. When the user accepts the invitation and logs into the Tanzu CloudHealth Platform, they are taken to the Organization that you selected and sorted into the User Group you identified.

Enable SAML SSO for FlexOrgs

Attach SSO attributes to user group so that users are dynamically sorted into the correct user group when they log in

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

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

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

   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.