Skip to content

G
gitlab-ce
Commit 2965a20a authored by Sean McGivern's avatar Sean McGivern
Browse files
Options

Merge branch 'docs/update-impersonation-tokens' into 'master' 

Update Impersonation tokens docs

See merge request !10055
parents b1699ff7 f4e7bc83
Show whitespace changes
Inline Side-by-side
Showing with 165 additions and 91 deletions
doc/api/README.md
View file @ 2965a20a
......@@ -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,65 +119,25 @@ 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.
## Basic Usage
Impersonation tokens are a type of [Personal Access Token](#personal-access-tokens)
that can only be created by an admin for a specific user.
API requests should be prefixed with `api` and the API version. The API version
is defined in [`lib/api.rb`][lib-api-url].
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.
Example of a valid API request:
For more information about the usage please refer to the
[users API](users.md#retrieve-user-impersonation-tokens) docs.
```shell
GET https://gitlab.example.com/api/v4/projects?private_token=9koXpg98eAheJpvBs5tK
```
Example of a valid API request using cURL and authentication via header:
```shell
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"
```
The API uses JSON to serialize data. You don't need to specify `.json` at the
end of an API URL.
## Status codes
The API is designed to return different status codes according to context and
action. This way, if a request results in an error, the caller is able to get
insight into what went wrong.
The following table gives an overview of how the API functions generally behave.
| Request type | Description |
| ------------ | ----------- |
| `GET` | Access one or more resources and return the result as JSON. |
| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. |
| `GET` / `PUT` / `DELETE` | Return `200 OK` if the resource is accessed, modified or deleted successfully. The (modified) result is returned as JSON. |
| `DELETE` | Designed to be idempotent, meaning a request to a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind this, is that the user is not really interested if the resource existed before or not. |
The following table shows the possible return codes for API requests.
| Return values | Description |
| ------------- | ----------- |
| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. |
| `204 No Content` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. |
| `201 Created` | The `POST` request was successful and the resource is returned as JSON. |
| `304 Not Modified` | Indicates that the resource has not been modified since the last request. |
| `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. |
| `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. |
| `403 Forbidden` | The request is not allowed, e.g., the user is not allowed to delete a project. |
| `404 Not Found` | A resource could not be accessed, e.g., an ID for a resource could not be found. |
| `405 Method Not Allowed` | The request is not supported. |
| `409 Conflict` | A conflicting resource already exists, e.g., creating a project with a name that already exists. |
| `422 Unprocessable` | The entity could not be processed. |
| `500 Server Error` | While handling the request something went wrong server-side. |
### Sudo
## 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
......@@ -202,7 +168,7 @@ returned with status code `404`:
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
```
......@@ -213,7 +179,7 @@ curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: username" "h
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
```
......@@ -221,13 +187,57 @@ GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v4/projects"
```
## Impersonation Tokens
## Basic Usage
API requests should be prefixed with `api` and the API version. The API version
is defined in [`lib/api.rb`][lib-api-url].
Example of a valid API request:
```
GET /projects?private_token=9koXpg98eAheJpvBs5tK
```
Example of a valid API request using cURL and authentication via header:
```shell
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"
```
The API uses JSON to serialize data. You don't need to specify `.json` at the
end of an API URL.
## Status codes
The API is designed to return different status codes according to context and
action. This way, if a request results in an error, the caller is able to get
insight into what went wrong.
The following table gives an overview of how the API functions generally behave.
| Request type | Description |
| ------------ | ----------- |
| `GET` | Access one or more resources and return the result as JSON. |
| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. |
| `GET` / `PUT` / `DELETE` | Return `200 OK` if the resource is accessed, modified or deleted successfully. The (modified) result is returned as JSON. |
| `DELETE` | Designed to be idempotent, meaning a request to a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind this, is that the user is not really interested if the resource existed before or not. |
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.
The following table shows the possible return codes for API requests.
For more information about the usage please refer to the [Users](users.md) page
| Return values | Description |
| ------------- | ----------- |
| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. |
| `204 No Content` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. |
| `201 Created` | The `POST` request was successful and the resource is returned as JSON. |
| `304 Not Modified` | Indicates that the resource has not been modified since the last request. |
| `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. |
| `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. |
| `403 Forbidden` | The request is not allowed, e.g., the user is not allowed to delete a project. |
| `404 Not Found` | A resource could not be accessed, e.g., an ID for a resource could not be found. |
| `405 Method Not Allowed` | The request is not supported. |
| `409 Conflict` | A conflicting resource already exists, e.g., creating a project with a name that already exists. |
| `422 Unprocessable` | The entity could not be processed. |
| `500 Server Error` | While handling the request something went wrong server-side. |
## Pagination
......@@ -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
doc/api/users.md
View file @ 2965a20a
......@@ -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
> Requires admin permissions.
It shows a user's impersonation token. Note that only administrators can do this.
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
......@@ -892,31 +941,45 @@ Parameters:
| --------- | ---- | -------- | ----------- |
| `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) |
| `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 |
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7