OAuth 2.0 Simplified

Portland Linux/Unix Group - December 7, 2017

aaronpk.com

@aaronpk

Twitter Clients (2012)

Twitter.com
Twitterific (OS X)
Echofon (Windows, OS X, Firefox)
Janetter (Windows, OS X)
Tweetings (Windows, OS X)
Echelon (OS X)
Hibari (OS X)
Destroy Twitter (Windows, OS X, Linux)
HootSuite (browser based)

Obvious problems...

Gave your username/password to third-party apps
Apps store the password in plaintext
Apps get complete access to your account
No way to revoke access except to change your password
Compromised apps may expose your password

What is OAuth?

OAuth is a framework for users to
authorize
applications to act on their behalf

Roles

The Third-Party Application: "Client"
The API: "Resource Server"
The Authorization Server
The User: "Resource Owner"

Access Token

Known as "Bearer Tokens"
Opaque to the application using the token
May be a database key, or may be self-contained (signed/encrypted, e.g. JWT)
Applications get a Bearer Token and make requests to the API

Obtaining an Access Token

Applications use an OAuth flow to obtain an access token

Authorization code flow: web apps, native apps
Device flow: browserless or input-constrained devices
Password: not really OAuth, only for first-party apps
Refresh token: getting a new access token when it expires

Using a Bearer Token

POST /resource/1/update HTTP/1.1
Authorization: Bearer RsT5OjbzRn430zqMLgV3Ia
Host: api.authorization-server.com

description=Hello+World

Registering an Application

Registering an application gives you a client_id and if the application is not a "public client", then also a client_secret.

These identify the application to the service.

Client ID and Secret

A "public client" means anything where the client cannot keep strings confidential.

Javascript clients: "view source"
Native apps: can decompile and see strings

No secret is used for these clients, only the ID

Web-Based Apps

Build the "Log in" link

response_type=code - indicates that your client expects to receive an authorization code
client_id=CLIENT_ID - The client ID you received when you first created the application
redirect_uri=REDIRECT_URI - Indicates the URI to return the user to after authorization is complete, such as https://example-app.com/callback
scope=photos - A space-separated string indicating which parts of the user's account you wish to access
state=1234zyx - A random string generated by your application, which you'll verify later

Build the "Log in" link

https://authorization-server.com/auth?
response_type=code&
client_id=CLIENT_ID&
redirect_uri=REDIRECT_URI&
scope=photos&
state=1234zyx

If Allowed

The user is redirected back to the application with an authorization code

https://example.com/auth?code=AUTH_CODE_HERE&state=1234zyx

If Denied

The user is redirected back to the application with an error code

https://example.com/auth?error=access_denied

Verify State

The application verifies the state matches the expected value, (or extracts session data from the state).

Obtaining an Access Token

grant_type=authorization_code - indicates that this request contains an authorization code
code=CODE_FROM_QUERY - Include the authorization code from the query string of this request
redirect_uri=REDIRECT_URI - This must match the redirect_uri used in the original request
client_id=CLIENT_ID - The client ID you received when you first created the application
client_secret=CLIENT_SECRET - Since this request is made from server-side code, the secret is included

Obtaining an Access Token

The application exchanges the authorization code for an access token.

POST https://api.authorization-server.com/token
  grant_type=authorization_code&
  code=AUTH_CODE_HERE&
  redirect_uri=REDIRECT_URI&
  client_id=CLIENT_ID&
  client_secret=CLIENT_SECRET

Obtaining an Access Token

The server replies with an access token and expiration time

{
  "access_token":"RsT5OjbzRn430zqMLgV3Ia",
  "expires_in":3600,
  "refresh_token":"64d049f8b2119a5aa51e12522d5dd96d5641af5e8"
}

or if there was an error:

{
  "error":"invalid_request"
}

Single-Page Apps

Build the "Log in" link

response_type=code - indicates that your client expects to receive an authorization code
client_id=CLIENT_ID - The client ID you received when you first created the application
redirect_uri=REDIRECT_URI - Indicates the URI to return the user to after authorization is complete, such as https://example-app.com/callback
scope=photos - A space-separated string indicating which parts of the user's account you wish to access
state=1234zyx - A random string generated by your application, which you'll verify later

Build the "Log in" link

https://authorization-server.com/auth?
response_type=code&
client_id=CLIENT_ID&
redirect_uri=REDIRECT_URI&
scope=photos&
state=1234zyx

If Allowed

