diff --git a/docs/v3/source/includes/resources/roles/_create.md.erb b/docs/v3/source/includes/resources/roles/_create.md.erb index d464d0917a3..37df7932ecd 100644 --- a/docs/v3/source/includes/resources/roles/_create.md.erb +++ b/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. diff --git a/docs/v3/source/includes/resources/users/_create.md.erb b/docs/v3/source/includes/resources/users/_create.md.erb index 0cd53eee872..10289de8d1f 100644 --- a/docs/v3/source/includes/resources/users/_create.md.erb +++ b/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 | diff --git a/docs/v3/source/includes/resources/users/_header.md b/docs/v3/source/includes/resources/users/_header.md index b0e8dcb3f4d..b231a70dd20 100644 --- a/docs/v3/source/includes/resources/users/_header.md +++ b/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). diff --git a/docs/v3/source/includes/resources/users/_object.md.erb b/docs/v3/source/includes/resources/users/_object.md.erb index 23708727003..4f50eb6caf2 100644 --- a/docs/v3/source/includes/resources/users/_object.md.erb +++ b/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 |