Commit 29a00e6c authored by Amy Qualls's avatar Amy Qualls

Merge branch 'api-docs-fixes-81821' into 'master'

API Docs Vale fixes

See merge request gitlab-org/gitlab!68493
parents 47c6e774 8867e5f8
......@@ -15,7 +15,7 @@ Available resources for the [GitLab REST API](index.md) can be grouped in the fo
See also:
- [V3 to V4](v3_to_v4.md).
- Adding [deploy keys for multiple projects](deploy_keys.md#adding-deploy-keys-to-multiple-projects).
- Adding [deploy keys for multiple projects](deploy_keys.md#add-deploy-keys-to-multiple-projects).
- [API Resources for various templates](#templates-api-resources).
## Project resources
......
......@@ -8,7 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w
## List all deploy keys
Get a list of all deploy keys across all projects of the GitLab instance. This endpoint requires administrator access and is not available on GitLab.com.
Get a list of all deploy keys across all projects of the GitLab instance. This
endpoint requires an administrator role and is not available on GitLab.com.
```plaintext
GET /deploy_keys
......@@ -74,7 +75,7 @@ Example response:
]
```
## Single deploy key
## Get a single deploy key
Get a single key.
......@@ -213,10 +214,10 @@ Example response:
}
```
## Adding deploy keys to multiple projects
## Add deploy keys to multiple projects
If you want to easily add the same deploy key to multiple projects in the same
group, this can be achieved quite easily with the API.
If you want to add the same deploy key to multiple projects in the same
group, this can be achieved with the API.
First, find the ID of the projects you're interested in, by either listing all
projects:
......
......@@ -5,7 +5,7 @@ group: Access
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
# GitLab as an OAuth2 provider
# GitLab as an OAuth 2.0 provider
This document covers using the [OAuth2](https://oauth.net/2/) protocol to allow
other services to access GitLab resources on user's behalf.
......@@ -15,9 +15,9 @@ other services, see the [OAuth2 authentication service provider](../integration/
documentation. This functionality is based on the
[doorkeeper Ruby gem](https://github.com/doorkeeper-gem/doorkeeper).
## Supported OAuth2 flows
## Supported OAuth 2.0 flows
GitLab currently supports the following authorization flows:
GitLab supports the following authorization flows:
- **Authorization code with [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636):**
Most secure. Without PKCE, you'd have to include client secrets on mobile clients,
......@@ -26,14 +26,13 @@ GitLab currently supports the following authorization flows:
server-side apps.
- **Implicit grant:** Originally designed for user-agent only apps, such as
single page web apps running on GitLab Pages).
The [IETF](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-09#section-2.1.2)
The [Internet Engineering Task Force (IETF)](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-09#section-2.1.2)
recommends against Implicit grant flow.
- **Resource owner password credentials:** To be used **only** for securely
hosted, first-party services. GitLab recommends against use of this flow.
The draft specification for [OAuth 2.1](https://oauth.net/2.1/) specifically omits both the
Implicit grant and Resource Owner Password Credentials flows.
it will be deprecated in the next OAuth specification version.
Implicit grant and Resource Owner Password Credentials flows. It will be deprecated in the next OAuth specification version.
Refer to the [OAuth RFC](https://tools.ietf.org/html/rfc6749) to find out
how all those flows work and pick the right one for your use case.
......@@ -57,7 +56,7 @@ parameter, which are securely bound to the user agent", with each request to the
For production, please use HTTPS for your `redirect_uri`.
For development, GitLab allows insecure HTTP redirect URIs.
As OAuth2 bases its security entirely on the transport layer, you should not use unprotected
As OAuth 2.0 bases its security entirely on the transport layer, you should not use unprotected
URIs. For more information, see the [OAuth 2.0 RFC](https://tools.ietf.org/html/rfc6749#section-3.1.2.1)
and the [OAuth 2.0 Threat Model RFC](https://tools.ietf.org/html/rfc6819#section-4.4.2.1).
These factors are particularly important when using the
......@@ -123,7 +122,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD
"created_at": 1607635748
}
```
1. To retrieve a new `access_token`, use the `refresh_token` parameter. Refresh tokens may
be used even after the `access_token` itself expires. This request:
- Invalidates the existing `access_token` and `refresh_token`.
......@@ -135,7 +134,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD
```
Example response:
```json
{
"access_token": "c97d1fe52119f38c7f67f0a14db68d60caa35ddc86fd12401718b649dcfa9c68",
......@@ -203,7 +202,7 @@ be used as a CSRF token.
"created_at": 1607635748
}
```
1. To retrieve a new `access_token`, use the `refresh_token` parameter. Refresh tokens may
be used even after the `access_token` itself expires. This request:
- Invalidates the existing `access_token` and `refresh_token`.
......@@ -245,12 +244,13 @@ scheduled to be removed for existing applications.
We recommend that you use [Authorization code with PKCE](#authorization-code-with-proof-key-for-code-exchange-pkce) instead. If you choose to use Implicit flow, be sure to verify the
`application id` (or `client_id`) associated with the access token before granting
access to the data, as described in [Retrieving the token information](#retrieving-the-token-information)).
access to the data. To learn more, read
[Retrieving the token information](#retrieve-the-token-information)).
Unlike the authorization code flow, the client receives an `access token`
immediately as a result of the authorization request. The flow does not use
the client secret or the authorization code because all of the application code
and storage is easily accessible on client browsers and mobile devices.
immediately as a result of the authorization request. The flow does not use the
client secret or the authorization code, as the application
code and storage is accessible on client browsers and mobile devices.
To request the access token, you should redirect the user to the
`/oauth/authorize` endpoint using `token` response type:
......@@ -367,10 +367,11 @@ or you can put the token to the Authorization header:
curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/user"
```
## Retrieving the token information
## Retrieve the token information
To verify the details of a token, use the `token/info` endpoint provided by the Doorkeeper gem.
For more information, see [`/oauth/token/info`](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples#get----oauthtokeninfo).
To verify the details of a token, use the `token/info` endpoint provided by the
Doorkeeper gem. For more information, see
[`/oauth/token/info`](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples#get----oauthtokeninfo).
You must supply the access token, either:
......@@ -407,9 +408,10 @@ prevent breaking changes introduced in [doorkeeper 5.0.2](https://github.com/doo
Don't rely on these fields as they are slated for removal in a later release.
## OAuth2 tokens and GitLab registries
## OAuth 2.0 tokens and GitLab registries
Standard OAuth2 tokens support different degrees of access to GitLab registries, as they:
Standard OAuth 2.0 tokens support different degrees of access to GitLab
registries, as they:
- Do not allow users to authenticate to:
- The GitLab [Container registry](../user/packages/container_registry/index.md#authenticate-with-the-container-registry).
......
......@@ -108,13 +108,14 @@ V1.
GET group/:id/-/packages/composer/:package_name$:sha
```
Note the `$` symbol in the URL. When making requests, you may need to use the URL-encoded version of
the symbol `%24` (see example below).
| Attribute | Type | Required | Description |
| -------------- | ------ | -------- | ----------- |
| `id` | string | yes | The ID or full path of the group. |
| `package_name` | string | yes | The name of the package. |
Note the `$` symbol in the URL. When making requests, you may need the
URL-encoded version of the symbol `%24`. Refer to the example after
the table:
| Attribute | Type | Required | Description |
|----------------|--------|----------|---------------------------------------------------------------------------------------|
| `id` | string | yes | The ID or full path of the group. |
| `package_name` | string | yes | The name of the package. |
| `sha` | string | yes | The SHA digest of the package, provided by the [V1 packages list](#v1-packages-list). |
```shell
......
......@@ -58,11 +58,11 @@ Upload a package.
PUT projects/:id/packages/npm/:package_name
```
| Attribute | Type | Required | Description |
| ----------------- | ------ | -------- | ----------- |
| `id` | string | yes | The ID or full path of the project. |
| `package_name` | string | yes | The name of the package. |
| `versions` | string | yes | Package version info. |
| Attribute | Type | Required | Description |
|----------------|--------|----------|-------------------------------------|
| `id` | string | yes | The ID or full path of the project. |
| `package_name` | string | yes | The name of the package. |
| `versions` | string | yes | Package version information. |
```shell
curl --request PUT
......
......@@ -47,7 +47,8 @@ To write the output to a file:
curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/groups/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1.tar.gz" >> my.pypi.package-0.0.1.tar.gz
```
This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current directory.
This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current
directory.
## Group level simple API entry point
......@@ -106,7 +107,7 @@ GET projects/:id/packages/pypi/files/:sha256/:file_identifier
| --------- | ---- | -------- | ----------- |
| `id` | string | yes | The ID or full path of the project. |
| `sha256` | string | yes | PyPI package file sha256 check sum. |
| `file_identifier` | string | yes | The PyPI package file name. |
| `file_identifier` | string | yes | The PyPI package filename. |
```shell
curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1.tar.gz"
......@@ -118,7 +119,8 @@ To write the output to a file:
curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1.tar.gz" >> my.pypi.package-0.0.1.tar.gz
```
This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current directory.
This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current
directory.
## Project-level simple API entry point
......
......@@ -43,7 +43,7 @@ This page gathers all the resources for the topic **Authentication** within GitL
- [Personal access tokens](../../api/index.md#personalproject-access-tokens)
- [Project access tokens](../../api/index.md#personalproject-access-tokens)
- [Impersonation tokens](../../api/index.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-oauth-20-provider)
## Third-party resources
......
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