OAuth2 - The Swiss Army Framework

© 2014 Adobe Systems Incorporated. All Rights Reserved. Adobe Confidential. 1

Brent ShafferOAuth2: The Swiss Army Framework


Who Is This Guy?

Hint: Brent Shaffer



Maintainer of #1 Open Source PHP library for Server-Side OAuth


I’m in a Band!

The ladies love us!

More Hazards More Heroes



Don’t require your users to authenticate with 3rd parties using passwords!

The moral of the story


Don’t require your users to authenticate with your APIs using passwords!

…and to a lesser extent


What is OAuth?

▪ Something to do with Facebook

▪ Twitter’s in the mix

▪ Maybe Google too? Github?

▪ Authorization and Authentication

▪ Tokens everywhere

▪ Two-legs, three-legs… crablegs?


Overview


“OAuth is a big set of rules that explain how two parties exchange tokens"


Currency for Tokens


Tokens Expire


Bearer Token


Applications (aka Clients)


▪ One user can have many apps

▪ Each app has its own set of credentials

▪ Each app represents a single program / application / script, etc

▪ A conceptual wrapper around your project

Applications (aka Clients)


User “Resource Owner”

Client “3rd Party”

Server “Resource and Authorization Provider”

Three Roles


USER

3RD PARTY

SERVICE

Three Legs


Authorize Token Resource

The user authorizes the client

The server returns a token to the client

Three Endpoints

The server provides the resource


Grant Types


“A Grant Type is just a specific way to obtain (or be granted) an Access Token"


“The multiple ways to get an access token, i.e. the Grant Types, are what make OAuth a

Swiss Army Framework™”


Brent ShafferOAuth2: The Swiss Army Framework


Difficulty: Easy


Client

Authorize

Token

Resource



Personal Access Token




▪ Easier than dirt

▪ Good for calling your APIs on your behalf

▪ No encryption other than HTTPS

▪ No expiration

▪ Treat these like a password

▪ Extension of OAuth2.0 Spec

Personal Access Tokens



$ curl https://api.github.com/users/bshaffer -u fd8e84b60c4bfd8e9277cb3b16f112859d60c45c:

$ curl https://api.github.com/users/bshaffer?access_token=xyz

GET /users/bshaffer HTTP/1.1!Host: api.github.com!Authorization: Basic czZCaGRSa3F0Mzp

GET /users/bshaffer?access_token=xyz HTTP/1.1!Host: api.github.com

$ curl https://api.github.com/users/bshaffer -H ‘Authorization: Bearer xyz

GET /users/bshaffer HTTP/1.1!Authorization: Bearer xyz!Host: api.github.com

http://api.github.com





▪ Slightly harder than dirt, but still very easy

▪ Good for calling YOUR apis

▪ Good for Server-to-Server calls

▪ Tokens expire

▪ Hardcoded credentials

▪ I couldn’t find this in the wild

Client Credentials


Client Credentials

$ curl https://api.example.com/token -d ‘grant_type=client_credentials’ -d ‘client_id=avatarfanclub’ -d ‘client_secret=df40b2’

POST /token HTTP/1.1!Host: api.example.com!Content-Type: application/x-www-form-urlencoded!!grant_type=client_credentials! &client_id=avatarfanclub! &client_secret=df40b2

$ curl https://api.example.com/token -u ‘avatarfanclub:df40b2’ POST /token HTTP/1.1!

Host: server.example.com!Authorization: Basic czZCaGRSa3F0Mzp!Content-Type: application/x-www-form-urlencoded!!grant_type=client_credentials


Client

Token

Client Credentials

Authorize

Resource

POST /token HTTP/1.1!Host: api.example.com!Content-Type: application/x-www-form-urlencoded!!grant_type=client_credentials! &client_id=avatarfanclub! &client_secret=df40b2

Client Credentials


Client

Token

Client Credentials

Authorize

Resource

HTTP/1.1 200 OK!Content-Type: application/json;charset=UTF-8!Cache-Control: no-store!Pragma: no-cache!{! "access_token":"2YotnFZFEjr1zCsicMWpAA",! "token_type":"bearer",! "expires_in":3600!}


Client

Resource

Client Credentials

Authorize

TokenGET /resource/1 HTTP/1.1! Host: example.com! Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA


Client

