The Grant Negotiation and Authorization Protocol
draft-hardt-xauth-protocol-13
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Expired".
|
|
|---|---|---|---|
| Author | Dick Hardt | ||
| Last updated | 2020-07-13 | ||
| RFC stream | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-hardt-xauth-protocol-13
Network Working Group D. Hardt, Ed.
Internet-Draft SignIn.Org
Intended status: Standards Track 13 July 2020
Expires: 14 January 2021
The Grant Negotiation and Authorization Protocol
draft-hardt-xauth-protocol-13
Abstract
Client software often desires resources or identity claims that are
independent of the client. This protocol allows a user and/or
resource owner to delegate resource authorization and/or release of
identity claims to a server. Client software can then request access
to resources and/or identity claims by calling the server. The
server acquires consent and authorization from the user and/or
resource owner if required, and then returns to the client software
the authorization and identity claims that were approved. This
protocol may be extended to support alternative authorizations,
claims, interactions, and client authentication mechanisms.
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 14 January 2021.
Copyright Notice
Copyright (c) 2020 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
Hardt Expires 14 January 2021 [Page 1]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
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. Parties . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Reused Terms . . . . . . . . . . . . . . . . . . . . . . 6
1.3. New Terms . . . . . . . . . . . . . . . . . . . . . . . . 6
1.4. Notational Conventions . . . . . . . . . . . . . . . . . 7
2. Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1. "redirect" Interaction . . . . . . . . . . . . . . . . . 8
2.2. "user_code" Interaction . . . . . . . . . . . . . . . . . 9
2.3. Independent RO Authorization . . . . . . . . . . . . . . 10
2.4. Resource Server Access . . . . . . . . . . . . . . . . . 11
3. GS APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1. GS API Table . . . . . . . . . . . . . . . . . . . . . . 12
3.2. Create Grant . . . . . . . . . . . . . . . . . . . . . . 12
3.3. Verify Grant . . . . . . . . . . . . . . . . . . . . . . 15
3.4. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 16
3.5. Request JSON . . . . . . . . . . . . . . . . . . . . . . 16
3.5.1. "client" Object . . . . . . . . . . . . . . . . . . . 17
3.5.2. "interaction" Object . . . . . . . . . . . . . . . . 17
3.5.3. "user" Object . . . . . . . . . . . . . . . . . . . . 18
3.5.4. "authorizations" Object . . . . . . . . . . . . . . . 18
3.5.5. Authorization Request Object . . . . . . . . . . . . 18
3.5.6. "claims" Object . . . . . . . . . . . . . . . . . . . 18
3.6. Read Authorization . . . . . . . . . . . . . . . . . . . 19
3.7. GS Options . . . . . . . . . . . . . . . . . . . . . . . 19
4. GS Responses . . . . . . . . . . . . . . . . . . . . . . . . 20
4.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 20
4.2. Interaction Response . . . . . . . . . . . . . . . . . . 22
4.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 22
4.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 23
4.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 23
4.4.2. "interaction" Object . . . . . . . . . . . . . . . . 23
4.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 23
4.4.4. "authorizations" Object . . . . . . . . . . . . . . . 24
4.4.5. Authorization response Object . . . . . . . . . . . . 24
4.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 24
4.4.7. "warnings" JSON Array . . . . . . . . . . . . . . . . 25
4.5. Authorization JSON . . . . . . . . . . . . . . . . . . . 25
4.6. Response Verification . . . . . . . . . . . . . . . . . . 26
5. Interaction Modes . . . . . . . . . . . . . . . . . . . . . . 26
5.1. "redirect" . . . . . . . . . . . . . . . . . . . . . . . 26
5.1.1. "redirect" verification . . . . . . . . . . . . . . . 27
Hardt Expires 14 January 2021 [Page 2]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
5.2. "indirect" . . . . . . . . . . . . . . . . . . . . . . . 27
5.3. "user_code" . . . . . . . . . . . . . . . . . . . . . . . 27
6. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 28
7. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 28
8. Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . 28
9. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 28
10. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 30
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 32
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32
13. Security Considerations . . . . . . . . . . . . . . . . . . . 32
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 32
14.1. Normative References . . . . . . . . . . . . . . . . . . 32
14.2. Informative References . . . . . . . . . . . . . . . . . 34
Appendix A. Document History . . . . . . . . . . . . . . . . . . 34
A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 34
A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 35
A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 35
A.4. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 35
A.5. draft-hardt-xauth-protocol-04 . . . . . . . . . . . . . . 35
A.6. draft-hardt-xauth-protocol-05 . . . . . . . . . . . . . . 36
A.7. draft-hardt-xauth-protocol-06 . . . . . . . . . . . . . . 36
A.8. draft-hardt-xauth-protocol-07 . . . . . . . . . . . . . . 36
A.9. draft-hardt-xauth-protocol-08 . . . . . . . . . . . . . . 36
A.10. draft-hardt-xauth-protocol-09 . . . . . . . . . . . . . . 36
A.11. draft-hardt-xauth-protocol-10 . . . . . . . . . . . . . . 37
A.12. draft-hardt-xauth-protocol-11 . . . . . . . . . . . . . . 37
A.13. draft-hardt-xauth-protocol-11 . . . . . . . . . . . . . . 37
A.14. draft-hardt-xauth-protocol-12 . . . . . . . . . . . . . . 37
Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 37
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 38
1. Introduction
*EDITOR NOTE*
_This document captures a number of concepts that may be adopted by
the proposed GNAP working group. Please refer to this document as:_
*XAuth*
_The use of GNAP in this document is not intended to be a declaration
of it being endorsed by the proposed GNAP working group._
Hardt Expires 14 January 2021 [Page 3]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
This document describes the core Grant Negotiation and Authorization
Protocol (GNAP). The protocol supports the widely deployed use cases
supported by OAuth 2.0 [RFC6749] & [RFC6750], OpenID Connect [OIDC] -
an extension of OAuth 2.0, as well as other extensions. Related
documents include: GNAP - Advanced Features [GNAP_Advanced] and JOSE
Authentication [JOSE_Authentication] that describes the JOSE
mechanisms for client authentication.
The technology landscape has changed since OAuth 2.0 was initially
drafted. More interactions happen on mobile devices than PCs.
Modern browsers now directly support asymetric cryptographic
functions. Standards have emerged for signing and encrypting tokens
with rich payloads (JOSE) that are widely deployed.
GNAP simplifies the overall architectural model, takes advantage of
today's technology landscape, provides support for all the widely
deployed use cases, offers numerous extension points, and addresses
many of the security issues in OAuth 2.0 by passing parameters
securely between parties, rather than via a browser redirection. .
While GNAP is not backwards compatible with OAuth 2.0, it strives to
minimize the migration effort.
GNAP centers around a Grant, a representation of the collection of
user identity claims and/or resource authorizations the Client is
requesting, and the resulting identity claims and/or resource
authorizations granted by the Grant Server (GS).
User consent is often required at the GS. GNAP enables a Client and
GS to negotiate the interaction mode for the GS to obtain consent.
The suggested pronunciation of GNAP is the same as the English word
"nap", a silent "g" as in "gnaw".
_[Editor: suggestions on how to improve this are welcome!]_
1.1. Parties
The parties and their relationships to each other:
Hardt Expires 14 January 2021 [Page 4]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
+--------+ +------------+
| User | | Resource |
| | | Owner (RO) |
+--------+ +------------+
| \ / |
| \ / |
| \ / |
| \ / |
+--------+ +---------------+ +------------+
| Client |---->| Grant | | Resource |
| | (1) | Server (GS) | _ _ | Server |
| |<----| | | (RS) |
| | +---------------+ | |
| |-------------------------->| |
| | (2) | |
| |<--------------------------| |
+--------+ +------------+
This document specifies interactions between the Client and GS (1),
and the Client and RS (2).
* *User* - the person interacting with the Client who has delegated
access to identity claims about themselves to the Grant Server
(GS), and can authenticate at the GS.
* *Client* - requests a Grant from the GS to access one or more
Resource Servers (RSs), and/or identity claims about the User.
The Grant may include access tokens that the Client uses to access
the RS. There are two types of Clients: Registered Clients and
Dynamic Clients. All Clients have a private asymetric key to
authenticate with the Grant Server.
* *Registered Client* - a Client that has registered with the GS and
has a Client ID to identify itself, and can prove it possesses a
key that is linked to the Client ID. The GS may have different
policies for what different Registered Clients can request. A
Registered Client MAY be interacting with a User.
* *Dynamic Client* - a Client that has not been previously
registered with the GS, and each instance will generate it's own
asymetric key pair so it can prove it is the same instance of the
Client on subsequent requests. The GS MAY return a Dynamic Client
a Client Handle for the Client to identify itself in subsequent
requests. A single-page application with no active server
component is an example of a Dynamic Client. A Dynamic Client
MUST be interacting with a User.
Hardt Expires 14 January 2021 [Page 5]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
* *Grant Server* (GS) - manages Grants for access to APIs at RSs and
release of identity claims about the User. The GS may require
explicit consent from the RO or User to provide these to the
Client. A GS may support Registered Clients and/or Dynamic
Clients. The GS is a combination of the Authorization Server (AS)
in OAuth 2.0, and the OpenID Provider (OP) in OpenID Connect.
* *Resource Server* (RS) - has API resources that require an access
token from the GS. Some, or all of the resources are owned by the
Resource Owner.
* *Resource Owner* (RO) - owns resources at the RS, and has
delegated RS access management to the GS. The RO may be the same
entity as the User, or may be a different entity that the GS
interacts with independently. GS and RO interactions are out of
scope of this document.
1.2. Reused Terms
* *access token* - an access token as defined in [RFC6749]
Section 1.4.
* *Claim* - a Claim as defined in [OIDC] Section 5. Claims may be
issued by the GS, or by other issuers.
* *Client ID* - a GS unique identifier for a Registered Client as
defined in [RFC6749] Section 2.2.
* *ID Token* - an ID Token as defined in [OIDC] Section 2.
* *NumericDate* - a NumericDate as defined in [RFC7519] Section 2.
* *authN* - short for authentication.
* *authZ* - short for authorization.
1.3. New Terms
* *GS URI* - the endpoint at the GS the Client calls to create a
Grant, and is the unique identifier for the GS.
* *Grant* - the user identity claims and/or RS authorizations the GS
has granted to the Client. The GS MAY invalidate a Grant at any
time.
* *Grant URI* - the URI that represents the Grant. The Grant URI
MUST start with the GS URI.
Hardt Expires 14 January 2021 [Page 6]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
* *Authorization* - the access granted by the RO to the Client and
contains an access token. The GS may invalidate an Authorization
at any time.
* *Authorization URI* (AZ URI) - the URI that represents the
Authorization the Client was granted by the RO. The AZ URI MUST
start with the GS URI. The AZ URI is used to refresh an access
token.
* *Interaction* - how the Client directs the User to interact with
the GS. This document defines the interaction modes: "redirect",
"indirect", and "user_code" in Section 5
* *Client Handle* - a unique identifier at the GS for a Dynamic
Client for the Dynamic Client to refer to itself in subsequent
requests.
1.4. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
specification are to be interpreted as described in [RFC2119].
Certain security-related terms are to be understood in the sense
defined in [RFC4949]. These terms include, but are not limited to,
"attack", "authentication", "authorization", "certificate",
"confidentiality", "credential", "encryption", "identity", "sign",
"signature", "trust", "validate", and "verify".
_[Editor: review terms]_
Unless otherwise noted, all the protocol parameter names and values
are case sensitive.
Some protocol parameters are parts of a JSON document, and are
referred to in JavaScript notation. For example, foo.bar refers to
the "bar" boolean attribute in the "foo" object in the following
example JSON document:
{
"foo" : {
"bar": true
}
}
Hardt Expires 14 January 2021 [Page 7]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
2. Sequences
Before any sequence, the Client needs to be manually or
programmatically configured for the GS. See GS Options Section 3.7
for details on programmatically acquiring GS metadata.
2.1. "redirect" Interaction
The Client is a web application and wants a Grant from the User:
+--------+ +-------+
| Client | | GS |
| |--(1)--- Create Grant ----------->| |
| | | |
| |<--- Interaction Response ---(2)--| | +------+
| | | | | User |
| |--(3)--- Interaction Transfer --- | - - - | ------->| (RO) |
| | | |<--(4)-->| |
| | | | authN | |
| | | | | |
| | | |<--(5)-->| |
| | | | authZ | |
| |<--- Interaction Transfer ---(6)- | - - - | --------| |
| | | | | |
| |--(7)--- Verify Grant ----------->| | +------+
| | | |
| |<--------- Grant Response ---(8)--| |
| | | |
+--------+ +-------+
1. *Create Grant* The Client creates a Request JSON document
Section 3.5 containing an interaction.redirect object and makes a
Create Grant request (Section 3.2) by sending the JSON with an
HTTP POST to the GS URI.
2. *Interaction Response* The GS determines that interaction with
the User is required and sends an Interaction Response
(Section 4.2) containing the Grant URI and an
interaction.redirect object.
3. *Interaction Transfer* The Client redirects the User to the
redirect_uri at the GS.
4. *User Authentication* The GS authenticates the User.
5. *User Authorization* If required, the GS interacts with the User
(who is also the RO) to determine which identity claims and/or
authorizations in the Grant Request are to be granted.
Hardt Expires 14 January 2021 [Page 8]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
6. *Interaction Transfer* The GS redirects the User to the
completion_uri at the Client.
7. *Verify Grant* The Client makes an HTTP PATCH request to the
Grant URI passing the verification code (Section 3.3).
8. *Grant Response* The GS responds with a Grant Response
(Section 4.1).
2.2. "user_code" Interaction
A Client is on a device wants a Grant from the User:
+--------+ +-------+
| Client | | GS |
| |--(1)--- Create Grant ----------->| |
| | | |
| |<--- Interaction Response ---(2)--| | +------+
| | | | | User |
| |--(3)--- Read Grant ------------->| | | (RO) |
| | | |<--(4)-->| |
| | | | authN | |
| | | | | |
| | | |<--(5)---| |
| | | | code | |
| | | | | |
| | | |<--(6)-->| |
| | | | authZ | |
| | | | | |
| |<--------- Grant Response ---(7)--| | | |
| | | | | |
+--------+ | | | |
| | | |
+--------+ | | | |
| Client |<---- Information URI Redirect -- | - - - | --(8)---| |
| Server | | | | |
+--------+ +-------+ +------+
1. *Create Grant* The Client creates a Request JSON document
Section 3.5 containing an interaction.user_code object and makes
a Create Grant request (Section 3.2) by sending the JSON with an
HTTP POST to the GS URI.
2. *Interaction Response* The GS determines that interaction with
the User is required and sends an Interaction Response
(Section 4.2) containing the Grant URI and an
interaction.user_code object.
Hardt Expires 14 January 2021 [Page 9]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
3. *Read Grant* The Client makes an HTTP GET request to the Grant
URI.
4. *User Authentication* The User loads display_uri in their
browser, and the GS authenticates the User.
5. *User Code* The User enters the code at the GS.
6. *User Authorization* If required, the GS interacts with the User
(who is also the RO) to determine which identity claims and/or
authorizations in the Grant Request are to be granted.
7. *Grant Response* The GS responds with a Grant Response
(Section 4.1).
8. *Information URI Redirect* The GS redirects the User to the
information_uri provided by the Client.
2.3. Independent RO Authorization
The Client wants access to resources that require the GS to interact
with the RO, who is not interacting with the Client. The
authorization from the RO may take some time, so the GS instructs the
Client to wait and check back later.
+--------+ +-------+
| Client | | GS |
| |--(1)--- Create Grant ----------->| |
| | | |
| |<---------- Wait Response ---(2)--| | +------+
| (3) | | | | RO |
| Wait | | |<--(4)-->| |
| | | | AuthZ | |
| |--(5)--- Read Grant ------------->| | +------+
| | | |
| |<--------- Grant Response --(6)---| |
| | | |
+--------+ +-------+
1. *Create Grant* The Client creates a Grant Request (Section 3.2)
and sends it with an HTTP POST to the GS GS URI.
2. *Wait Response* The GS sends an Wait Response (Section 4.3)
containing the Grant URI and the "wait" attribute.
3. *Client Waits* The Client waits for the time specified in the
"wait" attribute.
Hardt Expires 14 January 2021 [Page 10]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
4. *RO AuthZ* The GS interacts with the RO to determine which
identity claims and/or resource authorizations in the Grant
Request are to be granted.
5. *Read Grant* The Client does an HTTP GET of the Grant URI
(Section 3.4).
6. *Grant Response* The GS responds with a Grant Response
(Section 4.1).
2.4. Resource Server Access
The Client received an AZ URI from the GS. The Client acquires an
access token, calls the RS, and later the access token expires. The
Client then gets a fresh access token.
+--------+ +----------+ +-------+
| Client | | Resource | | GS |
| |--(1)--- Access Resource --->| Server | | |
| |<------- Resource Response --| (RS) | | |
| | | | | |
| |--(2)--- Access Resource --->| | | |
| |<------- Error Response -----| | | |
| | | | | |
| | +----------+ | |
| | | |
| |--(3)--- Read AuthZ ---------------------->| |
| |<------- AuthZ Response -------------------| |
| | | |
+--------+ +-------+
1. *Resource Request* The Client accesses the RS with the access
token per Section 6 and receives a response from the RS.
2. *Resource Request* The Client attempts to access the RS, but
receives an error indicating the access token needs to be
refreshed.
3. *Read AuthZ* The Client makes a Read AuthZ (Section 3.6) with an
HTTP GET to the AZ URI and receives as Response JSON
"authorization" object (Section 4.4.5) with a fresh access token.
3. GS APIs
*Client Authentication*
All GS APIs except for GS Options require the Client to authenticate.
Authentication mechanisms include:
Hardt Expires 14 January 2021 [Page 11]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
* JOSE Authentication [JOSE_Authentication]
* [Others TBD]*
3.1. GS API Table
+==============+=============+========+=============================+
| request | http method | uri | response |
+==============+=============+========+=============================+
| GS Options | OPTIONS | GS URI | metadata |
+--------------+-------------+--------+-----------------------------+
| Create Grant | POST | GS URI | interaction, |
| | | | wait, or grant |
+--------------+-------------+--------+-----------------------------+
| Verify Grant | PATCH | Grant | grant |
| | | URI | |
+--------------+-------------+--------+-----------------------------+
| Read Grant | GET | Grant | wait, or grant |
| | | URI | |
+--------------+-------------+--------+-----------------------------+
| Read AuthZ | GET | AZ URI | authorization |
+--------------+-------------+--------+-----------------------------+
Table 1
3.2. Create Grant
The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259]
document to the GS URI. This is a Grant Request.
The JSON document MUST include the following from the Request JSON
Section 3.5:
* iat
* nonce
* uri - MUST be set to the GS URI
* method - MUST be "POST"
* client
and MAY include the following from Request JSON Section 3.5
* user
* interaction
Hardt Expires 14 January 2021 [Page 12]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
* authorizations
* claims
The GS MUST respond with one of Grant Response Section 4.1,
Interaction Response Section 4.2, Wait Response Section 4.3, or one
of the following errors:
* TBD
from Error Responses Section 7.
Following is a non-normative example of a web application Client
requesting identity claims about the User and read access to the
User's contacts:
Hardt Expires 14 January 2021 [Page 13]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
Example 1
{
"iat" : 15790460234,
"uri" : "https://as.example/endpoint",
"method" : "POST,
"nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4",
"client": {
"display": {
"name" : "SPA Display Name",
"uri" : "https://spa.example/about"
}
},
"interaction": {
"redirect": {
"completion_uri" : "https://web.example/return"
},
"global" : {
"ui_locals" : "de"
}
},
"authorizations": {
"type" : "oauth_scope",
"scope" : "read_contacts"
},
"claims": {
"oidc": {
"id_token" : {
"email" : { "essential" : true },
"email_verified" : { "essential" : true }
},
"userinfo" : {
"name" : { "essential" : true },
"picture" : null
}
}
}
}
Following is a non-normative example of a device Client requesting
two different access tokens, one request with "oauth_scope", the
other with "oauth_rich":
Hardt Expires 14 January 2021 [Page 14]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
Example 2
{
"iat" : 15790460234,
"uri" : "https://as.example/endpoint",
"method" : "POST,
"nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6",
"client": {
"id" : "di3872h34dkJW"
},
"interaction": {
"indirect": {
"information_uri": "https://device.example/c/indirect"
},
"user_code": {
"information_uri": "https://device.example/c/user_code"
}
},
"authorizations": {
"play_music": {
"type" : "oauth_scope",
"scope" : "play_music",
},
"read_user_info: {
"type" : "customer_information",
"locations": [
"https://example.com/customers",
]
"actions": [
"read"
],
"datatypes": [
"contacts",
"photos"
]
}
}
}
[Editor: the "oauth_scope" and "customer_information" types are not
normative, but generally representative of what may be defined in
[RAR].
3.3. Verify Grant
The Client verifies a Grant by doing an HTTP PATCH of a JSON document
to the Grant URI. The Client MUST only verify a Grant once.
Hardt Expires 14 January 2021 [Page 15]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
The JSON document MUST include the following from the Request JSON
Section 3.5:
* iat
* nonce
* uri - MUST be set to the Grant URI
* method - MUST be PATCH
* interaction.redirection.verification - MUST be the verification
code received per Section 5.1.1.
Following is a non-normative example:
{
"iat" : 15790460235,
"uri" : "https://as.example/endpoint/grant/example1",
"method" : "PATCH,
"nonce" : "9b6afd70-2036-47c9-b953-5dd1fd0c699a",
"interaction": {
"redirect": {
"verification" : "cb4aa22d-2fe1-4321-b87e-bbaa66fbe707"
}
}
}
The GS MUST respond with one of Grant Response Section 4.1 or one of
the following errors:
* TBD
3.4. Read Grant
The Client reads a Grant by doing an HTTP GET of the corresponding
Grant URI. The Client MAY read a Grant until it expires or has been
invalidated.
The GS MUST respond with one of Grant Response Section 4.1, Wait
Response Section 4.3, or one of the following errors:
* TBD
3.5. Request JSON
* *iat* - the time of the request as a NumericDate.
Hardt Expires 14 January 2021 [Page 16]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
* *nonce* - a unique identifier for this request. Note the Grant
Response MUST contain a matching "nonce" attribute value.
* *uri* - the URI being invoked
* *method* - the HTTP method being used
3.5.1. "client" Object
The client object MUST only one of the following:
* *id* - the Client ID the GS has for a Registered Client.
* *handle* - the Client Handle the GS previously provided a Dynamic
Client
* *display* - the display object contains the following attributes:
- *name* - a string that represents the Dynamic Client
- *uri* - a URI representing the Dynamic Client
The GS will show the the User the display.name and display.uri values
when prompting for authorization.
_[Editor: a max length for the name and URI so a GS can reserve
appropriate space?]_
3.5.2. "interaction" Object
The interaction object contains one or more interaction mode objects
per Section 5 representing the interactions the Client is willing to
provide the User. In addition to the interaction mode objects, the
interaction object may contain the "global" object;
* *global* - an optional object containing parameters that are
applicable for all interaction modes. Only one attribute is
defined in this document:
- *ui_locales* - End-User's preferred languages and scripts for
the user interface, represented as a space-separated list of
[RFC5646] language tag values, ordered by preference. This
attribute is OPTIONAL.
_[Editor: ui_locales is taken from OIDC. Why space-separated and not
a JSON array?]_
Hardt Expires 14 January 2021 [Page 17]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
3.5.3. "user" Object
* *identifiers* - The identifiers MAY be used by the GS to improve
the User experience. This object contains one or more of the
following identifiers for the User:
- *phone_number* - contains a phone number per Section 5 of
[RFC3966].
- *email* - contains an email address per [RFC5322].
- *oidc* - is an object containing both the "iss" and "sub"
attributes from an OpenID Connect ID Token [OIDC] Section 2.
* *claims* - an optional object containing one or more assertions
the Client has about the User.
- *oidc_id_token* - an OpenID Connect ID Token per [OIDC]
Section 2.
3.5.4. "authorizations" Object
Contains either an authorization request object, or key / value
pairs, where each unique key is created by the client, and the value
is an authorization request object Section 3.5.5. The key value of
"type" is reserved and MUST not be used by the client. The GS
detects the authorizations object contains an authorization request
object by the presence of the "type" property.
3.5.5. Authorization Request Object
* *type* - any of the types per [RAR]. The remaining properties are
dependent on the type.
[Editor: in the example we made up the "oauth_scope" type as a way of
using existing OAuth scopes.]
[Editor: rather then using the "type" property to differentiate
between singular and plural authorization requests, the authorization
could be an array, which would allow multiple types to be included in
a single authorization, per the latest {{RAR} document}, and
detection is if authorizations contains an array(singular), or
object(plural)]
3.5.6. "claims" Object
Includes one or more of the following:
Hardt Expires 14 January 2021 [Page 18]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
* *oidc* - an object that contains one or both of the following
objects:
- *userinfo* - Claims that will be returned as a JSON object
- *id_token* - Claims that will be included in the returned ID
Token. If the null value, an ID Token will be returned
containing no additional Claims.
The contents of the userinfo and id_token objects are Claims as
defined in [OIDC] Section 5.
* *oidc4ia* - OpenID Connect for Identity Assurance claims request
per [OIDC4IA].
* *vc* - _[Editor: define how W3C Verifiable Credentials can be
requested.]_[W3C_VC]
3.6. Read Authorization
The Client acquires and refreshes an Authorization by doing an HTTP
GET to the corresponding AZ URI.
The GS MUST respond with a Authorization JSON document Section 4.5,
or one of the following errors:
* TBD
from Error Responses Section 7.
3.7. GS Options
The Client can get the metadata for the GS by doing an HTTP OPTIONS
of the corresponding GS URI. This is the only API where the GS MAY
respond to an unauthenticated request.
The GS MUST respond with the the following JSON document:
* *uri* - the GS URI.
* *client_authentication* - a JSON array of the Client
Authentication mechanisms supported by the GS
* *interactions* - a JSON array of the interaction modes supported
by the GS.
* *authorization* - an object containing the authorizations the
Client may request from the GS, if any.
Hardt Expires 14 January 2021 [Page 19]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
- Details TBD
* *claims* - an object containing the identity claims the Client may
request from the GS, if any, and what public keys the claims will
be signed with.
- Details TBD
* *algorithms* - a JSON array of the cryptographic algorithms
supported by the GS. [details TBD]*
* *features* - an object containing feature or extension support
or one of the following errors:
* TBD
from Error Responses Section 7.
4. GS Responses
There are three successful responses to a Grant Request: Grant
Response, Interaction Response, or Wait Response.
4.1. Grant Response
The Grant Response MUST include the following from the Response JSON
Section 4.4
* iat
* nonce
* uri
and MAY include the following from the Response JSON Section 4.4
* client.handle
* authorizations
* claims
* expires_in
* warnings
Hardt Expires 14 January 2021 [Page 20]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
Example non-normative Grant Response JSON document for Example 1 in
Section 3.2:
{
"iat" : 15790460234,
"nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4",
"uri" : "https://as.example/endpoint/grant/example1",
"expires_in" : 300
"authorizations": {
"access": {
"type" : "oauth_scope",
"scope" : "read_contacts"
},
"expires_in" : 3600,
"mechanism" : "bearer",
"token" : "eyJJ2D6.example.access.token.mZf9p"
},
"claims": {
"oidc": {
"id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW",
"userinfo" : {
"name" : "John Doe",
"picture" : "https://photos.example/p/eyJzdkiO"
}
}
}
}
Note in this example the access token can not be refreshed, and
expires in an hour.
Example non-normative Grant Response JSON document for Example 2 in
Section 3.2:
{
"iat" : 15790460234,
"nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6",
"uri" : "https://as.example/endpoint/grant/example2",
"authorizations": {
"play_music": { "uri" : "https://as.example/endpoint/authz/example2" },
"read_user_info: { "uri" " "https://as.example/endpoint/authz/"}
}
}
Note in this example the GS only provided the AZ URIs, and Client
must acquire the Authorizations per Section 3.6
Hardt Expires 14 January 2021 [Page 21]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
[Editor: the Client needs to remember if it asked for a single, or
multiple authorizations, as there is no crisp algorithm for
differentiating between the responses]
4.2. Interaction Response
The Interaction Response MUST include the following from the Response
JSON Section 4.4
* iat
* nonce
* uri
* interaction
and MAY include the following from the Response JSON Section 4.4
* user
* wait
* warnings
A non-normative example of an Interaction Response follows:
{
"iat" : 15790460234,
"nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b",
"uri" : "https://as.example/endpoint/grant/example4",
"interaction" : {
"redirect" : {
"redirect_uri" : "https://as.example/i/example4"
}
}
}
4.3. Wait Response
The Wait Response MUST include the following from the Response JSON
Section 4.4
* iat
* nonce
* uri
Hardt Expires 14 January 2021 [Page 22]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
* wait
and MAY include the following from the Response JSON Section 4.4
* warnings
A non-normative example of Wait Response follows:
{
"iat" : 15790460234,
"nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b",
"uri" : "https://as.example/endpoint/grant/example5",
"wait" : 300
}
4.4. Response JSON
Details of the JSON document:
* *iat* - the time of the response as a NumericDate.
* *nonce* - the nonce that was included in the Request JSON
Section 3.5.
* *uri* - the Grant URI.
* *wait* - a numeric value representing the number of seconds the
Client should want before making a Read Grant request to the Grant
URI.
* *expires_in* - a numeric value specifying how many seconds until
the Grant expires. This attribute is OPTIONAL.
4.4.1. "client" Object
The GS may
4.4.2. "interaction" Object
If the GS wants the Client to start the interaction, the GS MUST
return an interaction object containing one or more interaction mode
responses per Section 5 to one or more of the interaction mode
requests provided by the Client.
4.4.3. "user" Object
Hardt Expires 14 January 2021 [Page 23]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
* *exists* - a boolean value indicating if the GS has a user with
one or more of the provided identifiers in the Request
user.identifiers object Section 3.5.3
4.4.4. "authorizations" Object
The authorizations object MUST contain either an authorization
response object Section 4.4.5, or a key / value pair for each key in
the Grant Request "authorizations" objectSection 3.5.4, and the value
is an authorization response object Section 4.4.5.
4.4.5. Authorization response Object
The authorization response object MUST contain only a "uri" attribute
or the following from Authorization JSON Section 4.5:
* mechanism
* token
The authorization object MAY contain any of the following from
Authorization JSON Section 4.5:
* access
* expires_in
* uri
If there is no "uri" attribute, the access token can not be
refreshed. If only the "uri" attribute is present, the Client MUST
acquire the Authorization per Section 3.6
4.4.6. "claims" Object
The claims object is a response to the Grant Request "claims" object
Section 3.5.6.
* *oidc*
- *id_token* - an OpenID Connect ID Token containing the Claims
the User consented to be released.
- *userinfo* - the Claims the User consented to be released.
Claims are defined in [OIDC] Section 5.
Hardt Expires 14 January 2021 [Page 24]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
* *oidc4ia* - OpenID Connect for Identity Assurance claims response
per [OIDC4IA].
* *vc*
The verified claims the user consented to be released. _[Editor:
details TBD]_
4.4.7. "warnings" JSON Array
Includes zero or more warnings from Section 8,
4.5. Authorization JSON
The Authorization JSON is a Grant Response Authorization Object
Section 4.4.5 or the response to a Read AuthZ request by the Client
Section 3.6.
* *mechanism* - the RS access mechanism. This document defines the
"bearer" mechanism as defined in Section 6
* *token* - the access token for accessing an RS.
* *expires_in* - a numeric value specifying how many seconds until
the access token expires.
* *uri* - the AZ URI. Used to acquire or refresh an authorization.
* *access* - an object containing the access granted:
- *type* - the type of claim request: "oauth_scope" or
"oauth_rich". See the "type" object in Section 3.5.4 for
details. This attribute is REQUIRED.
- *scope* - the scopes the Client was granted authorization for.
This will be all, or a subset, of what was requested. This
attribute is OPTIONAL.
- *authorization_details* - the authorization details granted per
[RAR]. This attribute is OPTIONAL if "type" is "oauth_rich".
_[Editor: would an optional expiry for the Authorization be useful?]_
The following is a non-normative example of Authorization JSON:
Hardt Expires 14 January 2021 [Page 25]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
{
"mechanism" : "bearer",
"token" : "eyJJ2D6.example.access.token.mZf9p"
"expires_in" : 3600,
"uri" : "https://as.example/endpoint/authz/example2",
"access": {
"type" : "oauth_scope",
"scope" : "read_calendar write_calendar"
}
}
4.6. Response Verification
On receipt of a response, the Client MUST verify the following:
* TBD
5. Interaction Modes
This document defines three interaction modes: "redirect",
"indirect", and "user_code". Extensions may define additional
interaction modes.
The "global" attribute is reserved in the interaction object for
attributes that apply to all interaction modes.
5.1. "redirect"
A Redirect Interaction is characterized by the Client redirecting the
User's browser to the GS, the GS interacting with the User, and then
GS redirecting the User's browser back to the Client. The GS
correlates the Grant Request with the unique redirect_uri, and the
Client correlates the Grant Request with the unique completion_uri.
*The request "interaction" object contains:*
* *completion_uri* a unique URI at the Client that the GS will
return the User to. The URI MUST not contain the "nonce" from the
Grant Request, and MUST not be guessable. This attribute is
REQUIRED.
*The response "interaction" object contains:*
* *redirect_uri* a unique URI at the GS that the Client will
redirect the User to. The URI MUST not contain the "nonce" from
the Grant Request, and MUST not be guessable. This attribute is
REQUIRED.
Hardt Expires 14 January 2021 [Page 26]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
* *verification* a boolean value indicating the GS requires the
Client to make a Verify Grant request.(Section 3.3)
5.1.1. "redirect" verification
If the GS indicates that Grant Verification is required, the GS MUST
add a 'verification' query parameter with a value of a unique
verification code to the completion_uri.
On receiving the verification code in the redirect from the GS, the
Client makes a Verify Grant request (Section 3.3) with the
verification code.
5.2. "indirect"
An Indirect Interaction is characterized by the Client causing the
User's browser to load the indirect_uri at GS, the GS interacting
with the User, and then the GS MAY optionally redirect the User's
Browser to a information_uri. There is no mechanism for the GS to
redirect the User's browser back to the Client.
Examples of how the Client may initiate the interaction are encoding
the indirect_uri as a code scannable by the User's mobile device, or
launching a system browser from a command line interface (CLI)
application.
The "indirect" mode is susceptible to session fixation attacks. See
TBD in the Security Considerations for details.
*The request "interaction" object contains:*
* *information_uri* an OPTIONAL URI that the GS will redirect the
User's browser to after GS interaction.
*The response "interaction" object contains:*
* *indirect_uri* the URI the Client will cause to load in the User's
browser. The URI SHOULD be short enough to be easily encoded in a
scannable code. The URI MUST not contain the "nonce" from the
Grant Request, and MUST not be guessable. _[Editor: recommend a
maximum length?]_
5.3. "user_code"
An Indirect Interaction is characterized by the Client displaying a
code and a URI for the User to load in a browser and then enter the
code. _[Editor: recommend a minimum entropy?]_
Hardt Expires 14 January 2021 [Page 27]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
*The request "interaction" object contains:*
* *information_uri* an OPTIONAL URI that the GS will redirect the
User's browser to after GS interaction.
*The response "interaction" object contains:*
* *code* the code the Client displays to the User to enter at the
display_uri. This attribute is REQUIRED.
* *display_uri* the URI the Client displays to the User to load in a
browser to enter the code.
6. RS Access
The mechanism the Client MUST use to access an RS is in the
Authorization JSON "mechanism" attribute Section 4.4.5.
The "bearer" mechanism is defined in Section 2.1 of [RFC6750]
The "jose" and "jose+body" mechanisms are defined in
[JOSE_Authentication]
A non-normative "bearer" example of the HTTP request headers follows:
GET /calendar HTTP/2
Host: calendar.example
Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA
7. Error Responses
* TBD
8. Warnings
Warnings assist a Client in detecting non-fatal errors.
* TBD
9. Extensibility
This standard can be extended in a number of areas:
* *Client Authentication Mechanisms*
Hardt Expires 14 January 2021 [Page 28]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
- An extension could define other mechanisms for the Client to
authenticate to the GS and/or RS such as Mutual TLS or HTTP
Signing. Constrained environments could use CBOR [RFC7049]
instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP
[RFC8323] instead of HTTP/2.
* *Grant*
- An extension can define new objects in the Grant Request and
Grant Response JSON that return new URIs.
* *Top Level*
- Top level objects SHOULD only be defined to represent
functionality other the existing top level objects and
attributes.
* *"client" Object*
- Additional information about the Client that the GS would
require related to an extension.
* *"user" Object*
- Additional information about the User that the GS would require
related to an extension.
* *"authorization" Object*
- Additional authorization schemas in addition to OAuth 2.0
scopes and RAR.
* *"claims" Object*
- Additional claim schemas in addition to OpenID Connect claims
and Verified Credentials.
* *interaction modes*
- Additional types of interactions a Client can start with the
User.
* *Continuous Authentication*
- An extension could define a mechanism for the Client to
regularly provide continuous authentication signals and receive
responses.
Hardt Expires 14 January 2021 [Page 29]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
_[Editor: do we specify access token introspection in this document,
or leave that to an extension?]_
10. Rational
1. *Why do Clients now always use Asymetric cryptography? Why not
keep the client secret?*
In the past, asymetric cryptography was relatively computational
expensive. Modern browsers now have asymetric cryptographic
APIs available, and modern hardware has significantly reduced
the computational impact.
2. *Why have both Client ID and Client Handle?*
While they both refer to a Client in the protocol, the Client ID
refers to a pre-registered client,and the Client Handle is
specific to an instance of a Dynamic Client. Using separate
terms clearly differentiates which identifier is being presented
to the GS.
3. *Why allow Client and GS to negotiate the user interaction
mode?*
The Client knows what interaction modes it is capable of, and
the GS knows which interaction modes it will permit for a given
Grant Request. The Client can then present the intersection to
the User to choose which one is preferred. For example, while a
device based Client may be willing to do both "indirect" and
"user_code", a GS may not enable "indirect" for concern of a
session fixation attack. Additional interaction modes will
likely become available which allows new modes to be negotiated
between Client and GS as each adds additional interaction modes.
4. *Why have both claims and authorizations?*
There are use cases for each that are independent:
authenticating a user and providing claims vs granting access to
a resource. A request for an authorization returns an access
token which may have full CRUD capabilities, while a request for
a claim returns the claim about the User - with no create,
update or delete capabilities. While the UserInfo endpoint in
OIDC may be thought of as a resource, separating the concepts
and how they are requested keeps each of them simpler in the
Editor's opinion. :)
5. *Why do some of the JSON objects only have one child, such as
the identifiers object in the user object in the Grant Request?*
Hardt Expires 14 January 2021 [Page 30]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
It is difficult to forecast future use cases. Having more
resolution may mean the difference between a simple extension,
and a convoluted extension. For example, the "global" object in
the "interaction" object allows new global parameters to be
added without impacting new interaction modes.
6. *Why is the "iss" included in the "oidc" identifier object?
Would the "sub" not be enough for the GS to identify the User?*
This decouples the GS from the OpenID Provider (OP). The GS
identifier is the GS URI, which is the endpoint at the GS. The
OP issuer identifier will likely not be the same as the GS URI.
The GS may also provide claims from multiple OPs.
7. *Why is there not a UserInfo endpoint as there is with OpenID
Connect?*
Since the Client can Read Grant at any time, it get the same
functionality as the UserInfo endpoint, without the Client
having to manage a separate access token and refresh token. If
the Client would like additional claims, it can Update Grant,
and the GS will let the Client know if an interaction is
required to get any of the additional claims, which the Client
can then start.
_[Editor: is there some other reason to have the UserInfo
endpoint?]_
8. *Why use URIs for the Grant and Authorization?*
* Grant URI and AZ URI are defined to start with the GS URI,
allowing the Client, and GS to determine which GS a Grant or
Authorization belongs to.
* URIs also enable a RESTful interface to the GS functionality.
* A large scale GS can easily separate out the services that
provide functionality as routing of requests can be done at
the HTTP layer based on URI and HTTP method. This allows a
separation of concerns, independent deployment, and
resiliency.
9. *Why use the OPTIONS method on the GS URI? Why not use a .well-
known mechanism?*
Having the GS URI endpoint respond to the metadata allows the GS
to provide Client specific results using the same Client
authentication used for other requests to the GS. It also
Hardt Expires 14 January 2021 [Page 31]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
reduces the risk of a mismatch between the advertised metadata,
and the actual metadata. A .well-known discovery mechanism may
be defined to resolve from a hostname to the GS URI.
10. *Why is there a Verify Grant? The Client can protect itself
from session fixation without it.*
Client implementations may not always follow the best practices.
The Verify Grant allows the GS to ensure there is not a session
fixation as the instance of the Client making creating the Grant
is the one that gets the verification code in the redirect.
11. **Why use the [OIDC] claims rather than the [IANA_JWT] list of
claims?
The [IANA_JWT] claims include claims that are not identity
claims, and [IANA_JWT] references the [OIDC] claims, and [OIDC]
5.1 are only identity claims.
11. Acknowledgments
This draft derives many of its concepts from Justin Richer's
Transactional Authorization draft [TxAuth].
Additional thanks to Justin Richer and Annabelle Richard Backman for
their strong critique of earlier drafts.
12. IANA Considerations
TBD
13. Security Considerations
TBD
14. References
14.1. 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>.
[RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers",
RFC 3966, DOI 10.17487/RFC3966, December 2004,
<https://www.rfc-editor.org/info/rfc3966>.
Hardt Expires 14 January 2021 [Page 32]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
DOI 10.17487/RFC5322, October 2008,
<https://www.rfc-editor.org/info/rfc5322>.
[RFC4949] Shirey, R., "Internet Security Glossary, Version 2",
FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007,
<https://www.rfc-editor.org/info/rfc4949>.
[RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
September 2009, <https://www.rfc-editor.org/info/rfc5646>.
[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>.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750,
DOI 10.17487/RFC6750, October 2012,
<https://www.rfc-editor.org/info/rfc6750>.
[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>.
[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>.
[OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and
C. Mortimore, "OpenID Connect Core 1.0", November 2014,
<https://openiD.net/specs/openiD-connect-core-1_0.html>.
[OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity
Assurance 1.0", October 2019, <https://openid.net/specs/
openid-connect-4-identity-assurance-1_0.html>.
[RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0
Rich Authorization Requests", January 2020,
<https://tools.ietf.org/html/draft-ietf-oauth-rar-00>.
[W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable
Credentials Data Model 1.0", November 2019,
<https://w3c.github.io/vc-data-model/>.
Hardt Expires 14 January 2021 [Page 33]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
[JOSE_Authentication]
Hardt, D., "JOSE Authentication", June 2020,
<https://tools.ietf.org/html/draft-hardt-gnap-jose>.
[GNAP_Advanced]
Hardt, D., "The Grant Negotiation and Authorization
Protocol - Advanced Features", June 2020,
<https://tools.ietf.org/html/draft-hardt-gnap-advanced>.
14.2. Informative References
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <https://www.rfc-editor.org/info/rfc7049>.
[RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)",
RFC 8152, DOI 10.17487/RFC8152, July 2017,
<https://www.rfc-editor.org/info/rfc8152>.
[RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K.,
Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained
Application Protocol) over TCP, TLS, and WebSockets",
RFC 8323, DOI 10.17487/RFC8323, February 2018,
<https://www.rfc-editor.org/info/rfc8323>.
[browser_based_apps]
Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based
Apps", September 2019, <https://tools.ietf.org/html/draft-
ietf-oauth-browser-based-apps-04>.
[QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic
identification and data capture techniques - QR Code bar
code symbology specification", February 2015,
<https://www.iso.org/standard/62021.html>.
[TxAuth] Richer, J., "Transactional AuthN", December 2019,
<https://tools.ietf.org/html/draft-richer-transactional-
authz-04>.
[IANA_JWT] "JSON Web Token Claims", January 2015,
<https://www.iana.org/assignments/jwt/jwt.xhtml>.
Appendix A. Document History
A.1. draft-hardt-xauth-protocol-00
* Initial version
Hardt Expires 14 January 2021 [Page 34]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
A.2. draft-hardt-xauth-protocol-01
* text clean up
* added OIDC4IA claims
* added "jws" method for accessing a resource.
* renamed Initiation Request -> Grant Request
* renamed Initiation Response -> Interaction Response
* renamed Completion Request -> Authorization Request
* renamed Completion Response -> Grant Request
* renamed completion handle -> authorization handle
* added Authentication Request, Authentication Response,
authentication handle
A.3. draft-hardt-xauth-protocol-02
* major rewrite
* handles are now URIs
* the collection of claims and authorizations are a Grant
* an Authorization is its own type
* lots of sequences added
A.4. draft-hardt-xauth-protocol-03
* fixed RO definition
* improved language in Rationals
* added user code interaction method, and aligned qrcode interaction
method
* added information_uri for code flows
A.5. draft-hardt-xauth-protocol-04
* renamed interaction uris to have purpose specific names
Hardt Expires 14 January 2021 [Page 35]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
A.6. draft-hardt-xauth-protocol-05
* separated claims from identifiers in request user object
* simplified reciprocal grant flow
* reduced interactions to redirect and indirect
* simplified interaction parameters
* added in language for Client to verify interaction completion
* added Verify Grant API and Interaction Nonce
* replaced Refresh AuthZ with Read AuthZ. Read and refresh are same
operation.
A.7. draft-hardt-xauth-protocol-06
* fixup examples to match specification
A.8. draft-hardt-xauth-protocol-07
* refactored interaction request and response syntax, and enabled
interaction mode negotiation
* generation of client handle by GS for dynamic clients
* renamed title to Grant Negotiation and Authorization Protocol.
Preserved draft-hardt-xauth-protocol filename to ease tracking
changes.
* changed Authorizations to be key / value pairs (aka dictionary)
instead of a JSON array
A.9. draft-hardt-xauth-protocol-08
* split document into three documents: core, advanced, and JOSE
authentication.
* grouped access granted into "access" object in Authorization JSON
* added warnings object to the Grant Response JSON
A.10. draft-hardt-xauth-protocol-09
* added editorial note that this document should be referred to as
XAuth
Hardt Expires 14 January 2021 [Page 36]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
A.11. draft-hardt-xauth-protocol-10
* added example of RAR authorization request
* fixed typos
A.12. draft-hardt-xauth-protocol-11
* renamed authorization_uri to interaction_uri to avoid confusion
with AZ URI
* made URI names more consistent
- renamed completion_uri to information_uri
- renamed redirect_uri to completion_uri
- renamed interaction_uri to redirect_uri
- renamed short_uri to indirect_uri
* editorial fixes
* renamed http verb to method
* added Verify Grant and verification parameters
A.13. draft-hardt-xauth-protocol-11
* removed authorization object, and made authorizations object
polymorphic
A.14. draft-hardt-xauth-protocol-12
* added Q about referencing OIDC claims vs IANA JWT
* made all authorizations be a RAR type as it provides the required
flexibility, removed "oauth_rar" type
* added RO to places where the RO and User are the same
Appendix B. Comparison with OAuth 2.0 and OpenID Connect
*Changed Features*
The major changes between GNAP and OAuth 2.0 and OpenID Connect are:
Hardt Expires 14 January 2021 [Page 37]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
* The Client always uses a private asymetric key to authenticate to
the GS. There is no client secret. i
* The Client initiates the protocol by making a signed request
directly to the GS instead of redirecting the User to the GS.
* The Client does not pass any parameters in redirecting the User to
the GS.
* The refresh_token has been replaced with an AZ URI that both
represents the authorization, and is the URI for obtaining a fresh
access token.
* The Client can request identity claims to be returned independent
of the ID Token.
* The GS URI is the only static endpoint. All other URIs are
dynamically generated. The Client does not need to register it's
redirect URIs.
*Preserved Features*
* GNAP reuses the scopes, Client IDs, and access tokens of OAuth
2.0.
* GNAP reuses the Client IDs, Claims and ID Token of OpenID Connect.
* No change is required by the Client or the RS for accessing
existing bearer token protected APIs.
*New Features*
* All Client calls to the GS are authenticated with asymetric
cryptography
* A Grant represents both the user identity claims and RS access
granted to the Client.
* Support for scannable code initiated interactions.
* Highly extensible per Section 9.
Author's Address
Dick Hardt (editor)
SignIn.Org
United States
Hardt Expires 14 January 2021 [Page 38]
Internet-DraThe Grant Negotiation and Authorization Protocol July 2020
Email: dick.hardt@gmail.com
Hardt Expires 14 January 2021 [Page 39]