CIS13: Bootcamp: Ping Identity OAuth and OpenID Connect In Action with PingFederate Hands-On

7/8/13

1

Copyright ©2013 Ping Identity Corporation. All rights reserved. 1

Bootcamp: Ping Identity OAuth and OpenID Connect In Action with PingFederate Hands-On

John DaSilva Email: [email protected] Twitter: jdasilvaPI


•  Overview of most common OAuth2 options •  Gain an understanding of how OAuth is being

utilized •  Benefits of standards-based authorization •  Implementation approach •  See it in action! •  What is next…

Bootcamp Goals

7/8/13

2


•  I want to understand how OAuth2 works? –  Because I want to implement the a client or

resource server? –  Because I just want to understand the process

better? •  The session I wanted was full, second

choice? •  What no free T-Shirts for attending!

Why are you here?

Copyright ©2013 Ping Identity Corporation. All rights reserved. 4 Copyright ©2013 Ping Identity Corporation. All rights reserved. 4

Bootcamp Agenda

Ø  The Problem •  A Brief History of OAuth •  OAuth 2 •  OAuth 2 Dig A Little Deeper •  Flows in OAuth •  Deep Dive Into Authorization Code Flow •  Deep Dive Into Implicit Grant •  A Closer Look at Refresh Tokens •  End Notes on OAuth then Demo and Lab •  A Problem With OAuth? •  OpenID Connect •  The Details of OpenID Connect •  PingFederate and OpenID Connect •  Demo and Lab •  Some Additional Stuff

7/8/13

3


Problems: – Third-party applications are required to store the resource owner's credentials for future

use, typically a password in clear-text – Servers are required to support password authentication, despite the security

weaknesses inherent in passwords – Third-party applications gain overly broad access to the resource owner's protected

resources, leaving resource owners without any ability to restrict duration or access to a limited subset of resources

– Resource owners cannot revoke access to an individual third-party – Compromise of any third-party application results in compromise of the end-user's

password and all of the data protected by that password

Problem we’re trying to solve

Ever attempt to display your gmail or calendar from a 3rd party website or application?


•  OAuth - An open protocol standards for Web API authorization. •  Goals:

–  OAuth provides a method for users to grant third-party access to their resources without sharing their passwords.

–  Limit Access by •  Scope •  Action •  Time

•  How? –  OAuth allows users to hand out tokens instead of credentials to

their data hosted by a given service provider.

What is OAuth?

7/8/13

4


•  Valet key –  Will not drive more that a mile nor open the trunk –  Block access to your on board cell phone address book, etc

•  Master key will have full access to the car

•  So OAuth is a mechanism to issue a valet key with limited access permissions without handing out the master key (or password)

Real Life Analogy – a bit overused


OAuth Drivers

Lack of standards & support of RESTful API

Cloud APIs

Password anti-pattern

Native mobile Applications

OAuth

7/8/13

5


•  History: –  SOAP based API - WS-Security and WS-Trust to define how clients of

the APIs are authenticated and trusted.

•  RESTful architecture has no comparable standards

•  One way to address REST security issues is with the open-source protocol OAuth.

•  Why REST API? –  Web 2.0 –  Relatively easy to develop –  Standard HTTP operations such as GET, POST, PUT, and DELETE

•  Leads to less overhead –  Support data format XML and JSON

1) REST authentication


2) Password anti-pattern

Sites asks YOU for your GOOGLE password so it can access your Google stuff

7/8/13

6


•  Within move towards SaaS – trend towards API access to data/services to supplement/replace browser access

•  APIs of PaaS offerings allow the customer to expose its own cloud services

•  Clear trend for these APIs is towards REST

3) Cloud APIs


4) Native mobile apps

7/8/13

7


Bootcamp Agenda

ü  The Problem Ø  A Brief History of OAuth •  OAuth 2 •  OAuth 2 Dig A Little Deeper •  Flows in OAuth •  Deep Dive Into Authorization Code Flow •  Deep Dive Into Implicit Grant •  A Closer Look at Refresh Tokens •  End Notes on OAuth then Demo and Lab •  A Problem With OAuth? •  OpenID Connect •  The Details of OpenID Connect •  PingFederate and OpenID Connect •  Demo and Lab •  Some Additional Stuff


•  First was the Emergence of Proprietary Solutions –  Google AuthSub, AOL OpenAuth, Yahoo BBAuth,

Upcoming API, Flickr API, AWS API, and more •  OAuth Core 1.0 [Oct 2007]

–  Open protocol to standardize what was already being done

•  OAuth Core 1.0 Revision A [June 2009] –  Addresses a session fixation attack

•  The OAuth 1.0 Protocol / RFC 5849 [April 2010] –  Move to the IETF as informational documentation of

1.0a with editorial clarifications and errata

A [confusing] Little History

7/8/13

8


•  OAuth WRAP (Web Resource Authorization Profiles) [Jan 2010] –  Better Support for non-web applications –  Simplify the Client –  Short lived, opaque, bearer access tokens with long lived refresh

tokens –  Cleaner separation of roles

•  Server handling authorization requests –  Server handling protected resource access –  Client –  Simple Web Token (SWT) –  Attempt to standardize an access token format

•  OAuth 2.0 [done, sort of] –  Core defined

•  RFC 6749 - The OAuth 2.0 Authorization Framework •  RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage

More History, Still Confusing


Bootcamp Agenda

