PageRenderTime 41ms CodeModel.GetById 15ms RepoModel.GetById 0ms app.codeStats 0ms

/doc/api/oauth2.md

http://github.com/gitlabhq/gitlabhq
Markdown | 254 lines | 189 code | 65 blank | 0 comment | 0 complexity | 45c792a94812c6da120b3dfad4bb10cb MD5 | raw file
Possible License(s): CC-BY-SA-4.0, Apache-2.0, CC-BY-3.0, CC0-1.0, JSON
  1. # GitLab as an OAuth2 provider
  2. This document covers using the [OAuth2](https://oauth.net/2/) protocol to allow
  3. other services to access GitLab resources on user's behalf.
  4. If you want GitLab to be an OAuth authentication service provider to sign into
  5. other services, see the [OAuth2 authentication service provider](../integration/oauth_provider.md)
  6. documentation. This functionality is based on the
  7. [doorkeeper Ruby gem](https://github.com/doorkeeper-gem/doorkeeper).
  8. ## Supported OAuth2 flows
  9. GitLab currently supports the following authorization flows:
  10. - **Web application flow:** Most secure and common type of flow, designed for
  11. applications with secure server-side.
  12. - **Implicit grant flow:** This flow is designed for user-agent only apps (e.g., single
  13. page web application running on GitLab Pages).
  14. - **Resource owner password credentials flow:** To be used **only** for securely
  15. hosted, first-party services.
  16. Refer to the [OAuth RFC](https://tools.ietf.org/html/rfc6749) to find out
  17. how all those flows work and pick the right one for your use case.
  18. Both **web application** and **implicit grant** flows require `application` to be
  19. registered first via the `/profile/applications` page in your user's account.
  20. During registration, by enabling proper scopes, you can limit the range of
  21. resources which the `application` can access. Upon creation, you'll obtain the
  22. `application` credentials: _Application ID_ and _Client Secret_ - **keep them secure**.
  23. CAUTION: **Important:**
  24. OAuth specification advises sending the `state` parameter with each request to
  25. `/oauth/authorize`. We highly recommended sending a unique value with each request
  26. and validate it against the one in the redirect request. This is important in
  27. order to prevent [CSRF attacks](https://wiki.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)).
  28. The `state` parameter really should have been a requirement in the standard!
  29. In the following sections you will find detailed instructions on how to obtain
  30. authorization with each flow.
  31. ### Web application flow
  32. NOTE: **Note:**
  33. Check the [RFC spec](https://tools.ietf.org/html/rfc6749#section-4.1) for a
  34. detailed flow description.
  35. The web application flow is:
  36. 1. Request authorization code. To do that, you should redirect the user to the
  37. `/oauth/authorize` endpoint with the following GET parameters:
  38. ```plaintext
  39. https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=YOUR_UNIQUE_STATE_HASH&scope=REQUESTED_SCOPES
  40. ```
  41. This will ask the user to approve the applications access to their account
  42. based on the scopes specified in `REQUESTED_SCOPES` and then redirect back to
  43. the `REDIRECT_URI` you provided. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes)
  44. is a space separated list of scopes you want to have access to (e.g. `scope=read_user+profile`
  45. would request `read_user` and `profile` scopes). The redirect will
  46. include the GET `code` parameter, for example:
  47. ```plaintext
  48. http://myapp.com/oauth/redirect?code=1234567890&state=YOUR_UNIQUE_STATE_HASH
  49. ```
  50. You should then use `code` to request an access token.
  51. 1. Once you have the authorization code you can request an `access_token` using the
  52. code. You can do that by using any HTTP client. In the following example,
  53. we are using Ruby's `rest-client`:
  54. ```ruby
  55. parameters = 'client_id=APP_ID&client_secret=APP_SECRET&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI'
  56. RestClient.post 'http://gitlab.example.com/oauth/token', parameters
  57. ```
  58. Example response:
  59. ```json
  60. {
  61. "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
  62. "token_type": "bearer",
  63. "expires_in": 7200,
  64. "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
  65. }
  66. ```
  67. NOTE: **Note:**
  68. The `redirect_uri` must match the `redirect_uri` used in the original
  69. authorization request.
  70. You can now make requests to the API with the access token returned.
  71. ### Implicit grant flow
  72. NOTE: **Note:**
  73. Check the [RFC spec](https://tools.ietf.org/html/rfc6749#section-4.2) for a
  74. detailed flow description.
  75. CAUTION: **Important:**
  76. Avoid using this flow for applications that store data outside of the GitLab
  77. instance. If you do, make sure to verify `application id` associated with the
  78. access token before granting access to the data
  79. (see [`/oauth/token/info`](#retrieving-the-token-information)).
  80. Unlike the web flow, the client receives an `access token` immediately as a
  81. result of the authorization request. The flow does not use the client secret
  82. or the authorization code because all of the application code and storage is
  83. easily accessible, therefore secrets can leak easily.
  84. To request the access token, you should redirect the user to the
  85. `/oauth/authorize` endpoint using `token` response type:
  86. ```plaintext
  87. 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
  88. ```
  89. This will ask the user to approve the applications access to their account
  90. based on the scopes specified in `REQUESTED_SCOPES` and then redirect back to
  91. the `REDIRECT_URI` you provided. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes)
  92. is a space separated list of scopes you want to have access to (e.g. `scope=read_user+profile`
  93. would request `read_user` and `profile` scopes). The redirect
  94. will include a fragment with `access_token` as well as token details in GET
  95. parameters, for example:
  96. ```plaintext
  97. http://myapp.com/oauth/redirect#access_token=ABCDExyz123&state=YOUR_UNIQUE_STATE_HASH&token_type=bearer&expires_in=3600
  98. ```
  99. ### Resource owner password credentials flow
  100. NOTE: **Note:**
  101. Check the [RFC spec](https://tools.ietf.org/html/rfc6749#section-4.3) for a
  102. detailed flow description.
  103. NOTE: **Note:**
  104. The Resource Owner Password Credentials is disabled for users with [two-factor
  105. authentication](../user/profile/account/two_factor_authentication.md) turned on.
  106. These users can access the API using [personal access tokens](../user/profile/personal_access_tokens.md)
  107. instead.
  108. In this flow, a token is requested in exchange for the resource owner credentials
  109. (username and password).
  110. The credentials should only be used when:
  111. - There is a high degree of trust between the resource owner and the client. For
  112. example, the client is part of the device operating system or a highly
  113. privileged application.
  114. - Other authorization grant types are not available (such as an authorization code).
  115. CAUTION: **Important:**
  116. Never store the user's credentials and only use this grant type when your client
  117. is deployed to a trusted environment, in 99% of cases
  118. [personal access tokens](../user/profile/personal_access_tokens.md) are a better
  119. choice.
  120. Even though this grant type requires direct client access to the resource owner
  121. credentials, the resource owner credentials are used for a single request and
  122. are exchanged for an access token. This grant type can eliminate the need for
  123. the client to store the resource owner credentials for future use, by exchanging
  124. the credentials with a long-lived access token or refresh token.
  125. To request an access token, you must make a POST request to `/oauth/token` with
  126. the following parameters:
  127. ```json
  128. {
  129. "grant_type" : "password",
  130. "username" : "user@example.com",
  131. "password" : "secret"
  132. }
  133. ```
  134. Example cURL request:
  135. ```shell
  136. echo 'grant_type=password&username=<your_username>&password=<your_password>' > auth.txt
  137. curl --data "@auth.txt" --request POST https://gitlab.example.com/oauth/token
  138. ```
  139. Then, you'll receive the access token back in the response:
  140. ```json
  141. {
  142. "access_token": "1f0af717251950dbd4d73154fdf0a474a5c5119adad999683f5b450c460726aa",
  143. "token_type": "bearer",
  144. "expires_in": 7200
  145. }
  146. ```
  147. For testing, you can use the `oauth2` Ruby gem:
  148. ```ruby
  149. client = OAuth2::Client.new('the_client_id', 'the_client_secret', :site => "http://example.com")
  150. access_token = client.password.get_token('user@example.com', 'secret')
  151. puts access_token.token
  152. ```
  153. ## Access GitLab API with `access token`
  154. The `access token` allows you to make requests to the API on behalf of a user.
  155. You can pass the token either as GET parameter:
  156. ```plaintext
  157. GET https://gitlab.example.com/api/v4/user?access_token=OAUTH-TOKEN
  158. ```
  159. or you can put the token to the Authorization header:
  160. ```shell
  161. curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v4/user
  162. ```
  163. ## Retrieving the token information
  164. To verify the details of a token, use the `token/info` endpoint provided by the Doorkeeper gem.
  165. For more information, see [`/oauth/token/info`](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples#get----oauthtokeninfo).
  166. You must supply the access token, either:
  167. - As a parameter:
  168. ```plaintext
  169. GET https://gitlab.example.com/oauth/token/info?access_token=<OAUTH-TOKEN>
  170. ```
  171. - In the Authorization header:
  172. ```shell
  173. curl --header "Authorization: Bearer <OAUTH-TOKEN>" https://gitlab.example.com/oauth/token/info
  174. ```
  175. The following is an example response:
  176. ```json
  177. {
  178. "resource_owner_id": 1,
  179. "scope": ["api"],
  180. "expires_in": null,
  181. "application": {"uid": "1cb242f495280beb4291e64bee2a17f330902e499882fe8e1e2aa875519cab33"},
  182. "created_at": 1575890427
  183. }
  184. ```
  185. ### Deprecated fields
  186. The fields `scopes` and `expires_in_seconds` are included in the response.
  187. These are aliases for `scope` and `expires_in` respectively, and have been included to
  188. prevent breaking changes introduced in [doorkeeper 5.0.2](https://github.com/doorkeeper-gem/doorkeeper/wiki/Migration-from-old-versions#from-4x-to-5x).
  189. Don't rely on these fields as they will be removed in a later release.