OAuth 2 Grant Types Reference

This document has been extracted from what I wrote in 2015 for my previous work. The URLs have been replaced with the fake ones.

Assumptions

• The example client I used is: testclient / clientpass, the redirection URL is http://client.com/callback
• The example user I used is: testuser / userpass
• In the examples below, the last step is to use access_token to access a protected resource page. This is for demo purpose only.

Client Credentials Grant

Get access token:

Request (both methods work):

curl -i -X POST -H 'ContentType: x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=testclient&client_secret=clientpass' 'https://example.com/oauth/token.php'
curl -i -XPOST -u testclient:clientpass https://example.com/oauth/token.php -d 'grant_type=client_credentials'

Response:

{
  "access_token": "fee7e1d4247e1e561757983e9014862e4ffae690",
  "expires_in": 36000,
  "token_type": "bearer",
  "scope": null,
  "user_id": null
}

Access resource with token (all three methods work):

curl -i -X GET -H "Authorization: Bearer fee7e1d4247e1e561757983e9014862e4ffae690" 'https://example.com/oauth/resource.php'
curl -i -X POST -H "Authorization: Bearer fee7e1d4247e1e561757983e9014862e4ffae690" 'https://example.com/oauth/resource.php'
curl -i -X POST -d 'access_token=fee7e1d4247e1e561757983e9014862e4ffae690' 'https://example.com/oauth/resource.php'

User Credential (Password) Grant

Get access token:

Request:

curl -i -X POST -H 'ContentType: x-www-form-urlencoded' -d 'grant_type=password&client_id=testclient&client_secret=clientpass&username=testuser&password=userpass' 'https://example.com/oauth/token.php'

Response:

{
  "access_token": "060971b599a52e364da62f7788e970acee2da892",
  "expires_in": 36000,
  "token_type": "bearer",
  "scope": null,
  "refresh_token": "150c542e33feef4721a5b4adaafcf3c79d488e09",
  "user_id": "123456"
}

Access resource with the token:

curl -i -X POST -H "Authorization: Bearer 060971b599a52e364da62f7788e970acee2da892" 'https://example.com/oauth/resource.php'

Authorization Code (OAuth 3-leg dance) Grant

Redirect customer to the authorisation page (tip: try with incognito window):

https://example.com/oauth/authorize.php?response_type=code&client_id=testclient&state=xyz

NOTE:

1. state is an optional parameter -- but we recommend you to pass a random hash, which will be returned as is -- this is useful to resist CSRF attack
2. If there are more than one redirect URLs stored in client configuration (e.g. one for test, one for production), The redirect_uri becomes a compulsory parameter in the request:
   https://example.com/oauth/authorize.php?response_type=code&client_id=testclient&state=xyz&redirect_uri=http://client.com/callback

If customer approves, he will be redirected back to:

http://client.com/callback/?code=342248f1f8251fae69554f311fc381d3e3d1b095&state=xyz

http://client.com/callback is the redirect_url we set up for this fake client. Note https should always be used in real world.

Now you can exchange the access token with the code (the code expires in 30 seconds, so be quick!):

Request:

curl -i -X POST -H 'ContentType: x-www-form-urlencoded' -d 'grant_type=authorization_code&client_id=testclient&client_secret=clientpass&code=342248f1f8251fae69554f311fc381d3e3d1b095' 'https://example.com/oauth/token.php'

Response:

{
  "access_token": "971541d4c1f3313fda20570b75fae46503ba6210",
  "expires_in": 36000,
  "token_type": "bearer",
  "scope": null,
  "refresh_token": "6b51a5bd49b8b60a4ed5e3845952676dbe1ba8c6",
  "user_id": "123456"
}

Access resource with the token:

curl -i -X POST -d 'access_token=971541d4c1f3313fda20570b75fae46503ba6210' 'https://example.com/oauth/resource.php'

The implicit way

Redirect customer to the authentication page (tip: try with incognito window), note the different response_type:

https://example.com/oauth/authorize.php?response_type=token&client_id=testclient&state=xyz

If customer approves, he will be redirected back to:

http://client.com/callback/#access_token=6212a762a61e1760ad5e79e6ae3367bf95b3e460&expires_in=36000&token_type=bearer&user_id=183249&state=xyz

Now you get access_token directly, access resource with the token:

curl -i -X POST -d 'access_token=6212a762a61e1760ad5e79e6ae3367bf95b3e460' 'https://example.com/oauth/resource.php'

Refresh Token Grant

Request:

curl -i -X POST -H 'ContentType: x-www-form-urlencoded' -d 'grant_type=refresh_token&client_id=testclient&client_secret=clientpass&refresh_token=6b51a5bd49b8b60a4ed5e3845952676dbe1ba8c6' 'https://example.com/oauth/token.php'

Response:

{
  "access_token": "d148ebfa80d53eb58279b2d38e2c6ca180adad19",
  "expires_in": 36000,
  "token_type": "bearer",
  "scope": null,
  "refresh_token": "d2006a1f10701451d92610057e246fdcc9d67bd8",
  "user_id": "183249"
}

Access resource with the token:

curl -i -X POST -d 'access_token=d148ebfa80d53eb58279b2d38e2c6ca180adad19' 'https://example.com/oauth/resource.php'