ü  The Problem ü  A Brief History of OAuth Ø  OAuth 2 •  OAuth 2 Dig A Little Deeper •  Flows in OAuth •  Deep Dive Into Authorization Code Flow •  Deep Dive Into Implicit Grant •  A Closer Look at Refresh Tokens •  End Notes on OAuth then Demo and Lab •  A Problem With OAuth? •  OpenID Connect •  The Details of OpenID Connect •  PingFederate and OpenID Connect •  Demo and Lab •  Some Additional Stuff

7/8/13

9


•  Conceptually similar to WRAP •  With built in extensibility •  Clear separation of getting a token and using

a token –  Bearer Tokens

•  Applicable to many other scenarios – even those with no users

•  Notable for its optimizations for mobile –  Kind of…

OAuth 2.0


OAuth 2.0 Terminology: Roles

•  resource owner: an entity (usually an end-user/person)capable of granting access to a protected resource .

•  client: an application obtaining authorization and making protected resource requests (on behalf of the resource owner).

•  resource server (RS): the server hosting protected resources

•  authorization server (AS): a server capable of issuing tokens, obtaining authorization, and authenticating resource owners.

7/8/13

10


•  Client Key: A value used by the Consumer to identify itself to the Service Provider.

•  Client Secret: A secret used by the Consumer to establish ownership of the Consumer Key.

•  Authorization Code: A value used by the Consumer to obtain authorization from the User, and exchanged for an Access Token.

•  Access Token: A token used by the client to make authenticated requests on behalf of the resource owner.

•  Refresh Token: A token used by the client to obtain a new access token without having to involve the resource owner.

More Terminology


Bootcamp Agenda

ü  The Problem ü  A Brief History of OAuth ü  OAuth 2 Ø  OAuth 2 Dig A Little Deeper •  Flows in OAuth •  Deep Dive Into Authorization Code Flow •  Deep Dive Into Implicit Grant •  A Closer Look at Refresh Tokens •  End Notes on OAuth then Demo and Lab •  A Problem With OAuth? •  OpenID Connect •  The Details of OpenID Connect •  PingFederate and OpenID Connect •  Demo and Lab •  Some Additional Stuff

7/8/13

11


•  Access Token –  credential used by client to access protected resources at

the RS –  permissions afforded by the token can be scoped –  issued by the AS –  structure is undefined by the spec(s) –  usually opaque to the client –  generally short lived –  can be self contained or a reference –  shifts complexity from the RS to the AS

•  Refresh Token –  used by client to obtain a new access token when the old

one expires –  client only sends to AS, never to RS –  generally long lived

Tokens


•  Access tokens can have different –  formats –  structures –  methods of utilization (e.g. cryptographic properties)

•  Access tokens must be defined by companion specifications –  token_type –  additional parameters as needed –  how to use at RS

Access Token Types

7/8/13

12


•  Any party in possession of the token (a "bearer") can use the token in any way that any other party in possession of it can.

•  token_type: Bearer •  Token can be presented to the RS in HTTP

Authorization Header, Body Parameter, or Query Parameter

•  Requires TLS •  Token structure still undefined

Bearer Access Tokens


•  AS Endpoints –  Authorization endpoint

•  used, via user-agent redirection, to authenticate and obtain authorization from the resource owner.

•  End user on the front channel. –  Token endpoint

•  Used to exchange an authorization grant for an access token. •  Client on the back channel.

•  Client Endpoint –  Redirection URI

•  After completing its interaction with the resource owner, the AS directs the resource owner's user-agent back to the client at the client’s redirection URI.

•  Front channel callback

Endpoints

7/8/13

13


•  General term used to describe the intermediate credentials representing the resource owner authorization

•  Serves as an abstraction layer –  not the cleanest abstraction

•  Used by the client to obtain an access token •  All token endpoint calls involve exchanging some

grant for an access token •  Spec defines several types as well as an

extensibility mechanism

Authorization Grant


•  All clients must have an access token to gain access to protected resources.

•  Grant Types (ways to get an access token): –  Authorization Code Flow (apps on a web server) –  Implicit (browser-based or mobile apps, like javascript) –  Resource Owner Password Credentials (native mobile apps) –  Client Credentials (application access, server-server) –  SAML assertion bearer (federation access) – in progress

Grant Types

7/8/13

14


•  The definition of scope is (mostly) out of scope –  See what I did there? –  The scope of the access request is expressed as a list of

space-delimited, case sensitive strings. –  Order doesn’t matter. –  The value and meaning of scope strings are defined by the

authorization server and enforced by the resource server •  Requesting/granting specific scope(s) allows the access

rights associated with a token to be limited –  Enables the principle of least privilege (or less privilege anyway) –  Only ask for what is needed

•  Can look at as a permission or action that client application can do/request of the Resource Server

Scope


•  Facebook –  publish_stream –  publish_checkins –  read_mailbox –  email –  user_status

•  Google –  https://www.googleapis.com/auth/adsense –  https://www.googleapis.com/auth/plus.me –  https://www.googleapis.com/auth/urlshortener –  https://mail.google.com/mail/feed/atom –  https://www.googleapis.com/auth/plus.me

•  OpenID Connect –  openid –  email –  profile –  phone –  address

Some Scope Examples

7/8/13

15


Bootcamp Agenda

