BigW Consortium Gitlab

oauth2.md 5.31 KB
Newer Older
1
# GitLab as an OAuth2 provider
2

3
This document covers using the OAuth2 protocol to access GitLab.
4

5
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).
6

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

9
This functionality is based on [doorkeeper gem](https://github.com/doorkeeper-gem/doorkeeper)
10 11 12

## Web Application Flow

13 14 15 16
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.

>**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).
17

18 19 20
For more detailed information, check out the [RFC spec](http://tools.ietf.org/html/rfc6749#section-4.1)

In the following sections you will be introduced to the three steps needed for this flow.
21 22 23

### 1. Registering the client

24
First, you should create an application (`/profile/applications`) in your user's account.
25
Each application gets a unique App ID and App Secret parameters.
26 27 28

>**Note:**
**You should not share/leak your App ID or App Secret.**
29 30 31

### 2. Requesting authorization

32 33 34 35 36 37 38 39 40
To request the authorization code, you should redirect the user to the `/oauth/authorize` endpoint:

```
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.

The redirect will include the GET `code` parameter, for example:
41 42

```
43
http://myapp.com/oauth/redirect?code=1234567890&state=your_unique_state_hash
44 45
```

46 47 48
You should then use the `code` to request an access token.

>**Important:**
49 50
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.
51
This is important to prevent [CSRF attacks](http://www.oauthsecurity.com/#user-content-authorization-code-flow),
52
`state` really should have been a requirement in the standard!
53 54 55

### 3. Requesting the access token

56
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`:
57 58

```
59
parameters = 'client_id=APP_ID&client_secret=APP_SECRET&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI'
60
RestClient.post 'http://gitlab.example.com/oauth/token', parameters
61 62 63 64

# The response will be
{
 "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
65
 "token_type": "bearer",
66 67 68 69
 "expires_in": 7200,
 "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
}
```
70 71
>**Note:**
The `redirect_uri` must match the `redirect_uri` used in the original authorization request.
72 73 74 75 76 77 78 79

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.

```
80
GET https://gitlab.example.com/api/v4/user?access_token=OAUTH-TOKEN
81 82 83 84 85
```

Or you can put the token to the Authorization header:

```
86
curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v4/user
87 88 89 90
```

## Resource Owner Password Credentials

91 92
## Deprecation Notice

93
1. Starting in GitLab 8.11, the Resource Owner Password Credentials has been *disabled* for users with two-factor authentication turned on.
94 95 96 97
2. These users can access the API using [personal access tokens] instead.

---

98
In this flow, a token is requested in exchange for the resource owner credentials (username and password).
99 100 101 102
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).

103 104 105
>**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.

106 107 108 109 110 111 112 113 114
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",
115
  "password"      : "secret"
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
}
```

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")
133
access_token = client.password.get_token('user@example.com', 'secret')
134
puts access_token.token
135
```
136

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