The user is redirected back to the application with an authorization code

https://example.com/auth?code=AUTH_CODE_HERE&state=1234zyx

If Denied

The user is redirected back to the application with an error code

https://example.com/auth?error=access_denied

Verify State

The application verifies the state matches the expected value, (or extracts session data from the state).

Obtaining an Access Token

The application exchanges the authorization code for an access token.

POST https://api.authorization-server.com/token
  grant_type=authorization_code&
  code=AUTH_CODE_HERE&
  redirect_uri=REDIRECT_URI&
  client_id=CLIENT_ID

No client_secret is used!

Obtaining an Access Token

The server replies with an access token and expiration time

{
  "access_token":"RsT5OjbzRn430zqMLgV3Ia",
  "expires_in":3600
}

or if there was an error:

{
  "error":"invalid_request"
}

Mobile/Native Apps

also cannot use a client_secret!

Build the "Log in" link

response_type=code - indicates that your server expects to receive an authorization code
client_id=CLIENT_ID - The client ID you received when you first created the application
redirect_uri=REDIRECT_URI - Indicates the URI to return the user to after authorization is complete, such as fb00000000://authorize
scope=photos - A space-separated string indicating which parts of the user's account you wish to access
state=1234zyx - A random string generated by your application, which you'll verify later

Redirect URIs for Native Apps

⚠️

Redirect URIs for Native Apps

There is no built-in security for redirect URIs like when we use DNS, since any app can claim any URL scheme.

So instead, we add an extra step at the beginning to solve this:

PKCE: Proof-Key for Code Exchange

RFC 7636: Implemented by Google and a few others

First create a "code verifier", a random string 43-128 characters long.
Compute the SHA256 hash of the code verifier, call that the code challenge
Include code_challenge=XXXXXX and code_challenge_method=S256 in the initial authorization request
(For clients that can't support SHA256, include the plaintext verifier as the challenge, and set the method to "plain")

Build the "Log in" link

https://authorization-server.com/auth?
response_type=code&
client_id=CLIENT_ID&
redirect_uri=REDIRECT_URI&
scope=photos&
state=1234zyx&
code_challenge=XXXXXXXXXXXXX&
code_challenge_method=S256

And open this in a native browser, not an embedded browser!

If Allowed

The user is redirected back to the application with an authorization code

fb000000://auth?code=AUTH_CODE_HERE&state=1234zyx

If Denied

The user is redirected back to the application with an error code

fb000000://example.com/auth?error=access_denied

Verify State

The application verifies the state matches the expected value, (or extracts session data from the state).

Obtaining an Access Token

grant_type=authorization_code - indicates that this request contains an authorization code
code=CODE_FROM_QUERY - Include the authorization code from the query string of this request
redirect_uri=REDIRECT_URI - This must match the redirect_uri used in the original request
client_id=CLIENT_ID - The client ID you received when you first created the application
code_verifier=VERIFIER_STRING - The plaintext code verifier initially created

Obtaining an Access Token

The application exchanges the authorization code for an access token.

POST https://api.authorization-server.com/token
  grant_type=authorization_code&
  code=AUTH_CODE_HERE&
  redirect_uri=REDIRECT_URI&
  client_id=CLIENT_ID&
  code_verifier=VERIFIER_STRING

No client_secret is used, we use the code_verifier instead!

Obtaining an Access Token

The server compares the code_verifier with the code_challenge that was in the request when it generated the authorization code, and responds with an access token.

{
  "access_token":"RsT5OjbzRn430zqMLgV3Ia",
  "expires_in":3600,
  "refresh_token":"64d049f8b2119a5aa51e12522d5dd96d5641af5e8"
}

Refresh Tokens

If/when your access token expires, you'll need a new one.

You probably got a refresh token when you got the access token response (single-page apps usually don't though).

Refresh Tokens

POST https://api.authorization-server.com/token
  grant_type=refresh_token&
  refresh_token=REFRESH_TOKEN_HERE&
  client_id=CLIENT_ID&
  client_secret=CLIENT_SECRET

Refresh Tokens

The server replies with a new access token

{
  "access_token":"RsT5OjbzRn430zqMLgV3Ia",
  "expires_in":3600,
  "refresh_token":"64d049f8b2119a5aa51e12522d5dd96d5641af5e8"
}

Thanks!

oauth.net
the spec, links to libraries, etc

oauth2simplified.com
my book!

aaronpk.com @aaronpk