OAuth API documentation update

2 files changed, 117 insertions, 0 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
index ffe250df3ff..8f919f5257d 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -51,6 +51,24 @@ curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/p
 
 The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL.
 
+## Authentication with OAuth2 token
+
+Instead of the private_token you can transmit the OAuth2 access token as a header or as a parameter.
+
+### OAuth2 token (as a parameter)
+
+```
+curl https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN
+```
+
+###  OAuth2 token (as a header)
+
+```
+curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/api/v3/user
+```
+
+Read more about [OAuth2 in GitLab](oauth2.md).
+
 ## Status codes
 
 The API is designed to return different status codes according to context and action. In this way if a request results in an error the caller is able to get insight into what went wrong, e.g. status code `400 Bad Request` is returned if a required attribute is missing from the request. The following list gives an overview of how the API functions generally behave.
diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md
new file mode 100644
index 00000000000..b2dbba9bdeb
--- /dev/null
+++ b/doc/api/oauth2.md
@@ -0,0 +1,99 @@
+# OAuth2 authentication
+
+OAuth2 is a protocol that enables us to get access to private details of user's account without getting its password. 
+
+Before using the OAuth2 you should create an application in user's account. Each application getting unique App ID and App Secret parameters. You should not share them.
+
+This functianolity is based on [doorkeeper gem](https://github.com/doorkeeper-gem/doorkeeper)
+
+## Web Application Flow
+
+This flow is using for authentication from third-party web sites and probably is most used. 
+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
+
+Creat an application in user's account profile.
+
+### 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
+
+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
+```
\ No newline at end of file