< draft-bradley-oauth-pop-key-distribution-00.txt   draft-bradley-oauth-pop-key-distribution-01.txt >
Network Working Group J. Bradley Network Working Group J. Bradley
Internet-Draft Ping Identity Internet-Draft Ping Identity
Intended status: Standards Track P. Hunt Intended status: Standards Track P. Hunt
Expires: October 24, 2014 Oracle Corporation Expires: December 28, 2014 Oracle Corporation
M. Jones M. Jones
Microsoft Microsoft
H. Tschofenig H. Tschofenig
ARM Limited ARM Limited
April 22, 2014 June 26, 2014
OAuth 2.0 Proof-of-Possession: Authorization Server to Client Key OAuth 2.0 Proof-of-Possession: Authorization Server to Client Key
Distribution Distribution
draft-bradley-oauth-pop-key-distribution-00.txt draft-bradley-oauth-pop-key-distribution-01.txt
Abstract Abstract
RFC 6750 specified the bearer token concept for securing access to RFC 6750 specified the bearer token concept for securing access to
protected resources. Bearer tokens need to be protected in transit protected resources. Bearer tokens need to be protected in transit
as well as at rest since the security model is based on proof-of- as well as at rest. When a client requests access to a protected
possession. resource it hands-over the bearer token to the resource server.
The OAuth 2.0 Proof-of-Possession security concept extends bearer The OAuth 2.0 Proof-of-Possession security concept extends bearer
token security and requires the client to demonstrate possession of a token security and requires the client to demonstrate possession of a
key when accessing a protected resource. key when accessing a protected resource.
This document describes how the client obtains this keying material This document describes how the client obtains this keying material
from the authorization server. from the authorization server.
Status of This Memo Status of This Memo
skipping to change at page 1, line 46 skipping to change at page 1, line 46
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 24, 2014. This Internet-Draft will expire on December 28, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 49 skipping to change at page 2, line 49
10.2. Informative References . . . . . . . . . . . . . . . . . 16 10.2. Informative References . . . . . . . . . . . . . . . . . 16
Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 17 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 17
A.1. 'aud' Syntax . . . . . . . . . . . . . . . . . . . . . . 17 A.1. 'aud' Syntax . . . . . . . . . . . . . . . . . . . . . . 17
A.2. 'key' Syntax . . . . . . . . . . . . . . . . . . . . . . 17 A.2. 'key' Syntax . . . . . . . . . . . . . . . . . . . . . . 17
A.3. 'alg' Syntax . . . . . . . . . . . . . . . . . . . . . . 17 A.3. 'alg' Syntax . . . . . . . . . . . . . . . . . . . . . . 17
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17
1. Introduction 1. Introduction
The work on additional security mechanisms beyond OAuth 2.0 bearer The work on additional security mechanisms beyond OAuth 2.0 bearer
tokens [11] is motivated in [17], which also outlines use cases, tokens [12] is motivated in [17], which also outlines use cases,
requirements and an architecture. This document defines the ability requirements and an architecture. This document defines the ability
for the client indicate support for this functionality and to obtain for the client indicate support for this functionality and to obtain
keying material from the authorization server. As an outcome of the keying material from the authorization server. As an outcome of the
exchange between the client and the authorization server is an access exchange between the client and the authorization server is an access
token that is bound to keying material. Clients that access token that is bound to keying material. Clients that access
protected resources then need to demonstrate knowledge of the secret protected resources then need to demonstrate knowledge of the secret
key that is bound to the access token. key that is bound to the access token.
To best describe the scope of this specification, the OAuth 2.0 To best describe the scope of this specification, the OAuth 2.0
protocol exchange sequence is shown in Figure 1. The extension protocol exchange sequence is shown in Figure 1. The extension
skipping to change at page 3, line 34 skipping to change at page 3, line 34
| | +---------------+ | | +---------------+
| | | |
| | +---------------+ | | +---------------+
| |--(E)----- Access Token ------>| Resource | | |--(E)----- Access Token ------>| Resource |
| | | Server | | | | Server |
| |<-(F)--- Protected Resource ---| | | |<-(F)--- Protected Resource ---| |
+--------+ +---------------+ +--------+ +---------------+
Figure 1: Abstract OAuth 2.0 Protocol Flow Figure 1: Abstract OAuth 2.0 Protocol Flow
OAuth 2.0 [2] offers different ways to obtain an access token, namely In OAuth 2.0 [2] access tokens can be obtained via authorization
using authorization grants and using a refresh token. The core OAuth grants and using refresh tokens. The core OAuth specification
specification defines four authorization grants, see Section 1.3 of defines four authorization grants, see Section 1.3 of [2], and [14]
[2], and [14] adds an assertion-based authorization grant to that adds an assertion-based authorization grant to that list. The token
list. The token endpoint, which is described in Section 3.2 of [2], endpoint, which is described in Section 3.2 of [2], is used with
is used with every authorization grant except for the implicit grant every authorization grant except for the implicit grant type. In the
type. In the implicit grant type the access token is issued implicit grant type the access token is issued directly.
directly.
This document extends the functionality of the token endpoint, i.e., This document extends the functionality of the token endpoint, i.e.,
the protocol exchange between the client and the authorization the protocol exchange between the client and the authorization
server, to allow keying material to be bound to an access token. Two server, to allow keying material to be bound to an access token. Two
types of keying material can be bound to an access token, namely types of keying material can be bound to an access token, namely
symmetric keys and asymmetric keys. Conveying symmetric keys from symmetric keys and asymmetric keys. Conveying symmetric keys from
the authorization server to the client is described in Section 4 and the authorization server to the client is described in Section 4 and
the procedure for dealing with asymmetric keys is described in the procedure for dealing with asymmetric keys is described in
Section 5. Section 5.
QUESTION: This document focuses on binding the keys to access tokens
only. Keys can, however, also be bound to refresh tokens and to the
authorization code, as described in [15]. Should the scope of this
document be extended?
2. Terminology 2. Terminology
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
specification are to be interpreted as described in [1]. specification are to be interpreted as described in [1].
Session Key: Session Key:
The term session key refers to fresh and unique keying material The term session key refers to fresh and unique keying material
established between the client and the resource server. This established between the client and the resource server. This
skipping to change at page 4, line 42 skipping to change at page 4, line 37
JWK: JSON Web Key (JWK) [5] JWK: JSON Web Key (JWK) [5]
JWE: JSON Web Encryption (JWE) [8] JWE: JSON Web Encryption (JWE) [8]
3. Audience 3. Audience
When an authorization server creates an access token, according to When an authorization server creates an access token, according to
the PoP security architecture [17], it may need to know which the PoP security architecture [17], it may need to know which
resource server will process it. This information is necessary when resource server will process it. This information is necessary when
the authorization server applies integrity protection to the JWT the authorization server applies integrity protection to the JWT
using a symmetric key and has to selected a corresponding key based using a symmetric key and has to selected the key of the resource
on the resource server that has to verify the signature. The server that has to verify it. The authorization server also requires
authorization server also requires this audience information if it this audience information if it has to encrypt a symmetric session
embeds a session key inside the access token and if this symmetric key inside the access token using a long-term symmetric key.
key is encrypted with a symmetric key.
This section defines a new header that is used by the client to This section defines a new header that is used by the client to
indicate what protected resource at which resource server it wants to indicate what protected resource at which resource server it wants to
access. This information may subsequently also communicated by the access. This information may subsequently also communicated by the
authorization server securely to the resource server, for example authorization server securely to the resource server, for example
within the audience field of the access token. within the audience field of the access token.
QUESTION: With the use of public key cryptography the client might QUESTION: A benefit of asymmetric cryptography is to allow clients to
request a PoP token for use with multiple resource servers. The request a PoP token for use with multiple resource servers. The
audience parameter could carry an array of values. Is this downside of that approach is linkability since different resource
desirable? servers will be able to link individual requests to the same client.
(The same is true if the a single public key is linked with PoP
tokens used with different resource servers.) Nevertheless, to
support the functionality the audience parameter could carry an array
of values. Is this desirable?
3.1. Audience Parameter 3.1. Audience Parameter
The client constructs the access token request to the token endpoint The client constructs the access token request to the token endpoint
by adding the 'aud' parameter using the "application/x-www-form- by adding the 'aud' parameter using the "application/x-www-form-
urlencoded" format with a character encoding of UTF-8 in the HTTP urlencoded" format with a character encoding of UTF-8 in the HTTP
request entity-body. request entity-body.
The URI included in the aud parameter MUST be an absolute URI as The URI included in the aud parameter MUST be an absolute URI as
defined by Section 4.3 of [3]. It MAY include an "application/x-www- defined by Section 4.3 of [3]. It MAY include an "application/x-www-
form-urlencoded" formatted query component (Section 3.4 of [3] ). form-urlencoded" formatted query component (Section 3.4 of [3] ).
The URI MUST NOT include a fragment component. The URI MUST NOT include a fragment component.
The ABNF syntax for the 'aud' element is defined in Appendix A. The ABNF syntax for the 'aud' element is defined in Appendix A.
3.2. Processing Instructions 3.2. Processing Instructions
Step (0): As an initial step the client typically determines the Step (0): As an initial step the client typically determines the
resource server it wants to interact with, for example, as part of resource server it wants to interact with. This may, for example,
a discovery procedure. happen as part of a discovery procedure or via manual
configuration.
Step (1): The client starts the OAuth 2.0 protocol interaction Step (1): The client starts the OAuth 2.0 protocol interaction
based on the selected grant type. based on the selected grant type.
Step (2): When the client interacts with the token endpoint to Step (2): When the client interacts with the token endpoint to
obtain an access token it MUST populate the newly defined obtain an access token it MUST populate the newly defined
'audience' parameter with the information obtained in step (0). 'audience' parameter with the information obtained in step (0).
Step (2): The authorization server who obtains the request from Step (2): The authorization server who obtains the request from
the client needs to parse it to determine whether the provided the client needs to parse it to determine whether the provided
skipping to change at page 6, line 4 skipping to change at page 5, line 51
relationship with. If the authorization server fails to parse the relationship with. If the authorization server fails to parse the
provided value it MUST reject the request using an error response provided value it MUST reject the request using an error response
with the error code "invalid_request". If the authorization with the error code "invalid_request". If the authorization
server does not consider the resource server acceptable it MUST server does not consider the resource server acceptable it MUST
return an error response with the error code "access_denied". In return an error response with the error code "access_denied". In
both cases additional error information may be provided via the both cases additional error information may be provided via the
error_description, and the error_uri parameters. If the request error_description, and the error_uri parameters. If the request
has, however, been verified successfully then the authorization has, however, been verified successfully then the authorization
server MUST include the audience claim into the access token with server MUST include the audience claim into the access token with
the value copied from the audience field provided by the client. the value copied from the audience field provided by the client.
In case the access token is encoded using the JSON Web Token In case the access token is encoded using the JSON Web Token
format [9] the "aud" claim MUST be used. The access token MUST be format [9] the "aud" claim MUST be used. The access token, if
protected against modification by either using a digital signature passed per value, MUST be protected against modification by either
or a keyed message digest. The authorization server returns the using a digital signature or a keyed message digest. Access
tokens can also be passed by reference, which then requires the
token introspection endpoint (or a similiar, proprietary protocol
mechanism) to be used. The authorization server returns the
access token to the client, as specified in [2]. access token to the client, as specified in [2].
Subsequent steps for the interaction between the client and the Subsequent steps for the interaction between the client and the
resource server are beyond the scope of this document. resource server are beyond the scope of this document.
4. Symmetric Key Transport 4. Symmetric Key Transport
4.1. Client-to-AS Request 4.1. Client-to-AS Request
In case a symmetric key shall be bound to an access token the In case a symmetric key shall be bound to an PoP token the following
following procedure is applicable. In the request message from the procedure is applicable. In the request message from the OAuth
OAuth client to the OAuth authorization server the following client to the OAuth authorization server the following parameters MAY
parameters MAY be included: be included:
token_type: OPTIONAL. See Section 6 for more details. token_type: OPTIONAL. See Section 6 for more details.
alg: OPTIONAL. See Section 6 for more details. alg: OPTIONAL. See Section 6 for more details.
These two new parameters are optional in the case where the These two new parameters are optional in the case where the
authorization server has prior knowledge of the capabilities of the authorization server has prior knowledge of the capabilities of the
client otherwise these two parameters are required. client otherwise these two parameters are required. This prior
knowledge may, for example, be set by the use of a dynamic client
registration protocol exchange.
QUESTION: Should we register these two parameters for use with the
dynamic client registration protocol?
For example, the client makes the following HTTP request using TLS For example, the client makes the following HTTP request using TLS
(extra line breaks are for display purposes only). (extra line breaks are for display purposes only).
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded;charset=UTF-8 Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=authorization_code grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA &code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&token_type=pop &token_type=pop
&alg=HS256 &alg=HS256
Example Request to the Authorization Server Example Request to the Authorization Server
4.2. Client-to-AS Response 4.2. Client-to-AS Response
If the access token request is valid and authorized, the If the access token request has been successfully verified by the
authorization server issues an access token and optionally a refresh authorization server and the client is authorized to obtain a PoP
token. If the request client authentication failed or is invalid, token for the indicated resource server, the authorization server
the authorization server returns an error response as described in issues an access token and optionally a refresh token. If client
Section 5.2 of [2]. authentication failed or is invalid, the authorization server returns
an error response as described in Section 5.2 of [2].
The authorization server MUST include an access token and a 'key' The authorization server MUST include an access token and a 'key'
element in a successful response. The 'key' parameter either element in a successful response. The 'key' parameter either
contains a plain JWK structure or a JWK encrypted with a JWE. The contains a plain JWK structure or a JWK encrypted with a JWE. The
difference between the two approaches is the following: difference between the two approaches is the following:
Plain JWK: If the JWK container is placed in the 'key' element then Plain JWK: If the JWK container is placed in the 'key' element then
the security of the overall PoP architecture relies on Transport the security of the overall PoP architecture relies on Transport
Layer Security protection between the authorization server and the Layer Security (TLS) between the authorization server and the
client. Figure 2 illustrates an example response using a plain client. Figure 2 illustrates an example response using a plain
JWK for key transport from the authorization server to the client. JWK for key transport from the authorization server to the client.
JWK protected by JWE: If the JWK container is protected by a JWE JWK protected by a JWE: If the JWK container is protected by a JWE
then additional security protection at the application layer is then additional security protection at the application layer is
provided between the authorization server and the client beyond provided between the authorization server and the client beyond
the use of TLS. This approach is a reasonable choice, for the use of TLS. This approach is a reasonable choice, for
example, when a trusted security module is available on the client example, when a hardware security module is available on the
device and the confidentiality protection is offered directly to client device and confidentiality protection can be offered
this trusted element. directly to this hardware security module.
Note that there are potentially two JSON-encoded structures in the Note that there are potentially two JSON-encoded structures in the
response, namely the access token that may utilize the JWT format and response, namely the access token (with the recommended JWT encoding)
the actual key transport mechanism itself. and the actual key transport mechanism itself. Note, however, that
the two structures serve a different purpose and are consumed by
different parites. The access token is created by the authorization
server and processed by the resource server (and opaque to the
client) whereas the key transport payload is created by the
authorization server and processed by the client; it is never
forwarded to the resource server.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{ {
"access_token":"SlAV32hkKG ... "access_token":"SlAV32hkKG ...
... (remainder of JWT omitted for brevity)", (remainder of JWT omitted for brevity;
JWT contains JWK in the cnf claim)",
"token_type":"pop", "token_type":"pop",
"expires_in":3600, "expires_in":3600,
"refresh_token":"8xLOxBtZp8", "refresh_token":"8xLOxBtZp8",
"key":"eyJhbGciOiJSU0ExXzUi ... "key":"eyJhbGciOiJSU0ExXzUi ...
... (remainder of JWK/JWE omitted for brevity)" (remainder of plain JWK omitted for brevity)"
} }
Figure 2: Example: Response from the Authorization Server (Symmetric Figure 2: Example: Response from the Authorization Server (Symmetric
Variant) Variant)
The content of the key parameter, which is a JWK in our example, is The content of the key parameter, which is a JWK in our example, is
shown in Figure 3. shown in Figure 3.
{ {
"kty":"oct", "kty":"oct",
"kid":"id123",
"alg":"HS256", "alg":"HS256",
"k":"ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE" "k":"ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE"
} }
Figure 3: Example: Key Transport to Client via a JWK Figure 3: Example: Key Transport to Client via a JWK
The content of the 'access_token' in JWT format contains the 'cnf' The content of the 'access_token' in JWT format contains the 'cnf'
element, as shown in Figure 4. The digital signature or the keyed (confirmation) claim, as shown in Figure 4. The confirmation claim
message digest offering integrity protection is not shown in this is defined in [10]. The digital signature or the keyed message
example but must be present in a real deployment to mitigate a number digest offering integrity protection is not shown in this example but
of security threats. MUST be present in a real deployment to mitigate a number of security
threats. Those security threats are described in [17].
The JWK in the key element of the response from the authorization The JWK in the key element of the response from the authorization
server shown in Figure 2 contains the same session key as the JWK server, as shown in Figure 2, contains the same session key as the
inside the access token shown in Figure 4 but is, in this example, JWK inside the access token, as shown in Figure 4. It is, in this
protected by TLS and transmitted from the authorization server to the example, protected by TLS and transmitted from the authorization
client (for processing by the client). server to the client (for processing by the client).
{ {
"iss": "https://server.example.com", "iss": "https://server.example.com",
"sub": "24400320", "sub": "24400320",
"aud": "s6BhdRkqt3", "aud": "s6BhdRkqt3",
"nonce": "n-0S6_WzA2Mj", "nonce": "n-0S6_WzA2Mj",
"exp": 1311281970, "exp": 1311281970,
"iat": 1311280970, "iat": 1311280970,
"cnf":{ "cnf":{
"jwk": "jwk":
"JDLUhTMjU2IiwiY3R5Ijoi ... "JDLUhTMjU2IiwiY3R5Ijoi ...
... (remainder of JWE omitted for brevity)" (remainder of JWK protected by JWE omitted for brevity)"
} }
} }
Figure 4: Example: Access Token in JWT Format Figure 4: Example: Access Token in JWT Format
Note: The JWK content inside the access token is meant for Note: When the JWK inside the access token contains a symmetric key
consumption by the resource server. It MUST be confidentiality it MUST be confidentiality protected using a JWE to maintain the
protected using a JWE. security goals of the PoP architecture, as described in [17] since
content is meant for consumption by the selected resource server
only.
This document does not impose requirements on the encoding of the Note: This document does not impose requirements on the encoding of
access token. The examples used in this document make use of the JWT the access token. The examples used in this document make use of the
structure since this is the only standardized format if access tokens JWT structure since this is the only standardized format.
are conveyed per value between the authorization server, the client,
and the resource server.
If the access token is only a handle to the access token itself then If the access token is only a reference then a look-up by the
a look-up by the resource server is needed, as described in the token resource server is needed, as described in the token introspection
introspection specification [18]. specification [18].
5. Asymmetric Key Transport 5. Asymmetric Key Transport
5.1. Client-to-AS Request 5.1. Client-to-AS Request
In case an asymmetric key shall be bound to an access token then the In case an asymmetric key shall be bound to an access token then the
following procedure is applicable. In the request message from the following procedure is applicable. In the request message from the
OAuth client to the OAuth authorization server the following OAuth client to the OAuth authorization server the request MAY
parameters MAY include the following parameters: include the following parameters:
token_type: OPTIONAL. See Section 6 for more details. token_type: OPTIONAL. See Section 6 for more details.
alg: OPTIONAL. See Section 6 for more details. alg: OPTIONAL. See Section 6 for more details.
key: OPTIONAL. This field contains information about the public key key: OPTIONAL. This field contains information about the public key
the client would like to bind to the access token in the JSON the client would like to bind to the access token in the JWK
Web Key format. If the client does not provide a public key format. If the client does not provide a public key then the
then the authorization server MUST create an ephemeral key pair authorization server MUST create an ephemeral key pair
(considering the profile information provided by the client) or (considering the information provided by the client) or
alternative respond with an error message. alternatively respond with an error message. The client may
also convey the fingerprint of the public key to the
authorization server instead of passing the entire public key
along (to conserve bandwidth). [11] defines a way to compute a
thumbprint for a JWK and to embedd it within the JWK format.
The token_type and the alg parameters are optional in the case where The 'token_type' and the 'alg' parameters are optional in the case
the authorization server has prior knowledge of the capabilities of where the authorization server has prior knowledge of the
the client otherwise these two parameters are required. capabilities of the client otherwise these two parameters are
required.
For example, the client makes the following HTTP request using TLS For example, the client makes the following HTTP request using TLS
(extra line breaks are for display purposes only) shown in Figure 5. (extra line breaks are for display purposes only) shown in Figure 5.
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded;charset=UTF-8 Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=authorization_code grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA &code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&token_type=pop &token_type=pop
&alg=RS256 &alg=RS256
&key=eyJhbGciOiJSU0ExXzUi ... &key=eyJhbGciOiJSU0ExXzUi ...
... (remainder of JWK omitted for brevity) (remainder of JWK omitted for brevity)
Figure 5: Example Request to the Authorization Server (Asymmetric Key Figure 5: Example Request to the Authorization Server (Asymmetric Key
Variant) Variant)
The content of the key parameter contains the RSA public key the As shown in Figure 6 the content of the 'key' parameter contains the
client would like to associate with the access token, as shown in RSA public key the client would like to associate with the access
Figure 6. token.
{"kty":"RSA", {"kty":"RSA",
"n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs 4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2 tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2
QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI
SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb
w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
"e":"AQAB", "e":"AQAB",
"alg":"RS256", "alg":"RS256",
"kid":"client@example.com"} "kid":"id123"}
Figure 6: Client Providing Public Key to Authorization Server Figure 6: Client Providing Public Key to Authorization Server
5.2. Client-to-AS Response 5.2. Client-to-AS Response
If the access token request is valid and authorized, the If the access token request is valid and authorized, the
authorization server issues an access token and optionally a refresh authorization server issues an access token and optionally a refresh
token. If the request client authentication failed or is invalid, token. If the request client authentication failed or is invalid,
the authorization server returns an error response as described in the authorization server returns an error response as described in
Section 5.2 of [2]. Section 5.2 of [2].
skipping to change at page 12, line 20 skipping to change at page 12, line 22
"cnf":{ "cnf":{
"jwk":{"kty":"RSA", "jwk":{"kty":"RSA",
"n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs 4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2 tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2
QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI
SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb
w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
"e":"AQAB", "e":"AQAB",
"alg":"RS256", "alg":"RS256",
"kid":"client@example.com"} "kid":"id123"}
} }
} }
Figure 8: Example: Access Token Structure (Asymmetric Variant) Figure 8: Example: Access Token Structure (Asymmetric Variant)
Note: In this example there is no need for the authorization server Note: In this example there is no need for the authorization server
to convey further keying material to the client. to convey further keying material to the client since the client is
already in possession of the private RSA key.
6. Token Types and Algorithms 6. Token Types and Algorithms
To allow clients to indicate support for specific token types and To allow clients to indicate support for specific token types and
respective algorithms they need to interact with authorization respective algorithms they need to interact with authorization
servers. They can either provide this information out-of-band, for servers. They can either provide this information out-of-band, for
example, via pre-configuration or up-front via the dynamic client example, via pre-configuration or up-front via the dynamic client
registration protocol [16]. registration protocol [16].
The value in the 'alg' parameter together with value from the The value in the 'alg' parameter together with value from the
'token_type' parameter allow the client to indicate the supported 'token_type' parameter allow the client to indicate the supported
algorithms for a given token type. The token type refers to the algorithms for a given token type. The token type refers to the
specification used by the client to interact with the resource server specification used by the client to interact with the resource server
to demonstrate possession of the key. The alg parameter provides to demonstrate possession of the key. The 'alg' parameter provides
further information about the algorithm, such as whether a symmetric further information about the algorithm, such as whether a symmetric
or an asymmetric crypto-system is used. Hence, a client supporting a or an asymmetric crypto-system is used. Hence, a client supporting a
specific token type also knows how to populate the values to the alg specific token type also knows how to populate the values to the
parameter. 'alg' parameter.
The value for the token type MUST be taken from the 'OAuth Access The value for the 'token_type' MUST be taken from the 'OAuth Access
Token Types' registry created by [2]. Token Types' registry created by [2].
This document does not register a new value for the Access Token This document does not register a new value for the OAuth Access
Types registry nor does it define values to be used for the alg Token Types registry nor does it define values to be used for the
parameter. Instead this is the responsibility of specifications 'alg' parameter since this is the responsibility of specifications
defining the mechanism for clients interacting with resource servers, defining the mechanism for clients interacting with resource servers.
such as [19]. An example of such specification can be found in [19].
The values in the alg parameter are case-sensitive. If the client The values in the 'alg' parameter are case-sensitive. If the client
supports more than one algorithm then each individual value MUST be supports more than one algorithm then each individual value MUST be
separated by a space. separated by a space.
7. Security Considerations 7. Security Considerations
[17] describes the architecture for the OAuth 2.0 proof-of-possession [17] describes the architecture for the OAuth 2.0 proof-of-possession
security architecture, including use cases, threats, and security architecture, including use cases, threats, and
requirements. This requirements describes one solution component of requirements. This requirements describes one solution component of
that architecture, namely the mechanism for the client to interact that architecture, namely the mechanism for the client to interact
with the authorization server to either obtain a symmetric key from with the authorization server to either obtain a symmetric key from
skipping to change at page 14, line 8 skipping to change at page 14, line 15
associated key. associated key.
The authorization server MUST offer confidentiality protection for The authorization server MUST offer confidentiality protection for
any interactions with the client. This step is extremely important any interactions with the client. This step is extremely important
since the client will obtain the session key from the authorization since the client will obtain the session key from the authorization
server for use with a specific access token. Not using server for use with a specific access token. Not using
confidentiality protection exposes this secret (and the access token) confidentiality protection exposes this secret (and the access token)
to an eavesdropper thereby making the OAuth 2.0 proof-of-possession to an eavesdropper thereby making the OAuth 2.0 proof-of-possession
security model completely insecure. OAuth 2.0 [2] relies on TLS to security model completely insecure. OAuth 2.0 [2] relies on TLS to
offer confidentiality protection and additional protection can be offer confidentiality protection and additional protection can be
applied using the JSON Web Key (JWK) [5] offered security mechanism, applied using the JWK [5] offered security mechanism, which would add
which would add an additional layer of protection on top of TLS for an additional layer of protection on top of TLS for cases where the
cases where the keying material is conveyed, for example, to a keying material is conveyed, for example, to a hardware security
hardware security module. Which version(s) of TLS ought to be module. Which version(s) of TLS ought to be implemented will vary
implemented will vary over time, and depend on the widespread over time, and depend on the widespread deployment and known security
deployment and known security vulnerabilities at the time of vulnerabilities at the time of implementation. At the time of this
implementation. At the time of this writing, TLS version 1.2 [4] is writing, TLS version 1.2 [4] is the most recent version. The client
the most recent version. The client MUST validate the TLS MUST validate the TLS certificate chain when making requests to
certificate chain when making requests to protected resources, protected resources, including checking the validity of the
including checking the validity of the certificate. certificate.
Similarly to the security recommendations for the bearer token Similarly to the security recommendations for the bearer token
specification [11] developers MUST ensure that the ephemeral specification [12] developers MUST ensure that the ephemeral
credentials (i.e., the private key or the session key) is not leaked credentials (i.e., the private key or the session key) is not leaked
to third parties. An adversary in possession of the ephemeral to third parties. An adversary in possession of the ephemeral
credentials bound to the access token will be able to impersonate the credentials bound to the access token will be able to impersonate the
client. Be aware that this is a real risk with many smart phone app client. Be aware that this is a real risk with many smart phone app
and Web development environments. and Web development environments.
Clients can at any time request a new proof-of-possession capable Clients can at any time request a new proof-of-possession capable
access token. Using a refresh token to regularly request new access access token. Using a refresh token to regularly request new access
tokens that are bound to fresh and unique keys is important. Keeping tokens that are bound to fresh and unique keys is important. Keeping
the lifetime of the access token short allows the authorization the lifetime of the access token short allows the authorization
server to use shorter key sizes, which translate to a performance server to use shorter key sizes, which translate to a performance
benefit for the client and for the resource server. Shorter keys benefit for the client and for the resource server. Shorter keys
also lead to shorter messages (particularly with asymmetric keying also lead to shorter messages (particularly with asymmetric keying
material). material).
When authorization servers bind symmetric keys to access tokens then When authorization servers bind symmetric keys to access tokens then
they MUST scope these access tokens to a specific resource server. they SHOULD scope these access tokens to a specific permissions.
8. IANA Considerations 8. IANA Considerations
This specification registers the following parameters in the OAuth This specification registers the following parameters in the OAuth
Parameters Registry established by [2]. Parameters Registry established by [2].
Parameter name: alg Parameter name: alg
Parameter usage location: token request, token response, Parameter usage location: token request, token response,
authorization response authorization response
Change controller: IETF Change controller: IETF
Specification document(s): [[ this document ]] Specification document(s): [[ this document ]]
Related information: None Related information: None
Parameter name: key Parameter name: key
Parameter usage location: token request, token response, Parameter usage location: token request, token response,
authorization response authorization response
Change controller: IETF Change controller: IETF
Specification document(s): [[ this document ]] Specification document(s): [[ this document ]]
skipping to change at page 15, line 29 skipping to change at page 15, line 36
Parameter usage location: token request Parameter usage location: token request
Change controller: IETF Change controller: IETF
Specification document(s): [[This document.] Specification document(s): [[This document.]
Related information: None Related information: None
9. Acknowledgements 9. Acknowledgements
Add your name here. We would like to thank Chuck Mortimore for his review comments.
10. References 10. References
10.1. Normative References 10.1. Normative References
[1] Bradner, S., "Key words for use in RFCs to Indicate [1] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[2] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC [2] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC
6749, October 2012. 6749, October 2012.
[3] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [3] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005. 3986, January 2005.
[4] Dierks, T. and E. Rescorla, "The Transport Layer Security [4] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[5] Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- [5] Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web-
key-25 (work in progress), March 2014. key-29 (work in progress), June 2014.
[6] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [6] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draft-ietf-jose-json-web-signature-25 Signature (JWS)", draft-ietf-jose-json-web-signature-29
(work in progress), March 2014. (work in progress), June 2014.
[7] Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- [7] Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose-
json-web-algorithms-25 (work in progress), March 2014. json-web-algorithms-29 (work in progress), June 2014.
[8] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", [8] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
draft-ietf-jose-json-web-encryption-25 (work in progress), draft-ietf-jose-json-web-encryption-29 (work in progress),
March 2014. June 2014.
[9] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [9] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", draft-ietf-oauth-json-web-token-19 (work in (JWT)", draft-ietf-oauth-json-web-token-23 (work in
progress), March 2014. progress), June 2014.
[10] Jones, M., Bradley, J., and H. Tschofenig, "Proof-Of- [10] Jones, M., Bradley, J., and H. Tschofenig, "Proof-Of-
Possession Semantics for JSON Web Tokens (JWTs)", draft- Possession Semantics for JSON Web Tokens (JWTs)", draft-
jones-oauth-proof-of-possession-00 (work in progress), jones-oauth-proof-of-possession-00 (work in progress),
April 2014. April 2014.
[11] Jones, M., "JSON Web Key (JWK) Thumbprint", draft-jones-
jose-jwk-thumbprint-00 (work in progress), April 2014.
10.2. Informative References 10.2. Informative References
[11] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization [12] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, October 2012. Framework: Bearer Token Usage", RFC 6750, October 2012.
[12] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005.
[13] Crocker, D. and P. Overell, "Augmented BNF for Syntax [13] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. Specifications: ABNF", STD 68, RFC 5234, January 2008.
[14] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, [14] Campbell, B., Mortimore, C., Jones, M., and Y. Goland,
"Assertion Framework for OAuth 2.0 Client Authentication "Assertion Framework for OAuth 2.0 Client Authentication
and Authorization Grants", draft-ietf-oauth-assertions-15 and Authorization Grants", draft-ietf-oauth-assertions-16
(work in progress), March 2014. (work in progress), April 2014.
[15] Sakimura, N., Bradley, J., and N. Agarwal, "OAuth [15] Sakimura, N., Bradley, J., and N. Agarwal, "OAuth
Symmetric Proof of Posession for Code Extension", draft- Symmetric Proof of Posession for Code Extension", draft-
sakimura-oauth-tcse-03 (work in progress), April 2014. sakimura-oauth-tcse-03 (work in progress), April 2014.
[16] Richer, J., Jones, M., Bradley, J., Machulak, M., and P. [16] Richer, J., Jones, M., Bradley, J., Machulak, M., and P.
Hunt, "OAuth 2.0 Dynamic Client Registration Core Hunt, "OAuth 2.0 Dynamic Client Registration Protocol",
Protocol", draft-ietf-oauth-dyn-reg-16 (work in progress), draft-ietf-oauth-dyn-reg-17 (work in progress), May 2014.
February 2014.
[17] Hunt, P., Richer, J., Mills, W., Mishra, P., and H. [17] Hunt, P., Richer, J., Mills, W., Mishra, P., and H.
Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security
Architecture", draft-hunt-oauth-pop-architecture-00 (work Architecture", draft-hunt-oauth-pop-architecture-01 (work
in progress), April 2014. in progress), April 2014.
[18] Richer, J., "OAuth Token Introspection", draft-richer- [18] Richer, J., "OAuth Token Introspection", draft-richer-
oauth-introspection-04 (work in progress), May 2013. oauth-introspection-04 (work in progress), May 2013.
[19] Richer, J., "A Method for Signing an HTTP Requests for [19] Richer, J., Bradley, J., and H. Tschofenig, "A Method for
OAuth", April 2014. Signing an HTTP Requests for OAuth", draft-richer-oauth-
signed-http-request-01 (work in progress), April 2014.
Appendix A. Augmented Backus-Naur Form (ABNF) Syntax Appendix A. Augmented Backus-Naur Form (ABNF) Syntax
This section provides Augmented Backus-Naur Form (ABNF) syntax This section provides Augmented Backus-Naur Form (ABNF) syntax
descriptions for the elements defined in this specification using the descriptions for the elements defined in this specification using the
notation of [13]. notation of [13].
A.1. 'aud' Syntax A.1. 'aud' Syntax
The ABNF syntax is defined as follows where by the "URI-reference" The ABNF syntax is defined as follows where by the "URI-reference"
 End of changes. 62 change blocks. 
138 lines changed or deleted 159 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/