Skip to content

Commit

Permalink
Add shadow user creation to docs
Browse files Browse the repository at this point in the history
  • Loading branch information
svkrieger committed Jan 9, 2025
1 parent 36682b3 commit 5191738
Show file tree
Hide file tree
Showing 3 changed files with 64 additions and 7 deletions.
20 changes: 20 additions & 0 deletions docs/v3/source/includes/api_resources/_users.erb
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,26 @@
}
<% end %>

<% content_for :single_user_with_custom_origin do %>
{
"guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
"created_at": "2019-03-08T01:06:19Z",
"updated_at": "2019-03-08T01:06:19Z",
"username": "some-user",
"presentation_name": "some-user",
"origin": "some-origin",
"metadata": {
"labels": {},
"annotations":{}
},
"links": {
"self": {
"href": "https://api.example.org/v3/users/3a5d3d89-3f89-4f05-8188-8a2b298c79d5"
}
}
}
<% end %>

<% content_for :single_user_with_metadata do %>
{
"guid": "3a5d3d89-3f89-4f05-8188-8a2b298c79d5",
Expand Down
3 changes: 3 additions & 0 deletions docs/v3/source/includes/resources/roles/_create.md.erb
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,9 @@ For a user to be assigned a space role, the user must already have an organizati

If the associated user is valid but does not exist in Cloud Controller's database, a user resource will be created automatically.

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.

#### Definition
`POST /v3/roles`

Expand Down
48 changes: 41 additions & 7 deletions docs/v3/source/includes/resources/users/_create.md.erb
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,11 @@ 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.

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`.
Admins and OrgManagers can make use of the UAA user creation.

```
Example Request
Expand All @@ -31,19 +36,48 @@ Content-Type: application/json
<%= yield_content :single_user %>
```

```
Example Request (by username and origin)
```

```shell
curl "https://api.example.org/v3/users" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
"username": "some-user",
"origin": "some-origin"
}'
```

```
Example Response
```

```http
HTTP/1.1 201 Created
Content-Type: application/json

<%= yield_content :single_user_with_custom_origin %>
```

#### Definition
`POST /v3/users`

#### Required parameters

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 |
**metadata.labels** | [_label object_](#links) | Labels applied to the user |
**metadata.annotations** | [_annotation object_](#links) | Annotations added to the user |
------- | ------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------
**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 |
**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 |
**metadata.annotations** | [_annotation object_](#links) | Annotations added to the user |

#### Permitted roles

|
----- |
Admin |
Role | Notes
----- |----------------------------------------------------------------------------------------------------------------------------
Admin | |
OrgManager | can only create users by `username` and `origin` and when CAPI property `cc.allow_user_creation_by_org_manager` is enabled |

0 comments on commit 5191738

Please sign in to comment.