diff options
Diffstat (limited to 'doc/api/oauth2.md')
-rw-r--r-- | doc/api/oauth2.md | 48 |
1 files changed, 24 insertions, 24 deletions
diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index 8a1e6b52092..6786c0c5b5c 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -1,33 +1,33 @@ # GitLab as an OAuth2 provider -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 https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=token&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 +This will ask the user to approve the application's access to their account and then redirect back to the `REDIRECT_URI` you provided. The redirect will include a fragment with `access_token` as well as token details in GET parameters, for example: ``` @@ -100,7 +100,7 @@ http://myapp.com/oauth/redirect#access_token=ABCDExyz123&state=YOUR_UNIQUE_STATE 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 ``` @@ -160,4 +160,4 @@ curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api ``` [personal access tokens]: ../user/profile/personal_access_tokens.md -[CSRF attacks]: http://www.oauthsecurity.com/#user-content-authorization-code-flow
\ No newline at end of file +[CSRF attacks]: http://www.oauthsecurity.com/#user-content-authorization-code-flow |