What is OAuth 2.0?

OAuth 2.0 is the next evolution of the OAuth protocol which was originally created in late 2006.

What OAuth 2.0 focuses on

• Client developer simplicity
• Specific authorization flows for:
  • web applications
  • desktop applications
  • mobile phones
  • living room devices

Authentication

Browser-based or mobile applications

Authentication is accomplished by displaying an interface provided by the service to the user

Authorize access to the information (scopes)

Scopes let the user authorize or deny access to specific information. Some implementation let the user chose which information he wishes to share (facebook, for example).

Other applications

Authentication can be accomplished using client credentials, or username and password

Grant types

Default grant types

• Authorization Code for apps running on a web server
• Implicit for browser-based or mobile apps
• Password for logging in with a username and password
• Client credentials for application access
• Refresh token for simplifying user re-authentication

Authorization Code workflow

(3-legged authorization flow)

Schema

Redirection to the provider

• response_type (mandatory)
• client_id (mandatory)
• scope (mandatory)
• redirect_uri (mandatory)
• state (optional, think CSRF)

GET /oauth/authorize
    ?response_type=code
    &client_id=0d5e5af7-420c-4241-8cff-0cfd9d806e59
    &scope=profile%20email
    &state=48389488
    &redirect_uri=https%3A%2F%2Fwww.example.com%3A8443%2Fcallback
Host: server.example.com

Redirection to the client

HTTP/1.1 302 Found
Location: https://server2.example.com
    ?code=MF2AAQGBBlpxSGUtUYJQo2oB1p1kw3CNcM5QRmok-vzKYVltlykXrZE2AG0F3J3mQjUYOSP3dCOaIeYEUWSKm4QVx6mCTmT9gztIn45K9KKJ22p8IiJHiLXGEg2oUV
    &state=48389488

The code should be used by the client to retrieve an access token

Retrieve an access token with the code

Issue a POST request to /auth/token with the code, redirect_uri and authorization_code grant_type, using Basic authentication

POST /oauth/token HTTP/1.1
Host: server.example.com
Content-Type: application/w-www-form-urlencoded
Authorization: Basic <Base64-encoded client_id:client_secret>
grant_type=authorization_code
&code=MF2AAQGBBlpxSGUtUYJQo2oB1p1kw3CNcM5QRmok-vzKYVltlykXrZ E2AG0F3J3mQjUYOSP3dCOaIeYEUWSKnav_aXvvyuxT3ogtZT-dgNZEnk6X0XaoPf6BVlVRibA
&redirect_uri=https%3A%2F%2Fserver2%2Eexample%2Ecom

HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
Content-Type: applicaton/json;charset=UTF-8 Transfer-Encoding: chunked
Server: Jetty(8.1.12.v20130726)
{
    "access_token":"MF2AAQGBBlpxSGUtUYJQo2oB1p1kw3CNcM5QRmok-vzKYVltlykXrZE2AG0F3J3mQjUYOSP3dCOaIeYEUWSKMYeiJy-24paR9YLEZpKDc-mwlE4ML8LRqAyhPMtAoBA",
    "token_type":"bearer",
    "expires_in":41558,
    "scope":"email profile"
}

Make requests using the access token

GET /api/me HTTP/1.1
Host: server.example.com
Authorization: Bearer MF2AAQGBBlpxSGUtUYJQo2oB1p1kw3CNcM5QRmok-vzKYVltlykXrZE2AG0F3J3mQjUYOSP3dCOaIeYEUWSKMYeiJy-24paR9YLEZpKDc-mwlE4ML8LRqAyhPMtAoBA

Beware, Apache users!

Apache removes all authorization headers that it doesn't recognize from the request's headers.

Authorization header won't be found in $_SERVER['HTTP_AUTHORIZATION'].

You will need to use the apache_request_headers() function.

Implicit workflow

(2-legged authorization flow)

Schema

Redirection to the provider

• response_type (mandatory)
• client_id (mandatory)
• scope (mandatory)
• redirect_uri (mandatory)
• state (optional, think CSRF)

GET /oauth/authorize
    ?response_type=token
    &client_id=0d5e5af7-420c-4241-8cff-0cfd9d806e59
    &scope=profile%20email
    &state=48389488
    &redirect_uri=https%3A%2F%2Fwww.example.com%3A8443%2Fcallback
Host: server.example.com

Redirection to the client

HTTP/1.1 302 Found
Location: https://server2.example.com
    #access_token=1MF2AAQGBBlpxSGUtUYJQo2oB1p1kw3CNcM5QRmok-vzKYVltlykXrZE2AG0F3J3mQjUYOSP3dCOaIeYEUWSKMYeiJy-24paR9YLEZpKDc-mwlE4ML8LRqAyhPMtAoBA
    &token_type=bearer
    &state=4848573984983
    &expires_in=43062

Note that the access token information is sent through the hash, which is not transferrable to any webserver.

Make requests using the access token

GET /api/me HTTP/1.1
Host: server.example.com
Authorization: Bearer 1MF2AAQGBBlpxSGUtUYJQo2oB1p1kw3CNcM5QRmok-vzKYVltlykXrZE2AG0F3J3mQjUYOSP3dCOaIeYEUWSKMYeiJy-24paR9YLEZpKDc-mwlE4ML8LRqAyhPMtAoBA

Password

Schema

Retrieve an access token with the user's credentials

POST /oauth/token?grant_type=password&username=marysmith&password=123456
Host: server.example.com
Authorization: Basic <Base64-encoded client_id:client_secret>
Content-Type: application/w-www-form-urlencoded

HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
Content-Type: applicaton/json;charset=UTF-8 Transfer-Encoding: chunked
Server: Jetty(8.1.12.v20130726)
{
    "access_token":"MF2AAQGBBlpxSGUtUYJQo2oB1p1kw3CNcM5QRmok-vzKYVltlykXrZE2AG0F3J3mQjUYOSP3dCOaIeYEUWSKMYeiJy-24paR9YLEZpKDc-mwlE4ML8LRqAyhPMtAoBA",
    "token_type":"bearer",
    "expires_in":41558,
    "scope":"profile"
}

Client credentials

Schema

Retrieving an access token with the client's credentials

POST /oauth/token?grant_type=client_credentials Host: server.example.com
Authorization: Basic czQER9k3dD94aIdplr957Udk8 Content-Type: application/w-www-form-urlencoded

HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
Content-Type: applicaton/json;charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(8.1.12v20130726)

{
    "access_token": "MF2AAQGBBlpxSGUtUYJQo2oB1p1kw3CNcM5QRmok-vzKYVltlykXrZE2AG0F3J3mQjUYOSP3dCOaIeYEUWSKFEDrIpaEn5N9MfAm1BjZ5OYLHu0L823L2JsMn7i2wug",
    "token_type": "bearer",
    "expires_in": 42203,
    "scope": "profile"
}