improving info on service roles in multi-tenant environments

pages/doc/csp_invite-AoA-users_tutorial.md

@@ -22,15 +22,20 @@ To invite users, you must have the VMware Cloud **Organization Owner** or **Orga
 
 ## Roles to Assign
 
-When you invite new users, you must assign them:
+To invite new users, you assign them:
 
-* A role within the VMware Cloud organization, such as **Organization Administrator**, **Organization Owner**, or **Organization Member**. 
+* A role within the VMware Cloud organization, such as **Organization Administrator**, **Organization Owner**, or **Organization Member**. See [What organization roles are available in VMware Cloud services](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-C11D3AAC-267C-4F16-A0E3-3EDF286EBE53.html) in the VMware Cloud services documentation.
 
   Note that you can assign the **Organization Owner** role to another user only if you have the **Organization Owner** role.
 
-* A role within the Operations for Applications service instance. 
+* A role within the Operations for Applications service instance. We provide a number of [Operations for Applications service roles](csp_users_roles.html#operations-for-applications-service-roles-built-in).
+
+   Note that in a multi-tenant Operations for Applications environment, you must specify the service instance (tenant) for which you want to assign the service role. You can assign different service roles for different service instances (tenants). You invite the users only to the tenants for which you assigned them service roles.
+
+* Optionally, a custom role created in the VMware Cloud organization. [Custom roles](csp_users_roles.html#create-edit-or-delete-a-custom-role) are composed of different service permissions.
+
+   Note that a custom role with an Operations for Applications permission applies only if the user has at least one Operations for Applications service role. In a multi-tenant Operations for Applications environment, custom roles apply to all service instances (tenants) for which the user has at least one Operations for Applications service role.
 
-Optionally, you can also assign a custom role created in the VMware Cloud organization. Custom roles are composed of different service permissions.
 
 ## Verify That You Have the Required Organization Role
 
@@ -52,9 +57,10 @@ VMware Cloud uses organizations to provide controlled access to one or more serv
 1. Click your username and click **My Account**.
 2. On the **My Roles** tab you can see what organization roles are assigned to you.
 
-If do not have the VMware Cloud **Organization Owner** or **Organization Administrator** role assigned, you need to request them. To understand who the VMware Cloud **Organization Owner** or **Organization Administrator** users are, you can chat with VMware Support or file a VMware Cloud services support request. See [How do I get support](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-E4DC731F-C039-4FB2-949E-9A61584CD5BF.html) in the VMware Cloud services product documentation.
+If you do not have the VMware Cloud **Organization Owner** or **Organization Administrator** role assigned, you need to request them. To understand who the VMware Cloud **Organization Owner** or **Organization Administrator** users are, you can chat with our Technical Support team or file a VMware Cloud services support request. See [How do I get support](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-E4DC731F-C039-4FB2-949E-9A61584CD5BF.html) in the VMware Cloud services product documentation.
+
 
-## Invite a New User and Assign Service Roles Only
+## Example 1: Invite a New User and Assign Service Roles
 
 We provide a number of built-in Operations for Applications service roles.
 
@@ -73,23 +79,26 @@ For more information, see [Operations for Applications Service Roles (Built-in)]
 
 ### Step 2: Assign Roles and Invite the User
 
-In a multi-tenant environment, you can assign different service roles for each Operations for Applications instance. Let's first assign the mandatory organization role and then we will assign different service roles for two Operations for Applications instances. 
+In a multi-tenant environment, you assign service roles on a tenant basis. You can assign different service roles for different Operations for Applications instances (tenants). Let’s first assign the mandatory organization role and then assign different service roles for two Operations for Applications instances.
 
-1. Select a mandatory organization role to assign.
+1. Under **Assign Organization Roles**, select a mandatory organization role to assign.
 
    The **Organization Member** role is selected by default and is the minimum mandatory role to assign. 
 
-   You can also assign an additional role. For example, **Support User**. This means that the user will have read-only access to the VMware Cloud organization resources and will be able to submit and manage support tickets. For information about the VMware Cloud organization roles, see [What Organization roles are available in VMware Cloud Services](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-C11D3AAC-267C-4F16-A0E3-3EDF286EBE53.html).
+   You can also assign an additional role, for example, **Support User**. This means that the user will have read-only access to the VMware Cloud organization resources and will be able to submit and manage support tickets. For information about the VMware Cloud organization roles, see [What Organization roles are available in VMware Cloud Services](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-C11D3AAC-267C-4F16-A0E3-3EDF286EBE53.html).
 
    ![A screenshot with the Organization Member role, selected by default and the Support user additional role selected.](images/csp-mandatory-roles.png)
 
-2. Assign Operations for Applications service roles for the first Operations for Applications instance.
-   1. Click **Add a Service**.
-   1. From the drop-down menu, select **VMware Aria Operations for Applications**.
+2. Assign Operations for Applications service roles for the first Operations for Applications instance (tenant) to which you want to invite the new user.
+   1. Under **Assign Service Roles**, click **Add a Service**.
+   1. From the first drop-down menu, select **VMware Aria Operations for Applications**.
       ![A screenshot with the Operations for Applications service selected.](images/csp-select-service.png)
-   1. From the **in** drop-down menu, select the service instance to which you want to invite the new user.
+   1. From the **in** drop-down menu, select the target service instance (tenant).
       ![A screenshot with the Operations for Applications service instance selected.](images/csp-select-aoa-service.png)
-   1. Assign the service roles to the user.
+
+      {% include note.html content="This drop-down menu is available only for multi-tenant environments. If you want to grant access to all tenants, you must assign service roles for each tenant individually (see the next Step 3). If you miss selecting the target service instance, the users receive the `401 Unauthorized: User has no access to service` error message when trying to access that tenant."%}
+
+   1. From the **with roles** drop-down menu, select the service roles to assign for the selected service instance (tenant).
 
       Let's say that the user you're inviting will:
 
@@ -103,28 +112,28 @@ In a multi-tenant environment, you can assign different service roles for each O
       ![A screenshot with the Operations for Applications roles selected.](images/csp-assign-service-roles.png)
    1. Leave the never expires access field as is.
 
-3. Assign the **Super Admin** service role for another Operations for Applications instance.
+3. Assign another Operations for Applications service role for the second Operations for Applications instance (tenant) to which you want to invite the new user.
 
    1. Click **+ Add an Instance**.
-   1. From the **in** drop-down menu, select the other service instance to which you want to invite the new user.
+   1. From the **in** drop-down menu, select the target service instance (tenant).
       ![A screenshot with the Operations for Applications service instance selected.](images/csp-select-another-service.png)
-   1. Assign the **Super Admin** service role to the user.
+   1. From the **with roles** drop-down menu, select the **Super Admin** service role, so that you grant full administrative privileges for the selected service instance.
 
       ![A screenshot with the Operations for Applications roles selected.](images/csp-assign-superadmin-service-role.png)
    1. Leave the never expires access field as is.
 4. Leave the **Send emails to all invited users notifying them of this role assignment** selected and click **Add**.
 
 The invitations you send are valid for seven days. You can view the status of the invitation by expanding **Identity & Access Management** and then clicking **Pending Invitations**.
 
-## Invite a New User and Assign a Custom Role
+## Example 2: Invite a New User and Assign a Custom Role
 
 If you have created custom roles and want to assign custom roles to a user, you must make sure that you assign:
 
 * A mandatory organization role
 * At least one service role, for example **Viewer**
 * The custom roles of interest
 
-Custom roles work only in combination with service roles. The Operations for Applications permissions in a custom role apply to all service instances (tenants) for which the user has at least one Operations for Applications service role. 
+Custom roles work only in combination with service roles. In a multi-tenant environment, the Operations for Applications permissions in a custom role apply to all service instances (tenants) for which the user has at least one Operations for Applications service role.
 
 ### Step 1: Enter the New User Details
 
@@ -136,29 +145,27 @@ Custom roles work only in combination with service roles. The Operations for App
 
 ### Step 2: Assign the Roles and Invite the User
 
-Let's assign **Organization Administrator** as a mandatory organization role, then assign the **Viewer** service role to one tenant and the **Ingestion Policies** role to another tenant. After that we will assign the custom role. 
+Let's assign **Organization Administrator** as a mandatory organization role, then assign the **Viewer** service role for one tenant and the **Ingestion Policies** service role for another tenant. After that, we assign the custom role and it applies to the two tenants for which the user has service roles.
 
-1. Under mandatory roles, select the **Organization Administrator** role.
+1. Under **Assign Organization Roles**, select the **Organization Administrator** role.
 
    ![A screenshot with the Organization Administrator role selected.](images/csp-assign-org-admin.png)
 
-2. Assign the **Viewer** service role for a specific Operations for Applications service instance.
-   1. Click **Add a Service**.
-   1. From the drop-down menu, select **VMware Aria Operations for Applications**.
+2. Assign the **Viewer** service role for the first Operations for Applications service instance (tenant) to which you want to invite the new user.
+   1. Under **Assign Service Roles**, click **Add a Service**.
+   1. From the first drop-down menu, select **VMware Aria Operations for Applications**.
       ![A screenshot with the Operations for Applications service selected.](images/csp-select-service.png)
-   1. From the **in** drop-down menu, select the service instance to which you want to invite the new user and leave the **Viewer** service role selected so that you assign it to the user.
+   1. From the **in** drop-down menu, select the target service instance (tenant) and leave the **Viewer** service role selected.
       ![A screenshot with the Operations for Applications service instance  and the Viewer role selected.](images/csp-select-aoa-service-viewer.png)
    1. Leave the never expires access field as is.
-3. Assign the **Ingestion Policies** service role for another Operations for Applications service instance.
+3. Assign the **Ingestion Policies** service role for the second Operations for Applications service instance (tenant) to which you want to invite the new user.
    1. Click **+Add an Instance**.
-   1. From the **in** drop-down menu, select the other service instance to which you want to invite the new user.
-   1. Select the **Ingestion Policies** service role to assign it to the user.
+   1. From the **in** drop-down menu, select the target service instance (tenant).
+   1. From the **with roles** drop-down menu, select the **Ingestion Policies** service role to assign it to the user for the selected tenant.
       ![A screenshot with the Operations for Applications service instance and the Viewer and the Ingestion Policies service roles selected.](images/csp-assign-two-service-roles.png)
    1. Leave the never expires access field as is.
 
-3. Assign the custom role to the user.
-
-   The custom role is assigned for the already selected Operations for Applications service instances.
+3. Assign the custom role for the already selected Operations for Applications service instances (tenants).
 
    1. Click **+ Add Custom Roles Access**.
    1. In the **Add custom role access** popup window, search for, select the custom role that you want to assign, and click **Add**.   

pages/doc/csp_user_management.md

@@ -18,14 +18,16 @@ To add a user to your Operations for Applications service instance, you must ass
 
 1. An [organization role](csp_getting_started.html#whats-a-vmware-cloud-organization-role) for the VMware Cloud organization running the service instance.
 
-    {% include note.html content="I you are a VMware Cloud **Organization Administrator**, you can assign only the VMware Cloud **Organization Member** role. Only a VMware Cloud **Organization Owner** can add VMware Cloud **Organization Owners** and VMware Cloud **Organization Administrators**."%}
+    {% include note.html content="If you are a VMware Cloud **Organization Administrator**, you can assign only the VMware Cloud **Organization Member** role. Only a VMware Cloud **Organization Owner** can add VMware Cloud **Organization Owners** and VMware Cloud **Organization Administrators**."%}
 
 1. An [Operations for Applications service role](csp_users_roles.html#operations-for-applications-service-roles-built-in) for the service instance.
 
     You can assign a combination of service roles. For example, if the user that you want to invite will set up integrations, make sure that you assign that user both the **Integrations** and the **Proxies** service roles.
 
     If you plan to assign that user a custom role, you must assign that user at least the **Viewer** Operations for Applications service role, so that the user can access the service instance.
 
+    {% include note.html content="In a multi-tenant environment, you assign service roles on a tenant basis. You can assign different service roles for different Operations for Applications instances (tenants). The users have access only to the tenants for which they have service roles. The users receive the `401 Unauthorized: User has no access to service` error message when trying to access a tenant for which they don't have service roles."%}
+
     {% include important.html content="Make sure that you assign the [**Super Admin** service role](csp_users_roles.html#operations-for-applications-service-roles-built-in) to at least one user of your Operations for Applications service instance. There are some Super Admin tasks that no one else can perform. "%}
 
 1. Optionally, a [custom role](csp_users_roles.html#create-edit-or-delete-a-custom-role) with an [Operations for Applications permission](csp_permissions_overview.html#operations-for-applications-permissions).
@@ -36,7 +38,7 @@ You can assign users with these roles in the following ways:
 
 ### Adding Users to Your Organization
 
-When you are adding an individual user or a list of users to the VMware Cloud organization running the service instance, you must assign that users organization, service, and custom roles.
+When you are adding an individual user or a list of users to the VMware Cloud organization running the service instance, you must assign that users organization roles. To grant the users access to the Operations for Applications instance, you assign that users service roles. Optionally, you can also assign the users custom roles, which apply only in combination with service roles.
 
 For details, see [How do I add users to my Organization](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-47AA313E-9DAC-447C-B6C8-DF71ED45B0D5.html).