Commit f8740d5d authored by Sean Packham's avatar Sean Packham

Merge branch 'docs/personal-access-tokens' into 'master'

Add docs for personal access tokens

Closes #31740 and #33261

See merge request !12128
parents b29bf626 8fb33b8f
...@@ -55,6 +55,11 @@ following locations: ...@@ -55,6 +55,11 @@ following locations:
- [V3 to V4](v3_to_v4.md) - [V3 to V4](v3_to_v4.md)
- [Version](version.md) - [Version](version.md)
The following documentation is for the [internal CI API](ci/README.md):
- [Builds](ci/builds.md)
- [Runners](ci/runners.md)
## Road to GraphQL ## Road to GraphQL
Going forward, we will start on moving to Going forward, we will start on moving to
...@@ -65,22 +70,20 @@ controller-specific endpoints. GraphQL has a number of benefits: ...@@ -65,22 +70,20 @@ controller-specific endpoints. GraphQL has a number of benefits:
2. Callers of the API can request only what they need. 2. Callers of the API can request only what they need.
3. It is versioned by default. 3. It is versioned by default.
It will co-exist with the current V4 REST API. If we have a V5 API, this should be It will co-exist with the current v4 REST API. If we have a v5 API, this should
compatability layer on top of GraphQL. be a compatibility layer on top of GraphQL.
### Internal CI API
The following documentation is for the [internal CI API](ci/README.md):
- [Builds](ci/builds.md)
- [Runners](ci/runners.md)
## Authentication ## Authentication
Most API requests require authentication via a session cookie or token. For those cases where it is not required, this will be mentioned in the documentation Most API requests require authentication via a session cookie or token. For
those cases where it is not required, this will be mentioned in the documentation
for each individual endpoint. For example, the [`/projects/:id` endpoint](projects.md). for each individual endpoint. For example, the [`/projects/:id` endpoint](projects.md).
There are three types of tokens available: private tokens, OAuth 2 tokens, and personal
access tokens. There are three types of access tokens available:
1. [OAuth2 tokens](#oauth2-tokens)
1. [Private tokens](#private-tokens)
1. [Personal access tokens](#personal-access-tokens)
If authentication information is invalid or omitted, an error message will be If authentication information is invalid or omitted, an error message will be
returned with status code `401`: returned with status code `401`:
...@@ -91,20 +94,13 @@ returned with status code `401`: ...@@ -91,20 +94,13 @@ returned with status code `401`:
} }
``` ```
### Session Cookie ### Session cookie
When signing in to GitLab as an ordinary user, a `_gitlab_session` cookie is 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 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. the API to generate a new session cookie is currently not supported.
### Private Tokens ### OAuth2 tokens
You need to pass a `private_token` parameter via query string or header. If passed as a
header, the header name must be `PRIVATE-TOKEN` (uppercase and with a dash instead of
an underscore). You can find or reset your private token in your account page
(`/profile/account`).
### OAuth 2 Tokens
You can use an OAuth 2 token to authenticate with the API by passing it either in the You can use an OAuth 2 token to authenticate with the API by passing it either in the
`access_token` parameter or in the `Authorization` header. `access_token` parameter or in the `Authorization` header.
...@@ -117,30 +113,31 @@ curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api ...@@ -117,30 +113,31 @@ curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api
Read more about [GitLab as an OAuth2 client](oauth2.md). Read more about [GitLab as an OAuth2 client](oauth2.md).
### Personal Access Tokens ### Private tokens
> [Introduced][ce-3749] in GitLab 8.8. Private tokens provide full access to the GitLab API. Anyone with access to
them can interact with GitLab as if they were you. You can find or reset your
private token in your account page (`/profile/account`).
You can create as many personal access tokens as you like from your GitLab For examples of usage, [read the basic usage section](#basic-usage).
profile (`/profile/personal_access_tokens`); perhaps one for each application
that needs access to the GitLab API.
Once you have your token, pass it to the API using either the `private_token` ### Personal access tokens
parameter or the `PRIVATE-TOKEN` header.
> [Introduced][ce-5951] in GitLab 8.15. Instead of using your private token which grants full access to your account,
personal access tokens could be a better fit because of their granular
permissions.
Personal Access Tokens can be created with one or more scopes that allow various actions Once you have your token, pass it to the API using either the `private_token`
that a given token can perform. Although there are only two scopes available at the parameter or the `PRIVATE-TOKEN` header. For examples of usage,
moment – `read_user` and `api` – the groundwork has been laid to add more scopes easily. [read the basic usage section](#basic-usage).
At any time you can revoke any personal access token by just clicking **Revoke**. [Read more about personal access tokens.][pat]
### Impersonation tokens ### Impersonation tokens
> [Introduced][ce-9099] in GitLab 9.0. Needs admin permissions. > [Introduced][ce-9099] in GitLab 9.0. Needs admin permissions.
Impersonation tokens are a type of [Personal Access Token](#personal-access-tokens) Impersonation tokens are a type of [personal access token][pat]
that can only be created by an admin for a specific user. 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 They are a better alternative to using the user's password/private token
...@@ -149,9 +146,11 @@ or private token, since the password/token can change over time. Impersonation ...@@ -149,9 +146,11 @@ 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 tokens are a great fit if you want to build applications or tools which
authenticate with the API as a specific user. authenticate with the API as a specific user.
For more information about the usage please refer to the For more information, refer to the
[users API](users.md#retrieve-user-impersonation-tokens) docs. [users API](users.md#retrieve-user-impersonation-tokens) docs.
For examples of usage, [read the basic usage section](#basic-usage).
### Sudo ### Sudo
> Needs admin permissions. > Needs admin permissions.
...@@ -204,11 +203,16 @@ GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23 ...@@ -204,11 +203,16 @@ GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v4/projects" curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v4/projects"
``` ```
## Basic Usage ## Basic usage
API requests should be prefixed with `api` and the API version. The API version API requests should be prefixed with `api` and the API version. The API version
is defined in [`lib/api.rb`][lib-api-url]. is defined in [`lib/api.rb`][lib-api-url].
For endpoints that require [authentication](#authentication), you need to pass
a `private_token` parameter via query string or header. If passed as a header,
the header name must be `PRIVATE-TOKEN` (uppercase and with a dash instead of
an underscore).
Example of a valid API request: Example of a valid API request:
``` ```
...@@ -221,6 +225,12 @@ Example of a valid API request using cURL and authentication via header: ...@@ -221,6 +225,12 @@ Example of a valid API request using cURL and authentication via header:
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects" curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"
``` ```
Example of a valid API request using cURL and authentication via a query string:
```shell
curl "https://gitlab.example.com/api/v4/projects?private_token=9koXpg98eAheJpvBs5tK"
```
The API uses JSON to serialize data. You don't need to specify `.json` at the The API uses JSON to serialize data. You don't need to specify `.json` at the
end of an API URL. end of an API URL.
...@@ -436,3 +446,4 @@ programming languages. Visit the [GitLab website] for a complete list. ...@@ -436,3 +446,4 @@ programming languages. Visit the [GitLab website] for a complete list.
[ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749 [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-5951]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951
[ce-9099]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9099 [ce-9099]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9099
[pat]: ../user/profile/personal_access_tokens.md
...@@ -134,4 +134,4 @@ access_token = client.password.get_token('user@example.com', 'secret') ...@@ -134,4 +134,4 @@ access_token = client.password.get_token('user@example.com', 'secret')
puts access_token.token puts access_token.token
``` ```
[personal access tokens]: ./README.md#personal-access-tokens [personal access tokens]: ../user/profile/personal_access_tokens.md
\ No newline at end of file
# Session API # Session API
## Deprecation Notice >**Deprecation notice:**
Starting in GitLab 8.11, this feature has been **disabled** for users with
1. Starting in GitLab 8.11, this feature has been *disabled* for users with two-factor authentication turned on. [two-factor authentication][2fa] turned on. These users can access the API
2. These users can access the API using [personal access tokens] instead. using [personal access tokens] instead.
---
You can login with both GitLab and LDAP credentials in order to obtain the You can login with both GitLab and LDAP credentials in order to obtain the
private token. private token.
...@@ -52,4 +50,5 @@ Example response: ...@@ -52,4 +50,5 @@ Example response:
} }
``` ```
[personal access tokens]: ./README.md#personal-access-tokens [2fa]: ../user/profile/account/two_factor_authentication.md
[personal access tokens]: ../user/profile/personal_access_tokens.md
...@@ -804,7 +804,7 @@ Example response: ...@@ -804,7 +804,7 @@ Example response:
It creates a new impersonation token. Note that only administrators can do this. 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 You are only able to create impersonation tokens to impersonate the user and perform
both API calls and Git reads and writes. The user will not see these tokens in his profile both API calls and Git reads and writes. The user will not see these tokens in their profile
settings page. settings page.
``` ```
......
...@@ -282,9 +282,9 @@ which can be avoided if a different driver is used, for example `overlay`. ...@@ -282,9 +282,9 @@ which can be avoided if a different driver is used, for example `overlay`.
> **Notes:** > **Notes:**
- This feature requires GitLab 8.8 and GitLab Runner 1.2. - This feature requires GitLab 8.8 and GitLab Runner 1.2.
- Starting from GitLab 8.12, if you have 2FA enabled in your account, you need - Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need
to pass a personal access token instead of your password in order to login to to pass a [personal access token][pat] instead of your password in order to
GitLab's Container Registry. login to GitLab's Container Registry.
Once you've built a Docker image, you can push it up to the built-in Once you've built a Docker image, you can push it up to the built-in
[GitLab Container Registry](../../user/project/container_registry.md). For example, [GitLab Container Registry](../../user/project/container_registry.md). For example,
...@@ -409,3 +409,5 @@ Some things you should be aware of when using the Container Registry: ...@@ -409,3 +409,5 @@ Some things you should be aware of when using the Container Registry:
[docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/ [docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/
[docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities [docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities
[2fa]: ../../user/profile/account/two_factor_authentication.md
[pat]: ../../user/profile/personal_access_tokens.md
...@@ -125,23 +125,14 @@ applications and U2F devices. ...@@ -125,23 +125,14 @@ applications and U2F devices.
## Personal access tokens ## Personal access tokens
When 2FA is enabled, you can no longer use your normal account password to When 2FA is enabled, you can no longer use your normal account password to
authenticate with Git over HTTPS on the command line, you must use a personal authenticate with Git over HTTPS on the command line or when using
access token instead. [GitLab's API][api], you must use a [personal access token][pat] instead.
1. Log in to your GitLab account.
1. Go to your **Profile Settings**.
1. Go to **Access Tokens**.
1. Choose a name and expiry date for the token.
1. Click on **Create Personal Access Token**.
1. Save the personal access token somewhere safe.
When using Git over HTTPS on the command line, enter the personal access token
into the password field.
## Recovery options ## Recovery options
To disable two-factor authentication on your account (for example, if you To disable two-factor authentication on your account (for example, if you
have lost your code generation device) you can: have lost your code generation device) you can:
* [Use a saved recovery code](#use-a-saved-recovery-code) * [Use a saved recovery code](#use-a-saved-recovery-code)
* [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh) * [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh)
* [Ask a GitLab administrator to disable two-factor authentication on your account](#ask-a-gitlab-administrator-to-disable-two-factor-authentication-on-your-account) * [Ask a GitLab administrator to disable two-factor authentication on your account](#ask-a-gitlab-administrator-to-disable-two-factor-authentication-on-your-account)
...@@ -154,8 +145,9 @@ codes. If you saved these codes, you can use one of them to sign in. ...@@ -154,8 +145,9 @@ codes. If you saved these codes, you can use one of them to sign in.
To use a recovery code, enter your username/email and password on the GitLab To use a recovery code, enter your username/email and password on the GitLab
sign-in page. When prompted for a two-factor code, enter the recovery code. sign-in page. When prompted for a two-factor code, enter the recovery code.
> **Note:** Once you use a recovery code, you cannot re-use it. You can still >**Note:**
use the other recovery codes you saved. Once you use a recovery code, you cannot re-use it. You can still use the other
recovery codes you saved.
### Generate new recovery codes using SSH ### Generate new recovery codes using SSH
...@@ -190,11 +182,14 @@ a new set of recovery codes with SSH. ...@@ -190,11 +182,14 @@ a new set of recovery codes with SSH.
two-factor code. Then, visit your Profile Settings and add a new device two-factor code. Then, visit your Profile Settings and add a new device
so you do not lose access to your account again. so you do not lose access to your account again.
``` ```
3. Go to the GitLab sign-in page and enter your username/email and password. When prompted for a two-factor code, enter one of the recovery codes obtained
from the command-line output.
> **Note:** After signing in, visit your **Profile Settings -> Account** immediately to set up two-factor authentication with a new 3. Go to the GitLab sign-in page and enter your username/email and password.
device. When prompted for a two-factor code, enter one of the recovery codes obtained
from the command-line output.
>**Note:**
After signing in, visit your **Profile settings > Account** immediately to set
up two-factor authentication with a new device.
### Ask a GitLab administrator to disable two-factor authentication on your account ### Ask a GitLab administrator to disable two-factor authentication on your account
...@@ -206,19 +201,13 @@ Sign in and re-enable two-factor authentication as soon as possible. ...@@ -206,19 +201,13 @@ Sign in and re-enable two-factor authentication as soon as possible.
## Note to GitLab administrators ## Note to GitLab administrators
- You need to take special care to that 2FA keeps working after - You need to take special care to that 2FA keeps working after
[restoring a GitLab backup](../../../raketasks/backup_restore.md). [restoring a GitLab backup](../../../raketasks/backup_restore.md).
- To ensure 2FA authorizes correctly with TOTP server, you may want to ensure - To ensure 2FA authorizes correctly with TOTP server, you may want to ensure
your GitLab server's time is synchronized via a service like NTP. Otherwise, your GitLab server's time is synchronized via a service like NTP. Otherwise,
you may have cases where authorization always fails because of time differences. you may have cases where authorization always fails because of time differences.
[Google Authenticator]: https://support.google.com/accounts/answer/1066447?hl=en
[FreeOTP]: https://freeotp.github.io/
[YubiKey]: https://www.yubico.com/products/yubikey-hardware/
- The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from - The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from
multiple hostnames, or FQDNs. Each U2F registration is linked to the _current hostname_ at multiple hostnames, or FQDNs. Each U2F registration is linked to the _current hostname_ at
the time of registration, and cannot be used for other hostnames/FQDNs. the time of registration, and cannot be used for other hostnames/FQDNs.
For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`: For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`:
...@@ -226,3 +215,9 @@ the time of registration, and cannot be used for other hostnames/FQDNs. ...@@ -226,3 +215,9 @@ the time of registration, and cannot be used for other hostnames/FQDNs.
- The user logs out and attempts to log in via `first.host.xyz` - U2F authentication suceeds. - The user logs out and attempts to log in via `first.host.xyz` - U2F authentication suceeds.
- The user logs out and attempts to log in via `second.host.xyz` - U2F authentication fails, because - The user logs out and attempts to log in via `second.host.xyz` - U2F authentication fails, because
the U2F key has only been registered on `first.host.xyz`. the U2F key has only been registered on `first.host.xyz`.
[Google Authenticator]: https://support.google.com/accounts/answer/1066447?hl=en
[FreeOTP]: https://freeotp.github.io/
[YubiKey]: https://www.yubico.com/products/yubikey-hardware/
[api]: ../../../api/README.md
[pat]: ../personal_access_tokens.md
# Personal access tokens
> [Introduced][ce-3749] in GitLab 8.8.
Personal access tokens are useful if you need access to the [GitLab API][api].
Instead of using your private token which grants full access to your account,
personal access tokens could be a better fit because of their
[granular permissions](#limiting-scopes-of-a-personal-access-token).
You can also use them to authenticate against Git over HTTP. They are the only
accepted method of authentication when you have
[Two-Factor Authentication (2FA)][2fa] enabled.
Once you have your token, [pass it to the API][usage] using either the
`private_token` parameter or the `PRIVATE-TOKEN` header.
## Creating a personal access token
You can create as many personal access tokens as you like from your GitLab
profile.
1. Log in to your GitLab account.
1. Go to your **Profile settings**.
1. Go to **Access tokens**.
1. Choose a name and optionally an expiry date for the token.
1. Choose the [desired scopes](#limiting-scopes-of-a-personal-access-token).
1. Click on **Create personal access token**.
1. Save the personal access token somewhere safe. Once you leave or refresh
the page, you won't be able to access it again.
![Personal access tokens page](img/personal_access_tokens.png)
## Revoking a personal access token
At any time, you can revoke any personal access token by just clicking the
respective **Revoke** button under the 'Active personal access tokens' area.
## Limiting scopes of a personal access token
Personal access tokens can be created with one or more scopes that allow various
actions that a given token can perform. The available scopes are depicted in
the following table.
| Scope | Description |
| ----- | ----------- |
|`read_user` | Allows access to the read-only endpoints under `/users`. Essentially, any of the `GET` requests in the [Users API][users] are allowed ([introduced][ce-5951] in GitLab 8.15). |
| `api` | Grants complete access to the API (read/write) ([introduced][ce-5951] in GitLab 8.15). Required for accessing Git repositories over HTTP when 2FA is enabled. |
| `read_registry` | Allows to read [container registry] images if a project is private and authorization is required ([introduced][ce-11845] in GitLab 9.3). |
[2fa]: ../account/two_factor_authentication.md
[api]: ../../api/README.md
[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-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845
[container registry]: ../project/container_registry.md
[users]: ../../api/users.md
[usage]: ../../api/README.md#basic-usage
...@@ -8,8 +8,8 @@ ...@@ -8,8 +8,8 @@
Registry across your GitLab instance, visit the Registry across your GitLab instance, visit the
[administrator documentation](../../administration/container_registry.md). [administrator documentation](../../administration/container_registry.md).
- Starting from GitLab 8.12, if you have 2FA enabled in your account, you need - Starting from GitLab 8.12, if you have 2FA enabled in your account, you need
to pass a personal access token instead of your password in order to login to to pass a [personal access token][pat] instead of your password in order to
GitLab's Container Registry. login to GitLab's Container Registry.
- Multiple level image names support was added in GitLab 9.1 - Multiple level image names support was added in GitLab 9.1
With the Docker Container Registry integrated into GitLab, every project can With the Docker Container Registry integrated into GitLab, every project can
...@@ -114,12 +114,11 @@ and [Using the GitLab Container Registry documentation](../../ci/docker/using_do ...@@ -114,12 +114,11 @@ and [Using the GitLab Container Registry documentation](../../ci/docker/using_do
## Using with private projects ## Using with private projects
If a project is private, credentials will need to be provided for authorization. > [Introduced][ce-11845] in GitLab 9.3.
The preferred way to do this, is by using personal access tokens, which can be
created under `/profile/personal_access_tokens`. The minimal scope needed is:
`read_registry`.
This feature was introduced in GitLab 9.3. If a project is private, credentials will need to be provided for authorization.
The preferred way to do this, is by using [personal access tokens][pat].
The minimal scope needed is `read_registry`.
## Troubleshooting the GitLab Container Registry ## Troubleshooting the GitLab Container Registry
...@@ -264,4 +263,6 @@ The solution: check the [IAM permissions again](https://docs.docker.com/registry ...@@ -264,4 +263,6 @@ The solution: check the [IAM permissions again](https://docs.docker.com/registry
Once the right permissions were set, the error will go away. Once the right permissions were set, the error will go away.
[ce-4040]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4040 [ce-4040]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4040
[ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845
[docker-docs]: https://docs.docker.com/engine/userguide/intro/ [docker-docs]: https://docs.docker.com/engine/userguide/intro/
[pat]: ../profile/personal_access_tokens.md
...@@ -212,9 +212,9 @@ Container Registries for private projects. ...@@ -212,9 +212,9 @@ Container Registries for private projects.
access token created explicitly for this purpose). This issue is resolved with access token created explicitly for this purpose). This issue is resolved with
latest changes in GitLab Runner 1.8 which receives GitLab credentials with latest changes in GitLab Runner 1.8 which receives GitLab credentials with
build data. build data.
- Starting with GitLab 8.12, if you have 2FA enabled in your account, you need - Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need
to pass a personal access token instead of your password in order to login to to pass a [personal access token][pat] instead of your password in order to
GitLab's Container Registry. login to GitLab's Container Registry.
Your jobs can access all container images that you would normally have access Your jobs can access all container images that you would normally have access
to. The only implication is that you can push to the Container Registry of the to. The only implication is that you can push to the Container Registry of the
...@@ -239,3 +239,5 @@ test: ...@@ -239,3 +239,5 @@ test:
[update-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update [update-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update
[workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse [workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse
[jobenv]: ../../ci/variables/README.md#predefined-variables-environment-variables [jobenv]: ../../ci/variables/README.md#predefined-variables-environment-variables
[2fa]: ../profile/account/two_factor_authentication.md
[pat]: ../profile/personal_access_tokens.md
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