ü  The Problem ü  A Brief History of OAuth ü  OAuth 2 ü  OAuth 2 Dig A Little Deeper Ø  Flows in OAuth •  Deep Dive Into Authorization Code Flow •  Deep Dive Into Implicit Grant •  A Closer Look at Refresh Tokens •  End Notes on OAuth then Demo and Lab •  A Problem With OAuth? •  OpenID Connect •  The Details of OpenID Connect •  PingFederate and OpenID Connect •  Demo and Lab •  Some Additional Stuff


•  Client obtains authorization grant from resource owner

•  Client calls the authorization server to exchange the grant for an access token

•  Client uses the access token to access protected resources at the resource server

Abstract Flow – The Theory

7/8/13

16


•  Resource Owner authorizes access request to 3rd party application for Authorization Code

•  Authorization Code is then exchanged for an Access Token. •  Access Token is used to access protected resources. •  Refresh Token may be issue to obtain new Access Token when expired. •  End Points: (A),(B),(C) – Authorization Endpoint, (D), (E) – Token Endpoint

Authorization Code Flow


•  Resource Owner authorizes access request to 3rd party application •  Access Token is issued to the client application in URI Fragment •  The user-agent retains the fragment information locally and follow the

redirection to the Web server. •  Web server returns a Web page with embedded scripts to extract the

Access Token and pass it to the client. •  Tokens requirements – Access Token •  End Points: (A),(B),(C) – Authorization Endpoint

Implicit Grant

7/8/13

17


Client Application

•  OAuth client role

•  REST API (Resource Server) client

•  Needs to get a token and use it

•  May also involve refreshing a token, if tokens are expired

Client Application Integration


Bootcamp Agenda

ü  The Problem ü  A Brief History of OAuth ü  OAuth 2 ü  OAuth 2 Dig A Little Deeper ü  Flows in OAuth Ø  Deep Dive Into Authorization Code Flow •  Deep Dive Into Implicit Grant •  A Closer Look at Refresh Tokens •  End Notes on OAuth then Demo and Lab •  A Problem With OAuth? •  OpenID Connect •  The Details of OpenID Connect •  PingFederate and OpenID Connect •  Demo and Lab •  Some Additional Stuff

7/8/13

18