Resource

Client Credentials

Authorize

Token

HTTP/1.1 200 OK!Content-Type: application/json;charset=UTF-8!!{! "resource":"foo",! "value":"bar",! "success":true!}




▪ Equally difficult to dirt

▪ Good for trusted applications with login forms

▪ Good for testing

▪ Tokens expire

▪ Not good for server-to-server calls, as this would require hardcoded credentials

Resource Owner Password Credentials



$ curl https://api.github.com/login/oauth/token -d ‘grant_type=password’ -d ‘username=bshaffer’ -d ‘password=iheartavatar’ -d ‘client_id=avatarfanclub’ POST /login/oauth/token HTTP/1.1!

Host: api.github.com!Content-Type: application/x-www-form-urlencoded!!grant_type=password! &username=bshaffer! &password=iheartavatar! &client_id=avatarfanclub


Client

Resource Owner Username / PasswordToken

Authorization Code

Authorize

Resource

POST /login/oauth/token HTTP/1.1!Host: api.github.com!Content-Type: application/x-www-form-urlencoded!!grant_type=password! &username=bshaffer! &password=iheartavatar! &client_id=avatarfanclub


Client

Token


Authorize

Resource




Difficulty: Intermediate




▪ Why OAuth Exists

▪ For obtaining authorization to access a user’s information

▪ For when client credentials are secure (Web Applications)

Authorization Code


Authorization Code


Client

Authorization Request

Authorization Code

Authorization Code

Access Token

Access Token

Protected Resource

Authorize

Token

Resource

Authorization Code


Client

Authorize

Authorization Code

GET /authorize! ?response_type=code! &client_id=s6BhdRkqt3! HTTP/1.1!Host: server.example.com!


Client

Authorize

Authorization Code

Token HTTP/1.1 302 Found! Location: http://example.com/cb! ?code=SplxlOBeZQQYbYS6WxSbIA

Resource

http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA


Client

Token

Authorization Code

Resource

POST /token HTTP/1.1!Host: server.example.com!Authorization: Basic czZCaGRSa3F0Mzp!Content-Type: application/x-www-form-urlencoded!!grant_type=authorization_code! &code=SplxlOBeZQQYbYS6WxSbIA

Authorize


Client

Token


Authorize


Resource




▪ For native apps (Desktop, Mobile, Javascript in a browser)

▪ Your client’s credentials cannot be sent due to the public nature of the application

▪ We still want users to authorize our applications (3-legged)

▪ We want to prevent attackers from intercepting the request

Implicit / Device Grant




Public Client

Authorize

Token

Resource


Access Token!


▪ A native call is made containing the access token directly from the authorization request

▪ Javascript

▪ Uses a registered Redirect URI !

▪ Validated against Origins URL !

▪ iOS Applications

▪ Issues a call to your app using a registered Bundle ID

▪ Android Applications

▪ Issues a call to your app using a registered Package Name


https://mysite.com/myapp#access_token=xyz

function onAuthorizeCallback(authResult) {..}

https://mysite.com/my



Login With OAuth


▪ It’s a Trick!!

▪ This is just Authorization Code in disguise!

▪ The application uses your profile data from the other service to create a local account

▪ The two accounts, your local account and the OAuth-provided account, are matched up every time you log in

Login With OAuth


Client

Token

Login with OAuth

Authorize

Resource

