This document covers using the [OAuth2](https://oauth.net/2/) protocol to allow other services access GitLab resources on user's behalf.
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](../integration/oauth_provider.md)
documentation.
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
GitLab currently supports following authorization flows:
GitLab currently supports following authorization flows:
**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.
-*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.
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.
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
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**.
>**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
>**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!
In the following sections you will find detailed instructions on how to obtain authorization with each flow.
In the following sections you will find detailed instructions on how to obtain authorization with each flow.
### Web Application Flow
### Web Application Flow
Check [RFC spec](http://tools.ietf.org/html/rfc6749#section-4.1) for a detailed flow description
...
...
@@ -48,7 +48,7 @@ You should then use the `code` to request an access token.
#### 2. Requesting 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,
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`:
```
...
...
@@ -73,13 +73,13 @@ You can now make requests to the API with the access token returned.
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.
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)).
>**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
...
...
@@ -89,7 +89,7 @@ To request the access token, you should redirect the user to the `/oauth/authori
Check [RFC spec](http://tools.ietf.org/html/rfc6749#section-4.3) for a detailed flow description.
> **Deprecation notice:** Starting in GitLab 8.11, the Resource Owner Password Credentials has been *disabled* for users with two-factor authentication
> **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).
...
...
@@ -109,7 +109,7 @@ 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]
Never store the user's 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
...
...
@@ -148,7 +148,7 @@ 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
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
