Internet DRAFT - draft-spencer-oauth-claims
draft-spencer-oauth-claims
OAuth Working Group T. Spencer
Internet-Draft Curity AB
Intended status: Standards Track 23 November 2019
Expires: 26 May 2020
The OAuth 2.0 Authorization Framework: Claims
draft-spencer-oauth-claims-01
Abstract
This document extends the OAuth 2.0 framework to include a simple
query language that can be used by clients to request certain claims
from an authorization server. This mechanism can be used during the
authorization request and refresh request. It also defines a
response parameter of the token and introspection endpoints that
indicates to the caller which claims were authorized by the resource
owner. Lastly, it stipulates how this request parameter can be used
during token exchange, and how clients may request that certain
claims be placed in an access token intended for a particular
resource server.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
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
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 26 May 2020.
Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
Spencer Expires 26 May 2020 [Page 1]
Internet-Draft Claims November 2019
and restrictions with respect to this document. Code Components
extracted from this document must include Simplified BSD License text
as described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Claims vis-a-vis Scope Tokens . . . . . . . . . . . . . . 4
1.2. Notational Conventions . . . . . . . . . . . . . . . . . 5
1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. Authorization Request . . . . . . . . . . . . . . . . . . 6
2.2. Refresh Request . . . . . . . . . . . . . . . . . . . . . 7
2.3. Token Introspection . . . . . . . . . . . . . . . . . . . 8
2.4. Token Exchange . . . . . . . . . . . . . . . . . . . . . 8
3. Claims Request Object . . . . . . . . . . . . . . . . . . . . 8
3.1. Requesting Particular Claim Names and Claim Values . . . 9
3.2. Critical Members of a Claims Request Object . . . . . . . 14
3.3. Special Claims Sinks . . . . . . . . . . . . . . . . . . 17
4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 18
4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 18
4.1.1. Authorization Request . . . . . . . . . . . . . . . . 18
4.1.2. Error Response . . . . . . . . . . . . . . . . . . . 19
4.1.3. Access Token Response . . . . . . . . . . . . . . . . 20
4.2. Implicit Flow . . . . . . . . . . . . . . . . . . . . . . 20
4.2.1. Authorization Request . . . . . . . . . . . . . . . . 20
4.2.2. Access Token Response . . . . . . . . . . . . . . . . 20
4.2.3. Error Response . . . . . . . . . . . . . . . . . . . 21
4.3. Resource Owner Password Credentials Grant . . . . . . . . 21
4.3.1. Access Token Request . . . . . . . . . . . . . . . . 21
4.3.2. Access Token Response . . . . . . . . . . . . . . . . 22
4.4. Client Credentials Grant . . . . . . . . . . . . . . . . 22
4.4.1. Access Token Request . . . . . . . . . . . . . . . . 23
4.4.2. Access Token Response . . . . . . . . . . . . . . . . 23
5. Token Refresh . . . . . . . . . . . . . . . . . . . . . . . . 24
5.1. Token Refresh Request . . . . . . . . . . . . . . . . . . 24
5.2. Access Refresh Response . . . . . . . . . . . . . . . . . 24
6. Token Exchange . . . . . . . . . . . . . . . . . . . . . . . 25
7. Token Introspection . . . . . . . . . . . . . . . . . . . . . 25
8. Requesting Claims for a Particular Protected Resource . . . . 25
9. Authorization Server Metadata . . . . . . . . . . . . . . . . 25
10. Security Considerations . . . . . . . . . . . . . . . . . . . 27
11. Privacy Considerations . . . . . . . . . . . . . . . . . . . 27
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28
13. Normative References . . . . . . . . . . . . . . . . . . . . 28
14. Informative References . . . . . . . . . . . . . . . . . . . 28
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 29
Spencer Expires 26 May 2020 [Page 2]
Internet-Draft Claims November 2019
Appendix B. Document History . . . . . . . . . . . . . . . . . . 29
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 29
1. Introduction
As stated in Section 1.4 of [RFC6749], an access token represents the
specific scope and duration of access. The requested scope is
verified by the authorization server according to its policy, and the
perhaps-different scope is granted by the resource owner. The
requested and granted scope may vary due to the authorization
server's policy and/or the resource owner's limitation of the granted
scope. The resulting scope is enforced by the resource server. The
way in which the client indicates the intended scope of access is by
the "scope" request parameter defined in Section 3.3 of [RFC6749].
This specification defines a more sophisticated instrument to achieve
this same purpose.
At times, this existing mechanism is too limited. In some uses
cases, for example, a client may need to request particular claims
from an authorization server. It may also do this to request
specific claim values. Furthermore, a client may need to indicate to
the authorization server that certain claims are essential for its
ability to operate. In such cases, the grant is of little use to the
client if the resource owner does not comply. Another example of
when the existing "scope" parameter is insufficient is when the
client knows that some claim is required by a particular resource
server. The extent of a client's knowledge is usually limited to
knowing that a claim is needed in an access token; however, in some
cases, it may also know that a claim should be restricted to access
tokens issued to a particular resource server. In these situations,
the existing mechanism for stipulating the scope of access is
insufficient.
To accommodate these use cases and requirements, this specification
defines a new request parameter that can be used when the client
obtains an authorization grant, as described in Section 1.3 of
[RFC6749] and Section 2.1 of [I-D.ietf-oauth-token-exchange]. For
each request wherein these fix grant types -- authorization code,
implicit, resource owner password credentials, client credentials,
and token exchange -- are sought, this specification defines a new
parameter called "claims". It can be used by a client with any of
these to request that certain claims and/or particular claim values
be authorized by the resource owner. The value of this parameter is
a JavaScript Object Notation (JSON) object [RFC8259]. This can also
be used to indicate to the authorization server that the client
considers some or all of the claims to be required. The client can
also use this object to indicate that certain claim values are
Spencer Expires 26 May 2020 [Page 3]
Internet-Draft Claims November 2019
preferred or essential to its ability to operate on behalf of the
resource owner.
During a refresh request (as described in Section 1.5 of [RFC6749]),
the "claims" parameter defined herein can also be used to alter the
resulting scope of access. This can be used, for example, to lessen
the scope by including a certain subset of claims that should be in
the new access token. After such, a client may increase the scope in
a subsequent refresh request by including additional claim names in
the JSON object value of the "claims" authorization request
parameter. When it does so, the client cannot, however, expand the
scope from that which was initially authorized by the resource owner.
This specification also stipulates how the authorized claim names are
returned from an authorization request and the result of
introspecting a token.
This specification is designed to be compatible with OpenID Connect
[OpenID.Core] but does not require the authorization server to
support that protocol.
1.1. Claims vis-a-vis Scope Tokens
As previously stated, claims relate to scope tokens. How exactly is
beyond the extent of this specification. Instead, this document
provides a framework in which these two constructs can be used
together or independently. That said, however, there are at least
three common ways that claims will be used:
1. Not at all (in which case this specification is irrelevant).
2. In lieu of scope tokens.
3. Together with scope tokens.
The first and second option are straightforward. The third, however,
will require a specification to define the relation between the two
in order to achieve interoperability. For instance, [OpenID.Core]
relates claims to scope tokens by grouping certain claims into
various scope tokens. This grouping of claims into various scope
tokens is RECOMMENDED when simultaneously using claims and scope
tokens to request authorization.
Spencer Expires 26 May 2020 [Page 4]
Internet-Draft Claims November 2019
1.2. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
Unless otherwise noted, all the protocol parameter names and values
are case sensitive.
1.3. Terminology
This specification uses the terms "Access Token", "Authorization
Code", "Authorization Endpoint", "Authorization Grant",
"Authorization Server", "Client", "Grant Type", "Redirection URI",
"Refresh Token", "Resource Owner", "Resource Server", and "Token
Endpoint" defined by [RFC6749]; "Claim", "Claim Name", and "Claim
Value" defined by [RFC7519]; and the following defined herein:
Claims Sink
The location or destination where the authorization server
MAY include all requested claims that are authorized by the
resource owner. An access token intended for an unspecified
resource server or an access token the client intends to send
to a particular resource server or an ID token (when the
OpenID Connect profile of this specification is used) are
examples of claims sinks.
Claims Request Object
Has the meaning ascribed to it in Section 3.
Claims Sink Query Object
Has the meaning ascribed to it in Section 3.1.
Claim Value Query Object
Has the meaning ascribed to it in Section 3.1.
Critical Claim
Has the meaning ascribed to it in Section 3.2.
Essential Claim
A claim specified by the client as being necessary to ensure
a smooth authorization experience for a specific task
requested by the resource owner.
Scope Token
A case-sensitive string joined by spaces together with other
Spencer Expires 26 May 2020 [Page 5]
Internet-Draft Claims November 2019
such strings and included in the the "scope" request
parameter of an authorization request (i.e., a "scope-token"
as set forth in the ABNF of Section 3.3 of [RFC6749]).
Voluntary Claim
A claim specified by the client as being useful but not
essential for the specific task requested by the resource
owner.
2. Protocol Flow
2.1. Authorization Request
When a client requests authorization from the resource owner
indirectly via the authorization server, the protocol flow MAY
include a query for certain claims. Based on the policy of the
authorization server and the delegated access of the resource owner,
certain claims MAY be granted. Given an authorization grant, the
authorization server informs the client as to which claims were
actually issued (if different from those requested). This message
exchange pattern is shown in Figure 1:
+--------+ +---------------+
| Client |--(A)- Authorization request ->| Authorization |
| | including claims request | Server |
| | parameter | |
| | | |
| |<-(B)-- Authorization grant ---| |
| | | |
| |--(C)-- Authorization grant -->| |
| | | |
| |<-(D)-Access token including --| |
+--------+ granted claim names +---------------+
Figure 1: Protocol Flow that Includes Requested and Granted Claims
The steps in the flow illustrated in Figure 1 are generally the same
as those described in Section 1.2 of [RFC6749] with a few important
distinctions:
* During the authorization request (A), the client includes a claims
request object as the corresponding value of the "claims" request
parameter, as described in Section 3.1 below.
* After obtaining (B) and presenting the authorization grant (C),
the response MAY include an access token and a possibly-empty list
of claim names that were authorized (D). If the asserted claims
Spencer Expires 26 May 2020 [Page 6]
Internet-Draft Claims November 2019
embodied by the access token differ from those requested (A), then
the authorization server MUST include a list of authorized claim
names in the authorization response (D).
2.2. Refresh Request
As described in Section 1.5 of [RFC6749] and further explained in
section 6 thereof, a client that was issued a refresh token MAY use
this to narrow the scope of access for an access token. It does this
by sending the "scope" request parameter in step (G) of Figure 2 of
[RFC6749]. At times, the client might want to be more explicit about
which claims should be included in the refreshed access token or
about where those claims should be asserted.
To address this need, this document defines an additional input
parameter that the client may send to the authorization server when
it presents a refresh token to the token endpoint. This update to
the flow wherein a client refreshes an access token to narrow the
scope of access to a particular set of claims is shown in Figure 2.
+--------+ +---------------+
| Client |--(A)----- Refresh token ----->| Authorization |
| | including claims request | Server |
| | parameter | |
| | | |
| |<-(B)------ Access token ------| |
| | including granted claim names | |
+--------+ & optional refresh token +---------------+
Figure 2: Narrowing the Scope of Access to a Particular Set of Claims
Downscoping in this flow is achieved when the client requests a
subset of the claims authorized by the resource owner.
The client MAY request to change the claims sink where the authorized
claims should be asserted using this flow. If the client does so, it
is RECOMMENDED that the authorization server accept this change
baring any policy to the contrary. The client MAY also send a claim
value in the claim value query object(s) of the request. When it
does, the authorization server SHOULD consider this request when
asserting the claim but it MAY return an error if asserting a
different claim value is against its policy or exceeds the
authorization granted by the resource owner. If it is a critical
claim, the requested claim value MUST be asserted or an error MUST
result if the authorization server supports critical claims.
Spencer Expires 26 May 2020 [Page 7]
Internet-Draft Claims November 2019
There are many corner cases that can arise when implementing this
flow. Most stem from policy and configuration changes of the
authorization server which may happen between the time an access
token is issued and it is refreshed. Other complications arise when
claims are used together with scope tokens. Both are beyond the
scope of this specification and not addressed by this memo.
2.3. Token Introspection
[RFC7662] stipulates that the introspection endpoint of an
authorization server must return a JSON [RFC8259] document
representing the meta information surrounding the token, including
its scope. This specification extends that object to include the
claim names that the resource owner authorized the client for. This
request/response interaction pattern is shown in Figure 3.
+--------+ +---------------+
| Client |--(A)----- Access token -----> | Authorization |
| | send to introspection endpoint| Server |
| | | |
| | | |
| |<-(B)------ JSON object -------| |
| | including granted claim | |
+--------+ names +---------------+
Figure 3: Introspecting an Access Token and Obtaining Granted Claims
Using this flow, a client will be informed about the authorized claim
names in the same way it is informed about the scope of access by way
of the "scope" response member.
2.4. Token Exchange
TBD
3. Claims Request Object
The "claims" request parameter value is a UTF-8 encoded JSON object
("Claims Request Object") specifying requested claims. Prior to
transmission to the authorization server it is also form-URL-encoded
as appropriate. The claims request object is not intended to be a
mechanism that the client may use to instruct the authorization
server to assert specific claims. Instead, it is a simple query
language that a client can use to request certain claims or to
specify that it would like the authorization server to obtain
authorization from the resource owner for a claim, perhaps with a
particular claim value. The claims request object provides a client
Spencer Expires 26 May 2020 [Page 8]
Internet-Draft Claims November 2019
with a more structured method of requesting the scope of access that
the resource owner authorizes it for.
The top-level members of the claims request object SHOULD include at
least one claims sink. The only specific claims sinks defined by
this specification are "access_token", "*", and "?". Additionally,
this specification also sets forth a mechanism by which a client may
signal to the authorization server which claims it prefers to be
included in an access token that it intends to be furnished to a
particular resource server; this is done by using an absolute URI of
the target service or resource as a claims sink. A claims request
object MAY also contain the member "crit" to indicate parts of the
claims request object that the authorization server MUST understand
if the "crit" member itself is understood. Other members of a claims
request object MAY be present; any that are not understood by the
authorization server MUST be ignored.
An example of a claims request object that is sent to the
authorization server as the value of the "claims" request parameter
provided during an authorization request, refresh request or token
exchange request is shown in Figure 4.
{
"access_token" : {
}
}
Figure 4: Example of a Claims Request Object
In this non-normative example, the "access_token" member is the
claims sink. It is the location where the authorization server MAY
include any of the requested claims that the resource owner
authorizes. If the authorization server uses the requested claims
from a particular claims sink to derive or determine alternative
claims which it asserts, it is RECOMMENDED to consider the client's
request to include those alternative claims in the same requested
claims sink.
3.1. Requesting Particular Claim Names and Claim Values
Within the claims request object, a claims sink is associated with
another JSON object ("Claims Sink Query Object"). This object
contains properties that have the name of a claim which the client is
requesting the authorization server to assert. The possible values
associated with each of these is "null" or another JSON object
("Claim Value Query Object").
Spencer Expires 26 May 2020 [Page 9]
Internet-Draft Claims November 2019
When the value is "null", it indicates that the claim with the
associated claim name is a voluntary claim, and the client has no
specific requirements on the claim value. Conversely, when the claim
value query object is not "null" it is a JSON object with the
following properties:
essential
OPTIONAL. Indicates whether the claim being requested is an
essential claim. If the value is "true", this indicates that
the claim is an essential claim. If the value is "false" or
if this property is not include, then the claim is a
voluntary claim.
value
OPTIONAL. Requests that the claim be returned with a
particular value.
values
OPTIONAL. Requests that the claim be returned with one of a
set of values, with the values appearing in order of
preference.
The properties "value" and "values" are mutually exclusive. If the
client sends a claim value query object with both, the authorization
server MUST return an error as described in Section 4 below.
By requesting essential claims, the client indicates to the
authorization server (who indicates to the resource owner) that
releasing these claims will ensure a smooth authorization for the
specific task requested by that resource owner. If the claims are
not available because the resource owner did not authorize their
release or they are not present, the authorization server MUST NOT
generate an error when claims are not returned.
Other members of the claim value query object MAY be defined to
provide additional information about the requested claims. Any
members of the claims value query object that are not understood by
the authorization server MUST be ignored.
A non-normative example of the two possible types of values for a
claim value query object is shown in Figure 5.
Spencer Expires 26 May 2020 [Page 10]
Internet-Draft Claims November 2019
{
"access_token" : {
"https://example.com/claim1" : null,
"fname" : {
"value" : "John"
}
}
}
Figure 5: Example of a Claim Value Query Object
In this example, there are two claim names which the client is
requesting "https://example.com/claim1" and "fname". The values
associated with these are claim value query objects. The former is a
simple query where the client has no preference on a particular
value. For this reason, the client specifies the value "null". In
the later case, the client has more precise needs: it desires the
authorization server to assert a claim value of "John" for the claim
name "fname". In such situations the authorization server MAY issue
a claim with the claim name "fname" but with some other claim value
than "John". Both are voluntary claims.
An example of an essential claim is shown in the non-normative
listing of Figure 6.
{
"access_token" : {
"consentId" : {
"essential" : true
}
}
}
Figure 6: Example of querying for an Essential Claim
This query indicates that the client would like the authorization
server to issue an access token with a scope that includes a claim
with the claim name "consentId". To ensure a smooth authorization
experience at the resource server where the client will present the
resulting access token, the client has indicated that the "consentId"
claim is required, making it an essential claim.
As described above, a client may also indicate that it wishes the
authorization server to assert a claim having a claim value that the
client has some preference for. A non-normative example of such a
query is show in Figure 7.
Spencer Expires 26 May 2020 [Page 11]
Internet-Draft Claims November 2019
{
"access_token" : {
"accountId" : {
"values" : ["act-123", "act-456"],
"essential" : true
},
"paymentId" : {
"value" : "pid-123456",
"essential" : true
}
}
}
Figure 7: Example of querying for an Essential Claim with Certain
Values
In this example, the client is requesting that the authorization
server assert two essential claims: one named "accountId" and another
named "paymentId". In the former case, the client requests that the
claim value be "act-123" or "act-456". In the later case, a claim
named "paymentId" is requested by the client to have a claim value of
"pid-123456". Again, the authorization server MUST NOT return an
error if the resource owner does not authorize both of these claims
or if they are non-existent. This is merely a request for a certain
scope of access.
Another example inspired by the Revised Directive on Payment Services
(PSD2) is shown in the non-normative listing of Figure 8.
Spencer Expires 26 May 2020 [Page 12]
Internet-Draft Claims November 2019
{
"access_token" : {
"instructedAmount" : {
"value" : {
"amount" : 123.50,
"currency" : "EUR"
},
"essential" : true
},
"debtorAccount/iban" : {
"value" : "DE40100100103307118608",
"essential" : true
},
"creditorName" : {
"value" : "Merchant123",
"essential" : true
},
"creditorAccount/iban" : {
"value" : "DE02100100109307118603",
"essential" : true
},
"remittanceInformationUnstructured" : {
"value" : "Ref Number Merchant",
"essential" : true
}
}
}
Figure 8: PSD2-related Example
In this example, the client is requesting (but not forcing) the
authorization server to obtain authorization from the resource owner
for five essential claims: "instructedAmount", "debtorAccount/iban",
"creditorName", "creditorAccount/iban", and
"remittanceInformationUnstructured". The claim value query object
associated with each of these claim names has a particular value the
client strongly prefers. One interesting case is the value of the
"instructedAmount" essential claim; the query for the value of this
claim is a JSON object with two properties. The authorization server
might use this claims request object to obtain the resource owner's
consent before granting them, for instance. It might also check
these values against a data source before asserting them. Based on
the resource owner's choice or the data source lookup results, the
authorization server may not issue the claims at all or may do so
with some other value. For example, the authorization server may
actually find that the "instructedAmount" value requested exceeds its
policy's allowed limit and only prompt the resource owner to
authorize 100 Euro.
Spencer Expires 26 May 2020 [Page 13]
Internet-Draft Claims November 2019
Another interesting example of how structured scope of access can be
requested is shown in the listing of Figure 9.
{
"access_token" : {
"credentialID" : {
"value" : "qes_eidas",
"essential" : true
},
"documentDigests" : {
"value" : {
"hash":"sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HW=",
"label":"Mobile Subscription Contract"
},
"essential" : true
},
"hashAlgorithmOID" : {
"value" : "2.16.840.1.101.3.4.2.1"
}
}
}
Figure 9: ESI-related Example
This example shows how a client may request claims defined by the
Electronic Signatures and Infrastructures (ESI) Protocols for remote
digital signature creation. Like the previous example, the claims
request object for the "access_token" claims sink includes a claim
value query object for the "documentDigests" claim that includes a
JSON object with multiple properties.
These illustrative examples hopefully impress upon the reader the
versatility of this query language and the authorization server's
prerogative to assert any claims with any claim values it chooses in
its sole discretion. If the client's needs are stronger than
preferential, it MAY use the "crit" member of the claims request
object which the authorization server MAY understand.
3.2. Critical Members of a Claims Request Object
As described previously, the client can indicate to the authorization
server that certain claims are preferential or essential to the
smooth operation of the client. At times, however, the client's
needs are stronger and require certain claims to be asserted. In
such situations, the client would rather the authorization server
return an error than grant access with different claims than those
requested. This is not always possible for an authorization server,
Spencer Expires 26 May 2020 [Page 14]
Internet-Draft Claims November 2019
however, and a client MUST NOT assume that the authorization server
can be controlled in this manner. To know if this interaction
pattern in supported, the client must have a priori knowledge gained
by some means not defined by this specification or by the presence of
a "true" value in the authorization server's
"critical_claims_supported" metadata (see section Section 9 below).
An authorization server is RECOMMENDED to support this capability
unless it cannot. When it does, the authorization server MUST issue
any claim denoted as critical or it MUST return an error. The error
must be "invalid_claims" as described below in Section 4.
A client indicates to the authorization server that it must
understand certain claims and be able to assert them by including a
list of JSON Pointers [RFC6901] associated with the "crit" member of
the claims request object. Each such claim that the elements of this
list point to is a "Critical Claim". The JSON Pointers in this list
MUST refer to members of the claims request object and MUST NOT point
to elements within the list itself. If any JSON Pointer refers to an
element of the JSON Pointer list, the authorization server MUST
return an error with a code of "invalid_request" if it supports
critical claims. When the JSON Pointers are valid, if the
authorization server does not understand any of the claims pointed to
by any of the elements of this list, the authorization server MUST
return an error of "invalid_claims". Likewise, if the authorization
server is unable to assert a critical claim (and it supports critical
claims), it MUST return the same error. If a critical claim is
requested with a certain value (as in the following example), the
authorization server MUST assert the claim with that exact claim
value. If it's not able to (e.g., because the resource owner does
not have an attribute with that particular value), the authorization
server MUST return an error with a code of "invalid_claims" unless it
does not support critical claims.
A non-normative example of a claims request object with a critical
claim is shown in Figure 10.
Spencer Expires 26 May 2020 [Page 15]
Internet-Draft Claims November 2019
{
"crit" : [
"/access_token/verified_claims/verification/trust_framework/value"
],
"access_token" : {
"verified_claims" : {
"verification" : {
"trust_framework" : {
"value" : "de_aml"
}
}
}
}
}
Figure 10: Example of a Request Containing a Critical Claim
In this example, the "value" member of the JSON object associated
with "trust_framework" must be understood by the authorization server
because it is pointed by the element of the critical claims list.
The way in which the authorization server understands this particular
query is beyond the scope of this specification. The only part of
this example that is germane is the "crit" member of the claims
request object which requires the authorization server to understand
and assert a particular claim value (provided it understands the
"crit" itself). If it cannot and if it supports critical claims, it
must return an error.
It is not uncommon for a claim name to defined as a URI containing
slashes ("/", %x2F). When such a claim is critical, the escaping
described in Section 3 of [RFC6901] MUST be used, as in the non-
normative listing of Figure 11.
{
"crit" : ["/access_token/https:~1~1example.com~1claim1"],
"access_token" : {
"https://example.com/claim1" : null,
}
}
Figure 11: Example of Escaping the JSON Pointer used to Refer to
a Critical Claim with a Name Containing Slashes
Spencer Expires 26 May 2020 [Page 16]
Internet-Draft Claims November 2019
3.3. Special Claims Sinks
A client may know that it needs a particular claim; however, it may
not be aware which claims sink the claim should be included in. The
client may prefer to leave this determination to the authorization
server. In such cases, the client MAY use the claims sink "?" (%x3F)
as mentioned in Section 3 above. This special claim sink may result
in the claim being issued in the access token or any other claims
sink that the authorization server deems appropriate. A non-
normative example of a claims request object indicating that a
particular claim be asserted in any claims sink is shown in
Figure 12.
{
"?" : {
"https://example.com/claim1" : null,
}
}
Figure 12: Example Requesting a Claim to be Asserted in Any
Claims Sink
Similarly, there are situations where the client wishes claims to be
asserted in all claims sinks the authorization server supports.
Rather than requiring the the client to repeat its requirement for
each claims sink, it MAY use the special claims sink "*" (%x2A).
This claims sink indicates to the authorization server that the
client prefers all claims included in the claims request object to be
asserted in each claim sink that the authorization server supports.
The two claims request objects shown in Figure Figure 13 and
Figure 14 are equivalent (if the authorization server only supports
the two claims sinks shown in the latter).
{
"*" : {
"https://exmaple.com/claim1" : null,
}
}
Figure 13: Example Requesting a Claim to be Asserted in All
Claims Sinks
Spencer Expires 26 May 2020 [Page 17]
Internet-Draft Claims November 2019
{
"access_token" : {
"https://exmaple.com/claim1" : null,
},
"my-good-claims-sink" : {
"https://exmaple.com/claim1" : null,
}
}
Figure 14: Equivalent Example of Requesting a Claim to be
Asserted in All Claims Sinks
The use of either the claims sink "?" and "*" with any other claims
sink in the same claims request object is undefined. The
authorization server SHOULD return an error or apply some other logic
not defined by this specification. The client SHOULD NOT make such
queries unless it has some knowledge gained a priori about the
authorization server's support of such a query.
4. Obtaining Authorization
As stated in Section 4 of [RFC6749], a request for an access token
requires the client to obtain authorization from the resource owner.
As described there, this can be done using various grant types. To
make a request for certain claims, the "claims" request parameter
defined herein is used when requesting an authorization code,
implicit, resource owner password credentials, or client credentials
grant type. The "claims" request parameter MAY also be used with
additional grant type that use the extension mechanism defined in
Section 4.5 of [RFC6749] if so profiled by some other specification.
4.1. Authorization Code Grant
4.1.1. Authorization Request
When a client seeks to obtain authorization using the authorization
code grant type defined in Section 4.1 of [RFC6749], the client MAY
include the following additional query component that it sends to the
authorization endpoint URI:
claims
OPTIONAL. A claims request object as described in Section 3.
The value of this parameter must use the "application/x-www-form-
urlencoded" format defined in Appendix B of [RFC6749].
A non-normative example of a request to the authorization endpoint
Spencer Expires 26 May 2020 [Page 18]
Internet-Draft Claims November 2019
with a URL-encoded value of the claims parameter is shown in
Figure 15 (with extra line breaks for display purposes only):
GET /authorize?client_id=s6BhdRkqt3&response_type=code&
claims=%7B%0A%20%20%22access_token%22%20%3A%20%7B%20%0A
%20%20%20%20%22https%3A%2F%2Fexample.com%2Fclaim1%22%20%3A
%20null%2C%0A%20%20%20%20%22fname%22%20%3A%20%7B%0A%20%20
%20%20%20%20%22value%22%20%3A%20%22John%22%0A%20%20%20%20
%7D%0A%20%20%7D%0A%7D
Host: server.example.com
Figure 15: Example of Using the Claims Request Parameter on the
Authorize Endpoint
4.1.2. Error Response
If the authorization server understands the "claims" request
parameter, it MUST redirect the user-agent of the resource owner to
the client's redirection endpoint as described in Section 4.1.2.1 of
[RFC6749] with one of the following "error" values:
claims_not_supported
The authorization server understands but does not support the
"claims" request parameter, and the client SHOULD NOT use it
when requesting authorization.
invalid_request
The authorization server MAY use this less-descriptive error
code to indicate that the claims request parameter value is
not accepted, e.g., because it is syntactically incorrect.
It is, however, RECOMMENDED that the authorization server
return "claims_not_supported" or "invalid_claims" as
appropriate.
invalid_claims
When a client makes a request for a critical claim, and the
authorization server cannot assert such a claim because it is
invalid, unknown, or malformed, this error results. If the
request includes only claim names in the claims request
object which are disallowed according to the authorization
server's policy, this error (or the less-descriptive
alternative, "invalid_request") MUST result.
Spencer Expires 26 May 2020 [Page 19]
Internet-Draft Claims November 2019
4.1.3. Access Token Response
In a non-error case, the authorization server MAY include details
about the claims that the client is authorized for. This is done by
augmenting the response defined in Section 4.1.4 of [RFC6749]. In
particular, the authorization server MAY include the following
response member in the JSON object returned from the token endpoint:
claims
OPTIONAL, if identical to the claims requested by the client;
otherwise, REQUIRED. The space-separated claim names granted
by the resource owner which denote the scope of the access
token that is returned in the same response.
4.2. Implicit Flow
4.2.1. Authorization Request
When a client seeks to obtain authorization using the implicit grant
type defined in Section 4.2 of [RFC6749], the client MAY include the
following additional query component that it sends to the
authorization endpoint URI:
claims
OPTIONAL. A claims request object as described in Section 3.
The value of this parameter must use the "application/x-www-form-
urlencoded" format defined in Appendix B of [RFC6749].
4.2.2. Access Token Response
In a non-error case, the authorization server MAY include details
about the claims that the client is authorized for. This is done by
augmenting the response defined in Section 4.2.2 of [RFC6749]. In
particular, the authorization server MAY include the following
response parameter included on the fragment component of the
redirection URI:
claims
OPTIONAL, if identical to the claims requested by the client;
otherwise, REQUIRED. The space-separated claim names granted
by the resource owner which denote the scope of the access
token that is returned in the same response.
Spencer Expires 26 May 2020 [Page 20]
Internet-Draft Claims November 2019
4.2.3. Error Response
If the authorization server understands the "claims" request
parameter, it MUST redirect the user-agent of the resource owner to
the client's redirection URI as described in Section 4.2.2.1 of
[RFC6749] with one of the following "error" values:
claims_not_supported
The authorization server understands but does not support the
"claims" request parameter, and the client SHOULD NOT use it
when requesting authorization.
invalid_request
The authorization server MAY use this less-descriptive error
code to indicate that the claims request parameter value is
not accepted, e.g., because it is syntactically. incorrect.
It is, however, RECOMMENDED that the authorization server
return "claims_not_supported" or "invalid_claims" as
appropriate.
invalid_claims
When a client makes a request for a critical claim, and the
authorization server cannot assert such a claim because it is
invalid, unknown, or malformed, this error results. If the
request includes only claim names in the claims request
object which are disallowed according to the authorization
server's policy, this error (or the less-descriptive
alternative, "invalid_request") MUST result.
4.3. Resource Owner Password Credentials Grant
4.3.1. Access Token Request
When a client seeks to obtain authorization using the resource owner
password credentials grant type defined in Section 4.3 of [RFC6749],
the client MAY include the following additional parameter using the
"application/x-www-form-urlencoded" format per Appendix B of
[RFC6749] with a character encoding of UTF-8 in the HTTP request
entity-body:
claims
OPTIONAL. A claims request object as described in Section 3.
Spencer Expires 26 May 2020 [Page 21]
Internet-Draft Claims November 2019
4.3.2. Access Token Response
In a non-error case, the authorization server MAY include details
about the claims that the client is authorized for. This is done by
augmenting the response defined in Section 4.3.3 of [RFC6749]. In
particular, the authorization server MAY include the following
response member in the JSON object returned from the token endpoint:
claims
OPTIONAL, if identical to the claims requested by the client;
otherwise, REQUIRED. The space-separated claim names the
client is authorized for which denote the scope of the access
token that is returned in the same response.
If the request is invalid due to the value of the "claims" parameter,
the authorization server returns an error with one of the following
error codes:
claims_not_supported
The authorization server understands but does not support the
"claims" request parameter, and the client SHOULD NOT use it
when requesting an access token.
invalid_request
The authorization server MAY use this less-descriptive error
code to indicate that the claims request parameter value is
not accepted, accepted, e.g., because it is syntactically
incorrect. It is, however, RECOMMENDED that the
authorization server return "claims_not_supported" or
"invalid_claims" as appropriate.
invalid_claims
When a client makes a request for a critical claim, and the
authorization server cannot assert such a claim because it is
invalid, unknown, or malformed, this error results. If the
request includes only claim names in the claims request
object which are disallowed according to the authorization
server's policy, this error (or the less-descriptive
alternative, "invalid_request") MUST result.
4.4. Client Credentials Grant
Spencer Expires 26 May 2020 [Page 22]
Internet-Draft Claims November 2019
4.4.1. Access Token Request
When a client seeks to obtain authorization using the client
credentials grant type defined in Section 4.4 of [RFC6749], the
client MAY include the following additional parameter using the
"application/x-www-form-urlencoded" format per Appendix B of
[RFC6749] with a character encoding of UTF-8 in the HTTP request
entity-body:
claims
OPTIONAL. A claims request object as described in Section 3.
4.4.2. Access Token Response
In a non-error case, the authorization server MAY include details
about the claims that the client is authorized for. This is done by
augmenting the response defined in Section 4.4.3 of [RFC6749]. In
particular, the authorization server MAY include the following
response member in the JSON object returned from the token endpoint:
claims
OPTIONAL, if identical to the claims requested by the client;
otherwise, REQUIRED. The space-separated claim names the
client is authorized for which denote the scope of the access
token that is returned in the same response.
If the request is invalid due to the value of the "claims" parameter,
the authorization server returns an error with one of the following
error codes:
claims_not_supported
The authorization server understands but does not support the
"claims" request parameter, and the client SHOULD NOT use it
when requesting an access token.
invalid_request
The authorization server MAY use this less-descriptive error
code to indicate that the claims request parameter value is
not accepted, e.g., because it is syntactically incorrect.
It is, however, RECOMMENDED that the authorization server
return "claims_not_supported" or "invalid_claims" as
appropriate.
invalid_claims
When a client makes a request for a critical claim, and the
authorization server cannot assert such a claim because it is
invalid, unknown, or malformed, this error results. If the
request includes only claim names in the claims request
Spencer Expires 26 May 2020 [Page 23]
Internet-Draft Claims November 2019
object which are disallowed according to the authorization
server's policy, this error (or the less-descriptive
alternative, "invalid_request") MUST result.
5. Token Refresh
As defined in Section 6 of [RFC6749], a client may be provided with a
refresh token. When it is, it can present this to the token endpoint
of the authorization server in a refresh request. This specification
extends the request and response of this flow as described in the
following subsections.
5.1. Token Refresh Request
When performing a token refresh request, the client MAY send the
following parameter using the "application/x-www-form-urlencoded"
format per Appendix B of [RFC6749] with a character encoding of UTF-8
in the HTTP request entity-body:
claims
OPTIONAL. A claims request object as described in Section 3.
If the client includes a claims request object in the request, it
SHOULD ensure that the claim names in the claims value query
object(s) are ones that were authorized by the resource owner. It
can do this by remembering what was originally requested and/or from
the authorization server's response to its authorization request
which will include the list of claim names if they differ from those
originally requested.
5.2. Access Refresh Response
In a non-error case, the authorization server MAY include details
about the claims that the client is authorized for. This is done by
augmenting the response defined in Section 5.1 of [RFC6749]. In
particular, the authorization server MAY include the following
response member in the JSON object returned from the token endpoint:
claims
OPTIONAL, if identical to the claims requested by the client;
otherwise, REQUIRED. The space-separated claim names the
client is authorized for which denote the scope of the access
token that is returned in the same response.
If the request is invalid due to the value of the value of the
"claims" parameter, the authorization server returns an error with
one of the following error codes:
Spencer Expires 26 May 2020 [Page 24]
Internet-Draft Claims November 2019
claims_not_supported
The authorization server understands but does not support the
"claims" request parameter, and the client SHOULD NOT use it
when requesting an access token.
invalid_request
The authorization server MAY use this less-descriptive error
code to indicate that the claims request parameter value is
not accepted, e.g., because it is syntactically incorrect.
It is, however, RECOMMENDED that the authorization server
return "claims_not_supported" or "invalid_claims" as
appropriate.
invalid_claims
When a client makes a request for a critical claim, and the
authorization server cannot assert such a claim because it is
invalid, unknown, or malformed, this error results. If the
request includes only claim names in the claims request
object which are disallowed according to the authorization
server's policy, this error (or the less-descriptive
alternative, "invalid_request") MUST result.
6. Token Exchange
TBD
7. Token Introspection
This specification defines an additional top-level member in the JSON
[RFC8259] object of the authorization server's introspection endpoint
response as stipulated in Section 2.2 of [RFC7662].
claims
OPTIONAL. The space-separated claim names granted by the
resource owner which denote the scope of the access token.
8. Requesting Claims for a Particular Protected Resource
TBD
9. Authorization Server Metadata
An authorization server that supports the "claims" request parameter
SHOULD declare this fact by including the following property in the
authorization server metadata response [RFC8414]:
claims_parameter_supported
OPTIONAL. A boolean value indicating that the authorization
Spencer Expires 26 May 2020 [Page 25]
Internet-Draft Claims November 2019
server supports the "claims" request parameter or not. A
value of "true" indicates that it is supported. A value of
"false", a "null" value, or the absence of the property means
that the "claims" request parameter is not supported by the
authorization server.
claims_supported
RECOMMENDED. JSON array containing a list of the claim names
of the Claims that the authorization server MAY be able to
supply values for. Note that for privacy or other reasons,
this might not be an exhaustive list.
critical_claims_supported
OPTIONAL. A boolean value indicating that the authorization
server supports the possibility for the client to indicate
that certain parts of a claims request object MUST be
understood by the authorization server. A value of "false",
a "null" value, or the absence of this member means that the
authorization server MAY not support this interaction
pattern, and the client MUST NOT assume that it does.
If the authorization server returns a value of "false" for
"claims_parameter_supported" and true for
"critical_claims_supported", the interpretation by the client is
undefined. It is RECOMMENDED that the client assume that the
authorization server is misconfigured and that it not attempt to
request claims in a manner defined by this specification.
A non-normative example of an authorization server metadata response
which indicates that the "claims" request parameter and critical
claims are supported by the server is shown in Figure 16.
Spencer Expires 26 May 2020 [Page 26]
Internet-Draft Claims November 2019
HTTP/1.1 200 OK
Content-Type: application/json
{
"issuer" :
"https://server.example.com",
"authorization_endpoint" :
"https://server.example.com/authorize",
"token_endpoint" :
"https://server.example.com/token",
"token_endpoint_auth_methods_supported" :
["client_secret_basic", "private_key_jwt"],
"token_endpoint_auth_signing_alg_values_supported" :
["RS256", "ES256"],
"userinfo_endpoint" :
"https://server.example.com/userinfo",
"jwks_uri" :
"https://server.example.com/jwks.json",
"registration_endpoint" :
"https://server.example.com/register",
"scopes_supported" :
["openid", "profile", "email", "address", "phone",
"offline_access"],
"response_types_supported" :
["code", "code token"],
"service_documentation" :
"http://server.example.com/service_documentation.html",
"ui_locales_supported" :
["en-US", "en-GB", "en-CA", "fr-FR", "fr-CA"],
"claims_parameter_supported" : true,
"critical_claims_supported" : true,
"claims_supported" : ["sub", "http://example.com/monkey" ]
}
Figure 16: Example of Metadata of an Authorization Server that
Supports the Claims Request Parameter and Critical Claims
Note the last three members in particular.
10. Security Considerations
TBD
11. Privacy Considerations
TBD
Spencer Expires 26 May 2020 [Page 27]
Internet-Draft Claims November 2019
12. IANA Considerations
TBD
13. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/info/rfc6749>.
[RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed.,
"JavaScript Object Notation (JSON) Pointer", RFC 6901,
DOI 10.17487/RFC6901, April 2013,
<https://www.rfc-editor.org/info/rfc6901>.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://www.rfc-editor.org/info/rfc7519>.
[RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection",
RFC 7662, DOI 10.17487/RFC7662, October 2015,
<https://www.rfc-editor.org/info/rfc7662>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
[RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", RFC 8414,
DOI 10.17487/RFC8414, June 2018,
<https://www.rfc-editor.org/info/rfc8414>.
14. Informative References
[OpenID.Core]
Sakimura, N., Bradley, J., Jones, M.B., de Medeiros, B.,
and C. Mortimore, "OpenID Connect Core 1.0", OpenID
Spencer Expires 26 May 2020 [Page 28]
Internet-Draft Claims November 2019
Foundation Standards, 25 February 2014,
<http://openid.net/specs/openid-connect-core-1_0.html>.
[I-D.ietf-oauth-token-exchange]
Jones, M., Nadalin, A., Campbell, B., Bradley, J., and C.
Mortimore, "OAuth 2.0 Token Exchange", Work in Progress,
Internet-Draft, draft-ietf-oauth-token-exchange-19, 21
July 2019, <https://tools.ietf.org/html/draft-ietf-oauth-
token-exchange-19>.
Appendix A. Acknowledgements
The following individuals contributed ideas, feedback, wording and
editorial guidance to this specification:
Mark Dobrinic, Jacob Ideskog, Torsten Lodderstedt, Alice Russo
Appendix B. Document History
[[ to be removed by the RFC editor before publication as an RFC ]]
-01
* Use of XML entities for common terms in XML version of doc
* Convert XML to v. 3 format
* Added additional acknowledgements
* Updated keywords paragraph
* Updated links to other RFCs
* Small format changes and fixing of typos
-00
* Initial draft.
Author's Address
Travis Spencer
Curity AB
Email: travis@curity.io
Spencer Expires 26 May 2020 [Page 29]
