PageRenderTime 31ms CodeModel.GetById 24ms RepoModel.GetById 1ms app.codeStats 0ms

/doc/api/oauth2.md

https://gitlab.com/muhonglong/gitlab-ce
Markdown | 102 lines | 71 code | 31 blank | 0 comment | 0 complexity | 5b338652e1a2730fd6afbd6ca22d7dac MD5 | raw file
Possible License(s): CC-BY-3.0
  1. # GitLab as an OAuth2 client
  2. This document is about using other OAuth authentication service providers to sign into GitLab.
  3. 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).
  4. OAuth2 is a protocol that enables us to authenticate a user without requiring them to give their password.
  5. 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.
  6. This functionality is based on [doorkeeper gem](https://github.com/doorkeeper-gem/doorkeeper)
  7. ## Web Application Flow
  8. This flow is using for authentication from third-party web sites and is probably used the most.
  9. 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)
  10. This flow consists from 3 steps.
  11. ### 1. Registering the client
  12. Create an application in user's account profile.
  13. ### 2. Requesting authorization
  14. To request the authorization token, you should visit the `/oauth/authorize` endpoint. You can do that by visiting manually the URL:
  15. ```
  16. http://localhost:3000/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code
  17. ```
  18. Where REDIRECT_URI is the URL in your app where users will be sent after authorization.
  19. ### 3. Requesting the access token
  20. 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:
  21. ```
  22. parameters = 'client_id=APP_ID&client_secret=APP_SECRET&code=RETURNED_CODE&grant_type=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI'
  23. RestClient.post 'http://localhost:3000/oauth/token', parameters
  24. # The response will be
  25. {
  26. "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
  27. "token_type": "bearer",
  28. "expires_in": 7200,
  29. "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
  30. }
  31. ```
  32. You can now make requests to the API with the access token returned.
  33. ### Use the access token to access the API
  34. The access token allows you to make requests to the API on a behalf of a user.
  35. ```
  36. GET https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN
  37. ```
  38. Or you can put the token to the Authorization header:
  39. ```
  40. curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/api/v3/user
  41. ```
  42. ## Resource Owner Password Credentials
  43. In this flow, a token is requested in exchange for the resource owner credentials (username and password).
  44. The credentials should only be used when there is a high degree of trust between the resource owner and the client (e.g. the
  45. client is part of the device operating system or a highly privileged application), and when other authorization grant types are not
  46. available (such as an authorization code).
  47. Even though this grant type requires direct client access to the resource owner credentials, the resource owner credentials are used
  48. for a single request and are exchanged for an access token. This grant type can eliminate the need for the client to store the
  49. resource owner credentials for future use, by exchanging the credentials with a long-lived access token or refresh token.
  50. You can do POST request to `/oauth/token` with parameters:
  51. ```
  52. {
  53. "grant_type" : "password",
  54. "username" : "user@example.com",
  55. "password" : "sekret"
  56. }
  57. ```
  58. Then, you'll receive the access token back in the response:
  59. ```
  60. {
  61. "access_token": "1f0af717251950dbd4d73154fdf0a474a5c5119adad999683f5b450c460726aa",
  62. "token_type": "bearer",
  63. "expires_in": 7200
  64. }
  65. ```
  66. For testing you can use the oauth2 ruby gem:
  67. ```
  68. client = OAuth2::Client.new('the_client_id', 'the_client_secret', :site => "http://example.com")
  69. access_token = client.password.get_token('user@example.com', 'sekret')
  70. puts access_token.token
  71. ```