Merge branch 'docs/update-impersonation-tokens' into 'master'
Update Impersonation tokens docs See merge request !10055
This commit is contained in:
Sean McGivern
commit
2965a20a1f
|
|
@ -74,6 +74,12 @@ returned with status code `401`:
|
|||
}
|
||||
```
|
||||
|
||||
### Session Cookie
|
||||
|
||||
When signing in to GitLab as an ordinary user, a `_gitlab_session` cookie is
|
||||
set. The API will use this cookie for authentication if it is present, but using
|
||||
the API to generate a new session cookie is currently not supported.
|
||||
|
||||
### Private Tokens
|
||||
|
||||
You need to pass a `private_token` parameter via query string or header. If passed as a
|
||||
|
|
@ -113,11 +119,73 @@ moment – `read_user` and `api` – the groundwork has been laid to add more sc
|
|||
|
||||
At any time you can revoke any personal access token by just clicking **Revoke**.
|
||||
|
||||
### Session Cookie
|
||||
### Impersonation tokens
|
||||
|
||||
When signing in to GitLab as an ordinary user, a `_gitlab_session` cookie is
|
||||
set. The API will use this cookie for authentication if it is present, but using
|
||||
the API to generate a new session cookie is currently not supported.
|
||||
> [Introduced][ce-9099] in GitLab 9.0. Needs admin permissions.
|
||||
|
||||
Impersonation tokens are a type of [Personal Access Token](#personal-access-tokens)
|
||||
that can only be created by an admin for a specific user.
|
||||
|
||||
They are a better alternative to using the user's password/private token
|
||||
or using the [Sudo](#sudo) feature which also requires the admin's password
|
||||
or private token, since the password/token can change over time. Impersonation
|
||||
tokens are a great fit if you want to build applications or tools which
|
||||
authenticate with the API as a specific user.
|
||||
|
||||
For more information about the usage please refer to the
|
||||
[users API](users.md#retrieve-user-impersonation-tokens) docs.
|
||||
|
||||
### Sudo
|
||||
|
||||
> Needs admin permissions.
|
||||
|
||||
All API requests support performing an API call as if you were another user,
|
||||
provided your private token is from an administrator account. You need to pass
|
||||
the `sudo` parameter either via query string or a header with an ID/username of
|
||||
the user you want to perform the operation as. If passed as a header, the
|
||||
header name must be `SUDO` (uppercase).
|
||||
|
||||
If a non administrative `private_token` is provided, then an error message will
|
||||
be returned with status code `403`:
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "403 Forbidden - Must be admin to use sudo"
|
||||
}
|
||||
```
|
||||
|
||||
If the sudo user ID or username cannot be found, an error message will be
|
||||
returned with status code `404`:
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "404 Not Found: No user id or username for: <id/username>"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Example of a valid API call and a request using cURL with sudo request,
|
||||
providing a username:
|
||||
|
||||
```
|
||||
GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=username
|
||||
```
|
||||
|
||||
```shell
|
||||
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: username" "https://gitlab.example.com/api/v4/projects"
|
||||
```
|
||||
|
||||
Example of a valid API call and a request using cURL with sudo request,
|
||||
providing an ID:
|
||||
|
||||
```
|
||||
GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
|
||||
```
|
||||
|
||||
```shell
|
||||
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v4/projects"
|
||||
```
|
||||
|
||||
## Basic Usage
|
||||
|
||||
|
|
@ -126,8 +194,8 @@ is defined in [`lib/api.rb`][lib-api-url].
|
|||
|
||||
Example of a valid API request:
|
||||
|
||||
```shell
|
||||
GET https://gitlab.example.com/api/v4/projects?private_token=9koXpg98eAheJpvBs5tK
|
||||
```
|
||||
GET /projects?private_token=9koXpg98eAheJpvBs5tK
|
||||
```
|
||||
|
||||
Example of a valid API request using cURL and authentication via header:
|
||||
|
|
@ -171,64 +239,6 @@ The following table shows the possible return codes for API requests.
|
|||
| `422 Unprocessable` | The entity could not be processed. |
|
||||
| `500 Server Error` | While handling the request something went wrong server-side. |
|
||||
|
||||
## Sudo
|
||||
|
||||
All API requests support performing an API call as if you were another user,
|
||||
provided your private token is from an administrator account. You need to pass
|
||||
the `sudo` parameter either via query string or a header with an ID/username of
|
||||
the user you want to perform the operation as. If passed as a header, the
|
||||
header name must be `SUDO` (uppercase).
|
||||
|
||||
If a non administrative `private_token` is provided, then an error message will
|
||||
be returned with status code `403`:
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "403 Forbidden - Must be admin to use sudo"
|
||||
}
|
||||
```
|
||||
|
||||
If the sudo user ID or username cannot be found, an error message will be
|
||||
returned with status code `404`:
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "404 Not Found: No user id or username for: <id/username>"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Example of a valid API call and a request using cURL with sudo request,
|
||||
providing a username:
|
||||
|
||||
```shell
|
||||
GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=username
|
||||
```
|
||||
|
||||
```shell
|
||||
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: username" "https://gitlab.example.com/api/v4/projects"
|
||||
```
|
||||
|
||||
Example of a valid API call and a request using cURL with sudo request,
|
||||
providing an ID:
|
||||
|
||||
```shell
|
||||
GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
|
||||
```
|
||||
|
||||
```shell
|
||||
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v4/projects"
|
||||
```
|
||||
|
||||
## Impersonation Tokens
|
||||
|
||||
Impersonation Tokens are a type of Personal Access Token that can only be created by an admin for a specific user. These can be used by automated tools
|
||||
to authenticate with the API as a specific user, as a better alternative to using the user's password or private token directly, which may change over time,
|
||||
and to using the [Sudo](#sudo) feature, which requires the tool to know an admin's password or private token, which can change over time as well and are extremely powerful.
|
||||
|
||||
For more information about the usage please refer to the [Users](users.md) page
|
||||
|
||||
## Pagination
|
||||
|
||||
Sometimes the returned result will span across many pages. When listing
|
||||
|
|
@ -307,14 +317,14 @@ For example, an issue might have `id: 46` and `iid: 5`.
|
|||
|
||||
That means that if you want to get an issue via the API you should use the `id`:
|
||||
|
||||
```bash
|
||||
```
|
||||
GET /projects/42/issues/:id
|
||||
```
|
||||
|
||||
On the other hand, if you want to create a link to a web page you should use
|
||||
the `iid`:
|
||||
|
||||
```bash
|
||||
```
|
||||
GET /projects/42/issues/:iid
|
||||
```
|
||||
|
||||
|
|
@ -398,3 +408,4 @@ programming languages. Visit the [GitLab website] for a complete list.
|
|||
[lib-api-url]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api/api.rb
|
||||
[ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749
|
||||
[ce-5951]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951
|
||||
[ce-9099]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9099
|
||||
|
|
|
|||
121
doc/api/users.md
121
doc/api/users.md
|
|
@ -828,10 +828,12 @@ Example response:
|
|||
]
|
||||
```
|
||||
|
||||
## Retrieve user impersonation tokens
|
||||
## Get all impersonation tokens of a user
|
||||
|
||||
It retrieves every impersonation token of the user. Note that only administrators can do this.
|
||||
This function takes pagination parameters `page` and `per_page` to restrict the list of impersonation tokens.
|
||||
> Requires admin permissions.
|
||||
|
||||
It retrieves every impersonation token of the user. Use the pagination
|
||||
parameters `page` and `per_page` to restrict the list of impersonation tokens.
|
||||
|
||||
```
|
||||
GET /users/:user_id/impersonation_tokens
|
||||
|
|
@ -842,27 +844,50 @@ Parameters:
|
|||
| Attribute | Type | Required | Description |
|
||||
| --------- | ---- | -------- | ----------- |
|
||||
| `user_id` | integer | yes | The ID of the user |
|
||||
| `state` | string | no | filter tokens based on state (all, active, inactive) |
|
||||
| `state` | string | no | filter tokens based on state (`all`, `active`, `inactive`) |
|
||||
|
||||
```
|
||||
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"name": "mytoken",
|
||||
"revoked": false,
|
||||
"expires_at": "2017-01-04",
|
||||
"scopes": ['api'],
|
||||
"active": true,
|
||||
"impersonation": true,
|
||||
"token": "9koXpg98eAheJpvBs5tK"
|
||||
}
|
||||
{
|
||||
"active" : true,
|
||||
"token" : "EsMo-vhKfXGwX9RKrwiy",
|
||||
"scopes" : [
|
||||
"api"
|
||||
],
|
||||
"revoked" : false,
|
||||
"name" : "mytoken",
|
||||
"id" : 2,
|
||||
"created_at" : "2017-03-17T17:18:09.283Z",
|
||||
"impersonation" : true,
|
||||
"expires_at" : "2017-04-04"
|
||||
},
|
||||
{
|
||||
"active" : false,
|
||||
"scopes" : [
|
||||
"read_user"
|
||||
],
|
||||
"revoked" : true,
|
||||
"token" : "ZcZRpLeEuQRprkRjYydY",
|
||||
"name" : "mytoken2",
|
||||
"created_at" : "2017-03-17T17:19:28.697Z",
|
||||
"id" : 3,
|
||||
"impersonation" : true,
|
||||
"expires_at" : "2017-04-14"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Show a user's impersonation token
|
||||
## Get an impersonation token of a user
|
||||
|
||||
It shows a user's impersonation token. Note that only administrators can do this.
|
||||
> Requires admin permissions.
|
||||
|
||||
It shows a user's impersonation token.
|
||||
|
||||
```
|
||||
GET /users/:user_id/impersonation_tokens/:impersonation_token_id
|
||||
|
|
@ -875,7 +900,31 @@ Parameters:
|
|||
| `user_id` | integer | yes | The ID of the user |
|
||||
| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
|
||||
|
||||
## Create a impersonation token
|
||||
```
|
||||
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```json
|
||||
{
|
||||
"active" : true,
|
||||
"token" : "EsMo-vhKfXGwX9RKrwiy",
|
||||
"scopes" : [
|
||||
"api"
|
||||
],
|
||||
"revoked" : false,
|
||||
"name" : "mytoken",
|
||||
"id" : 2,
|
||||
"created_at" : "2017-03-17T17:18:09.283Z",
|
||||
"impersonation" : true,
|
||||
"expires_at" : "2017-04-04"
|
||||
}
|
||||
```
|
||||
|
||||
## Create an impersonation token
|
||||
|
||||
> Requires admin permissions.
|
||||
|
||||
It creates a new impersonation token. Note that only administrators can do this.
|
||||
You are only able to create impersonation tokens to impersonate the user and perform
|
||||
|
|
@ -891,32 +940,46 @@ Parameters:
|
|||
| Attribute | Type | Required | Description |
|
||||
| --------- | ---- | -------- | ----------- |
|
||||
| `user_id` | integer | yes | The ID of the user |
|
||||
| `name` | string | yes | The name of the impersonation token |
|
||||
| `expires_at` | date | no | The expiration date of the impersonation token |
|
||||
| `scopes` | array | no | The array of scopes of the impersonation token (api, read_user) |
|
||||
| `name` | string | yes | The name of the impersonation token |
|
||||
| `expires_at` | date | no | The expiration date of the impersonation token in ISO format (`YYYY-MM-DD`)|
|
||||
| `scopes` | array | yes | The array of scopes of the impersonation token (`api`, `read_user`) |
|
||||
|
||||
```
|
||||
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "name=mytoken" --data "expires_at=2017-04-04" --data "scopes[]=api" https://gitlab.example.com/api/v4/users/42/impersonation_tokens
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"name": "mytoken",
|
||||
"revoked": false,
|
||||
"expires_at": "2017-01-04",
|
||||
"scopes": ['api'],
|
||||
"active": true,
|
||||
"impersonation": true,
|
||||
"token": "9koXpg98eAheJpvBs5tK"
|
||||
"id" : 2,
|
||||
"revoked" : false,
|
||||
"scopes" : [
|
||||
"api"
|
||||
],
|
||||
"token" : "EsMo-vhKfXGwX9RKrwiy",
|
||||
"active" : true,
|
||||
"impersonation" : true,
|
||||
"name" : "mytoken",
|
||||
"created_at" : "2017-03-17T17:18:09.283Z",
|
||||
"expires_at" : "2017-04-04"
|
||||
}
|
||||
```
|
||||
|
||||
## Revoke an impersonation token
|
||||
|
||||
It revokes an impersonation token. Note that only administrators can revoke impersonation tokens.
|
||||
> Requires admin permissions.
|
||||
|
||||
It revokes an impersonation token.
|
||||
|
||||
```
|
||||
DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id
|
||||
```
|
||||
|
||||
```
|
||||
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1
|
||||
```
|
||||
|
||||
Parameters:
|
||||
|
||||
| Attribute | Type | Required | Description |
|
||||
|
|
|
|||
Loading…
Reference in New Issue