HTTP/1.1 200 OK!Content-Type: application/json;charset=UTF-8!Cache-Control: no-store!Pragma: no-cache!{! "access_token":"2YotnFZFEjr1zCsicMWpAA",! "token_type":"bearer",! “expires_in":3600!}


Client

Resource

Client Credentials

Authorize

TokenGET /profile HTTP/1.1! Host: api.example.com! Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA


Client

Resource

Login With OAuth

Authorize

Token

HTTP/1.1 200 OK!Content-Type: application/json;charset=UTF-8!!{! “user_id":"f560f23b24feff2g",! “first_name”:"Ash",! “nickname”:”Poke-Master”,! “favorite_pokemon”: “magikarp”!}


▪ This is not SSO

▪ Very nice way to trick your users into creating an account on your website (clients)

▪ Very nice way to maintain a single canonical user base (server)

▪ While being nefarious, it’s also convenient for your users

▪ Stay tuned for OpenID Connect (advanced)

Login With OAuth



▪ Usually comes back with an access token

▪ When your access token expires, you get another one

▪ Allows the user to not have to reauthorize

▪ Refresh Tokens can expire, or not

Refresh Tokens


Client

Token

Refresh Token

Authorize

Resource

HTTP/1.1 200 OK!Content-Type: application/json;charset=UTF-8!Cache-Control: no-store!Pragma: no-cache!{! "access_token":"2YotnFZFEjr1zCsicMWpAA",! "token_type":"bearer",! "expires_in":3600,! “refresh_token”: “tGzv3JOkF0XG5Qx2TlKWIA“!}


Client

Token

Refresh Token

Authorize

Resource

POST /token HTTP/1.1!Host: server.example.com!Authorization: Basic czZCaGRSa3F0Mzp!Content-Type: application/x-www-form-urlencoded!!grant_type=refresh_token! &refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

Refresh Token



Difficulty: Expert



▪ Json Web Token

▪ For Service Accounts (2-legged)

▪ Enterprise-style

▪ Uses Public/Private Keys rather than Client Credentials

▪ Signs a request and receives an access token upon validation

JWT Bearer


JWT Bearer

© 2014 Adobe Systems Incorporated. All Rights Reserved. Adobe Confidential.

// Create the payload$payload = json_encode(array( ‘iss’ => ‘myclient’, ‘sub’ => ‘myuser’, ‘aud’ => ‘api.example.com’ // ... ));

89

JWT Bearer

// Create the header$header = base64_encode(json_encode(array( ‘algo’ => ‘RS256’, ‘typ’ => ‘jwt’ )));

eyJpc3MiOiJteWNsaWVudCIsInN1YiI6Im15dXNlciIsImF1ZCI6ImFwaS5leGFtcGxlLmNvbSJ9

eyJhbGdvIjoiUlNBMjU2IiwidHlwIjoiand0In0=


JWT Bearer

$ curl https://api.example.com/token -d ‘grant_type=jwt_bearer’ -d ‘assertion=$JWT’

// sign that with a public keyopenssl_sign($input, $signature, $key, ‘RS256’);return sprintf(‘%s.%s’, $input, $signature); eyJhbGdvIjoiUlNBMjU2IiwidHlwIjoiand0I

n0.eyJpc3MiOiJteWNsaWVudCIsInN1YiI6Im15dXNlciIsImF1ZCI6ImFwaS5leGFtcGxlLmNvbSJ9.ZW50IiwicJKV3

// Patch em together$input = sprintf(‘%s.%s’, $header, $payload); eyJhbGdvIjoiUlNBMjU2IiwidHlwIjoiand0I

n0.eyJpc3MiOiJteWNsaWVudCIsInN1YiI6Im15dXNlciIsImF1ZCI6ImFwaS5leGFtcGxlLmNvbSJ9

YOU GET A TOKEN


▪ Layered Security

▪ No credentials are ever sent over the wire

▪ Similar to OAuth 1.0

JWT Bearer



▪ Allows for Decentralized API Validation

▪ Authorization Server issues tokens signed using "key db” and a certificate authority

▪ Resource Server validates access tokens according to "Trust Model"

▪ Metadata for token exists in the token itself

▪ Very scalable

JWT as Access Tokens


Client

Token

JWT Access Token

Authorize

Resource

HTTP/1.1 200 OK!Content-Type: application/json;charset=UTF-8!Cache-Control: no-store!Pragma: no-cache!{! “access_token”:”eyJhbGdvIjoiUlNBMjU2IiwidH lwIjoiand0In0.eyJpc3MiOiJteWNsaWVudCIsInN1YiI6Im15dXNlciIsImF1ZCI6ImFwaS5leGFtcGxlLmNvbSJ9.ZW50IiwicJKV3",! "token_type":"bearer",! "expires_in":3600!}



▪ An effort to standardize the “Login with OAuth” flow

▪ Answers the question “What is the identity of the person using this browser/device?”

▪ Standardizes the exchanging of user profile data

▪ Uses JWT to send profile data with the access token to save additional round trip request

OpenID Connect


Client

Authorize

OpenID Connect

GET /authorize! ?response_type=token! &client_id=s6BhdRkqt3&state=xyz! &redirect_uri=https://example.com/cb! &scope=openid,email,profile! HTTP/1.1!Host: server.example.com!

https://example.com

http://server.example.com


Client

Token

OpenID Connect

Authorize

Resource

HTTP/1.1 200 OK!Content-Type: application/json;charset=UTF-8!Cache-Control: no-store!Pragma: no-cache!{! “access_token”:”xyz”,! “id_token”:”eyJhbGdvIjoiUlNBMjU2IiwidH lwIjoiand0In0.eyJpc3MiOiJteWNsaWVudCIsInN1YiI6Im15dXNlciIsImF1ZCI6ImFwaS5leGFtcGxlLmNvbSJ9.ZW50IiwicJKV3",! "token_type":"bearer",! "expires_in":3600!}


OpenID Connect

// Decode the ID Token Payload$id_token = $response[‘id_token’];list($header, $payload, $signature) = explode($id_token);$userData = base64_decode($payload);

{! "iss":"accounts.google.com",! “email_verified":"true",! "email":"[email protected]",! "sub":"10769150350006150715113082367",! "azp":"xyz.apps.googleusercontent.com",! // ...!}


!Scope Type Description

sub string Subject - Identifier for the End-User at the Issuer.

name string End-User's full name in displayable form including all name parts, possibly including titles and suffixes

given_name string Given name(s) or first name(s) of the End-User.

family_name string Surname(s) or last name(s) of the End-User.

middle_name string Middle name(s) of the End-User.

nickname string Casual name of the End-User

preferred_username string Shorthand name by which the End-User wishes to be referred to at the RP

profile string URL of the End-User's profile page. The contents of this Web page SHOULD be about the End-User.

picture string URL of the End-User's profile picture. This URL MUST refer to an image file

website string URL of the End-User's Web page or blog.

email string End-User's preferred e-mail address.

email_verified boolean True if the End-User's e-mail address has been verified; otherwise false.

gender string End-User's gender. Values defined by this specification are female and male.

birthdate string End-User's birthday, represented as an ISO 8601:2004 [ISO8601-2004] YYYY-MM-DD format.

zoneinfo string String from zoneinfo [zoneinfo] time zone database representing the End-User's time zone.

locale string End-User's locale

phone_number string End-User's preferred telephone number.

phone_number_verified boolean True if the End-User's phone number has been verified; otherwise false.

address JSON object End-User's preferred postal address.

updated_at number Time the End-User's information was last updated.

OpenID Connect

http://openid.net/specs/openid-connect-basic-1_0.html#ISO8601-2004

http://openid.net/specs/openid-connect-basic-1_0.html#zoneinfo


Review

Difficulty # of Legs Description

Personal Access Token Easy Two Dead simple way to receive an access token

Client Credentials Easy Two Uses client credentials (which are implicitly associated with a user or organization) to retrieve an access token


Easy Two/Three Uses a user’s credentials to retrieve an access token

Authorization Code Intermediate Three Allows authentication of third parties without requiring their passwords

Implicit / Device Grant Intermediate Three Authorization Code, but for native apps, where credentials are public

Login with OAuth Intermediate Three Uses Authorization Code to tie the authorized account to a local one

Refresh Tokens Intermediate Three Used to get a new access tokens upon expiration without prompting the user

JWT Bearer Expert Two Uses an Encrypted Payload to establish trust between server and client

JWT Access Tokens Expert Two/Three Uses Encrypted Payload to establish trust amongst servers

OpenID Connect Expert Three A standardization for retrieving user data who have Logged in with OAuth


Resources

▪ OAuth Screencast: https://knpuniversity.com/screencast/oauth

▪ PHP Server-Side Library: https://github.com/bshaffer/oauth2-server-php

▪ OAuth 2.0 Spec - http://tools.ietf.org/html/rfc6749

▪ JWT Spec - http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-20

▪ More Great Slides - http://www.slideshare.net/rnewton/oauth-in-the-real-world-featuring-webshell

https://knpuniversity.com/screencast/oauth

http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-20

http://www.slideshare.net/rnewton/oauth-in-the-real-world-featuring-webshell

© 2014 Adobe Systems Incorporated. All Rights Reserved. Adobe Confidential.

OAuth2 - The Swiss Army Framework

Technology

OAuth2 - The Swiss Army Framework