From f07b165ab7b0834eadbe05da81fc167dcc23d59d Mon Sep 17 00:00:00 2001 From: Valery Sizov Date: Mon, 12 Jan 2015 15:30:34 -0800 Subject: OAuth API documentation update --- doc/api/oauth2.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 doc/api/oauth2.md (limited to 'doc/api/oauth2.md') 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 -- cgit v1.2.1 From ad6c372eeee5d112ad199dd4e487df584976445d Mon Sep 17 00:00:00 2001 From: Ewan Edwards Date: Tue, 3 Feb 2015 15:18:40 -0800 Subject: Fix a number of discovered typos, capitalization of developer and product names, plus a couple of instances of bad Markdown markup. --- doc/api/oauth2.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/api/oauth2.md') diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index b2dbba9bdeb..7bb391054ce 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -4,7 +4,7 @@ OAuth2 is a protocol that enables us to get access to private details of user's 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) +This functionality is based on [doorkeeper gem](https://github.com/doorkeeper-gem/doorkeeper) ## Web Application Flow @@ -15,7 +15,7 @@ This flow consists from 3 steps. ### 1. Registering the client -Creat an application in user's account profile. +Create an application in user's account profile. ### 2. Requesting authorization @@ -96,4 +96,4 @@ 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 +``` -- cgit v1.2.1 From 10e4e2110c388ac43f1ebf437b963f13a1882129 Mon Sep 17 00:00:00 2001 From: Sytse Sijbrandij Date: Wed, 18 Feb 2015 20:49:19 -0800 Subject: Improve the explanation and linking of the Oauth docs. --- doc/api/oauth2.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'doc/api/oauth2.md') diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index 7bb391054ce..d416a826f79 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -1,14 +1,17 @@ -# OAuth2 authentication +# GitLab as an OAuth2 client -OAuth2 is a protocol that enables us to get access to private details of user's account without getting its password. +This document is about using other OAuth authentication service providers to sign into GitLab. +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). -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. +OAuth2 is a protocol that enables us to authenticate a user without requiring them to give their password. + +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. This functionality 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. +This flow is using for authentication from third-party web sites and is probably used the most. 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. -- cgit v1.2.1