OAuth2 - The Swiss Army Framework

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

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

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

▪ 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

$ 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

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

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

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

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

Client

Authorization Request

Authorization Code

Access Token

Protected Resource

Authorize

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

Client

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

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

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) {..}

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

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

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

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

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

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

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

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!

Client

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":"jsmith@example.com",! "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

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

OAuth2 - The Swiss Army Framework

Technology

Mongodb, our Swiss Army Knife Database

Swiss Army Marketing

The Swiss Army Knife for Waste Management

swiss army knife

Emacs - Professionals Swiss Army Knife

The iPhone: Your Instructional Swiss Army Knife

Version 3 - HL7’s “Swiss Army Knife”

Your schedule as a Swiss Army knife

WLST: WebLogic's Swiss Army Knife

Elastic the swiss army knife for Redbooth

Victorinox Swiss Army Knife

The Web Analytics Swiss Army Knife

Jetpack: The Swiss Army Knife of Plugins

CTSOs - The Swiss Army Knife of Education

Swiss army knife Spring

Employee Generated Content: HR’s Swiss Army Knife

Catalogo Victorinox Swiss Army

victorinox swiss army

Analytics swiss army knife

Swiss army-knife-analysis