rfc9068.original   rfc9068.txt 
OAuth Working Group V. Bertocci Internet Engineering Task Force (IETF) V. Bertocci
Internet-Draft Auth0 Request for Comments: 9068 Auth0
Intended status: Standards Track May 25, 2021 Category: Standards Track October 2021
Expires: November 26, 2021 ISSN: 2070-1721
JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens
draft-ietf-oauth-access-token-jwt-13
Abstract Abstract
This specification defines a profile for issuing OAuth 2.0 access This specification defines a profile for issuing OAuth 2.0 access
tokens in JSON web token (JWT) format. Authorization servers and tokens in JSON Web Token (JWT) format. Authorization servers and
resource servers from different vendors can leverage this profile to resource servers from different vendors can leverage this profile to
issue and consume access tokens in an interoperable manner. issue and consume access tokens in an interoperable manner.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on November 26, 2021. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9068.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2021 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
(https://trustee.ietf.org/license-info) in effect on the date of (https://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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction
1.1. Requirements Notation and Conventions . . . . . . . . . . 3 1.1. Requirements Notation and Conventions
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.2. Terminology
2. JWT Access Token Header and Data Structure . . . . . . . . . 4 2. JWT Access Token Header and Data Structure
2.1. Header . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Header
2.2. Data Structure . . . . . . . . . . . . . . . . . . . . . 4 2.2. Data Structure
2.2.1. Authentication Information Claims . . . . . . . . . . 5 2.2.1. Authentication Information Claims
2.2.2. Identity Claims . . . . . . . . . . . . . . . . . . . 5 2.2.2. Identity Claims
2.2.3. Authorization Claims . . . . . . . . . . . . . . . . 6 2.2.3. Authorization Claims
2.2.3.1. Claims for Authorization Outside of Delegation 2.2.3.1. Claims for Authorization Outside of Delegation
Scenarios . . . . . . . . . . . . . . . . . . . . 6 Scenarios
3. Requesting a JWT Access Token . . . . . . . . . . . . . . . . 7 3. Requesting a JWT Access Token
4. Validating JWT Access Tokens . . . . . . . . . . . . . . . . 8 4. Validating JWT Access Tokens
5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 5. Security Considerations
6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 11 6. Privacy Considerations
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 7. IANA Considerations
7.1. Media Type Registration . . . . . . . . . . . . . . . . . 12 7.1. Media Type Registration
7.1.1. Registry Content . . . . . . . . . . . . . . . . . . 12 7.1.1. Registry Content
7.2. Claims Registration . . . . . . . . . . . . . . . . . . . 13 7.2. Claims Registration
7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 13 7.2.1. Registry Content
7.2.1.1. Roles . . . . . . . . . . . . . . . . . . . . . . 13 7.2.1.1. Roles
7.2.1.2. Groups . . . . . . . . . . . . . . . . . . . . . 14 7.2.1.2. Groups
7.2.1.3. Entitlements . . . . . . . . . . . . . . . . . . 14 7.2.1.3. Entitlements
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 8. References
8.1. Normative References . . . . . . . . . . . . . . . . . . 14 8.1. Normative References
8.2. Informative References . . . . . . . . . . . . . . . . . 16 8.2. Informative References
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 16 Acknowledgements
Appendix B. Document History . . . . . . . . . . . . . . . . . . 17 Author's Address
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22
1. Introduction 1. Introduction
The original OAuth 2.0 Authorization Framework [RFC6749] The original OAuth 2.0 Authorization Framework [RFC6749]
specification does not mandate any specific format for access tokens. specification does not mandate any specific format for access tokens.
While that remains perfectly appropriate for many important While that remains perfectly appropriate for many important
scenarios, in-market use has shown that many commercial OAuth 2.0 scenarios, in-market use has shown that many commercial OAuth 2.0
implementations elected to issue access tokens using a format that implementations elected to issue access tokens using a format that
can be parsed and validated by resource servers directly, without can be parsed and validated by resource servers directly, without
further authorization server involvement. The approach is further authorization server involvement. The approach is
particularly common in topologies where the authorization server and particularly common in topologies where the authorization server and
resource server are not co-located, are not run by the same entity, resource server are not co-located, are not run by the same entity,
or are otherwise separated by some boundary. At the time of writing, or are otherwise separated by some boundary. At the time of writing,
many commercial implementations leverage the JSON Web Tokens (JWT) many commercial implementations leverage the JSON Web Token (JWT)
[RFC7519] format. [RFC7519] format.
Many vendor specific JWT access tokens share the same functional Many vendor-specific JWT access tokens share the same functional
layout, using JWT claims to convey the information needed to support layout, using JWT claims to convey the information needed to support
a common set of use cases: token validation, transporting a common set of use cases: token validation, transporting
authorization information in forms of scopes and entitlements, authorization information in the form of scopes and entitlements,
carrying identity information about the subject, and so on. The carrying identity information about the subject, and so on. The
differences are mostly confined to the claim names and syntax used to differences are mostly confined to the claim names and syntax used to
represent the same entities, suggesting that interoperability could represent the same entities, suggesting that interoperability could
be easily achieved by standardizing on a common set of claims and be easily achieved by standardizing a common set of claims and
validation rules. validation rules.
The assumption that access tokens are associated to specific The assumption that access tokens are associated with specific
information doesn't appear only in commercial implementations. information doesn't appear only in commercial implementations.
Various specifications in the OAuth 2.0 family (such as resource Various specifications in the OAuth 2.0 family (such as resource
indicators [RFC8707], OAuth 2.0 bearer token usage [RFC6750] and indicators [RFC8707], OAuth 2.0 bearer token usage [RFC6750], and
others) postulate the presence in access tokens of scoping others) postulate the presence of scoping mechanisms, such as an
mechanisms, such as an audience. The family of specifications audience, in access tokens. The family of specifications associated
associated to introspection also indirectly suggest a fundamental set with introspection also indirectly suggests a fundamental set of
of information access tokens are expected to carry or at least be information that access tokens are expected to carry or at least be
associated with. associated with.
This specification aims to provide a standardized and interoperable This specification aims to provide a standardized and interoperable
profile as an alternative to the proprietary JWT access token layouts profile as an alternative to the proprietary JWT access token layouts
going forward. Besides defining a common set of mandatory and going forward. Besides defining a common set of mandatory and
optional claims, the profile provides clear indications on how optional claims, the profile provides clear indications on how
authorization request parameters determine the content of the issued authorization request parameters determine the content of the issued
JWT access token, how an authorization server can publish metadata JWT access token, how an authorization server can publish metadata
relevant to the JWT access tokens it issues, and how a resource relevant to the JWT access tokens it issues, and how a resource
server should validate incoming JWT access tokens. server should validate incoming JWT access tokens.
Finally, this specification provides security and privacy Finally, this specification provides security and privacy
considerations meant to prevent common mistakes and anti patterns considerations meant to prevent common mistakes and anti-patterns
that are likely to occur in naive use of the JWT format to represent that are likely to occur in naive use of the JWT format to represent
access tokens. access tokens.
Please note: although both this document and [RFC7523] use JSON Web Please note: Although both this document and [RFC7523] use JSON
Tokens in the context of the OAuth2 framework, the two specifications Web Tokens in the context of the OAuth2 framework, the two
differ in both intent and mechanics. Whereas [RFC7523] defines how a specifications differ in both intent and mechanics. Whereas
JWT Bearer Token can be used to request an access token, this [RFC7523] defines how a JWT Bearer Token can be used to request an
documents describes how to encode access tokens in JWT format. access token, this document describes how to encode access tokens
in JWT format.
1.1. Requirements Notation and Conventions 1.1. Requirements Notation and Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
1.2. Terminology 1.2. Terminology
JWT access token: An OAuth 2.0 access token encoded in JWT format JWT access token: An OAuth 2.0 access token encoded in JWT format
and complying with the requirements described in this and complying with the requirements described in this
specification. specification.
This specification uses the terms "access token", "refresh token", This specification uses the terms "access token", "refresh token",
"authorization server", "resource server", "authorization endpoint", "authorization server", "resource server", "authorization endpoint",
skipping to change at page 4, line 38 skipping to change at line 173
specification MUST include RS256 (as defined in [RFC7518]) among specification MUST include RS256 (as defined in [RFC7518]) among
their supported signature algorithms. their supported signature algorithms.
This specification registers the "application/at+jwt" media type, This specification registers the "application/at+jwt" media type,
which can be used to indicate that the content is a JWT access token. which can be used to indicate that the content is a JWT access token.
JWT access tokens MUST include this media type in the "typ" header JWT access tokens MUST include this media type in the "typ" header
parameter to explicitly declare that the JWT represents an access parameter to explicitly declare that the JWT represents an access
token complying with this profile. Per the definition of "typ" in token complying with this profile. Per the definition of "typ" in
Section 4.1.9 of [RFC7515], it is RECOMMENDED that the "application/" Section 4.1.9 of [RFC7515], it is RECOMMENDED that the "application/"
prefix be omitted. Therefore, the "typ" value used SHOULD be prefix be omitted. Therefore, the "typ" value used SHOULD be
"at+jwt". See the security considerations section for details on the "at+jwt". See the Security Considerations section for details on the
importance of preventing OpenID Connect ID Tokens (as defined by importance of preventing OpenID Connect ID Tokens (as defined by
Section 2 of [OpenID.Core]) from being accepted as access tokens by Section 2 of [OpenID.Core]) from being accepted as access tokens by
resource servers implementing this profile. resource servers implementing this profile.
2.2. Data Structure 2.2. Data Structure
The following claims are used in the JWT access token data structure. The following claims are used in the JWT access token data structure.
iss REQUIRED - as defined in Section 4.1.1 of [RFC7519]. iss REQUIRED - as defined in Section 4.1.1 of [RFC7519].
exp REQUIRED - as defined in Section 4.1.4 of [RFC7519]. exp REQUIRED - as defined in Section 4.1.4 of [RFC7519].
aud REQUIRED - as defined in Section 4.1.3 of [RFC7519]. See aud REQUIRED - as defined in Section 4.1.3 of [RFC7519]. See
Section 3 for indications on how an authorization server should Section 3 for indications on how an authorization server should
determine the value of "aud" depending on the request. determine the value of "aud" depending on the request.
sub REQUIRED - as defined in Section 4.1.2 of [RFC7519]. In case of sub REQUIRED - as defined in Section 4.1.2 of [RFC7519]. In cases
access tokens obtained through grants where a resource owner is of access tokens obtained through grants where a resource owner is
involved, such as the authorization code grant, the value of "sub" involved, such as the authorization code grant, the value of "sub"
SHOULD correspond to the subject identifier of the resource owner. SHOULD correspond to the subject identifier of the resource owner.
In case of access tokens obtained through grants where no resource In cases of access tokens obtained through grants where no
owner is involved, such as the client credentials grant, the value resource owner is involved, such as the client credentials grant,
of "sub" SHOULD correspond to an identifier the authorization the value of "sub" SHOULD correspond to an identifier the
server uses to indicate the client application. See Section 5 for authorization server uses to indicate the client application. See
more details on this scenario. Also, see Section 6 for a Section 5 for more details on this scenario. Also, see Section 6
discussion about how different choices in assigning "sub" values for a discussion about how different choices in assigning "sub"
can impact privacy. values can impact privacy.
client_id REQUIRED - as defined in Section 4.3 of [RFC8693]. client_id REQUIRED - as defined in Section 4.3 of [RFC8693].
iat REQUIRED - as defined in Section 4.1.6 of [RFC7519]. This claim iat REQUIRED - as defined in Section 4.1.6 of [RFC7519]. This claim
identifies the time at which the JWT access token was issued. identifies the time at which the JWT access token was issued.
jti REQUIRED - as defined in Section 4.1.7 of [RFC7519]. jti REQUIRED - as defined in Section 4.1.7 of [RFC7519].
2.2.1. Authentication Information Claims 2.2.1. Authentication Information Claims
The claims listed in this section MAY be issued in the context of The claims listed in this section MAY be issued in the context of
authorization grants involving the resource owner, and reflect in the authorization grants involving the resource owner and reflect the
access token the types and strength of authentication that the types and strength of authentication in the access token that the
authentication server enforced prior to returning the authorization authentication server enforced prior to returning the authorization
response to the client. Their values are fixed, and remain the same response to the client. Their values are fixed and remain the same
across all access tokens that derive from a given authorization across all access tokens that derive from a given authorization
response, whether the access token was obtained directly in the response, whether the access token was obtained directly in the
response (e.g., via the implicit flow) or after one or more token response (e.g., via the implicit flow) or after one or more token
exchanges (e.g., obtaining a fresh access token using a refresh exchanges (e.g., obtaining a fresh access token using a refresh token
token, or exchanging one access token for another via [RFC8693] or exchanging one access token for another via [RFC8693] procedures).
procedures).
auth_time OPTIONAL - as defined in Section 2 of [OpenID.Core]. auth_time OPTIONAL - as defined in Section 2 of [OpenID.Core].
acr OPTIONAL - as defined in Section 2 of [OpenID.Core]. acr OPTIONAL - as defined in Section 2 of [OpenID.Core].
amr OPTIONAL - as defined in Section 2 of [OpenID.Core]. amr OPTIONAL - as defined in Section 2 of [OpenID.Core].
2.2.2. Identity Claims 2.2.2. Identity Claims
In the context of authorization grants involving the resource owner, In the context of authorization grants involving the resource owner,
commercial authorization servers will often include resource owner commercial authorization servers will often include resource owner
attributes directly in access tokens, so that resource servers can attributes directly in access tokens so that resource servers can
consume them directly for authorization or other purposes without any consume them directly for authorization or other purposes without any
further round trips to introspection ( [RFC7662]) or UserInfo ( further round trips to introspection ([RFC7662]) or UserInfo
[OpenID.Core]) endpoints. This is particularly common in scenarios ([OpenID.Core]) endpoints. This is particularly common in scenarios
where the client and the resource server belong to the same entity where the client and the resource server belong to the same entity
and are part of the same solution, as is the case for first party and are part of the same solution, as is the case for first-party
clients invoking their own backend API. clients invoking their own backend API.
This profile does not introduce any mechanism for a client to This profile does not introduce any mechanism for a client to
directly request the presence of specific claims in JWT access directly request the presence of specific claims in JWT access
tokens, as the authorization server can determine what additional tokens, as the authorization server can determine what additional
claims are required by a particular resource server by taking in claims are required by a particular resource server by taking the
consideration the client_id of the client, the "scope" and the client_id of the client and the "scope" and the "resource" parameters
"resource" parameters included in the request. included in the request into consideration.
Any additional identity attribute whose semantic is well described by Any additional identity attribute whose semantic is well described by
an entry in the JSON Web Token (JWT) IANA registry introduced in an entry in the "JSON Web Token (JWT)" IANA registry introduced in
[RFC7519] SHOULD be encoded using the corresponding claim name, if [RFC7519] SHOULD be encoded using the corresponding claim name, if
that attribute is to be included in the JWT access token. Note that that attribute is to be included in the JWT access token. Note that
the JWT IANA registry includes the claims found in Section 5.1 of the JWT IANA registry includes the claims found in Section 5.1 of
[OpenID.Core]. [OpenID.Core].
Authorization servers MAY return arbitrary attributes not defined in Authorization servers MAY return arbitrary attributes not defined in
any existing specification, as long as the corresponding claim names any existing specification, as long as the corresponding claim names
are collision resistant or the access tokens are meant to be used are collision resistant or the access tokens are meant to be used
only within a private subsystem. Please refer to Sections 4.2 and only within a private subsystem. Please refer to Sections 4.2 and
4.3 of [RFC7519] for details. 4.3 of [RFC7519] for details.
skipping to change at page 6, line 48 skipping to change at line 277
corresponding issued JWT access token SHOULD include a "scope" claim corresponding issued JWT access token SHOULD include a "scope" claim
as defined in Section 4.2 of [RFC8693]. as defined in Section 4.2 of [RFC8693].
All the individual scope strings in the "scope" claim MUST have All the individual scope strings in the "scope" claim MUST have
meaning for the resources indicated in the "aud" claim. See meaning for the resources indicated in the "aud" claim. See
Section 5 for more considerations about the relationship between Section 5 for more considerations about the relationship between
scope strings and resources indicated by the "aud" claim. scope strings and resources indicated by the "aud" claim.
2.2.3.1. Claims for Authorization Outside of Delegation Scenarios 2.2.3.1. Claims for Authorization Outside of Delegation Scenarios
Many authorization servers embed in the access tokens they issue Many authorization servers embed authorization attributes that go
authorization attributes that go beyond the delegated scenarios beyond the delegated scenarios described by [RFC7519] in the access
described by [RFC7519]. Typical examples include resource owner tokens they issue. Typical examples include resource owner
memberships in roles and groups that are relevant to the resource memberships in roles and groups that are relevant to the resource
being accessed, entitlements assigned to the resource owner for the being accessed, entitlements assigned to the resource owner for the
targeted resource that the authorization server knows about, and so targeted resource that the authorization server knows about, and so
on. on.
An authorization server wanting to include such attributes in a JWT An authorization server wanting to include such attributes in a JWT
access token SHOULD use as claim types the "groups","roles" and access token SHOULD use the "groups", "roles", and "entitlements"
"entitlements" attributes of the "User" resource schema defined by attributes of the "User" resource schema defined by Section 4.1.2 of
Section 4.1.2 of [RFC7643]). [RFC7643]) as claim types.
Authorization servers SHOULD encode the corresponding claim values Authorization servers SHOULD encode the corresponding claim values
according to the guidance defined in [RFC7643]. In particular, a according to the guidance defined in [RFC7643]. In particular, a
non-normative example of "groups" attribute can be found in non-normative example of a "groups" attribute can be found in
Section 8.2 of [RFC7643]. No specific vocabulary is provided for Section 8.2 of [RFC7643]. No specific vocabulary is provided for
"roles" and "entitlements". "roles" and "entitlements".
Section 7 of this document provides entries for registering "groups", Section 7.2.1 of this document provides entries for registering
"roles" and "entitlements" attributes from [RFC7643] as claim types "groups", "roles", and "entitlements" attributes from [RFC7643] as
to be used in this profile. claim types to be used in this profile.
3. Requesting a JWT Access Token 3. Requesting a JWT Access Token
An authorization server can issue a JWT access token in response to An authorization server can issue a JWT access token in response to
any authorization grant defined by [RFC6749] and subsequent any authorization grant defined by [RFC6749] and subsequent
extensions meant to result in an access token. extensions meant to result in an access token.
If the request includes a "resource" parameter (as defined in If the request includes a "resource" parameter (as defined in
[RFC8707]), the resulting JWT access token "aud" claim SHOULD have [RFC8707]), the resulting JWT access token "aud" claim SHOULD have
the same value as the "resource" parameter in the request. the same value as the "resource" parameter in the request.
skipping to change at page 7, line 43 skipping to change at line 320
Example request below: Example request below:
GET /as/authorization.oauth2?response_type=code GET /as/authorization.oauth2?response_type=code
&client_id=s6BhdRkqt3 &client_id=s6BhdRkqt3
&state=xyz &state=xyz
&scope=openid%20profile%20reademail &scope=openid%20profile%20reademail
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&resource=https%3A%2F%2Frs.example.com%2F HTTP/1.1 &resource=https%3A%2F%2Frs.example.com%2F HTTP/1.1
Host: authorization-server.example.com Host: authorization-server.example.com
Figure 1: Authorization Request with Resource and Scope Parameters Figure 1: Authorization Request with Resource and Scope Parameters
Once redeemed, the code obtained from the request above will result Once redeemed, the code obtained from the request above will result
in a JWT access token in the form shown below: in a JWT access token in the form shown below:
Header: Header:
{"typ":"at+JWT","alg":"RS256","kid":"RjEwOwOA"} {"typ":"at+JWT","alg":"RS256","kid":"RjEwOwOA"}
Claims: Claims:
skipping to change at page 8, line 30 skipping to change at line 350
} }
Figure 2: The Header and JWT Claims Set of a JWT Access Token Figure 2: The Header and JWT Claims Set of a JWT Access Token
The authorization server MUST NOT issue a JWT access token if the The authorization server MUST NOT issue a JWT access token if the
authorization granted by the token would be ambiguous. See Section 5 authorization granted by the token would be ambiguous. See Section 5
for more details about common cases that might lead to ambiguity and for more details about common cases that might lead to ambiguity and
strategies an authorization server can enact to prevent them. strategies an authorization server can enact to prevent them.
If the request does not include a "resource" parameter, the If the request does not include a "resource" parameter, the
authorization server MUST use in the "aud" claim a default resource authorization server MUST use a default resource indicator in the
indicator. If a "scope" parameter is present in the request, the "aud" claim. If a "scope" parameter is present in the request, the
authorization server SHOULD use it to infer the value of the default authorization server SHOULD use it to infer the value of the default
resource indicator to be used in the "aud" claim. The mechanism resource indicator to be used in the "aud" claim. The mechanism
through which scopes are associated to default resource indicator through which scopes are associated with default resource indicator
values is outside the scope of this specification. If the values in values is outside the scope of this specification. If the values in
the "scope" parameter refer to different default resource indicator the "scope" parameter refer to different default resource indicator
values, the authorization server SHOULD reject the request with values, the authorization server SHOULD reject the request with
"invalid_scope" as described in Section 4.1.2.1 of [RFC6749]. "invalid_scope" as described in Section 4.1.2.1 of [RFC6749].
4. Validating JWT Access Tokens 4. Validating JWT Access Tokens
For the purpose of facilitating validation data retrieval, it is here For the purpose of facilitating validation data retrieval, it is
RECOMMENDED that authorization servers sign JWT access tokens with an RECOMMENDED here that authorization servers sign JWT access tokens
asymmetric algorithm. with an asymmetric algorithm.
Authorization servers SHOULD use OAuth 2.0 Authorization Server Authorization servers SHOULD use OAuth 2.0 Authorization Server
Metadata [RFC8414] to advertise to resource servers their signing Metadata [RFC8414] to advertise to resource servers their signing
keys via "jwks_uri" and what "iss" claim value to expect via the keys via "jwks_uri" and what "iss" claim value to expect via the
"issuer" metadata value. Alternatively, authorization servers "issuer" metadata value. Alternatively, authorization servers
implementing OpenID Connect MAY use the "OpenID Connect discovery implementing OpenID Connect MAY use the OpenID Connect discovery
[OpenID.Discovery] document for the same purpose. If an [OpenID.Discovery] document for the same purpose. If an
authorization server supports both OAuth 2.0 Authorization Server authorization server supports both OAuth 2.0 Authorization Server
Metadata and OpenID Connect discovery, the values provided MUST be Metadata and OpenID Connect discovery, the values provided MUST be
consistent across the two publication methods. consistent across the two publication methods.
An authorization server MAY elect to use different keys to sign An authorization server MAY elect to use different keys to sign
OpenID Connect ID Tokens and JWT access tokens. This specification OpenID Connect ID Tokens and JWT access tokens. This specification
does not provide a mechanism for identifying a specific key as the does not provide a mechanism for identifying a specific key as the
one used to sign JWT access tokens. An authorization server can sign one used to sign JWT access tokens. An authorization server can sign
JWT access tokens with any of the keys advertised via AS metadata or JWT access tokens with any of the keys advertised via authorization
OpenID Connect discovery. See Section 5 for further guidance on server (AS) metadata or OpenID Connect discovery. See Section 5 for
security implications. further guidance on security implications.
Resource servers receiving a JWT access token MUST validate it in the Resource servers receiving a JWT access token MUST validate it in the
following manner. following manner.
o The resource server MUST verify that the typ header value is * The resource server MUST verify that the "typ" header value is
"at+jwt" or "application/at+jwt" and reject tokens carrying any "at+jwt" or "application/at+jwt" and reject tokens carrying any
other value. other value.
o If the JWT access token is encrypted, decrypt it using the keys * If the JWT access token is encrypted, decrypt it using the keys
and algorithms that the resource server specified during and algorithms that the resource server specified during
registration. If encryption was negotiated with the authorization registration. If encryption was negotiated with the authorization
server at registration time and the incoming JWT access token is server at registration time and the incoming JWT access token is
not encrypted, the resource server SHOULD reject it. not encrypted, the resource server SHOULD reject it.
o The Issuer Identifier for the authorization server (which is * The issuer identifier for the authorization server (which is
typically obtained during discovery) MUST exactly match the value typically obtained during discovery) MUST exactly match the value
of the "iss" claim. of the "iss" claim.
o The resource server MUST validate that the "aud" claim contains a * The resource server MUST validate that the "aud" claim contains a
resource indicator value corresponding to an identifier the resource indicator value corresponding to an identifier the
resource server expects for itself. The JWT access token MUST be resource server expects for itself. The JWT access token MUST be
rejected if "aud" does not contain a resource indicator of the rejected if "aud" does not contain a resource indicator of the
current resource server as a valid audience. current resource server as a valid audience.
o The resource server MUST validate the signature of all incoming * The resource server MUST validate the signature of all incoming
JWT access tokens according to [RFC7515] using the algorithm JWT access tokens according to [RFC7515] using the algorithm
specified in the JWT alg Header Parameter. The resource server specified in the JWT "alg" Header Parameter. The resource server
MUST reject any JWT in which the value of "alg" is "none". The MUST reject any JWT in which the value of "alg" is "none". The
resource server MUST use the keys provided by the authorization resource server MUST use the keys provided by the authorization
server. server.
o The current time MUST be before the time represented by the "exp" * The current time MUST be before the time represented by the "exp"
claim. Implementers MAY provide for some small leeway, usually no claim. Implementers MAY provide for some small leeway, usually no
more than a few minutes, to account for clock skew. more than a few minutes, to account for clock skew.
The resource server MUST handle errors as described in Section 3.1 of The resource server MUST handle errors as described in Section 3.1 of
[RFC6750]. In particular, in case of any failure in the validation [RFC6750]. In particular, in case of any failure in the validation
checks listed above the authorization server response MUST include checks listed above, the authorization server response MUST include
the error code "invalid_token". Please note that this requirement the error code "invalid_token". Please note that this requirement
does not prevent JWT access tokens to use authentications schemes does not prevent JWT access tokens from using authentication schemes
other than Bearer. other than "Bearer".
If the JWT access token includes authorization claims as described in If the JWT access token includes authorization claims as described in
Section 2.2.3, the resource server SHOULD use them in combination Section 2.2.3, the resource server SHOULD use them in combination
with any other contextual information available to determine whether with any other contextual information available to determine whether
the current call should be authorized or rejected. Details about how the current call should be authorized or rejected. Details about how
a resource server performs those checks is beyond the scope of this a resource server performs those checks is beyond the scope of this
profile specification. profile specification.
5. Security Considerations 5. Security Considerations
The JWT access token data layout described here is very similar to The JWT access token data layout described here is very similar to
the one of the id_token as defined by [OpenID.Core]. The explicit that of the id_token as defined by [OpenID.Core]. The explicit
typing required in this profile, in line with the recommendations in typing required in this profile, in line with the recommendations in
[RFC8725] helps the resource server to distinguish between JWT access [RFC8725], helps the resource server to distinguish between JWT
tokens and OpenID Connect ID Tokens. access tokens and OpenID Connect ID Tokens.
Authorization servers should prevent scenarios where clients can Authorization servers should prevent scenarios where clients can
affect the value of the "sub" claim in ways that could confuse affect the value of the "sub" claim in ways that could confuse
resource servers. For example, if the authorization server elects to resource servers. For example, if the authorization server elects to
use the client_id as the "sub" value for access tokens issued using use the client_id as the "sub" value for access tokens issued using
the client credentials grant, the authorization server should prevent the client credentials grant, the authorization server should prevent
clients from registering an arbitrary client_id value, as this would clients from registering an arbitrary client_id value, as this would
allow malicious clients to select the sub of a high privilege allow malicious clients to select the sub of a high-privilege
resource owner and confuse any authorization logic on the resource resource owner and confuse any authorization logic on the resource
server relying on the "sub" value. For more details please refer to server relying on the "sub" value. For more details, please refer to
Section 4.14 of [OAuth2.Security.BestPractices]. Section 4.14 of [OAuth2.Security.BestPractices].
To prevent cross-JWT confusion, authorization servers MUST use a To prevent cross-JWT confusion, authorization servers MUST use a
distinct identifier as "aud" claim value to uniquely identify access distinct identifier as an "aud" claim value to uniquely identify
tokens issued by the same issuer for distinct resources. For more access tokens issued by the same issuer for distinct resources. For
details on cross-JWT confusion please refer to Section 2.8 of more details on cross-JWT confusion, please refer to Section 2.8 of
[RFC8725]. [RFC8725].
Authorization servers should use particular care when handling Authorization servers should use particular care when handling
requests that might lead to ambiguous authorization grants. For requests that might lead to ambiguous authorization grants. For
example: if a request includes multiple resource indicators, the example, if a request includes multiple resource indicators, the
authorization server should ensure that each scope string included in authorization server should ensure that each scope string included in
the resulting JWT access token, if any, can be unambiguously the resulting JWT access token, if any, can be unambiguously
correlated to a specific resource among the ones listed in the "aud" correlated to a specific resource among the ones listed in the "aud"
claim. The details on how to recognize and mitigate this and other claim. The details on how to recognize and mitigate this and other
ambiguous situations is highly scenario-dependent, hence out of scope ambiguous situations is highly scenario dependent and hence is out of
for this profile. scope for this profile.
Authorization servers cannot rely on the use of different keys for Authorization servers cannot rely on the use of different keys for
signing OpenID Connect ID Tokens and JWT tokens as a method to signing OpenID Connect ID Tokens and JWT tokens as a method to
safeguard against the consequences of leaking specific keys. Given safeguard against the consequences of leaking specific keys. Given
that resource servers have no way of knowing what key should be used that resource servers have no way of knowing what key should be used
to validate JWT access tokens in particular, they have to accept to validate JWT access tokens in particular, they have to accept
signatures performed with any of the keys published in AS metadata or signatures performed with any of the keys published in AS metadata or
OpenID Connect discovery: consequently, an attacker just needs to OpenID Connect discovery; consequently, an attacker just needs to
compromise any key among the ones published to be able to generate compromise any key among the ones published to be able to generate
and sign JWTs that will be accepted as valid by the resource server. and sign JWTs that will be accepted as valid by the resource server.
6. Privacy Considerations 6. Privacy Considerations
As JWT access tokens carry information by value, it now becomes As JWT access tokens carry information by value, it now becomes
possible for clients and potentially even end users to directly peek possible for clients and potentially even end users to directly peek
inside the token claims collection of unencrypted tokens. inside the token claims collection of unencrypted tokens.
The client MUST NOT inspect the content of the access token: the The client MUST NOT inspect the content of the access token: the
authorization server and the resource server might decide to change authorization server and the resource server might decide to change
token format at any time (for example by switching from this profile the token format at any time (for example, by switching from this
to opaque tokens) hence any logic in the client relying on the profile to opaque tokens); hence, any logic in the client relying on
ability to read the access token content would break without the ability to read the access token content would break without
recourse. The OAuth 2.0 framework assumes that access tokens are recourse. The OAuth 2.0 framework assumes that access tokens are
treated as opaque by clients. Administrators of authorization treated as opaque by clients. Administrators of authorization
servers should also take into account that the content of an access servers should also take into account that the content of an access
token is visible to the client. Whenever client access to the access token is visible to the client. Whenever client access to the access
token content presents privacy issues for a given scenario, the token content presents privacy issues for a given scenario, the
authorization server needs to take explicit steps to prevent it. authorization server needs to take explicit steps to prevent them.
In scenarios in which JWT access tokens are accessible to the end In scenarios in which JWT access tokens are accessible to the end
user, it should be evaluated whether the information can be accessed user, it should be evaluated whether the information can be accessed
without privacy violations (for example, if an end user would simply without privacy violations (for example, if an end user would simply
access his or her own personal information) or if steps must be taken access his or her own personal information) or if steps must be taken
to enforce confidentiality. to enforce confidentiality.
Possible measures to prevent leakage of information to clients and Possible measures to prevent leakage of information to clients and
end users include: encrypting the access token, encrypting the end users include: encrypting the access token, encrypting the
sensitive claims, omitting the sensitive claims or not using this sensitive claims, omitting the sensitive claims or not using this
profile, falling back on opaque access tokens. profile, and falling back on opaque access tokens.
In every scenario, the content of the JWT access token will In every scenario, the content of the JWT access token will
eventually be accessible to the resource server. It's important to eventually be accessible to the resource server. It's important to
evaluate whether the resource server gained the proper entitlement to evaluate whether the resource server gained the proper entitlement to
have access to any content received in form of claims, for example have access to any content received in the form of claims, for
through user consent in some form, policies and agreements with the example, through user consent in some form, policies and agreements
organization running the authorization servers, and so on. For with the organization running the authorization servers, and so on.
example, a user might not wish to consent to granting a given For example, a user might not wish to consent to granting given
resource server information about any of the non-mandatory claims resource server information about any of the non-mandatory claims
enumerated in Section 2 (and subsections)." enumerated in Section 2 (and its subsections).
This profile mandates the presence of the "sub" claim in every JWT This profile mandates the presence of the "sub" claim in every JWT
access token, making it possible for resource servers to rely on that access token, making it possible for resource servers to rely on that
information for correlating incoming requests with data stored information for correlating incoming requests with data stored
locally for the authenticated principal. Although the ability to locally for the authenticated principal. Although the ability to
correlate requests might be required by design in many scenarios, correlate requests might be required by design in many scenarios,
there are scenarios where the authorization server might want to there are scenarios where the authorization server might want to
prevent correlation. The "sub" claim should be populated by the prevent correlation. The "sub" claim should be populated by the
authorization servers according to a privacy impact assessment. For authorization servers according to a privacy impact assessment. For
instance, if a solution requires preventing tracking principal instance, if a solution requires preventing tracking of principal
activities across multiple resource servers, the authorization server activities across multiple resource servers, the authorization server
should ensure that JWT access tokens meant for different resource should ensure that JWT access tokens meant for different resource
servers have distinct "sub" values that cannot be correlated in the servers have distinct "sub" values that cannot be correlated in the
event of resource servers collusion. Similarly, if a solution event of resource server collusion. Similarly, if a solution
requires preventing a resource server from correlating the requires preventing a resource server from correlating the
principal's activity within the resource itself, the authorization principal's activity within the resource itself, the authorization
server should assign different "sub" values for every JWT access server should assign different "sub" values for every JWT access
token issued. In turn, the client should obtain a new JWT access token issued. In turn, the client should obtain a new JWT access
token for every call to the resource server, to ensure that the token for every call to the resource server to ensure that the
resource server receives different "sub" and "jti" values at every resource server receives different "sub" and "jti" values at every
call, thus preventing correlation between distinct requests. call, thus preventing correlation between distinct requests.
7. IANA Considerations 7. IANA Considerations
7.1. Media Type Registration 7.1. Media Type Registration
7.1.1. Registry Content 7.1.1. Registry Content
This section registers the "application/at+jwt" media type [RFC2046] This section registers "application/at+jwt", a new media type
in the "Media Types" registry [IANA.MediaTypes] in the manner [RFC2046] in the "Media Types" registry [IANA.MediaTypes] in the
described in [RFC6838], which can be used to indicate that the manner described in [RFC6838]. It can be used to indicate that the
content is an access token encoded in JWT format. content is an access token encoded in JWT format.
o Type name: application Type name: Application
o Subtype name: at+jwt Subtype name: at+jwt
o Required parameters: N/A Required parameters: N/A
o Optional parameters: N/A Optional parameters: N/A
o Encoding considerations: binary; JWT values are encoded as a Encoding considerations: Binary; JWT values are encoded as a series
series of base64url-encoded values (with trailing '=' characters of base64url-encoded values (with trailing '=' characters
removed), some of which may be the empty string, separated by removed), some of which may be the empty string, separated by
period ('.') characters. period ('.') characters.
o Security considerations: See the Security Considerations Security considerations: See the Security Considerations section of
Section of [[TODO: update once there's a RFC number for the JWT AT RFC 9068.
profile]]
o Interoperability considerations: N/A Interoperability considerations: N/A
o Published specification: [[TODO: update once there's a RFC number Published specification: RFC 9068
for the JWT AT profile]]
o Applications that use this media type: Applications that access Applications that use this media type: Applications that access
resource servers using OAuth 2.0 access tokens encoded in JWT resource servers using OAuth 2.0 access tokens encoded in JWT
format format
o Fragment identifier considerations: N/A Fragment identifier considerations: N/A
o Additional information: Magic number(s): N/A File extension(s): N/ Additional information:
A Macintosh file type code(s): N/A
o Person and email address to contact for further information: Magic number(s): N/A
Vittorio Bertocci, vittorio@auth0.com File extension(s): N/A
Macintosh file type code(s): N/A
o Intended usage: COMMON Person & email address to contact for further information:
Vittorio Bertocci <vittorio@auth0.com>
o Restrictions on usage: none Intended usage: COMMON
o Author: Vittorio Bertocci, vittorio@auth0.com Restrictions on usage: None
o Change controller: IESG Author: Vittorio Bertocci <vittorio@auth0.com>
o Provisional registration? No Change controller: IETF
Provisional registration? No
7.2. Claims Registration 7.2. Claims Registration
Section 2.2.3.1 of this specification refers to the attributes Section 2.2.3.1 of this specification refers to the attributes
"roles", "groups", "entitlements" defined in [RFC7643] to express "roles", "groups", "entitlements" defined in [RFC7643] to express
authorization information in JWT access tokens. This section authorization information in JWT access tokens. This section
registers those attributes as claims in the JSON Web Token (JWT) IANA registers those attributes as claims in the "JSON Web Token (JWT)"
registry introduced in [RFC7519]. IANA registry introduced in [RFC7519].
7.2.1. Registry Contents 7.2.1. Registry Content
7.2.1.1. Roles 7.2.1.1. Roles
o Claim Name: "roles" Claim Name: roles
Claim Description: Roles
o Claim Description: Roles Change Controller: IETF
Specification Document(s): Section 4.1.2 of [RFC7643] and
o Change Controller: IESG Section 2.2.3.1 of RFC 9068
o Specification Document(s): Section 4.1.2 of [RFC7643] and
Section 2.2.3.1 of [[this specification]]
7.2.1.2. Groups 7.2.1.2. Groups
o Claim Name: "groups" Claim Name: groups
Claim Description: Groups
o Claim Description: Groups Change Controller: IETF
Specification Document(s): Section 4.1.2 of [RFC7643] and
o Change Controller: IESG Section 2.2.3.1 of RFC 9068
o Specification Document(s): Section 4.1.2 of [RFC7643] and
Section 2.2.3.1 of [[this specification]]
7.2.1.3. Entitlements 7.2.1.3. Entitlements
o Claim Name: "entitlements" Claim Name: entitlements
Claim Description: Entitlements
o Claim Description: Entitlements Change Controller: IETF
Specification Document(s): Section 4.1.2 of [RFC7643] and
o Change Controller: IESG Section 2.2.3.1 of RFC 9068
o Specification Document(s): Section 4.1.2 of [RFC7643] and
Section 2.2.3.1 of [[this specification]]
8. References 8. References
8.1. Normative References 8.1. Normative References
[OpenID.Core] [OpenID.Core]
Sakimura, N., Bradley, J., Jones, M., Medeiros, B., and C. Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
Mortimore, "OpenID Connect Core 1.0", November 2014, C. Mortimore, "OpenID Connect Core 1.0 incorporating
errata set 1", November 2014,
<https://openid.net/specs/openid-connect-core-1_0.html>. <https://openid.net/specs/openid-connect-core-1_0.html>.
[OpenID.Discovery] [OpenID.Discovery]
Sakimura, N., Bradley, J., Jones, M., and J. Jay, "OpenID Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID
Connect Discovery 1.0", November 2014, Connect Discovery 1.0 incorporating errata set 1",
<https://openid.net/specs/openid-connect-discovery- November 2014, <https://openid.net/specs/openid-connect-
1_0.html>. discovery-1_0.html>.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046, Extensions (MIME) Part Two: Media Types", RFC 2046,
DOI 10.17487/RFC2046, November 1996, DOI 10.17487/RFC2046, November 1996,
<https://www.rfc-editor.org/info/rfc2046>. <https://www.rfc-editor.org/info/rfc2046>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
skipping to change at page 16, line 7 skipping to change at line 704
Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707,
February 2020, <https://www.rfc-editor.org/info/rfc8707>. February 2020, <https://www.rfc-editor.org/info/rfc8707>.
[RFC8725] Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best [RFC8725] Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best
Current Practices", BCP 225, RFC 8725, Current Practices", BCP 225, RFC 8725,
DOI 10.17487/RFC8725, February 2020, DOI 10.17487/RFC8725, February 2020,
<https://www.rfc-editor.org/info/rfc8725>. <https://www.rfc-editor.org/info/rfc8725>.
8.2. Informative References 8.2. Informative References
[IANA.MediaTypes]
IANA, "Media Types",
<https://www.iana.org/assignments/media-types/>.
[OAuth2.Security.BestPractices] [OAuth2.Security.BestPractices]
Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett,
"OAuth 2.0 Security Best Current Practice", July 2019, "OAuth 2.0 Security Best Current Practice", Work in
Progress, Internet-Draft, draft-ietf-oauth-security-
topics-18, 13 April 2021,
<https://datatracker.ietf.org/doc/html/draft-ietf-oauth- <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-
security-topics-18>. security-topics-18>.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, Framework: Bearer Token Usage", RFC 6750,
DOI 10.17487/RFC6750, October 2012, DOI 10.17487/RFC6750, October 2012,
<https://www.rfc-editor.org/info/rfc6750>. <https://www.rfc-editor.org/info/rfc6750>.
[RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token
(JWT) Profile for OAuth 2.0 Client Authentication and (JWT) Profile for OAuth 2.0 Client Authentication and
Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May
2015, <https://www.rfc-editor.org/info/rfc7523>. 2015, <https://www.rfc-editor.org/info/rfc7523>.
[RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection",
RFC 7662, DOI 10.17487/RFC7662, October 2015, RFC 7662, DOI 10.17487/RFC7662, October 2015,
<https://www.rfc-editor.org/info/rfc7662>. <https://www.rfc-editor.org/info/rfc7662>.
Appendix A. Acknowledgements Acknowledgements
The initial set of requirements informing this specification was The initial set of requirements informing this specification was
extracted by numerous examples of access tokens issued in JWT format extracted by numerous examples of access tokens issued in JWT format
by production systems. Thanks to Dominick Baier (IdentityServer), by production systems. Thanks to Dominick Baier (IdentityServer),
Brian Campbell (Ping Identity), Daniel Dobalian (Microsoft), Karl Brian Campbell (Ping Identity), Daniel Dobalian (Microsoft), and Karl
Guinness (Okta) for providing sample tokens issued by their products Guinness (Okta) for providing sample tokens issued by their products
and services. Brian Campbell and Filip Skokan provided early and services. Brian Campbell and Filip Skokan provided early
feedback that shaped the direction of the specification. This feedback that shaped the direction of the specification. This
profile was discussed at length during the OAuth Security Workshop profile was discussed at length during the OAuth Security Workshop
2019, with several individuals contributing ideas and feedback. The 2019, with several individuals contributing ideas and feedback. The
author would like to acknowledge the contributions of: author would like to acknowledge the contributions of:
John Bradley, Brian Campbell, Vladimir Dzhuvinov, Torsten John Bradley, Brian Campbell, Vladimir Dzhuvinov, Torsten
Lodderstedt, Nat Sakimura, Hannes Tschofenig and everyone who Lodderstedt, Nat Sakimura, Hannes Tschofenig, and everyone who
actively participated in the unconference discussions. actively participated in the unconference discussions.
The following individuals contributed useful feedback and insights on The following individuals contributed useful feedback and insights on
the drafts, both on the IETF OAuth 2.0 WG DL and during the IIW28 the drafts, both at the IETF OAuth 2.0 WG mailing list and during the
conference: 28th Internet Identity Workshop (IIW 28):
Dale Olds, George Fletcher, David Waite, Michael Engan, Mike Jones, Dale Olds, George Fletcher, David Waite, Michael Engan, Mike Jones,
Hans Zandbelt, Vladimir Dzhuvinov, Martin Schanzenbach , Aaron Hans Zandbelt, Vladimir Dzhuvinov, Martin Schanzenbach, Aaron
Parecki, Annabelle Richard Backman, Dick Hardt, Denis Pinkas, Parecki, Annabelle Richard Backman, Dick Hardt, Denis Pinkas,
Benjamin Kaduk, Dominick Baier, Andrii Deinega, Mike Jones and Benjamin Kaduk, Dominick Baier, Andrii Deinega, Mike Jones, and
everyone who actively participated in the IIW28 unconference everyone who actively participated in the IIW 28 unconference
discussions and the IETF OAuth 2.0 WG DL discussions. Thanks to discussions and the IETF OAuth 2.0 WG mailing list discussions.
Roman Danyliw for the AD review, Joseph Salowey and Roni Even for the Thanks to Roman Danyliw for the AD review; Joseph Salowey and Roni
SECDIR/GENART reviews, Francesca Palomini, Lars Eggert, Murray Even for the SECDIR and GENART reviews; and Francesca Palomini, Lars
Kucherawy, Roberto Polli, Martin Duke, Benjamin Kaduk for the IESG Eggert, Murray Kucherawy, Roberto Polli, Martin Duke, Benjamin Kaduk
reviews. for the IESG reviews.
Appendix B. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]]
draft-ietf-oauth-access-token-jwt-13
o Added an explicit requirement for the JWT access tokens to be
signed in Section 2.1.
o Added sections in Section 7.2 for improving readability.
o In Figure 2, added jti and iat claims.
o Editorial fixes in Section 2.2.1 and Section 4.
o Clarified that additional claims are to be added only if necessary
- in Section 2.2.2. Editorial changes in the same section.
o Updates sample values in Section 3.
o Added leeway language to the exp validation step in Section 4.
o In Section 4, clarified that the use of RFC6750 error codes does
not imply that JWT ATs can only be Bearer tokens.
o Various edits and nits in Section 5 and Section 6.
o Added clarifying language in Section 6 regarding what claims in
the AT might require explicit user consent.
o Added URLs for the OpenID references and the oauth security BCP.
Moved RFC7523 to the informative references section.
draft-ietf-oauth-access-token-jwt-12
o Editorial changes in the abstract.
o Updated the client_id value in the figures in Section 3.
o Added clarifying language in Section 1 positioning this
specification vs [RFC7523].
o In section Section 2.1 added a sentence that makes RS256 support
mandatory for AS and RS.
draft-ietf-oauth-access-token-jwt-11
o Editorial updates and typo fixes in Section 1.2, Section 2.2,
Section 2.2.1, Section 2.2.2, Section 3, Section 4, Section 5,
Appendix A
o Updated language in Section 2.2.2 to explicitly refer to the JWT
IANA registry.
o Citation added in in Section 2.1
o Added a normative reference entry for OpenID Connect Discovery 1.0
and referenced it from Section 4
o Updated Figure 2 in Section 3 to clarify that the intent of that
snippet is to describe the content rather than exact JWT AT
format.
o Updated registry references in Section 7.2.1 to point to
Section 2.2.3.1
o Modified Section 2.2.3.1 to make it easier for the reader to
understand what values and format is expected for the groups,
roles and entitlement claims. Minor formatting issues fixed.
draft-ietf-oauth-access-token-jwt-09
o Removed unused reference to http://www.iana.org/assignments/oauth-
parameters; moved the OAuth2 security BCP to the informative
references section.
o Restructured opening paragraphs in Section 6 for clarity.
draft-ietf-oauth-access-token-jwt-08
o Numerous edits for correcting typos, improving clarity and
precision of language.
o Moved RFC7519 to the normative section; eliminated unused
references RFC7644 and RFC3986.
draft-ietf-oauth-access-token-jwt-07
o In Section 2.1, added language that forbids use of none as alg
value, and references Section 4 where the same prohibition was
already expressed from the RS perspective.
o In the sub definition in Section 2.2, added a sentence that
clarifies what goes in the sub in the case of grants where a
resource owner is involved.
o Updated acknowledgements.
o Updated Section 2.2.1 to clarify that acr, amr and auth_type can
occur if the AT has been obtained by grants where the resource
owner is involved.
o Updated Section 2.2.2 to clarify that identity claims can occur if
the AT has been obtained by grants where the resource owner is
involved.
o In Section 2.2.3.1 eliminated the claim that SCIM doesn't provide
a vocabulary for the attributes listed there.
o In Section 5 added reference to 8725.
o In Section 4 added application/jwt+at as accepted typ value.
o Various typos and formatting issues fixed.
draft-ietf-oauth-access-token-jwt-06
o In Section 2.2 and Section 6 added a discussion about how
different sub values affect the privacy properties of a solution.
o In Section 2.2.3 and Section 3 eliminated language prohibiting JWT
AT requests featuring multiple resources, substituting it with the
prohibition for the AS to emit JWT ATs expressing ambiguous
authorization grants. In Section 5, added language warning
against scope confusion and mentioned the existence of other
ambiguous authorization grant.
o In Section 2.2 promoted claims iat and jti from RECOMMENDED to
REQUIRED.
o In Section 2.1 eliminated temporary note on the lack of
authenticated encryption methods specifications.
o Updated acknowledgements.
draft-ietf-oauth-access-token-jwt-05
o Varios typos, grammar issues and improper abbreviations fixed.
o Reworded the definition of at+jwt in Section 2.1.
o In Section 2.2, clarified that iat refers to the issuance time of
the JWT itself.
o In Section 2.2.2, added a reference to public/private claims
definitions (Sections 4.2, 4.3) of [RFC7519].
o In Section 3, removed the paragrah stating that every JWT AT MUST
have an aud, as it is already defined in Section 2.2.
o Reworded description of the JWT AT adoption landscape in
Section 1.
o Simplified the individual descriptions of the claims list in
Section 2.2.1.
o Updated Section 4 and Section 5 to clarify that the AS can use any
of the published keys to sign JWT access tokens, and that the AS
should not rely on use of different signing keys per token type as
a security mechanism.
o In Section 2.2 promoted claims iat and jti from OPTIONAL to
RECOMMENDED
o In Section 4, switched the validation steps list type from numbers
to bullets.
o In Section 4, eliminated the auth_time instructions from the
validation steps list.
o In Section 2.2.2, added a reference to the JWT claims registry as
source of claims for JWT ATs
o In Section 4, clarified that failures in JWT AT validation checks
will result in invalid_token.
draft-ietf-oauth-access-token-jwt-04
o Eliminated reference to resource aliases list from the aud claim
description in Section 2.
o Eliminated references to resource aliases list from the aud
validation guidance in Section 4.
o Introduced a new subsection Section 2.2.1, moved the definitions
of auth_time, acr and amr there and incorporated the language
proposed by Annabelle and Brian on the WG mailing list.
o In section Section 3 softened (from MUST to SHOULD) the
requirement that ties the resource identifier in the request to
the value in the aud claim of the issued access token.
o Updated acknowledgements.
o In the section Section 3, the example request now has
response_type=code.
o Updated text in the Privacy Consideration section to clarify what
protection steps the text refers to.
o Updated the typ header discussion in Section 2.1 to clarify that
it helps preventing resources from accepting OpenID Connect ID
Tokens as JWT access tokens.
o Updated refrences to token exchange, resource indicators and JWT
best practices to reflect their RFC status (8693,8707,8725).
draft-ietf-oauth-access-token-jwt-03
o Varios typos fixed.
o In the security considerations section, relaxed the claim that the
typ header value "at+jwt" will prevent RS from misinterpreting JWT
ATs as idtokens.
o In the "Requesting JWT Access Tokens" section, added
"invalid_target" as a possible error returned for the multiple
resources request case.
o In the Validating JWT Access Tokens" section, disallowed JWTs with
"alg":"none"
o in the IANA registration entries for the SCIM claim types,
complemented the reference to the SCIM spec with a reference to
this spec so that the eventual registration entries have better
context.
o Updated acknowledgements.
o In the section Section 3, the example request now has
response_type=code.
o Updated text in the Privacy Consideration section to clarify what
protection steps the text refers to.
draft-ietf-oauth-access-token-jwt-02
o In 2.2.1, opened the sources of identity attributes to any
identity related specification.
o In 2.2.2, relaxed from MUST to SHOULD the requirement that
requests including a scope always result in access tkens
containing a corresponding scope claim.
o In the security considerations setting, added a requirement for
the authorization server to assing unique identifiers for
different resources- to prevent cross JWT confusion.
o Added IANA registration for the authorization attributes borrowed
from SCIM CORE
draft-ietf-oauth-access-token-jwt-01
o Added note on authenticated encryption.
o Added a mention to the 1st party clients scenarios in the identity
claims section.
o Changed the definition reference for the iss, exp, aud, sub, iat
claims from OpenID.Core to RFC7519.
o Added a mention of the client_id==sub case in the security
considerations section, added a reference to draft-ietf-oauth-
security-topics-13. Added a reference to the security
considerations from the sub claim definition section.
o Specified invalid_request as the error code the authorization
server should return in case of multiple resources in the access
token request.
o Specified invalid_scope as the error code the authorization server
should return in case it isn;t possible to determine to which
resource the requested scopes refers to.
o In the identity claims section, added a reference to introspection
as possible source of claim types and added language explicitly
stating that the AS can add arbitrary attributes as long as they
are collision resistant or private.
o Updated language for the auth_time claim to include the case in
which the AS reauthenticates the user mid-session (e.g. during
step up auth).
o Removed note about adding a mechanism for extablishing whether the
token was obtained on behalf or the resource owner or of the
client itself (client credentials grant).
o Removed note about adding a mechanism for indicating whether the
authorization server sent the resource owner to authenticate with
a federated identity provider, and the identity of that federated
provider.
o Removed the note in the security consideration sections about
discussing the purpose of aud, iss, exp validation (redundant).
o In the authorization claims section, stated intent to register
roles, groups and entitlements as claim types in IANA
o Clarified in the privacy considerations that clients should not
inspect access tokens.
o Expanded the privacy considerations with more explicit guidance
about privacy preserving approaches.
o Added IANA registry content for the at+JWT MIME type.
o Updated acknowledgements.
o Initial draft to define a JWTt profile for OAuth 2.0 access
tokens.
Author's Address Author's Address
Vittorio Bertocci Vittorio Bertocci
Auth0 Auth0
Email: vittorio@auth0.com Email: vittorio@auth0.com
 End of changes. 96 change blocks. 
452 lines changed or deleted 212 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/