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: jdasilva@pingidentity.com
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?
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
•  Demo and Lab
•  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
ü  A Brief History of OAuth
Ø  OAuth 2
•  Demo and Lab

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
ü  OAuth 2
Ø  OAuth 2 Dig A Little Deeper
•  Demo and Lab

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
–  email
–  profile
–  phone
–  address
Some Scope Examples

7/8/13
15
Bootcamp Agenda
ü  OAuth 2
ü  OAuth 2 Dig A Little Deeper
Ø  Flows in OAuth
•  Demo and Lab
•  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
ü  OAuth 2
ü  Flows in OAuth
Ø  Deep Dive Into Authorization Code Flow
•  Demo and Lab

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
!
•  Authorization page (default template):
OAuth client
details
Requested
scope

7/8/13
20
•  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)
•  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
•  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.
•  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)
"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=qANLTbu17rk17lPszecHRi7rqJt46pG1qx0
nTAqXWH
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:
"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
ü  OAuth 2
ü  Deep Dive Into Authorization Code Flow
Ø  Deep Dive Into Implicit Grant
•  Demo and Lab

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&redire
ct_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
ü  OAuth 2
ü  Deep Dive Into Implicit Grant
Ø  A Closer Look at Refresh Tokens
•  Demo and Lab

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
ü  OAuth 2
ü  A Closer Look at Refresh Tokens
Ø  End Notes on OAuth then Demo and Lab
•  Demo and Lab

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
ü  OAuth 2
ü  End Notes on OAuth then Demo and Lab
Ø  A Problem With OAuth?
•  Demo and Lab
•  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
ü  OAuth 2
ü  A Problem With OAuth?
Ø  OpenID Connect
•  Demo and Lab
•  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
ü  OAuth 2
ü  OpenID Connect
Ø  The Details of OpenID Connect
•  Demo and Lab

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": "janedoe@example.com",
"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","ES3
84","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": "janedoe@example.com",
}
OpenID Connect – Basic Client Profile
Web
client
UserInfo
Endpoint
AuthZ
Endpoint
6
7

7/8/13
41
Bootcamp Agenda
ü  OAuth 2
ü  The Details of OpenID Connect
Ø  PingFederate and OpenID Connect
•  Demo and Lab
•  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
ü  OAuth 2
ü  PingFederate and OpenID Connect
Ø  Demo and Lab

7/8/13
47
Demo and Lab
Bootcamp Agenda
ü  OAuth 2
ü  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?

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

More Related Content

What's hot (20)

Viewers also liked (20)

Similar to CIS13: Bootcamp: Ping Identity OAuth and OpenID Connect In Action with PingFederate Hands-On (20)

More from CloudIDSummit (20)

Recently uploaded (20)

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