#20628 Enable implicit flow in Gitlab as OAuth Provider
Closes #20628 by re-enabling implicit grant in Doorkeeper config. OAuth2 documentation refactored.
This commit is contained in:
parent
bf0b3d8352
commit
a7c571ae4d
|
@ -0,0 +1,4 @@
|
|||
---
|
||||
title: "#20628 Enable implicit grant in GitLab as OAuth Provider"
|
||||
merge_request: 12384
|
||||
author: Mateusz Pytel
|
|
@ -87,9 +87,7 @@ Doorkeeper.configure do
|
|||
# "password" => Resource Owner Password Credentials Grant Flow
|
||||
# "client_credentials" => Client Credentials Grant Flow
|
||||
#
|
||||
# If not specified, Doorkeeper enables all the four grant flows.
|
||||
#
|
||||
grant_flows %w(authorization_code password client_credentials)
|
||||
grant_flows %w(authorization_code implicit password client_credentials)
|
||||
|
||||
# Under some circumstances you might want to have applications auto-approved,
|
||||
# so that the user skips the authorization step.
|
||||
|
|
|
@ -1,59 +1,55 @@
|
|||
# GitLab as an OAuth2 provider
|
||||
|
||||
This document covers using the OAuth2 protocol to access GitLab.
|
||||
This document covers using the [OAuth2](https://oauth.net/2/) protocol to allow other services access Gitlab resources on user's behalf.
|
||||
|
||||
If you want GitLab to be an OAuth authentication service provider to sign into other services please see the [Oauth2 provider documentation](../integration/oauth_provider.md).
|
||||
If you want GitLab to be an OAuth authentication service provider to sign into other services please see the [OAuth2 provider](../integration/oauth_provider.md)
|
||||
documentation.
|
||||
|
||||
OAuth2 is a protocol that enables us to authenticate a user without requiring them to give their password to a third-party.
|
||||
This functionality is based on [doorkeeper gem](https://github.com/doorkeeper-gem/doorkeeper).
|
||||
|
||||
This functionality is based on [doorkeeper gem](https://github.com/doorkeeper-gem/doorkeeper)
|
||||
## Supported OAuth2 Flows
|
||||
|
||||
## Web Application Flow
|
||||
Gitlab currently supports following authorization flows:
|
||||
|
||||
This is the most common type of flow and is used by server-side clients that wish to access GitLab on a user's behalf.
|
||||
* *Web Application Flow* - Most secure and common type of flow, designed for the applications with secure server-side.
|
||||
* *Implicit Flow* - This flow is designed for user-agent only apps (e.g. single page web application running on GitLab Pages).
|
||||
* *Resource Owner Password Credentials Flow* - To be used **only** for securely hosted, first-party services.
|
||||
|
||||
>**Note:**
|
||||
This flow **should not** be used for client-side clients as you would leak your `client_secret`. Client-side clients should use the Implicit Grant (which is currently unsupported).
|
||||
Please refer to [OAuth RFC](https://tools.ietf.org/html/rfc6749) to find out in details how all those flows work and pick the right one for your use case.
|
||||
|
||||
For more detailed information, check out the [RFC spec](http://tools.ietf.org/html/rfc6749#section-4.1)
|
||||
Both *web application* and *implicit* flows require `application` to be registered first via `/profile/applications` page
|
||||
in your user's account. During registration, by enabling proper scopes you can limit the range of resources which the `application` can access. Upon creation
|
||||
you'll obtain `application` credentials: _Application ID_ and _Client Secret_ - **keep them secure**.
|
||||
|
||||
In the following sections you will be introduced to the three steps needed for this flow.
|
||||
>**Important:** OAuth specification advises sending `state` parameter with each request to `/oauth/authorize`. We highly recommended to send a unique
|
||||
value with each request and validate it against the one in redirect request. This is important to prevent [CSRF attacks]. The `state` param really should
|
||||
have been a requirement in the standard!
|
||||
|
||||
### 1. Registering the client
|
||||
In the following sections you will find detailed instructions on how to obtain authorization with each flow.
|
||||
|
||||
First, you should create an application (`/profile/applications`) in your user's account.
|
||||
Each application gets a unique App ID and App Secret parameters.
|
||||
### Web Application Flow
|
||||
|
||||
>**Note:**
|
||||
**You should not share/leak your App ID or App Secret.**
|
||||
Check [RFC spec](http://tools.ietf.org/html/rfc6749#section-4.1) for a detailed flow description
|
||||
|
||||
### 2. Requesting authorization
|
||||
#### 1. Requesting authorization code
|
||||
|
||||
To request the authorization code, you should redirect the user to the `/oauth/authorize` endpoint:
|
||||
To request the authorization code, you should redirect the user to the `/oauth/authorize` endpoint with following GET parameters:
|
||||
|
||||
```
|
||||
https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=your_unique_state_hash
|
||||
https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=YOUR_UNIQUE_STATE_HASH
|
||||
```
|
||||
|
||||
This will ask the user to approve the applications access to their account and then redirect back to the `REDIRECT_URI` you provided.
|
||||
This will ask the user to approve the applications access to their account and then redirect back to the `REDIRECT_URI` you provided. The redirect will
|
||||
include the GET `code` parameter, for example:
|
||||
|
||||
The redirect will include the GET `code` parameter, for example:
|
||||
|
||||
```
|
||||
http://myapp.com/oauth/redirect?code=1234567890&state=your_unique_state_hash
|
||||
```
|
||||
`http://myapp.com/oauth/redirect?code=1234567890&state=YOUR_UNIQUE_STATE_HASH`
|
||||
|
||||
You should then use the `code` to request an access token.
|
||||
|
||||
>**Important:**
|
||||
It is highly recommended that you send a `state` value with the request to `/oauth/authorize` and
|
||||
validate that value is returned and matches in the redirect request.
|
||||
This is important to prevent [CSRF attacks](http://www.oauthsecurity.com/#user-content-authorization-code-flow),
|
||||
`state` really should have been a requirement in the standard!
|
||||
#### 2. Requesting access token
|
||||
|
||||
### 3. Requesting the access token
|
||||
|
||||
Once you have the authorization code you can request an `access_token` using the code, to do that you can use any HTTP client. In the following example, we are using Ruby's `rest-client`:
|
||||
Once you have the authorization code you can request an `access_token` using the code, to do that you can use any HTTP client. In the following example,
|
||||
we are using Ruby's `rest-client`:
|
||||
|
||||
```
|
||||
parameters = 'client_id=APP_ID&client_secret=APP_SECRET&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI'
|
||||
|
@ -72,28 +68,40 @@ The `redirect_uri` must match the `redirect_uri` used in the original authorizat
|
|||
|
||||
You can now make requests to the API with the access token returned.
|
||||
|
||||
### Use the access token to access the API
|
||||
|
||||
The access token allows you to make requests to the API on a behalf of a user.
|
||||
### Implicit Grant
|
||||
|
||||
Check [RFC spec](http://tools.ietf.org/html/rfc6749#section-4.2) for a detailed flow description.
|
||||
|
||||
Unlike the web flow, the client receives an `access token` immediately as a result of the authorization request. The flow does not use client secret
|
||||
or authorization code because all of the application code and storage is easily accessible, therefore __secrets__ can leak easily.
|
||||
|
||||
>**Important:** Avoid using this flow for applications that store data outside of the Gitlab instance. If you do, make sure to verify `application id`
|
||||
associated with access token before granting access to the data
|
||||
(see [/oauth/token/info](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples#get----oauthtokeninfo)).
|
||||
|
||||
|
||||
#### 1. Requesting access token
|
||||
|
||||
To request the access token, you should redirect the user to the `/oauth/authorize` endpoint using `token` response type:
|
||||
|
||||
```
|
||||
GET https://gitlab.example.com/api/v4/user?access_token=OAUTH-TOKEN
|
||||
https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=token&state=YOUR_UNIQUE_STATE_HASH
|
||||
```
|
||||
|
||||
Or you can put the token to the Authorization header:
|
||||
This will ask the user to approve the applications access to their account and then redirect back to the `REDIRECT_URI` you provided. The redirect
|
||||
will include a fragment with `access_token` as well as token details in GET parameters, for example:
|
||||
|
||||
```
|
||||
curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v4/user
|
||||
http://myapp.com/oauth/redirect#access_token=ABCDExyz123&state=YOUR_UNIQUE_STATE_HASH&token_type=bearer&expires_in=3600
|
||||
```
|
||||
|
||||
## Resource Owner Password Credentials
|
||||
### Resource Owner Password Credentials
|
||||
|
||||
## Deprecation Notice
|
||||
Check [RFC spec](http://tools.ietf.org/html/rfc6749#section-4.3) for a detailed flow description.
|
||||
|
||||
1. Starting in GitLab 8.11, the Resource Owner Password Credentials has been *disabled* for users with two-factor authentication turned on.
|
||||
2. These users can access the API using [personal access tokens] instead.
|
||||
|
||||
---
|
||||
> **Deprecation notice:** Starting in GitLab 8.11, the Resource Owner Password Credentials has been *disabled* for users with two-factor authentication
|
||||
turned on. These users can access the API using [personal access tokens] instead.
|
||||
|
||||
In this flow, a token is requested in exchange for the resource owner credentials (username and password).
|
||||
The credentials should only be used when there is a high degree of trust between the resource owner and the client (e.g. the
|
||||
|
@ -101,12 +109,16 @@ client is part of the device operating system or a highly privileged application
|
|||
available (such as an authorization code).
|
||||
|
||||
>**Important:**
|
||||
Never store the users credentials and only use this grant type when your client is deployed to a trusted environment, in 99% of cases [personal access tokens] are a better choice.
|
||||
Never store the users credentials and only use this grant type when your client is deployed to a trusted environment, in 99% of cases [personal access tokens]
|
||||
are a better choice.
|
||||
|
||||
Even though this grant type requires direct client access to the resource owner credentials, the resource owner credentials are used
|
||||
for a single request and are exchanged for an access token. This grant type can eliminate the need for the client to store the
|
||||
resource owner credentials for future use, by exchanging the credentials with a long-lived access token or refresh token.
|
||||
You can do POST request to `/oauth/token` with parameters:
|
||||
|
||||
#### 1. Requesting access token
|
||||
|
||||
POST request to `/oauth/token` with parameters:
|
||||
|
||||
```
|
||||
{
|
||||
|
@ -134,4 +146,18 @@ access_token = client.password.get_token('user@example.com', 'secret')
|
|||
puts access_token.token
|
||||
```
|
||||
|
||||
## Access Gitlab API with `access token`
|
||||
|
||||
The `access token` allows you to make requests to the API on a behalf of a user. You can pass the token either as GET parameter
|
||||
```
|
||||
GET https://gitlab.example.com/api/v4/user?access_token=OAUTH-TOKEN
|
||||
```
|
||||
|
||||
or you can put the token to the Authorization header:
|
||||
|
||||
```
|
||||
curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v4/user
|
||||
```
|
||||
|
||||
[personal access tokens]: ../user/profile/personal_access_tokens.md
|
||||
[CSRF attacks]: http://www.oauthsecurity.com/#user-content-authorization-code-flow
|
Loading…
Reference in New Issue