①  Web application redirects user to Authorization Server (AS), which is PingFederate, at its authorization endpoint (https://<pf>/as/authorization.oauth2). Request query string includes the OAuth client ID, response type and requested scopes.

②  User authenticates to AS via IdP adapter or IdP connection. After authentication, user sees confirmation page with requested scopes from the OAuth client redirect, and clicks "Approve”.

③  AS redirects user back to client site with Authorization Code in query string.

④  Website resolves Authorization Code to an OAuth token (Access Token [and Refresh Token]) via API call to the AS Token Endpoint (https://<pf>/as/token.oauth2)

⑤  The result is an HTTP 200 response to the client indicating success from the Token Endpoint. The response is returned formatted in JSON (JavaScript Object Notation) containing the OAuth Access Token

Client Applications – Getting Code and Token

Web client

Token Endpoint

AuthZ Endpoint

1

1

2

3

3

4

5



Getting a Token •  Identify when a user needs to grant access to

something at the Resource Server

•  When this situation occurs, redirect to: https://<pfhost:port>/as/authorization.oauth2?client_id=<client_id>&response_type=code

Note: Additional (optional) query parameters: •  scope – space delimited (URL encoded as %20) requested

permissions of the client

•  state – an opaque value used by the OAuth client to maintain state on the callback

•  idp – PingFederate specific parameter to request SAML IdP based authentication

•  pfidpadapterid – PingFederate specific parameter to authenticate the user with a named IdP Adapter

PingFederate Config Prerequisites: •  The OAuth client must be defined •  Client must be assigned (at a minimum)

the Authorization Code grant type, and thus a defined callback URL.

•  IdP adapter mappings to authenticate via an adapter

7/8/13

19



Getting a Token (continued) •  User authenticates to Authorization Server

!



Getting a Token (continued) •  Authorization page (default template):

OAuth client details

Requested scope

7/8/13

20



Getting a Token (continued) •  After the user authenticates and authorizes access at

PingFederate, a callback (via HTTP redirect) will be made back to the client application.

•  The following parameters are possible on the callback: •  code – the Authorization Code that will be subsequently used

to resolve the OAuth token •  error – an error code (e.g.: access_denied) •  error_description – descriptive text about the error •  state –the same state value given in the original redirection

(if supplied)



Getting a Token (continued) •  Callback processing:

•  The code callback parameter must be resolved into OAuth tokens by making a API call to the PingFederate Token Endpoint .

•  If error is present in the callback, the application

should gracefully fail and present a meaningful error to the user.

7/8/13

21



Getting a Token (continued) •  Example HTTP Request:

•  This request is exchanging the Authorization Code obtained in the callback for the desired tokens.

POST /as/token.oauth2 HTTP/1.1

Host: as.pingidentity.com

Authorization: Basic Y2xpZW50X2lkMTpjbGllbnRfc2VjcmV0MQ==

Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA

base64(client_id:client_secret)

Note: If the OAuth client has a registered Client Secret, then the client must authenticate - typically via the HTTP Basic authentication Authorization header.



Getting a Token (continued) •  Example Token Endpoint response: HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

Cache-Control: no-store

Pragma: no-cache

{"token_type":"Bearer",

"expires_in":60,

"refresh_token":"uyAVrtyLZ2qPzI8rQ5UUTckCdGaJsz8XE8S58ecnt8",

"access_token":"PeRTSD9RQrbiuoaHVPxV41MzW1qS"}

Note: refresh_token is present only if the Refresh grant type is configured for this client .

7/8/13

22



Using a Token •  Once an access_token is obtained, it can be used in

the REST API call to the Resource Server. •  "Bearer" tokens should be inserted into an HTTP

Authorization header. They may also appear in the query string or request body.

•  Example REST API request: POST /msg/api HTTP/1.1

Host: rs.pingidentity.com

Authorization: Bearer PeRTSD9RQrbiuoaHVPxV41MzW1qS


msg=This%20is%20a%20test%20message.%20%20Please%20respond.


User was previously granted an Access Token (and potentially a Refresh Token). User accesses Web application and requests an action that will result in a call to the Resource Server (RS). ①  Web application checks if user has

a valid (non-expired) Access Token. If none available, but a Refresh Token is available, a request is made to the AS Token Endpoint (https://<pf>/as/token.oauth2) to obtain a new Access Token.

②  AS looks up the Refresh Token in its persistent grant storage. If valid, AS issues a new Access Token (and possibly a new Refresh Token).

③  Web application inserts the OAuth Access Token in an Authorization HTTP header (Bearer type), and makes the REST API call to the RS.

④  RS validates incoming Access Token with AS using the Token Endpoint (https://</pf>/as/token.oauth2) with a PingFederate Validation grant type. AS returns validation results including user attributes.

⑤  Protected data is sent to Web application.

Client Applications – Refresh Token and Usage

Web client

Token Endpoint

AuthZ Endpoint

1

2

3

5 Resource

Server

4

7/8/13

23



Refreshing a Token •  The JSON structure returned by the Token Endpoint

containing the access_token may also contain other useful parameters such as: •  expires_in – number of seconds before

access_token can no longer be used. •  refresh_token – can be stored persistently to

request another access_token (e.g.: after expiry)

{"token_type":"Bearer",

"expires_in":60,

"refresh_token":"uyAVrtyLZ2qPzI8rQ5UUTckCdGaJsz8XE8S58ecnt8",

"access_token":"PeRTSD9RQrbiuoaHVPxV41MzW1qS"}



Refreshing a Token (cont)

•  To refresh an Access Token after expiry, use the Refresh Token to make a call to the Token Endpoint.

•  Example request: POST /as/token.oauth2 HTTP/1.1

Host: as.pingidentity.com

Authorization: Basic Y2xpZW50X2lkMTpjbGllbnRfc2VjcmV0MQ==


grant_type=refresh_token&refresh_token=qANLTbu17rk17lPszecHRi7rqJt46pG1qx0nTAqXWH

Pre-requisite: The OAuth client as defined in PingFederate must have assigned (at a minimum) the Refresh grant type. Additional token mapping configuration is also required for persistent grants.

base64(client_id:client_secret)

Note: If the OAuth client has a registered Client Secret, then the client must authenticate - typically via the HTTP Basic authentication Authorization header.

7/8/13

24



Refreshing a Token (continued) •  The JSON response structure will contain an Access

Token, expiry and type details and (depending on policy) a Refresh Token.

•  Example JSON response structure: {"token_type":"Bearer", "expires_in":60,

"refresh_token":"5HmQjHHP6lGDDWxNh3tuwCzxtRjl95xYnVgvrfh5Kt",

"access_token":"sqhZPzxb7IAIa4kxdyLDJpxpgTFj"}

Note: The default policy in PingFederate is to roll the Refresh Token on each use. Once a Refresh Token is returned in the response, the previously sent Refresh Token is rendered invalid.


Bootcamp Agenda

ü  The Problem ü  A Brief History of OAuth ü  OAuth 2 ü  OAuth 2 Dig A Little Deeper ü  Flows in OAuth ü  Deep Dive Into Authorization Code Flow Ø  Deep Dive Into Implicit Grant •  A Closer Look at Refresh Tokens •  End Notes on OAuth then Demo and Lab •  A Problem With OAuth? •  OpenID Connect •  The Details of OpenID Connect •  PingFederate and OpenID Connect •  Demo and Lab •  Some Additional Stuff

7/8/13

25


•  Application that runs in the browser, typically JavaScript or ‘widget’ clients

•  Tunes Partner Widget •  Grant Type: Implicit

Browser-Based Apps

Website hosting Client

Authorization Server

Resource Server

Resource Owner


Browser-Based Apps

①  Browser application redirects user to AS, which is PingFederate, at its authorization endpoint (https://<pf>/as/authorization.oauth2). The request query string includes the client ID, response type (token) and requested scope (charge $10)

②  User authenticates to AS.

③  AS redirects user back to web app with the access token embedded in the query fragment.

④  The browser app runs a javascript method to pull out the access token for use.

Web client

Token Endpoint

AuthZ Endpoint

1

2 – User Authenticates

3 – Access Token in URL

3

1 – Client ID, Redirect URI

7/8/13

26


Browser-Based Apps - Getting an Access Token

•  Create a link sending the user to: https://<pfhost:port>/as/authorization.oauth2?client_id=<client_id>&response_type=token&redirect_uri=<REDIRECT_URI>&scope=<scope>

The user authenticates and authorizes like before, but just gets back that access token


Browser-Based Apps - Getting an Access Token

Client Authorization Request – to AS Auth Endpoint

•  After the user authorizes access at AS, the AS returns the access token as a fragment on the URI.

•  Since it is returned to the app, not the server, client-side script must parse the fragment and extract the value of the access_token parameter to pass to the server over HTTPS

GET /as/idtel.com?

client_id=TunesPartner&

redirect_uri=https%3A//tunespartner.com/cb&

response_type=token&

scope=oneTimeCharge

HTTP/1.1

Host: IdTel.com

Access Token redirect – from AS Token Endpoint: https://tunespartner.com/cb#token=Ljfaf57252SfafnkUA&expires_in=3600

7/8/13

27


•  Call the resource server, same as before •  No refresh token

–  No way for client application to store it securely

Use Access Token


Bootcamp Agenda

ü  The Problem ü  A Brief History of OAuth ü  OAuth 2 ü  OAuth 2 Dig A Little Deeper ü  Flows in OAuth ü  Deep Dive Into Authorization Code Flow ü  Deep Dive Into Implicit Grant Ø  A Closer Look at Refresh Tokens •  End Notes on OAuth then Demo and Lab •  A Problem With OAuth? •  OpenID Connect •  The Details of OpenID Connect •  PingFederate and OpenID Connect •  Demo and Lab •  Some Additional Stuff

7/8/13

28


•  Idea: –  Short-lived tokens between the client and the RS –  Long-lived tokens between the client and the AS

•  Refresh an expired access token without involving user authorization

•  Refresh tokens can be revoked; access tokens can’t (usually, depends)

•  The AS may issue a new refresh token –  Previous token is rendered invalid

Refresh Tokens


•  Persistent Grant Lifetime –  Usability vs Security –  May overwrite in Client Management –  A Refresh token lifetime should be set longer than the average time period

between application usages

•  For added security –  Set Roll Refresh Token Values & Minimum Interval to Roll Refresh Token

PingFederate – General Refresh Token & Persistent Grant

7/8/13

29


•  Reuse Existing Persistent Access Grants for Grant Types (checkboxes) –  Reuse same Refresh token for same user and scope –  Limit to one Grant per client/per user –  Should not use these setting if same user uses multiple

instances of same client.

PingFederate – General Refresh Token & Persistent Grant


PingFederate – Persistent Grants Table

•  SQL here: <pf-home>/pingfederate/server/default/conf/access-grant/sql-scripts

•  Single table (pingfederate_access_grant):

Column Type guid VARCHAR(32)

hashed_refresh_token VARCHAR(256)

unique_user_id VARCHAR(256)

scope VARCHAR(1024)

client_id VARCHAR(256)

grant_type VARCHAR(128)

context_qualifier VARCHAR(64)

issued TIMESTAMP

updated TIMESTAMP

expires TIMESTAMP

7/8/13

30


PingFederate – User Management of Persistent Grants

•  https://<pfhost:port>/as/oauth_access_grants.ping

•  Template: <pf-home>/pingfederate/server/default/conf/template/oauth.access.grants.page.template.html


Bootcamp Agenda

ü  The Problem ü  A Brief History of OAuth ü  OAuth 2 ü  OAuth 2 Dig A Little Deeper ü  Flows in OAuth ü  Deep Dive Into Authorization Code Flow ü  Deep Dive Into Implicit Grant ü  A Closer Look at Refresh Tokens Ø  End Notes on OAuth then Demo and Lab •  A Problem With OAuth? •  OpenID Connect •  The Details of OpenID Connect •  PingFederate and OpenID Connect •  Demo and Lab •  Some Additional Stuff

7/8/13

31


•  It’s not terribly difficult –  There are libraries; use them!

•  Default to SSL •  Roll refresh tokens •  Send access token requests in HTTP Header •  Scopes: Only ask for what is needed

•  Now to the hands-on

Ending Notes on OAuth


QUICK OPENID CONNECT REVIEW - MAYBE NOT SO QUICK?

7/8/13

32


Bootcamp Agenda

ü  The Problem ü  A Brief History of OAuth ü  OAuth 2 ü  OAuth 2 Dig A Little Deeper ü  Flows in OAuth ü  Deep Dive Into Authorization Code Flow ü  Deep Dive Into Implicit Grant ü  A Closer Look at Refresh Tokens ü  End Notes on OAuth then Demo and Lab Ø  A Problem With OAuth? •  OpenID Connect •  The Details of OpenID Connect •  PingFederate and OpenID Connect •  Demo and Lab •  Some Additional Stuff


•  OAuth is a protocol allowing users to authorize 3rd party applications to access h/her private data

•  The outcome of the handshake is the application getting an access token

•  This access token does not directly provide useful information for the application to identify the user

Problem we’re trying to solve

Token Endpoint

Validation Endpoint

AuthZ Endpoint

User

3rd Party Client

Server/Provider OAuth Authorization Server

3rd party application obtain an Access token but does not know who the user is OR

if the token is meant for them or for another Relying Party

User info Endpoint

User JOE

3rd Party Client


X

3rd party application recognizes user as Joe

•  Provider exposes an API which returns information about that user, the application can use this as a means to close the loop on the delegated authentication

Custom API

7/8/13

33


Bootcamp Agenda

ü  The Problem ü  A Brief History of OAuth ü  OAuth 2 ü  OAuth 2 Dig A Little Deeper ü  Flows in OAuth ü  Deep Dive Into Authorization Code Flow ü  Deep Dive Into Implicit Grant ü  A Closer Look at Refresh Tokens ü  End Notes on OAuth then Demo and Lab ü  A Problem With OAuth? Ø  OpenID Connect •  The Details of OpenID Connect •  PingFederate and OpenID Connect •  Demo and Lab •  Some Additional Stuff


•  OpenID Connect defines an identity layer (OpenID) on top of the OAuth 2.0 authorization framework: •  OAuth allows resource owners to delegate resource

access rights to 3rd parties in a discretionary fashion with a limited scope (functionality, time) via web APIs

•  OpenID is a way of proving to a server that you are who you say you are

•  OIDC Clients can •  verify the identity of the End-User based on an

authentication performed by an OAuth Authorization Server

•  may obtain additional information about user identity from OAuth-protected service endpoints

What is OpenID Connect? (OIDC)

7/8/13

34


OpenID Connect Family Tree

JWT

Hybrid Extension

OAuth 1

OAuth 2

Artifact


OpenID Connect and its Supporting Stack

7/8/13

35


•  Whereas OAuth is a general mechanism to authorize API access, OpenID Connect profiles the generic for purposes of sharing profile information

•  OpenID Connect adds a security token explicitly for SSO from AS to Client

•  Uses the authorization code & implicit grant types – the pieces of OAuth optimized for user-consent scenarios

•  Leverages the authorization & token endpoints & adds identity-based params to core OAuth messages

OpenID Connect Relation to OAuth


Bootcamp Agenda

ü  The Problem ü  A Brief History of OAuth ü  OAuth 2 ü  OAuth 2 Dig A Little Deeper ü  Flows in OAuth ü  Deep Dive Into Authorization Code Flow ü  Deep Dive Into Implicit Grant ü  A Closer Look at Refresh Tokens ü  End Notes on OAuth then Demo and Lab ü  A Problem With OAuth? ü  OpenID Connect Ø  The Details of OpenID Connect •  PingFederate and OpenID Connect •  Demo and Lab •  Some Additional Stuff

7/8/13

36


•  openid •  REQUIRED. Informs the Authorization Server that the Client is making an OpenID Connect

request. If the openid scope value is not present, the request MUST NOT be treated as an OpenID Connect request

•  profile •  OPTIONAL. This scope value requests that access to the End-User's default profile Claims •  These Claims are: name, family_name, given_name, middle_name, nickname,

preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_time

•  email •  OPTIONAL. This scope value requests that access to the email and email_verified Claims

•  address •  OPTIONAL. This scope value requests that access to the address Claim •  These Claims are: name, fomatted, street_address, locality, region, postal_code and country

•  phone •  OPTIONAL. This scope value requests that access to the phone_number

•  offline_access •  OPTIONAL. This scope value requests that an OAuth 2.0 Refresh Token be issued that can be

used to obtain an access token that grants access the End-User's UserInfo endpoint even when the user is not present (not logged in)

Extension to OAuth - Scope


Extension to OAuth – Standard Claims

Member Description

sub Subject -‐ Iden.fier for the End-‐User at the Issuer. The sub (subject) Claim MUST always be returned in the UserInfo response.

name End-‐User's full name in displayable form including all name parts, ordered according to End-‐User's locale and preferences.

given_name Given name or first name of the End-‐User. family_name Surname or last name of the End-‐User. middle_name Middle name of the End-‐User.

nickname Casual name of the End-‐User that may or may not be the same as the given_name. For instance, a nickname value of Mike might be returned alongside a given_name value of Michael.

preferred_username Shorthand name that the End-‐User wishes to be referred to at the RP, such as janedoe or j.doe. This value MAY be any valid JSON string including special characters such as @, /, or whitespace. This value MUST NOT be relied upon to be unique by the RP. (See Sec.on 2.4.2.2.)

profile URL of the End-‐User's profile page. picture URL of the End-‐User's profile picture. website URL of the End-‐User's web page or blog.

email End-‐User's preferred e-‐mail address. This value MUST NOT be relied upon to be unique by the RP. (See Sec.on 2.4.2.2.) email_verified True if the End-‐User's e-‐mail address has been verified; otherwise false.

gender End-‐User's gender. Values defined by this specifica.on are female and male. Other values MAY be used when neither of the defined values are applicable.

birthdate End-‐User's birthday, represented as an ISO 8601:2004 [ISO8601-2004] YYYY-‐MM-‐DD format. The year MAY be 9999, indica.ng that it is omiced. To represent only the year, YYYY format is allowed. Note that depending on the underlying pladorm's date related func.on, providing just year may result in varying month and day, so the implementers should take this factor into account to correctly process the dates.

zoneinfo String from zoneinfo [zoneinfo] .me zone database represen.ng the End-‐User's .me zone. For example, Europe/Paris or America/Los_Angeles.

locale

End-‐User's locale, represented as a BCP47 [RFC5646] language tag. This is typically an ISO 639-‐1 Alpha-‐2 [ISO639-1] language code in lowercase and an ISO 3166-‐1 Alpha-‐2 [ISO3166-1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compa.bility note, some implementa.ons have used an underscore as the separator rather than a dash, for example, en_US; Implementa.ons MAY choose to accept this locale syntax as well.

phone_number End-‐User's preferred telephone number. E.164 [E.164] is RECOMMENDED as the format of this Claim. For example, +1 (425) 555-‐1212 or +56 (2) 687 2400.

address End-‐User's preferred address. The value of the address member is a JSON [RFC4627] structure containing some or all of the members defined in Sec.on 2.4.2.1.

updated_.me Time the End-‐User's informa.on was last updated, represented as a RFC 3339 [RFC3339] date.me. For example, 2011-‐01-‐03T23:58:42+0000.

7/8/13

37


•  ID_Token •  A security token that contains Claims about the authentication event and other requested Claims •  JSON Web Token (JWT) •  It is signed by the server using the client secret that was previously established over a trusted channel

or by certificate that client can retrieve the public key from the server •  Validation:

•  client MUSTverify the signature •  iss (issuer) Claim is valid for the Token Endpoint that the id_token was received from •  aud (audience) Claim contains its client_id value registered at the Issuer identified

Extension to OAuth – ID_Token

Token Endpoint

Validation Endpoint

AuthZ Endpoint

User

3rd Party Client


HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache {

"access_token":"SlAV32hkKG", "token_type":"bearer", "expires_in":3600, "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", "id_token":"eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso"

}

{ "iss": "https://server.example.com", "sub": "24400320", "aud": "s6BhdRkqt3", "exp": 1311281970, "iat": 1311280970 }

Base64url decode


The following Claims are REQUIRED within the ID Token: •  iss

–  REQUIRED. Issuer Identifier for the Issuer of the response.

•  sub (~user_id) –  REQUIRED. Subject identifier. A locally unique and never reassigned identifier within the Issuer

for the End-User, which is intended to be consumed by the Client. e.g. 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4. It MUST NOT exceed 255 ASCII characters in length.

•  aud –  REQUIRED. Audience that this ID Token is intended for. It MUST contain the OAuth 2.0 client_id

of the Client.

•  exp –  REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for

processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 [RFC3339] for details regarding date/times in general and UTC in particular. The exp value is a number.

•  iat –  REQUIRED. Time at which the JWT was issued. The time is represented as the number of

seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. The iat value is a number.

Obtaining an ID Token

7/8/13

38


•  UserInfo Endpoint •  Protected resource that, when presented with an Access Token by the Client, returns

authorized information about the End-User represented by the corresponding Authorization Grant

•  MUST require the use of a transport-layer security mechanism (For example, TLS 1.0/1.2) •  Claim format: JSON object or JSON Web Token (JWT)

Extension to OAuth – UserInfo Endpoint

Token Endpoint

Validation Endpoint

AuthZ Endpoint


Token Endpoint

Validation Endpoint

AuthZ Endpoint


UserInfo Endpoint

User JOE

3rd Party Client

X

Claims

Access Token


Extension to OAuth – UserInfo Endpoint

The client constructs an HTTPS “GET” request to the user info endpoint and includes the access token as a parameter

GET /userinfo? HTTP/1.1 Host: server.example.com Authorization: Bearer SlAV32hkKG

The response is a JSON object that contains some (or all) of the following reserved keys: {

"sub": "248289761001", "name": "Jane Doe", "given_name": "Jane", "family_name": "Doe", "preferred_username": "j.doe", "email": "[email protected]", "picture": http://example.com/janedoe/me.jpg

}

The server is free to add additional data to this response (such as Portable Contacts) so long as they do not change the reserved OpenID Connect keys

Access Token (required)

Schema (required) - openid

7/8/13

39


§  version: 3.0 §  issuer: https://sso.jgd.home:9031 §  authorization_endpoint: https://sso.jgd.home:9031/as/

authorization.oauth2" §  token_endpoint: https://sso.jgd.home:9031/as/token.oauth2 §  userinfo_endpoint: https://sso.jgd.home:9031/idp/userinfo.openid §  jwks_uri: https://sso.jgd.home:9031/pf/JWKS §  scopes_supported: ["admin","write","openid"] §  response_types_supported: ["code","token","id_token","code

token","code id_token","token id_token","code token id_token"] §  subject_types_supported: ["public"] §  id_token_signing_alg_values_supported:

["none","HS256","HS384","HS512","RS256","RS384","RS512","ES256","ES384","ES512"]

§  token_endpoint_auth_methods_supported: ["client_secret_basic","client_secret_post"]

§  claim_types_supported: ["normal"] §  claims_parameter_supported: false §  request_parameter_supported: false §  request_uri_parameter_supported: false

Configuration Endpoint Request Example


•  Hash-based Message Authentication Codes (HMACs) o  HS256 - HMAC using SHA-256 hash - REQUIRED o  HS384 - HMAC using SHA-384 hash - OPTIONAL o  HS512 - HMAC using SHA-512 hash - OPTIONAL

•  RSASSA-PKCS1-V1_5 o  RS256 - RSASSA using SHA-256 hash - RECOMMENDED o  RS384 - RSASSA using SHA-384 hash - OPTIONAL o  RS512 - RSASSA using SHA-512 hash - OPTIONAL

•  Elliptic Curve Digital Signature Algorithm (ECDSA) o  ES256 - ECDSA using P-256 curve & SHA-256 hash - RECOMMENDED o  ES384 - ECDSA using P-384 curve & SHA-384 hash - OPTIONAL o  ES512 - ECDSA using P-521 curve & SHA-512 hash - OPTIONAL

•  none - No digital signature or MAC - REQUIRED

Signing of Tokens - Algorithms Supported

7/8/13

40


①  Web application redirects user to Authorization Server (AS), https://<pf>/as/authorization.oauth2 response_type=code &client_id=58ut85ie &redirect_uri=https://client.example.org/cb &scope=openid email

②  User authenticates to AS via IdP adapter or IdP connection. After authentication user sees confirmation page with requested scopes from the OAuth client redirect, and clicks "Approve”.

③  AS redirects user back to client site with Authorization Code in query string.

HTTP/1.1 302 Found Location: https://client.example.org/cb? code=SplxlOBeZQQYbYS6WxSbIA

④  Web site resolves Authorization Code to an OAuth token via REST API

POST /token HTTP/1.1 Host: <pf>/as/token.oauth2 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code=SplxlOBeZQQYbYS6WxSbIA &redirect_uri=https://client.example.com/cb

OpenID Connect – Basic Client Profile

Web client

Token Endpoint

AuthZ Endpoint

1

1

2

3

3

4

5

with Authorization Code Flow

⑤  The result is an HTTP 200 response to the client indicating success from the Token Endpoint. The response is returned formatted in JSON (JavaScript Object Notation) containing the OAuth Access Token and ID_Token

{ "access_token":"SlAV32hkKG", "token_type":"bearer", "expires_in":3600, "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA”, "id_token":”JTJ0 ... NiJu8reI6DD" }


⑥  Web application can request for authenticated user’s information via a REST API call to the AS Userinfo Endpoint with the access token.

GET /userinfo?schema=openid HTTP/1.1 Host: server.example.com Authorization: Bearer SlAV32hkKG

⑦  The result is an HTTP 200 response to

the client indicating success from the UserInfo Endpoint. The response is returned formatted in JSON containing the User’s attributes.

{ "sub": "248289761001", "name": "Jane Doe", "given_name": "Jane", "family_name": "Doe", "preferred_username": "j.doe", "email": "[email protected]", }

OpenID Connect – Basic Client Profile

Web client

UserInfo Endpoint

AuthZ Endpoint

6

7

7/8/13

41


Bootcamp Agenda

ü  The Problem ü  A Brief History of OAuth ü  OAuth 2 ü  OAuth 2 Dig A Little Deeper ü  Flows in OAuth ü  Deep Dive Into Authorization Code Flow ü  Deep Dive Into Implicit Grant ü  A Closer Look at Refresh Tokens ü  End Notes on OAuth then Demo and Lab ü  A Problem With OAuth? ü  OpenID Connect ü  The Details of OpenID Connect Ø  PingFederate and OpenID Connect •  Demo and Lab •  Some Additional Stuff


•  Enable through Roles & Protocols

•  When enabled the openid scope created

OpenID Connect in PingFederate

7/8/13

42


•  Metadata: /.well-known/openid-configuration

•  Authorization: /as/authorization.oauth2

•  Token: /as/token.oauth2 •  User Info: /idp/userinfo.openid •  JWS KS: /pf/JWKS

OpenID Connect Endpoints


Select Algorithm Client Will Use

7/8/13

43


•  openid - added by default, it is required •  Other scopes you can add in Authorization

Server Settings o  profile o  email o  address o  phone o  offline_access

Scopes


PingFederate OpenID Connection Policy

7/8/13

44


OpenID Policy - Mapping of Attributes for Token


OpenID Connect Policy Attribute Contract

7/8/13

45


OpenID Connect Attribute Contract Mapping


OpenID Connect Authorization Code client - secret

7/8/13

46


AC Client Tokens and OpenID Connect Config


Bootcamp Agenda

ü  The Problem ü  A Brief History of OAuth ü  OAuth 2 ü  OAuth 2 Dig A Little Deeper ü  Flows in OAuth ü  Deep Dive Into Authorization Code Flow ü  Deep Dive Into Implicit Grant ü  A Closer Look at Refresh Tokens ü  End Notes on OAuth then Demo and Lab ü  A Problem With OAuth? ü  OpenID Connect ü  The Details of OpenID Connect ü  PingFederate and OpenID Connect Ø  Demo and Lab •  Some Additional Stuff

7/8/13

47


Demo and Lab


Bootcamp Agenda

ü  The Problem ü  A Brief History of OAuth ü  OAuth 2 ü  OAuth 2 Dig A Little Deeper ü  Flows in OAuth ü  Deep Dive Into Authorization Code Flow ü  Deep Dive Into Implicit Grant ü  A Closer Look at Refresh Tokens ü  End Notes on OAuth then Demo and Lab ü  A Problem With OAuth? ü  OpenID Connect ü  The Details of OpenID Connect ü  PingFederate and OpenID Connect ü  Demo and Lab Ø  Some Additional Stuff

7/8/13

48


1. OAuth Scope Adapter Selector


OAuth Scope Adapter Selector

7/8/13

49


OAuth Scope Adapter Selector


2. JWT – JSON Web Tokens

•  With JWT tokens, the access token payload is application-readable

7/8/13

50


JWT – Define Cert Key to Be Used to Sign Token


JWT – JWS Algorithm To Use

HMAC means a Symmetric key will be used. RSA means an Asymmetric (certificate private/public) key will be used.

7/8/13

51


JWT – Active Signing Certificate Key ID


JWT – Define Access Token Attributes like usual

7/8/13

52


THANK YOU – QUESTIONS?

Technology

CIS13: Bootcamp: Ping Identity OAuth and OpenID Connect In Action with PingFederate Hands-On