Commit d97f1c84 authored by Fiona Neill's avatar Fiona Neill

Merge branch 'eread/increase-visibility-of-deprecation' into 'master'

Increase visibility of deprecation

See merge request gitlab-org/gitlab!84134
parents 332c9498 5e589bf7
......@@ -24,10 +24,6 @@ GitLab supports the following authorization flows:
and is recommended for both client and server apps.
- **Authorization code:** Secure and common flow. Recommended option for secure
server-side apps.
- **Implicit grant:** Originally designed for user-agent only apps, such as
single page web apps running on GitLab Pages.
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.
......@@ -64,7 +60,7 @@ As OAuth 2.0 bases its security entirely on the transport layer, you should not
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
[Implicit grant flow](#implicit-grant-flow), where actual credentials are included in the `redirect_uri`.
[Implicit grant flow](#implicit-grant-flow-deprecated), where actual credentials are included in the `redirect_uri`.
In the following sections you can find detailed instructions on how to obtain
authorization with each flow.
......@@ -242,40 +238,6 @@ authorization request.
You can now make requests to the API with the access token returned.
### Implicit grant flow
WARNING:
Implicit grant flow is inherently insecure and the IETF has removed it in [OAuth 2.1](https://oauth.net/2.1/).
It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/288516) for use in GitLab 14.0, and is planned for
[removal](https://gitlab.com/gitlab-org/gitlab/-/issues/344609) in GitLab 15.0.
We recommend that you use [Authorization code with PKCE](#authorization-code-with-proof-key-for-code-exchange-pkce)
instead.
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, 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:
```plaintext
https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=token&state=YOUR_UNIQUE_STATE_HASH&scope=REQUESTED_SCOPES
```
This prompts the user to approve the applications access to their account
based on the scopes specified in `REQUESTED_SCOPES` and then redirect back to
the `REDIRECT_URI` you provided. The [scope parameter](../integration/oauth_provider.md#authorized-applications)
is a space-separated list of scopes you want to have access to (for example, `scope=read_user+profile`
would request `read_user` and `profile` scopes). The redirect
includes a fragment with `access_token` as well as token details in GET
parameters, for example:
```plaintext
https://example.com/oauth/redirect#access_token=ABCDExyz123&state=YOUR_UNIQUE_STATE_HASH&token_type=bearer&expires_in=3600
```
### Resource owner password credentials flow
NOTE:
......@@ -357,6 +319,40 @@ access_token = client.password.get_token('user@example.com', 'secret')
puts access_token.token
```
### Implicit grant flow (DEPRECATED)
WARNING:
Implicit grant flow is inherently insecure and the IETF has removed it in [OAuth 2.1](https://oauth.net/2.1/).
It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/288516) for use in GitLab 14.0, and is planned for
[removal](https://gitlab.com/gitlab-org/gitlab/-/issues/344609) in GitLab 15.0.
We recommend that you use [Authorization code with PKCE](#authorization-code-with-proof-key-for-code-exchange-pkce)
instead.
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, 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:
```plaintext
https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=token&state=YOUR_UNIQUE_STATE_HASH&scope=REQUESTED_SCOPES
```
This prompts the user to approve the applications access to their account
based on the scopes specified in `REQUESTED_SCOPES` and then redirect back to
the `REDIRECT_URI` you provided. The [scope parameter](../integration/oauth_provider.md#authorized-applications)
is a space-separated list of scopes you want to have access to (for example, `scope=read_user+profile`
would request `read_user` and `profile` scopes). The redirect
includes a fragment with `access_token` as well as token details in GET
parameters, for example:
```plaintext
https://example.com/oauth/redirect#access_token=ABCDExyz123&state=YOUR_UNIQUE_STATE_HASH&token_type=bearer&expires_in=3600
```
## Access GitLab API with `access token`
The `access token` allows you to make requests to the API on behalf of a user.
......
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