Commit 1534be16 authored by Mike Jang's avatar Mike Jang

Merge branch 'docs-project-level-access-tokens-project-bots' into 'master'

Docs: Project access tokens (PrAT)

See merge request gitlab-org/gitlab!30562
parents 9994b8e1 4131c5d0
...@@ -77,10 +77,11 @@ authentication is not provided. For ...@@ -77,10 +77,11 @@ authentication is not provided. For
those cases where it is not required, this will be mentioned in the documentation 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 four ways to authenticate with the GitLab API: There are several ways to authenticate with the GitLab API:
1. [OAuth2 tokens](#oauth2-tokens) 1. [OAuth2 tokens](#oauth2-tokens)
1. [Personal access tokens](#personal-access-tokens) 1. [Personal access tokens](../user/profile/personal_access_tokens.md)
1. [Project access tokens](../user/project/settings/project_access_tokens.md) **(CORE ONLY)**
1. [Session cookie](#session-cookie) 1. [Session cookie](#session-cookie)
1. [GitLab CI/CD job token](#gitlab-ci-job-token) **(Specific endpoints only)** 1. [GitLab CI/CD job token](#gitlab-ci-job-token) **(Specific endpoints only)**
...@@ -117,31 +118,29 @@ curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api ...@@ -117,31 +118,29 @@ curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api
Read more about [GitLab as an OAuth2 provider](oauth2.md). Read more about [GitLab as an OAuth2 provider](oauth2.md).
### Personal access tokens ### Personal/project access tokens
You can use a [personal access token](../user/profile/personal_access_tokens.md) to authenticate with the API by passing it in either the Access tokens can be used to authenticate with the API by passing it in either the `private_token` parameter
`private_token` parameter or the `Private-Token` header. or the `Private-Token` header.
Example of using the personal access token in a parameter: Example of using the personal/project access token in a parameter:
```shell ```shell
curl https://gitlab.example.com/api/v4/projects?private_token=<your_access_token> curl https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>
``` ```
Example of using the personal access token in a header: Example of using the personal/project access token in a header:
```shell ```shell
curl --header "Private-Token: <your_access_token>" https://gitlab.example.com/api/v4/projects curl --header "Private-Token: <your_access_token>" https://gitlab.example.com/api/v4/projects
``` ```
You can also use personal access tokens with OAuth-compliant headers: You can also use personal/project access tokens with OAuth-compliant headers:
```shell ```shell
curl --header "Authorization: Bearer <your_access_token>" https://gitlab.example.com/api/v4/projects curl --header "Authorization: Bearer <your_access_token>" https://gitlab.example.com/api/v4/projects
``` ```
Read more about [personal access tokens](../user/profile/personal_access_tokens.md).
### Session cookie ### Session cookie
When signing in to the main GitLab application, a `_gitlab_session` cookie is When signing in to the main GitLab application, a `_gitlab_session` cookie is
......
...@@ -38,7 +38,8 @@ This page gathers all the resources for the topic **Authentication** within GitL ...@@ -38,7 +38,8 @@ This page gathers all the resources for the topic **Authentication** within GitL
## API ## API
- [OAuth 2 Tokens](../../api/README.md#oauth2-tokens) - [OAuth 2 Tokens](../../api/README.md#oauth2-tokens)
- [Personal access tokens](../../api/README.md#personal-access-tokens) - [Personal access tokens](../../api/README.md#personalproject-access-tokens)
- [Project access tokens](../../api/README.md#personalproject-access-tokens) **(CORE ONLY)**
- [Impersonation tokens](../../api/README.md#impersonation-tokens) - [Impersonation tokens](../../api/README.md#impersonation-tokens)
- [GitLab as an OAuth2 provider](../../api/oauth2.md#gitlab-as-an-oauth2-provider) - [GitLab as an OAuth2 provider](../../api/oauth2.md#gitlab-as-an-oauth2-provider)
......
...@@ -148,6 +148,7 @@ The following table depicts the various user permission levels in a project. ...@@ -148,6 +148,7 @@ The following table depicts the various user permission levels in a project.
| Delete wiki pages | | | | ✓ | ✓ | | Delete wiki pages | | | | ✓ | ✓ |
| View project Audit Events | | | | ✓ | ✓ | | View project Audit Events | | | | ✓ | ✓ |
| Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | | Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ |
| Manage [project access tokens](./project/settings/project_access_tokens.md) **(CORE ONLY)** | | | | ✓ | ✓ |
| Switch visibility level | | | | | ✓ | | Switch visibility level | | | | | ✓ |
| Transfer project to another namespace | | | | | ✓ | | Transfer project to another namespace | | | | | ✓ |
| Remove fork relationship | | | | | ✓ | | Remove fork relationship | | | | | ✓ |
......
...@@ -8,7 +8,7 @@ type: concepts, howto ...@@ -8,7 +8,7 @@ type: concepts, howto
> - [Notifications about expiring tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) added in GitLab 12.6. > - [Notifications about expiring tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) added in GitLab 12.6.
> - [Token lifetime limits](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) added in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. > - [Token lifetime limits](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) added in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6.
If you're unable to use [OAuth2](../../api/oauth2.md), you can use a personal access token to authenticate with the [GitLab API](../../api/README.md#personal-access-tokens). If you're unable to use [OAuth2](../../api/oauth2.md), you can use a personal access token to authenticate with the [GitLab API](../../api/README.md#personalproject-access-tokens).
You can also use personal access tokens with Git to authenticate over HTTP or SSH. Personal access tokens are required when [Two-Factor Authentication (2FA)](../account/two_factor_authentication.md) is enabled. In both cases, you can authenticate with a token in place of your password. You can also use personal access tokens with Git to authenticate over HTTP or SSH. Personal access tokens are required when [Two-Factor Authentication (2FA)](../account/two_factor_authentication.md) is enabled. In both cases, you can authenticate with a token in place of your password.
...@@ -17,7 +17,7 @@ Personal access tokens expire on the date you define, at midnight UTC. ...@@ -17,7 +17,7 @@ Personal access tokens expire on the date you define, at midnight UTC.
- GitLab runs a check at 01:00 AM UTC every day to identify personal access tokens that will expire in under seven days. The owners of these tokens are notified by email. - GitLab runs a check at 01:00 AM UTC every day to identify personal access tokens that will expire in under seven days. The owners of these tokens are notified by email.
- In GitLab Ultimate, administrators may [limit the lifetime of personal access tokens](../admin_area/settings/account_and_limit_settings.md#limiting-lifetime-of-personal-access-tokens-ultimate-only). - In GitLab Ultimate, administrators may [limit the lifetime of personal access tokens](../admin_area/settings/account_and_limit_settings.md#limiting-lifetime-of-personal-access-tokens-ultimate-only).
For examples of how you can use a personal access token to authenticate with the API, see the following section from our [API Docs](../../api/README.md#personal-access-tokens). For examples of how you can use a personal access token to authenticate with the API, see the following section from our [API Docs](../../api/README.md#personalproject-access-tokens).
GitLab also offers [impersonation tokens](../../api/README.md#impersonation-tokens) which are created by administrators via the API. They're a great fit for automated authentication as a specific user. GitLab also offers [impersonation tokens](../../api/README.md#impersonation-tokens) which are created by administrators via the API. They're a great fit for automated authentication as a specific user.
......
# Project access tokens **(CORE ONLY)**
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0.
Project access tokens are scoped to a project and can be used to authenticate with the [GitLab API](../../../api/README.md#personalproject-access-tokens).
You can also use project access tokens with Git to authenticate over HTTP or SSH.
Project access tokens expire on the date you define, at midnight UTC.
For examples of how you can use a project access token to authenticate with the API, see the following section from our [API Docs](../../../api/README.md#personalproject-access-tokens).
## Creating a project access token
1. Log in to GitLab.
1. Navigate to the project you would like to create an access token for.
1. In the **{settings}** **Settings** menu choose **Access Tokens**.
1. Choose a name and optional expiry date for the token.
1. Choose the [desired scopes](#limiting-scopes-of-a-project-access-token).
1. Click the **Create project access token** button.
1. Save the project access token somewhere safe. Once you leave or refresh
the page, you won't be able to access it again.
## Project bot users
For each project access token created, a bot user will also be created and added to the project with
["Maintainer" level permissions](../../permissions.md#project-members-permissions). API calls made with a
project access token will be associated to the corresponding bot user.
These users will appear in **{settings}** **Settings > Members** but can not be modified.
Furthermore, the bot user can not be added to any other project.
When the project access token is [revoked](#revoking-a-project-access-token) the bot user will be deleted and all
records will be moved to a system-wide user with the username "Ghost User". For more information,
see [Associated Records](../../profile/account/delete_account.md#associated-records).
## Revoking a project access token
At any time, you can revoke any project access token by clicking the
respective **Revoke** button in **{settings}** **Settings > Access Tokens**.
## Limiting scopes of a project access token
Project 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 |
| ------------------ | ----------- |
| `api` | Grants complete read/write access to scoped project API. |
| `read_api` | Grants read access to the scoped project API. |
| `read_registry` | Allows read-access (pull) to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. |
| `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). |
| `read_repository` | Allows read-only access (pull) to the repository. |
| `write_repository` | Allows read-write access (pull, push) to the repository. |
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