diff options
author | Valery Sizov <valery@gitlab.com> | 2015-01-13 02:30:34 +0300 |
---|---|---|
committer | Valery Sizov <valery@gitlab.com> | 2015-01-13 06:29:06 +0300 |
commit | f07b165ab7b0834eadbe05da81fc167dcc23d59d (patch) | |
tree | 4f058527c976dfc9512d70dc62c3f986912980ab /doc/api | |
parent | 1c6a1253899219b84cc9cb8b090a3bfbbd19605e (diff) |
OAuth API documentation update
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/README.md | 18 | ||||
-rw-r--r-- | doc/api/oauth2.md | 99 |
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 |