oauth2.md 4.2 KB
Newer Older
1
# GitLab as an OAuth2 client
Valery Sizov's avatar
Valery Sizov committed
2

3 4
This document is about using other OAuth authentication service providers to sign into GitLab.
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).
Valery Sizov's avatar
Valery Sizov committed
5

6 7 8
OAuth2 is a protocol that enables us to authenticate a user without requiring them to give their password. 

Before using the OAuth2 you should create an application in user's account. Each application gets a unique App ID and App Secret parameters. You should not share these.
Valery Sizov's avatar
Valery Sizov committed
9

10
This functionality is based on [doorkeeper gem](https://github.com/doorkeeper-gem/doorkeeper)
Valery Sizov's avatar
Valery Sizov committed
11 12 13

## Web Application Flow

14
This flow is using for authentication from third-party web sites and is probably used the most. 
Valery Sizov's avatar
Valery Sizov committed
15 16 17 18 19 20
It basically consists of an exchange of an authorization token for an access token. For more detailed info, check out the [RFC spec here](http://tools.ietf.org/html/rfc6749#section-4.1)

This flow consists from 3 steps.

### 1. Registering the client

21
Create an application in user's account profile.
Valery Sizov's avatar
Valery Sizov committed
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67

### 2. Requesting authorization

To request the authorization token, you should visit the `/oauth/authorize` endpoint. You can do that by visiting manually the URL:

```
http://localhost:3000/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code
```

Where REDIRECT_URI is the URL in your app where users will be sent after authorization. 	

### 3. Requesting the access token

To request the access token, you should use the returned code and exchange it for an access token. To do that you can use any HTTP client. In this case, I used rest-client:

```
parameters = 'client_id=APP_ID&client_secret=APP_SECRET&code=RETURNED_CODE&grant_type=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI'
RestClient.post 'http://localhost:3000/oauth/token', parameters

# The response will be
{
 "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
 "token_type": "bearer", 
 "expires_in": 7200,
 "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
}
```

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.

```
GET https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN
```

Or you can put the token to the Authorization header:

```
curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/api/v3/user
```

## Resource Owner Password Credentials

68 69 70 71 72 73 74
## Deprecation Notice

1. Starting in GitLab 9.0, the Resource Owner Password Credentials will be *disabled* for users with two-factor authentication turned on.
2. These users can access the API using [personal access tokens] instead.

---

Valery Sizov's avatar
Valery Sizov committed
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
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
client is part of the device operating system or a highly privileged application), and when other authorization grant types are not
available (such as an authorization code).

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:

```
{
  "grant_type"    : "password",
  "username"      : "user@example.com",
  "password"      : "sekret"
}
```

Then, you'll receive the access token back in the response:

```
{
  "access_token": "1f0af717251950dbd4d73154fdf0a474a5c5119adad999683f5b450c460726aa",
  "token_type": "bearer",
  "expires_in": 7200
}
```

For testing you can use the oauth2 ruby gem:

```
client = OAuth2::Client.new('the_client_id', 'the_client_secret', :site => "http://example.com")
access_token = client.password.get_token('user@example.com', 'sekret')
puts access_token.token
109
```
110 111

[personal access tokens]: ./README.md#personal-access-tokens