Update API docs for "UAA client" users (#4668)

- Assigning role to a UAA client has been possible for a long time and
  is well-supported by the cf CLI.
- This is to support authenticating using the UAA "client_credentials"
  grant, and then using to make CAPI API requests.
- This use case was present in the API docs, but was not emphasized, so
  it was easy to miss.

[No AI Usage]

Author: Gerg

docs/v3/source/includes/resources/roles/_create.md.erb

@@ -83,7 +83,7 @@ To create a space role you must be an admin, an organization manager in the pare
 
 For a user to be assigned a space role, the user must already have an organization role in the parent organization.
 
-If the associated user is valid but does not exist in Cloud Controller's database, a user resource will be created automatically.
+If the associated user does not exist in Cloud Controller's database, a user resource will be created automatically. This user may correspond to a UAA user or client. See the [user resource](#users) for more details.
 
 If CAPI property `cc.allow_user_creation_by_org_manager` is enabled, the organization role is being created by username + origin and the user does not exist in UAA yet, the user will be created.
 The origin must be different from `uaa` in this case.

docs/v3/source/includes/resources/users/_create.md.erb

@@ -3,9 +3,10 @@
 Creating a user requires one value, a GUID. This creates a user in the Cloud
 Controller database.
 
-Generally, the GUID should match the GUID of an already-created user in the
-UAA database, though this is not required.
-Creating a user by guid is only permitted by admins.
+Generally, the GUID should match the ID of an already-created user in the UAA
+database, though this is not required. The GUID can also be a UAA client ID, to
+support the UAA `client_credentials` grant type. Creating a user by guid is
+only permitted by admins.
 
 If CAPI property `cc.allow_user_creation_by_org_manager` is enabled, a UAA user will be automatically created if it does not exist yet.
 The UAA user will be only created when `username` and `origin` have been provided instead of a guid. Additionally `origin` must be different from `uaa`.
@@ -69,7 +70,7 @@ Content-Type: application/json
 
 Name     | Type     | Description
 -------  | -------  |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-**guid** | _string_ | Unique identifier for the user. For UAA users this will match the user ID of an existing UAA user's GUID; in the case of UAA clients, this will match the UAA client ID |
+**guid** | _string_ | Unique identifier for the user. For UAA users this will match the UAA user ID; in the case of UAA clients, this will match the UAA client ID |
 **username** | _string_ | Username of the user to be created. This can only be provided together with `origin`.                                                                                   |
 **origin** | _string_ | Origin of the user to be created. This can only be provided together with `username` and cannot be `uaa`.                                                               |
 **metadata.labels**   | [_label object_](#links) | Labels applied to the user                                                                                                                                              |

docs/v3/source/includes/resources/users/_header.md

@@ -1,8 +1,16 @@
 ## Users
 
-Every Cloud Foundry action (pushing an application, creating a space) requires a
-user. Each Cloud Foundry installation has one pre-installed user, admin, which
-can create subsequent users. Users can be assigned roles which give them
-privileges to perform actions. For example, the Space Developer role grants a
-user permission to manage apps and services in a space (to push apps, scale
+The user resource is used to manage access to organizations, spaces, and other
+resources within Cloud Foundry. Cloud Controller is not the ultimate authority
+on the users in the Cloud Foundry system; UAA and its configured identity
+providers determine which users are able to sign in to Cloud Foundry.
+
+To be functional, Cloud Controller users must "shadow" a corresponding user or
+client in UAA. The Cloud Controller user resource's guid should match either a
+UAA user or a UAA client id. However, Cloud Controller does not enforce that
+a user's guid is a valid UAA user or client id.
+
+Users can be assigned roles, which give them privileges to perform actions
+within a given context. For example, the Space Developer role grants a user
+permission to manage apps and services in a space (e.g. to push apps, scale
 apps, delete apps).

docs/v3/source/includes/resources/users/_object.md.erb

@@ -9,7 +9,7 @@ Example User object
 
 | Name                                      | Type                          | Description                                                                                                                   |
 | --------------                            | ------------------------      | ------------------------------------------------------                                                                        |
-| **guid**                                  | _uuid_                        | Unique identifier for the user                                                                                               |
+| **guid**                                  | _uuid_                        | Unique identifier for the user, matching either a UAA user id or client id                                                                                               |
 | **created_at**                            | _[timestamp](#timestamps)_                    | The time with zone when the object was created                                                                               |
 | **updated_at**                            | _[timestamp](#timestamps)_                    | The time with zone when the object was last updated                                                                          |
 | **username**                              | _string_                      | The name registered in UAA; will be `null` for UAA clients and non-UAA users                                                 |