Commit be9f5589 authored by Dmitriy Zaporozhets's avatar Dmitriy Zaporozhets

Merge branch 'oauth_api_doc' into 'master'

OAuth2 API documentation

https://dev.gitlab.org/gitlab/gitlabhq/issues/1713

See merge request !1388
parents 1e37e892 f07b165a
......@@ -10,6 +10,11 @@ Doorkeeper.configure do
current_user || redirect_to(new_user_session_url)
end
resource_owner_from_credentials do |routes|
u = User.find_by(email: params[:username])
u if u && u.valid_password?(params[:password])
end
# If you want to restrict access to the web interface for adding oauth authorized applications, you need to declare the block below.
# admin_authenticator do
# # Put your admin authentication logic here.
......
......@@ -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.
......
# 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
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment