< draft-hardt-xauth-protocol-10.txt		draft-hardt-xauth-protocol-11.txt >
	Network Working Group D. Hardt, Ed.		Network Working Group D. Hardt, Ed.
	Internet-Draft SignIn.Org		Internet-Draft SignIn.Org
	Intended status: Standards Track 8 June 2020		Intended status: Standards Track 4 July 2020
	Expires: 10 December 2020		Expires: 5 January 2021
	The Grant Negotiation and Authorization Protocol		The Grant Negotiation and Authorization Protocol
	draft-hardt-xauth-protocol-10		draft-hardt-xauth-protocol-11
	Abstract		Abstract
	Client software often desires resources or identity claims that are		Client software often desires resources or identity claims that are
	independent of the client. This protocol allows a user and/or		independent of the client. This protocol allows a user and/or
	resource owner to delegate resource authorization and/or release of		resource owner to delegate resource authorization and/or release of
	identity claims to a server. Client software can then request access		identity claims to a server. Client software can then request access
	to resources and/or identity claims by calling the server. The		to resources and/or identity claims by calling the server. The
	server acquires consent and authorization from the user and/or		server acquires consent and authorization from the user and/or
	resource owner if required, and then returns to the client software		resource owner if required, and then returns to the client software
	skipping to change at page 1, line 39 ¶		skipping to change at page 1, line 39 ¶
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute		Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-		working documents as Internet-Drafts. The list of current Internet-
	Drafts is at https://datatracker.ietf.org/drafts/current/.		Drafts is at https://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	This Internet-Draft will expire on 10 December 2020.		This Internet-Draft will expire on 5 January 2021.
	Copyright Notice		Copyright Notice
	Copyright (c) 2020 IETF Trust and the persons identified as the		Copyright (c) 2020 IETF Trust and the persons identified as the
	document authors. All rights reserved.		document authors. All rights reserved.
	This document is subject to BCP 78 and the IETF Trust's Legal		This document is subject to BCP 78 and the IETF Trust's Legal
	Provisions Relating to IETF Documents (https://trustee.ietf.org/		Provisions Relating to IETF Documents (https://trustee.ietf.org/
	license-info) in effect on the date of publication of this document.		license-info) in effect on the date of publication of this document.
	Please review these documents carefully, as they describe your rights		Please review these documents carefully, as they describe your rights
	skipping to change at page 2, line 24 ¶		skipping to change at page 2, line 24 ¶
	1.3. New Terms . . . . . . . . . . . . . . . . . . . . . . . . 6		1.3. New Terms . . . . . . . . . . . . . . . . . . . . . . . . 6
	1.4. Notational Conventions . . . . . . . . . . . . . . . . . 7		1.4. Notational Conventions . . . . . . . . . . . . . . . . . 7
	2. Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . 8		2. Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . 8
	2.1. "redirect" Interaction . . . . . . . . . . . . . . . . . 8		2.1. "redirect" Interaction . . . . . . . . . . . . . . . . . 8
	2.2. "user_code" Interaction . . . . . . . . . . . . . . . . . 9		2.2. "user_code" Interaction . . . . . . . . . . . . . . . . . 9
	2.3. Independent RO Authorization . . . . . . . . . . . . . . 10		2.3. Independent RO Authorization . . . . . . . . . . . . . . 10
	2.4. Resource Server Access . . . . . . . . . . . . . . . . . 11		2.4. Resource Server Access . . . . . . . . . . . . . . . . . 11
	3. GS APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 11		3. GS APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
	3.1. GS API Table . . . . . . . . . . . . . . . . . . . . . . 12		3.1. GS API Table . . . . . . . . . . . . . . . . . . . . . . 12
	3.2. Create Grant . . . . . . . . . . . . . . . . . . . . . . 12		3.2. Create Grant . . . . . . . . . . . . . . . . . . . . . . 12
	3.3. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 15		3.3. Verify Grant . . . . . . . . . . . . . . . . . . . . . . 15
	3.4. Request JSON . . . . . . . . . . . . . . . . . . . . . . 16		3.4. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 16
	3.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 16		3.5. Request JSON . . . . . . . . . . . . . . . . . . . . . . 16
	3.4.2. "interaction" Object . . . . . . . . . . . . . . . . 16		3.5.1. "client" Object . . . . . . . . . . . . . . . . . . . 17
	3.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 17		3.5.2. "interaction" Object . . . . . . . . . . . . . . . . 17
	3.4.4. "authorization" Object . . . . . . . . . . . . . . . 17		3.5.3. "user" Object . . . . . . . . . . . . . . . . . . . . 17
	3.4.5. "authorizations" Object . . . . . . . . . . . . . . . 17		3.5.4. "authorization" Object . . . . . . . . . . . . . . . 18
	3.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 17		3.5.5. "authorizations" Object . . . . . . . . . . . . . . . 18
	3.5. Read Authorization . . . . . . . . . . . . . . . . . . . 18		3.5.6. "claims" Object . . . . . . . . . . . . . . . . . . . 18
	3.6. GS Options . . . . . . . . . . . . . . . . . . . . . . . 18		3.6. Read Authorization . . . . . . . . . . . . . . . . . . . 19
	4. GS Responses . . . . . . . . . . . . . . . . . . . . . . . . 19		3.7. GS Options . . . . . . . . . . . . . . . . . . . . . . . 19
	4.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 19		4. GS Responses . . . . . . . . . . . . . . . . . . . . . . . . 20
			4.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 20
	4.2. Interaction Response . . . . . . . . . . . . . . . . . . 21		4.2. Interaction Response . . . . . . . . . . . . . . . . . . 21
	4.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 21		4.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 22
	4.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 22		4.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 23
	4.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 22		4.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 23
	4.4.2. "interaction" Object . . . . . . . . . . . . . . . . 22		4.4.2. "interaction" Object . . . . . . . . . . . . . . . . 23
	4.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 22		4.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 23
	4.4.4. "authorization" Object . . . . . . . . . . . . . . . 23		4.4.4. "authorization" Object . . . . . . . . . . . . . . . 23
	4.4.5. "authorizations" Object . . . . . . . . . . . . . . . 23		4.4.5. "authorizations" Object . . . . . . . . . . . . . . . 24
	4.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 23		4.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 24
	4.4.7. "warnings" JSON Array . . . . . . . . . . . . . . . . 24		4.4.7. "warnings" JSON Array . . . . . . . . . . . . . . . . 24
	4.5. Authorization JSON . . . . . . . . . . . . . . . . . . . 24		4.5. Authorization JSON . . . . . . . . . . . . . . . . . . . 25
	4.6. Response Verification . . . . . . . . . . . . . . . . . . 25		4.6. Response Verification . . . . . . . . . . . . . . . . . . 26
	5. Interaction Modes . . . . . . . . . . . . . . . . . . . . . . 25		5. Interaction Modes . . . . . . . . . . . . . . . . . . . . . . 26
	5.1. "redirect" . . . . . . . . . . . . . . . . . . . . . . . 25		5.1. "redirect" . . . . . . . . . . . . . . . . . . . . . . . 26
	5.2. "indirect" . . . . . . . . . . . . . . . . . . . . . . . 26		5.1.1. "redirect" verification . . . . . . . . . . . . . . . 26
	5.3. "user_code" . . . . . . . . . . . . . . . . . . . . . . . 26
	6. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 27		5.2. "indirect" . . . . . . . . . . . . . . . . . . . . . . . 27
	7. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 27		5.3. "user_code" . . . . . . . . . . . . . . . . . . . . . . . 27
	8. Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . 27		6. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 28
	9. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 27		7. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 28
	10. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 28		8. Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . 28
	11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30		9. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 28
	12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30		10. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 29
	13. Security Considerations . . . . . . . . . . . . . . . . . . . 30		11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 32
	14. References . . . . . . . . . . . . . . . . . . . . . . . . . 30		12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32
	14.1. Normative References . . . . . . . . . . . . . . . . . . 30		13. Security Considerations . . . . . . . . . . . . . . . . . . . 32
	14.2. Informative References . . . . . . . . . . . . . . . . . 32		14. References . . . . . . . . . . . . . . . . . . . . . . . . . 32
	Appendix A. Document History . . . . . . . . . . . . . . . . . . 33		14.1. Normative References . . . . . . . . . . . . . . . . . . 32
	A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 33		14.2. Informative References . . . . . . . . . . . . . . . . . 33
	A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 33		Appendix A. Document History . . . . . . . . . . . . . . . . . . 34
	A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 33		A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 34
	A.4. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 33		A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 34
	A.5. draft-hardt-xauth-protocol-04 . . . . . . . . . . . . . . 34		A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 35
	A.6. draft-hardt-xauth-protocol-05 . . . . . . . . . . . . . . 34		A.4. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 35
	A.7. draft-hardt-xauth-protocol-06 . . . . . . . . . . . . . . 34		A.5. draft-hardt-xauth-protocol-04 . . . . . . . . . . . . . . 35
	A.8. draft-hardt-xauth-protocol-07 . . . . . . . . . . . . . . 34		A.6. draft-hardt-xauth-protocol-05 . . . . . . . . . . . . . . 35
	A.9. draft-hardt-xauth-protocol-08 . . . . . . . . . . . . . . 34		A.7. draft-hardt-xauth-protocol-06 . . . . . . . . . . . . . . 36
	A.10. draft-hardt-xauth-protocol-09 . . . . . . . . . . . . . . 35		A.8. draft-hardt-xauth-protocol-07 . . . . . . . . . . . . . . 36
	A.11. draft-hardt-xauth-protocol-10 . . . . . . . . . . . . . . 35		A.9. draft-hardt-xauth-protocol-08 . . . . . . . . . . . . . . 36
	Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 35		A.10. draft-hardt-xauth-protocol-09 . . . . . . . . . . . . . . 36
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 36		A.11. draft-hardt-xauth-protocol-10 . . . . . . . . . . . . . . 36
			A.12. draft-hardt-xauth-protocol-11 . . . . . . . . . . . . . . 36
			Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 37
			Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 38
	1. Introduction		1. Introduction
	*EDITOR NOTE*		*EDITOR NOTE*
	_This document captures a number of concepts that may be adopted by		_This document captures a number of concepts that may be adopted by
	the proposed GNAP working group. Please refer to this document as:_		the proposed GNAP working group. Please refer to this document as:_
	*XAuth*		*XAuth*
	skipping to change at page 8, line 8 ¶		skipping to change at page 8, line 8 ¶
	{		{
	"foo" : {		"foo" : {
	"bar": true		"bar": true
	}		}
	}		}
	2. Sequences		2. Sequences
	Before any sequence, the Client needs to be manually or		Before any sequence, the Client needs to be manually or
	programmatically configured for the GS. See GS Options Section 3.6		programmatically configured for the GS. See GS Options Section 3.7
	for details on programmatically acquiring GS metadata.		for details on programmatically acquiring GS metadata.
	2.1. "redirect" Interaction		2.1. "redirect" Interaction
	The Client is a web application and wants a Grant from the User:		The Client is a web application and wants a Grant from the User:
	+--------+ +-------+		+--------+ +-------+
	| Client | | GS |		| Client | | GS |
	| |--(1)--- Create Grant ----------->| |		| |--(1)--- Create Grant ----------->| |
	| | | |		| | | |
	| |<--- Interaction Response ---(2)--| | +------+		| |<--- Interaction Response ---(2)--| | +------+
	| | | | | User |		| | | | | User |
	| |--(3)--- Interaction Transfer --- | - - - | ------->| |		| |--(3)--- Interaction Transfer --- | - - - | ------->| |
	| | | |<--(4)-->| |		| | | |<--(4)-->| |
	| | | | authN | |		| | | | authN | |
	| | | | | |		| | | | | |
	| | | |<--(5)-->| |		| | | |<--(5)-->| |
	| | | | authZ | |		| | | | authZ | |
	| |<--- Interaction Transfer ---(6)- | - - - | --------| |		| |<--- Interaction Transfer ---(6)- | - - - | --------| |
	| | | | | |		| | | | | |
	| |--(7)--- Read Grant ------------->| | +------+		| |--(7)--- Verify Grant ----------->| | +------+
	| | | |		| | | |
	| |<--------- Grant Response ---(8)--| |		| |<--------- Grant Response ---(8)--| |
	| | | |		| | | |
	+--------+ +-------+		+--------+ +-------+
	1. *Create Grant* The Client creates a Request JSON document		1. *Create Grant* The Client creates a Request JSON document
	Section 3.4 containing an interaction.redirect object and makes a		Section 3.5 containing an interaction.redirect object and makes a
	Create Grant request (Section 3.2) by sending the JSON with an		Create Grant request (Section 3.2) by sending the JSON with an
	HTTP POST to the GS URI.		HTTP POST to the GS URI.
	2. *Interaction Response* The GS determines that interaction with		2. *Interaction Response* The GS determines that interaction with
	the User is required and sends an Interaction Response		the User is required and sends an Interaction Response
	(Section 4.2) containing the Grant URI and an		(Section 4.2) containing the Grant URI and an
	interaction.redirect object.		interaction.redirect object.
	3. *Interaction Transfer* The Client redirects the User to the		3. *Interaction Transfer* The Client redirects the User to the
	authorization_uri at the GS.		redirect_uri at the GS.
	4. *User Authentication* The GS authenticates the User.		4. *User Authentication* The GS authenticates the User.
	5. *User Authorization* If required, the GS interacts with the User		5. *User Authorization* If required, the GS interacts with the User
	to determine which identity claims and/or authorizations in the		to determine which identity claims and/or authorizations in the
	Grant Request are to be granted.		Grant Request are to be granted.
	6. *Interaction Transfer* The GS redirects the User to the		6. *Interaction Transfer* The GS redirects the User to the
	redirect_uri at the Client.		completion_uri at the Client.
	7. *Read Grant* The Client makes an HTTP GET request to the Grant		7. *Verify Grant* The Client makes an HTTP PATCH request to the
	URI.		Grant URI passing the verification code (Section 3.3).
	8. *Grant Response* The GS responds with a Grant Response		8. *Grant Response* The GS responds with a Grant Response
	(Section 4.1).		(Section 4.1).
	2.2. "user_code" Interaction		2.2. "user_code" Interaction
	A Client is on a device wants a Grant from the User:		A Client is on a device wants a Grant from the User:
	+--------+ +-------+		+--------+ +-------+
	| Client | | GS |		| Client | | GS |
	| |--(1)--- Create Grant ----------->| |		| |--(1)--- Create Grant ----------->| |
	| | | |		| | | |
	| |<--- Interaction Response ---(2)--| | +------+		| |<--- Interaction Response ---(2)--| | +------+
	| | | | | User |		| | | | | User |
	| |--(3)--- Read Grant ------------->| | | |		| |--(3)--- Read Grant ------------->| | | |
	| | | |<--(4)-->| |		| | | |<--(4)-->| |
	| | | | authN | |		| | | | authN | |
	| | | | | |		| | | | | |
	| | | |<--(5)---| |		| | | |<--(5)---| |
	| | | | code | |		| | | | code | |
	| | | | | |		| | | | | |
	| | | |<--(6)-->| |		| | | |<--(6)-->| |
	| | | | authZ | |		| | | | authZ | |
	| | | | | |		| | | | | |
	| |<--------- Grant Response ---(7)--| | | |		| |<--------- Grant Response ---(7)--| | | |
	| | | | | |		| | | | | |
	+--------+ | | | |		+--------+ | | | |
	| | | |		| | | |
	+--------+ | | | |		+--------+ | | | |
	| Client |<----- Completion URI Redirect -- | - - - | --(8)---| |		| Client |<---- Information URI Redirect -- | - - - | --(8)---| |
	| Server | | | | |		| Server | | | | |
	+--------+ +-------+ +------+		+--------+ +-------+ +------+
	1. *Create Grant* The Client creates a Request JSON document		1. *Create Grant* The Client creates a Request JSON document
	Section 3.4 containing an interaction.user_code object and makes		Section 3.5 containing an interaction.user_code object and makes
	a Create Grant request (Section 3.2) by sending the JSON with an		a Create Grant request (Section 3.2) by sending the JSON with an
	HTTP POST to the GS URI.		HTTP POST to the GS URI.
	2. *Interaction Response* The GS determines that interaction with		2. *Interaction Response* The GS determines that interaction with
	the User is required and sends an Interaction Response		the User is required and sends an Interaction Response
	(Section 4.2) containing the Grant URI and an		(Section 4.2) containing the Grant URI and an
	interaction.user_code object.		interaction.user_code object.
	3. *Read Grant* The Client makes an HTTP GET request to the Grant		3. *Read Grant* The Client makes an HTTP GET request to the Grant
	URI.		URI.
	skipping to change at page 10, line 20 ¶		skipping to change at page 10, line 20 ¶
	5. *User Code* The User enters the code at the GS.		5. *User Code* The User enters the code at the GS.
	6. *User Authorization* If required, the GS interacts with the User		6. *User Authorization* If required, the GS interacts with the User
	to determine which identity claims and/or authorizations in the		to determine which identity claims and/or authorizations in the
	Grant Request are to be granted.		Grant Request are to be granted.
	7. *Grant Response* The GS responds with a Grant Response		7. *Grant Response* The GS responds with a Grant Response
	(Section 4.1).		(Section 4.1).
	8. *Completion URI Redirect* The GS redirects the User to the		8. *Information URI Redirect* The GS redirects the User to the
	completion_uri provided by the Client.		information_uri provided by the Client.
	2.3. Independent RO Authorization		2.3. Independent RO Authorization
	The Client wants access to resources that require the GS to interact		The Client wants access to resources that require the GS to interact
	with the RO, who is not interacting with the Client. The		with the RO, who is not interacting with the Client. The
	authorization from the RO may take some time, so the GS instructs the		authorization from the RO may take some time, so the GS instructs the
	Client to wait and check back later.		Client to wait and check back later.
	+--------+ +-------+		+--------+ +-------+
	| Client | | GS |		| Client | | GS |
	| |--(1)--- Create Grant ----------->| |		| |--(1)--- Create Grant ----------->| |
	| | | |		| | | |
	| |<---------- Wait Response ---(2)--| | +------+		| |<---------- Wait Response ---(2)--| | +------+
	| (3) | | | | RO |		| (3) | | | | RO |
	| Wait | | |<--(4)-->| |		| Wait | | |<--(4)-->| |
	| | | | AuthZ | |		| | | | AuthZ | |
	| |--(5)--- Read Grant ------------->| | +------+		| |--(5)--- Read Grant ------------->| | +------+
	| | | |		| | | |
	| |<--------- Grant Response --(6)---| |		| |<--------- Grant Response --(6)---| |
	| | | |		| | | |
	+--------+ +-------+		+--------+ +-------+
	1. *Create Grant* The Client creates a Grant Request (Section 3.2)		1. *Create Grant* The Client creates a Grant Request (Section 3.2)
	and sends it with an HTTP POST to the GS GS URI.		and sends it with an HTTP POST to the GS GS URI.
	2. *Wait Response* The GS sends an Wait Response (Section 4.3)		2. *Wait Response* The GS sends an Wait Response (Section 4.3)
	containing the Grant URI and the "wait" attribute.		containing the Grant URI and the "wait" attribute.
	3. *Client Waits* The Client waits for the time specified in the		3. *Client Waits* The Client waits for the time specified in the
	"wait" attribute.		"wait" attribute.
	4. *RO AuthZ* The GS interacts with the RO to determine which		4. *RO AuthZ* The GS interacts with the RO to determine which
	identity claims and/or resource authorizations in the Grant		identity claims and/or resource authorizations in the Grant
	Request are to be granted.		Request are to be granted.
	5. *Read Grant* The Client does an HTTP GET of the Grant URI		5. *Read Grant* The Client does an HTTP GET of the Grant URI
	(Section 3.3).		(Section 3.4).
	6. *Grant Response* The GS responds with a Grant Response		6. *Grant Response* The GS responds with a Grant Response
	(Section 4.1).		(Section 4.1).
	2.4. Resource Server Access		2.4. Resource Server Access
	The Client received an AZ URI from the GS. The Client acquires an		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		access token, calls the RS, and later the access token expires. The
	Client then gets a fresh access token.		Client then gets a fresh access token.
	skipping to change at page 11, line 43 ¶		skipping to change at page 11, line 43 ¶
	| | | |		| | | |
	+--------+ +-------+		+--------+ +-------+
	1. *Resource Request* The Client accesses the RS with the access		1. *Resource Request* The Client accesses the RS with the access
	token per Section 6 and receives a response from the RS.		token per Section 6 and receives a response from the RS.
	2. *Resource Request* The Client attempts to access the RS, but		2. *Resource Request* The Client attempts to access the RS, but
	receives an error indicating the access token needs to be		receives an error indicating the access token needs to be
	refreshed.		refreshed.
	3. *Read AuthZ* The Client makes a Read AuthZ (Section 3.5) with an		3. *Read AuthZ* The Client makes a Read AuthZ (Section 3.6) with an
	HTTP GET to the AZ URI and receives an Response JSON		HTTP GET to the AZ URI and receives an Response JSON
	"authorization" object (Section 4.4.4) with a fresh access token.		"authorization" object (Section 4.4.4) with a fresh access token.
	3. GS APIs		3. GS APIs
	*Client Authentication*		*Client Authentication*
	All GS APIs except for GS Options require the Client to authenticate.		All GS APIs except for GS Options require the Client to authenticate.
	Authentication mechanisms include:		Authentication mechanisms include:
	* JOSE Authentication [JOSE_Authentication]		* JOSE Authentication [JOSE_Authentication]
	* [Others TBD]*		* [Others TBD]*
	3.1. GS API Table		3.1. GS API Table
	+--------------+-----------+--------+-----------------------------+		+==============+=============+========+=============================+
	| request | http verb | uri | response |		| request | http method | uri | response |
	+==============+===========+========+=============================+		+==============+=============+========+=============================+
	| GS Options | OPTIONS | GS URI | metadata |		| GS Options | OPTIONS | GS URI | metadata |
	+--------------+-----------+--------+-----------------------------+		+--------------+-------------+--------+-----------------------------+
	| Create Grant | POST | GS URI | interaction, wait, or grant |		| Create Grant | POST | GS URI | interaction, |
	+--------------+-----------+--------+-----------------------------+		| | | | wait, or grant |
	| Read Grant | GET | Grant | wait, or grant |		+--------------+-------------+--------+-----------------------------+
	| | | URI | |		| Verify Grant | PATCH | Grant | grant |
	+--------------+-----------+--------+-----------------------------+		| | | URI | |
	| Read AuthZ | GET | AZ URI | authorization |		+--------------+-------------+--------+-----------------------------+
	+--------------+-----------+--------+-----------------------------+		| Read Grant | GET | Grant | wait, or grant |
			| | | URI | |
			+--------------+-------------+--------+-----------------------------+
			| Read AuthZ | GET | AZ URI | authorization |
			+--------------+-------------+--------+-----------------------------+
	Table 1		Table 1
	3.2. Create Grant		3.2. Create Grant
	The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259]		The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259]
	document to the GS URI. This is a Greant Request.		document to the GS URI. This is a Grant Request.
	The JSON document MUST include the following from the Request JSON		The JSON document MUST include the following from the Request JSON
	Section 3.4:		Section 3.5:
	* iat		* iat
	* nonce		* nonce
	* uri set to the GS URI		* uri - MUST be set to the GS URI
			* method - MUST be "POST"
	* client		* client
	and MAY include the following from Request JSON Section 3.4		and MAY include the following from Request JSON Section 3.5
	* user		* user
	* interaction		* interaction
	* authorization or authorizations		* authorization or authorizations
	* claims		* claims
	The GS MUST respond with one of Grant Response Section 4.1,		The GS MUST respond with one of Grant Response Section 4.1,
	Interaction Response Section 4.2, Wait Response Section 4.3, or one		Interaction Response Section 4.2, Wait Response Section 4.3, or one
	of the following errors:		of the following errors:
	* TBD		* TBD
	from Error Responses Section 7.		from Error Responses Section 7.
	Following is a non-normative example of a web application Client		Following is a non-normative example of a web application Client
	requesting identity claims about the User and read access to the		requesting identity claims about the User and read access to the
	User's contacts:		User's contacts:
	Example 1		Example 1
	{		{
	"iat" : 15790460234,		"iat" : 15790460234,
	"uri" : "https://as.example/endpoint",		"uri" : "https://as.example/endpoint",
			"method" : "POST,
	"nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4",		"nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4",
	"client": {		"client": {
	"display": {		"display": {
	"name" : "SPA Display Name",		"name" : "SPA Display Name",
	"uri" : "https://spa.example/about"		"uri" : "https://spa.example/about"
	}		}
	},		},
	"interaction": {		"interaction": {
	"redirect": {		"redirect": {
	"redirect_uri" : "https://web.example/return"		"completion_uri" : "https://web.example/return"
	},		},
	"global" : {		"global" : {
	"ui_locals" : "de"		"ui_locals" : "de"
	}		}
	},		},
	"authorization": {		"authorization": {
	"type" : "oauth_scope",		"type" : "oauth_scope",
	"scope" : "read_contacts"		"scope" : "read_contacts"
	},		},
	"claims": {		"claims": {
	skipping to change at page 15, line 10 ¶		skipping to change at page 15, line 10 ¶
	}		}
	Following is a non-normative example of a device Client requesting		Following is a non-normative example of a device Client requesting
	access to play music using "oauth_rich":		access to play music using "oauth_rich":
	Example 2		Example 2
	{		{
	"iat" : 15790460234,		"iat" : 15790460234,
	"uri" : "https://as.example/endpoint",		"uri" : "https://as.example/endpoint",
			"method" : "POST,
	"nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6",		"nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6",
	"client": {		"client": {
	"id" : "di3872h34dkJW"		"id" : "di3872h34dkJW"
	},		},
	"interaction": {		"interaction": {
	"indirect": {		"indirect": {
	"completion_uri": "https://device.example/c/indirect"		"information_uri": "https://device.example/c/indirect"
	},		},
	"user_code": {		"user_code": {
	"completion_uri": "https://device.example/c/user_code"		"information_uri": "https://device.example/c/user_code"
	}		}
	},		},
	"authorization": {		"authorization": {
	"type" : "oauth_rich",		"type" : "oauth_rich",
	"scope" : "play_music",		"scope" : "play_music",
	"authorization_details" [		"authorization_details" [
	{		{
	"type": "customer_information",		"type": "customer_information",
	"locations": [		"locations": [
	"https://example.com/customers",		"https://example.com/customers",
	skipping to change at page 15, line 43 ¶		skipping to change at page 15, line 44 ¶
	],		],
	"datatypes": [		"datatypes": [
	"contacts",		"contacts",
	"photos"		"photos"
	]		]
	}		}
	]		]
	}		}
	}		}
	3.3. Read Grant		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.
			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		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		Grant URI. The Client MAY read a Grant until it expires or has been
	invalidated.		invalidated.
	The GS MUST respond with one of Grant Response Section 4.1, Wait		The GS MUST respond with one of Grant Response Section 4.1, Wait
	Response Section 4.3, or one of the following errors:		Response Section 4.3, or one of the following errors:
	* TBD		* TBD
	3.4. Request JSON		3.5. Request JSON
	* *iat* - the time of the request as a NumericDate.		* *iat* - the time of the request as a NumericDate.
	* *nonce* - a unique identifier for this request. Note the Grant		* *nonce* - a unique identifier for this request. Note the Grant
	Response MUST contain a matching "nonce" attribute value.		Response MUST contain a matching "nonce" attribute value.
	* *uri* - the GS URI		* *uri* - the URI being invoked
			* *method* - the HTTP method being used
	3.4.1. "client" Object		3.5.1. "client" Object
	The client object MUST only one of the following:		The client object MUST only one of the following:
	* *id* - the Client ID the GS has for a Registered Client.		* *id* - the Client ID the GS has for a Registered Client.
	* *handle* - the Client Handle the GS previously provided a Dynamic		* *handle* - the Client Handle the GS previously provided a Dynamic
	Client		Client
	* *display* - the display object contains the following attributes:		* *display* - the display object contains the following attributes:
	- *name* - a string that represents the Dynamic Client		- *name* - a string that represents the Dynamic Client
	- *uri* - a URI representing the Dynamic Client		- *uri* - a URI representing the Dynamic Client
	The GS will show the the User the display.name and display.uri values		The GS will show the the User the display.name and display.uri values
	when prompting for authorization.		when prompting for authorization.
	_[Editor: a max length for the name and URI so a GS can reserve		_[Editor: a max length for the name and URI so a GS can reserve
	appropriate space?]_		appropriate space?]_
	3.4.2. "interaction" Object		3.5.2. "interaction" Object
	The interaction object contains one or more interaction mode objects		The interaction object contains one or more interaction mode objects
	per Section 5 representing the interactions the Client is willing to		per Section 5 representing the interactions the Client is willing to
	provide the User. In addition to the interaction mode objects, the		provide the User. In addition to the interaction mode objects, the
	interaction object may contain the "global" object;		interaction object may contain the "global" object;
	* *global* - an optional object containing parameters that are		* *global* - an optional object containing parameters that are
	applicable for all interaction modes. Only one attribute is		applicable for all interaction modes. Only one attribute is
	defined in this document:		defined in this document:
	- *ui_locales* - End-User's preferred languages and scripts for		- *ui_locales* - End-User's preferred languages and scripts for
	the user interface, represented as a space-separated list of		the user interface, represented as a space-separated list of
	[RFC5646] language tag values, ordered by preference. This		[RFC5646] language tag values, ordered by preference. This
	attribute is OPTIONAL.		attribute is OPTIONAL.
	_[Editor: ui_locales is taken from OIDC. Why space-separated and not		_[Editor: ui_locales is taken from OIDC. Why space-separated and not
	a JSON array?]_		a JSON array?]_
	3.4.3. "user" Object		3.5.3. "user" Object
	* *identifiers* - The identifiers MAY be used by the GS to improve		* *identifiers* - The identifiers MAY be used by the GS to improve
	the User experience. This object contains one or more of the		the User experience. This object contains one or more of the
	following identifiers for the User:		following identifiers for the User:
	- *phone_number* - contains a phone number per Section 5 of		- *phone_number* - contains a phone number per Section 5 of
	[RFC3966].		[RFC3966].
	- *email* - contains an email address per [RFC5322].		- *email* - contains an email address per [RFC5322].
	- *oidc* - is an object containing both the "iss" and "sub"		- *oidc* - is an object containing both the "iss" and "sub"
	attributes from an OpenID Connect ID Token [OIDC] Section 2.		attributes from an OpenID Connect ID Token [OIDC] Section 2.
	* *claims* - an optional object containing one or more assertions		* *claims* - an optional object containing one or more assertions
	the Client has about the User.		the Client has about the User.
	- *oidc_id_token* - an OpenID Connect ID Token per [OIDC]		- *oidc_id_token* - an OpenID Connect ID Token per [OIDC]
	Section 2.		Section 2.
	3.4.4. "authorization" Object		3.5.4. "authorization" Object
	* *type* - one of the following values: "oauth_scope" or		* *type* - one of the following values: "oauth_scope" or
	"oauth_rich". Extensions MAY define additional types, and the		"oauth_rich". Extensions MAY define additional types, and the
	required attributes. This attribute is REQUIRED.		required attributes. This attribute is REQUIRED.
	* *scope* - a string containing the OAuth 2.0 scope per [RFC6749]		* *scope* - a string containing the OAuth 2.0 scope per [RFC6749]
	section 3.3. MUST be included if type is "oauth_scope". MAY be		section 3.3. MUST be included if type is "oauth_scope". MAY be
	included if type is "oauth_rich".		included if type is "oauth_rich".
	* *authorization_details* - an authorization_details JSON array of		* *authorization_details* - an authorization_details JSON array of
	objects per [RAR]. MUST be included if type is "oauth_rich".		objects per [RAR]. MUST be included if type is "oauth_rich".
	MUST not be included if type is "oauth_scope"		MUST not be included if type is "oauth_scope"
	_[Editor: details may change as the RAR document evolves]_		_[Editor: details may change as the RAR document evolves]_
	3.4.5. "authorizations" Object		3.5.5. "authorizations" Object
	One or more key / value pairs, where each unique key is created by		One or more key / value pairs, where each unique key is created by
	the client, and the value is an authorization object per		the client, and the value is an authorization object per
	Section 3.4.4.		Section 3.5.4.
	3.4.6. "claims" Object		3.5.6. "claims" Object
	Includes one or more of the following:		Includes one or more of the following:
	* *oidc* - an object that contains one or both of the following		* *oidc* - an object that contains one or both of the following
	objects:		objects:
	- *userinfo* - Claims that will be returned as a JSON object		- *userinfo* - Claims that will be returned as a JSON object
	- *id_token* - Claims that will be included in the returned ID		- *id_token* - Claims that will be included in the returned ID
	Token. If the null value, an ID Token will be returned		Token. If the null value, an ID Token will be returned
	skipping to change at page 18, line 20 ¶		skipping to change at page 19, line 14 ¶
	The contents of the userinfo and id_token objects are Claims as		The contents of the userinfo and id_token objects are Claims as
	defined in [OIDC] Section 5.		defined in [OIDC] Section 5.
	* *oidc4ia* - OpenID Connect for Identity Assurance claims request		* *oidc4ia* - OpenID Connect for Identity Assurance claims request
	per [OIDC4IA].		per [OIDC4IA].
	* *vc* - _[Editor: define how W3C Verifiable Credentials can be		* *vc* - _[Editor: define how W3C Verifiable Credentials can be
	requested.]_[W3C_VC]		requested.]_[W3C_VC]
	3.5. Read Authorization		3.6. Read Authorization
	The Client acquires and refreshes an Authorization by doing an HTTP		The Client acquires and refreshes an Authorization by doing an HTTP
	GET to the corresponding AZ URI.		GET to the corresponding AZ URI.
	The GS MUST respond with a Authorization JSON document Section 4.5,		The GS MUST respond with a Authorization JSON document Section 4.5,
	or one of the following errors:		or one of the following errors:
	* TBD		* TBD
	from Error Responses Section 7.		from Error Responses Section 7.
	3.6. GS Options		3.7. GS Options
	The Client can get the metadata for the GS by doing an HTTP 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		of the corresponding GS URI. This is the only API where the GS MAY
	respond to an unauthenticated request.		respond to an unauthenticated request.
	The GS MUST respond with the the following JSON document:		The GS MUST respond with the the following JSON document:
	* *uri* - the GS URI.		* *uri* - the GS URI.
	* *client_authentication* - a JSON array of the Client		* *client_authentication* - a JSON array of the Client
	skipping to change at page 20, line 4 ¶		skipping to change at page 20, line 46 ¶
	* client.handle		* client.handle
	* authorization or authorizations		* authorization or authorizations
	* claims		* claims
	* expires_in		* expires_in
	* warnings		* warnings
	Example non-normative Grant Response JSON document for Example 1 in		Example non-normative Grant Response JSON document for Example 1 in
	Section 3.2:		Section 3.2:
	{		{
	"iat" : 15790460234,		"iat" : 15790460234,
	"nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4",		"nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4",
	"uri" : "https://as.example/endpoint/grant/example1",		"uri" : "https://as.example/endpoint/grant/example1",
	"expires_in" : 300		"expires_in" : 300
	"authorization": {		"authorization": {
	"access": {		"access": {
	"type" : "oauth_scope",		"type" : "oauth_scope",
	"scope" : "read_contacts"		"scope" : "read_contacts"
	},		},
	"expires_in" : 3600,		"expires_in" : 3600,
	"mechanism" : "bearer",		"mechanism" : "bearer",
	"token" : "eyJJ2D6.example.access.token.mZf9p"		"token" : "eyJJ2D6.example.access.token.mZf9p"
	},		},
	"claims": {		"claims": {
	"oidc": {		"oidc": {
	"id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW",		"id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW",
	"userinfo" : {		"userinfo" : {
	"name" : "John Doe",		"name" : "John Doe",
	"picture" : "https://photos.example/p/eyJzdkiO"		"picture" : "https://photos.example/p/eyJzdkiO"
	}		}
	}		}
	}		}
	}		}
	Note in this example the access token can not be refreshed, and		Note in this example the access token can not be refreshed, and
	expires in an hour.		expires in an hour.
	Example non-normative Grant Response JSON document for Example 2 in		Example non-normative Grant Response JSON document for Example 2 in
	Section 3.2:		Section 3.2:
	{		{
	"iat" : 15790460234,		"iat" : 15790460234,
	"nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6",		"nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6",
	"uri" : "https://as.example/endpoint/grant/example2",		"uri" : "https://as.example/endpoint/grant/example2",
	"authorization": {		"authorization": {
	"uri" : "https://as.example/endpoint/authz/example2"		"uri" : "https://as.example/endpoint/authz/example2"
	}		}
	}		}
	Note in this example the GS only provided the AZ URI, and Client must		Note in this example the GS only provided the AZ URI, and Client must
	acquire the Authorization per Section 3.5		acquire the Authorization per Section 3.6
	4.2. Interaction Response		4.2. Interaction Response
	The Interaction Response MUST include the following from the Response		The Interaction Response MUST include the following from the Response
	JSON Section 4.4		JSON Section 4.4
	* iat		* iat
	* nonce		* nonce
	* uri		* uri
	* interaction		* interaction
	and MAY include the following from the Response JSON Section 4.4		and MAY include the following from the Response JSON Section 4.4
	skipping to change at page 21, line 34 ¶		skipping to change at page 22, line 28 ¶
	* warnings		* warnings
	A non-normative example of an Interaction Response follows:		A non-normative example of an Interaction Response follows:
	{		{
	"iat" : 15790460234,		"iat" : 15790460234,
	"nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b",		"nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b",
	"uri" : "https://as.example/endpoint/grant/example4",		"uri" : "https://as.example/endpoint/grant/example4",
	"interaction" : {		"interaction" : {
	""redirect" : {		""redirect" : {
	"authorization_uri" : "https://as.example/i/example4"		"redirect_uri" : "https://as.example/i/example4"
	}		}
	},
	"user": {
	"exists" : true
	}		}
	}		}
	4.3. Wait Response		4.3. Wait Response
	The Wait Response MUST include the following from the Response JSON		The Wait Response MUST include the following from the Response JSON
	Section 4.4		Section 4.4
	* iat		* iat
	skipping to change at page 22, line 26 ¶		skipping to change at page 23, line 19 ¶
	"wait" : 300		"wait" : 300
	}		}
	4.4. Response JSON		4.4. Response JSON
	Details of the JSON document:		Details of the JSON document:
	* *iat* - the time of the response as a NumericDate.		* *iat* - the time of the response as a NumericDate.
	* *nonce* - the nonce that was included in the Request JSON		* *nonce* - the nonce that was included in the Request JSON
	Section 3.4.		Section 3.5.
	* *uri* - the Grant URI.		* *uri* - the Grant URI.
	* *wait* - a numeric value representing the number of seconds the		* *wait* - a numeric value representing the number of seconds the
	Client should want before making a Read Grant request to the Grant		Client should want before making a Read Grant request to the Grant
	URI.		URI.
	* *expires_in* - a numeric value specifying how many seconds until		* *expires_in* - a numeric value specifying how many seconds until
	the Grant expires. This attribute is OPTIONAL.		the Grant expires. This attribute is OPTIONAL.
	skipping to change at page 23, line 4 ¶		skipping to change at page 23, line 42 ¶
	The GS may		The GS may
	4.4.2. "interaction" Object		4.4.2. "interaction" Object
	If the GS wants the Client to start the interaction, the GS MUST		If the GS wants the Client to start the interaction, the GS MUST
	return an interaction object containing one or more interaction mode		return an interaction object containing one or more interaction mode
	responses per Section 5 to one or more of the interaction mode		responses per Section 5 to one or more of the interaction mode
	requests provided by the Client.		requests provided by the Client.
	4.4.3. "user" Object		4.4.3. "user" Object
	* *exists* - a boolean value indicating if the GS has a user with		* *exists* - a boolean value indicating if the GS has a user with
	one or more of the provided identifiers in the Request		one or more of the provided identifiers in the Request
	user.identifiers object Section 3.4.3		user.identifiers object Section 3.5.3
	4.4.4. "authorization" Object		4.4.4. "authorization" Object
	The authorization object MUST contain only a "uri" attribute or the		The authorization object MUST contain only a "uri" attribute or the
	following from Authorization JSON Section 4.5:		following from Authorization JSON Section 4.5:
	* mechanism		* mechanism
	* token		* token
	The authorization object MAY contain any of the following from		The authorization object MAY contain any of the following from
	Authorization JSON Section 4.5:		Authorization JSON Section 4.5:
	* access		* access
	* expires_in		* expires_in
	* uri		* uri
	If there is no "uri" attribute, the access token can not be		If there is no "uri" attribute, the access token can not be
	refreshed. If only the "uri" attribute is present, the Client MUST		refreshed. If only the "uri" attribute is present, the Client MUST
	acquire the Authorization per Section 3.5		acquire the Authorization per Section 3.6
	4.4.5. "authorizations" Object		4.4.5. "authorizations" Object
	A key / value pair for each key in the Grant Request "authorizations"		A key / value pair for each key in the Grant Request "authorizations"
	object, and the value is per Section 4.4.4.		object, and the value is per Section 4.4.4.
	4.4.6. "claims" Object		4.4.6. "claims" Object
	The claims object is a response to the Grant Request "claims" object		The claims object is a response to the Grant Request "claims" object
	Section 3.4.4.		Section 3.5.4.
	* *oidc*		* *oidc*
	- *id_token* - an OpenID Connect ID Token containing the Claims		- *id_token* - an OpenID Connect ID Token containing the Claims
	the User consented to be released.		the User consented to be released.
	- *userinfo* - the Claims the User consented to be released.		- *userinfo* - the Claims the User consented to be released.
	Claims are defined in [OIDC] Section 5.		Claims are defined in [OIDC] Section 5.
	skipping to change at page 24, line 18 ¶		skipping to change at page 25, line 9 ¶
	details TBD]_		details TBD]_
	4.4.7. "warnings" JSON Array		4.4.7. "warnings" JSON Array
	Includes zero or more warnings from Section 8,		Includes zero or more warnings from Section 8,
	4.5. Authorization JSON		4.5. Authorization JSON
	The Authorization JSON is the contents of a Grant Response		The Authorization JSON is the contents of a Grant Response
	"authorization" object Section 4.4.5 or the response to a Read AuthZ		"authorization" object Section 4.4.5 or the response to a Read AuthZ
	request by the Client Section 3.5.		request by the Client Section 3.6.
	* *type* - the type of claim request: "oauth_scope" or "oauth_rich".		* *type* - the type of claim request: "oauth_scope" or "oauth_rich".
	See the "type" object in Section 3.4.4 for details.		See the "type" object in Section 3.5.4 for details.
	* *mechanism* - the RS access mechanism. This document defines the		* *mechanism* - the RS access mechanism. This document defines the
	"bearer" mechanism as defined in Section 6		"bearer" mechanism as defined in Section 6
	* *token* - the access token for accessing an RS.		* *token* - the access token for accessing an RS.
	* *expires_in* - a numeric value specifying how many seconds until		* *expires_in* - a numeric value specifying how many seconds until
	the access token expires.		the access token expires.
	* *uri* - the AZ URI. Used to acquire or refresh an authorization.		* *uri* - the AZ URI. Used to acquire or refresh an authorization.
	* *access* - an object containing the access granted:		* *access* - an object containing the access granted:
	- *type* - the type of claim request: "oauth_scope" or		- *type* - the type of claim request: "oauth_scope" or
	"oauth_rich". See the "type" object in Section 3.4.4 for		"oauth_rich". See the "type" object in Section 3.5.4 for
	details. This attribute is REQUIRED.		details. This attribute is REQUIRED.
	- *scope* - the scopes the Client was granted authorization for.		- *scope* - the scopes the Client was granted authorization for.
	This will be all, or a subset, of what was requested. This		This will be all, or a subset, of what was requested. This
	attribute is OPTIONAL.		attribute is OPTIONAL.
	- *authorization_details* - the authorization details granted per		- *authorization_details* - the authorization details granted per
	[RAR]. This attribute is OPTIONAL if "type" is "oauth_rich".		[RAR]. This attribute is OPTIONAL if "type" is "oauth_rich".
	_[Editor: would an optional expiry for the Authorization be useful?]_		_[Editor: would an optional expiry for the Authorization be useful?]_
	skipping to change at page 25, line 36 ¶		skipping to change at page 26, line 25 ¶
	interaction modes.		interaction modes.
	The "global" attribute is reserved in the interaction object for		The "global" attribute is reserved in the interaction object for
	attributes that apply to all interaction modes.		attributes that apply to all interaction modes.
	5.1. "redirect"		5.1. "redirect"
	A Redirect Interaction is characterized by the Client redirecting the		A Redirect Interaction is characterized by the Client redirecting the
	User's browser to the GS, the GS interacting with the User, and then		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		GS redirecting the User's browser back to the Client. The GS
	correlates the Grant Request with the unique authorization_uri, and		correlates the Grant Request with the unique redirect_uri, and the
	the Client correlates the Grant Request with the unique redirect_uri.		Client correlates the Grant Request with the unique completion_uri.
	*The request "interaction" object contains:*		*The request "interaction" object contains:*
	* *redirect_uri* a unique URI at the Client that the GS will return		* *completion_uri* a unique URI at the Client that the GS will
	the User to. The URI MUST not contain the "nonce" from the Grant		return the User to. The URI MUST not contain the "nonce" from the
	Request, and MUST not be guessable. This attribute is REQUIRED.		Grant Request, and MUST not be guessable. This attribute is
			REQUIRED.
	*The response "interaction" object contains:*		*The response "interaction" object contains:*
	* *authorization_uri* a unique URI at the GS that the Client will		* *redirect_uri* a unique URI at the GS that the Client will
	redirect the User to. The URI MUST not contain the "nonce" from		redirect the User to. The URI MUST not contain the "nonce" from
	the Grant Request, and MUST not be guessable. This attribute is		the Grant Request, and MUST not be guessable. This attribute is
	REQUIRED.		REQUIRED.
			* *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"		5.2. "indirect"
	An Indirect Interaction is characterized by the Client causing the		An Indirect Interaction is characterized by the Client causing the
	User's browser to load the short_uri at GS, the GS interacting with		User's browser to load the indirect_uri at GS, the GS interacting
	the User, and then the GS MAY optionally redirect the User's Browser		with the User, and then the GS MAY optionally redirect the User's
	to a completion_uri. There is no mechanism for the GS to redirect		Browser to a information_uri. There is no mechanism for the GS to
	the User's browser back to the Client.		redirect the User's browser back to the Client.
	Examples of how the Client may initiate the interaction are encoding		Examples of how the Client may initiate the interaction are encoding
	the short_uri as a code scannable by the User's mobile device, or		the indirect_uri as a code scannable by the User's mobile device, or
	launching a system browser from a command line interface (CLI)		launching a system browser from a command line interface (CLI)
	application.		application.
	The "indirect" mode is susceptible to session fixation attacks. See		The "indirect" mode is susceptible to session fixation attacks. See
	TBD in the Security Considerations for details.		TBD in the Security Considerations for details.
	*The request "interaction" object contains:*		*The request "interaction" object contains:*
	* *completion_uri* an OPTIONAL URI that the GS will redirect the		* *information_uri* an OPTIONAL URI that the GS will redirect the
	User's browser to after GS interaction.		User's browser to after GS interaction.
	*The response "interaction" object contains:*		*The response "interaction" object contains:*
	* *short_uri* the URI the Client will cause to load in the User's		* *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		browser. The URI SHOULD be short enough to be easily encoded in a
	scannable code. The URI MUST not contain the "nonce" from the		scannable code. The URI MUST not contain the "nonce" from the
	Grant Request, and MUST not be guessable. _[Editor: recommend a		Grant Request, and MUST not be guessable. _[Editor: recommend a
	maximum length?]_		maximum length?]_
	5.3. "user_code"		5.3. "user_code"
	An Indirect Interaction is characterized by the Client displaying a		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 and a URI for the User to load in a browser and then enter the
	code. _[Editor: recommend a minimum entropy?]_		code. _[Editor: recommend a minimum entropy?]_
	*The request "interaction" object contains:*		*The request "interaction" object contains:*
	* *completion_uri* an OPTIONAL URI that the GS will redirect the		* *information_uri* an OPTIONAL URI that the GS will redirect the
	User's browser to after GS interaction.		User's browser to after GS interaction.
	*The response "interaction" object contains:*		*The response "interaction" object contains:*
	* *code* the code the Client displays to the User to enter at the		* *code* the code the Client displays to the User to enter at the
	display_uri. This attribute is REQUIRED.		display_uri. This attribute is REQUIRED.
	* *display_uri* the URI the Client displays to the User to load in a		* *display_uri* the URI the Client displays to the User to load in a
	browser to enter the code.		browser to enter the code.
	skipping to change at page 28, line 41 ¶		skipping to change at page 29, line 44 ¶
	- An extension could define a mechanism for the Client to		- An extension could define a mechanism for the Client to
	regularly provide continuous authentication signals and receive		regularly provide continuous authentication signals and receive
	responses.		responses.
	_[Editor: do we specify access token introspection in this document,		_[Editor: do we specify access token introspection in this document,
	or leave that to an extension?]_		or leave that to an extension?]_
	10. Rational		10. Rational
	1. *Why have both Client ID and Client Handle?*		1. *Why do Clients now always use Asymetric cryptography? Why not
			keep the client secret?*
	While they both refer to a Client in the protocol, the Client ID		In the past, asymetric cryptography was relatively computational
	refers to a pre-registered client,and the Client Handle is		expensive. Modern browsers now have asymetric cryptographic
	specific to an instance of a Dynamic Client. Using separate		APIs available, and modern hardware has significantly reduced
	terms clearly differentiates which identifier is being presented		the computational impact.
	to the GS.
	2. *Why allow Client and GS to negotiate the user interaction mode?*		2. *Why have both Client ID and Client Handle?*
	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.
	3. *Why have both claims and authorizations?*		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.
	There are use cases for each that are independent: authenticating		3. *Why allow Client and GS to negotiate the user interaction
	a user and providing claims vs granting access to a resource. A		mode?*
	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. :)
	4. *Why do some of the JSON objects only have one child, such as the		The Client knows what interaction modes it is capable of, and
	identifiers object in the user object in the Grant Request?*		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.
	It is difficult to forecast future use cases. Having more		4. *Why have both claims and authorizations?*
	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.
	5. *Why is the "iss" included in the "oidc" identifier object?		There are use cases for each that are independent:
	Would the "sub" not be enough for the GS to identify the User?*		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. :)
	This decouples the GS from the OpenID Provider (OP). The GS		5. *Why do some of the JSON objects only have one child, such as
	identifier is the GS URI, which is the endpoint at the GS. The		the identifiers object in the user object in the Grant Request?*
	OP issuer identifier will likely not be the same as the GS URI.
	The GS may also provide claims from multiple OPs.
	6. *Why is there not a UserInfo endpoint as there is with OpenID		It is difficult to forecast future use cases. Having more
	Connect?*		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.
	Since the Client can Read Grant at any time, it get the same		6. *Why is the "iss" included in the "oidc" identifier object?
	functionality as the UserInfo endpoint, without the Client having		Would the "sub" not be enough for the GS to identify the User?*
	to manage a separate access token and refresh token. If the		This decouples the GS from the OpenID Provider (OP). The GS
	Client would like additional claims, it can Update Grant, and the		identifier is the GS URI, which is the endpoint at the GS. The
	GS will let the Client know if an interaction is required to get		OP issuer identifier will likely not be the same as the GS URI.
	any of the additional claims, which the Client can then start.		The GS may also provide claims from multiple OPs.
	_[Editor: is there some other reason to have the UserInfo		7. *Why is there not a UserInfo endpoint as there is with OpenID
	endpoint?]_		Connect?*
	7. *Why use URIs for the Grant and Authorization?*		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.
	* Grant URI and AZ URI are defined to start with the GS URI,		_[Editor: is there some other reason to have the UserInfo
	allowing the Client, and GS to determine which GS a Grant or		endpoint?]_
	Authorization belongs to.
	* URIs also enable a RESTful interface to the GS functionality.		8. *Why use URIs for the Grant and Authorization?*
	* A large scale GS can easily separate out the services that		* Grant URI and AZ URI are defined to start with the GS URI,
	provide functionality as routing of requests can be done at		allowing the Client, and GS to determine which GS a Grant or
	the HTTP layer based on URI and HTTP verb. This allows a		Authorization belongs to.
	separation of concerns, independent deployment, and
	resiliency.
	8. *Why use the OPTIONS verb on the GS URI? Why not use a .well-		* URIs also enable a RESTful interface to the GS functionality.
	known mechanism?*
	Having the GS URI endpoint respond to the metadata allows the GS		* A large scale GS can easily separate out the services that
	to provide Client specific results using the same Client		provide functionality as routing of requests can be done at
	authentication used for other requests to the GS. It also		the HTTP layer based on URI and HTTP method. This allows a
	reduces the risk of a mismatch between the advertised metadata,		separation of concerns, independent deployment, and
	and the actual metadata. A .well-known discovery mechanism may		resiliency.
	be defined to resolve from a hostname to the GS URI.
			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
			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. Acknowledgments		11. Acknowledgments
	This draft derives many of its concepts from Justin Richer's		This draft derives many of its concepts from Justin Richer's
	Transactional Authorization draft [TxAuth].		Transactional Authorization draft [TxAuth].
	Additional thanks to Justin Richer and Annabelle Richard Backman for		Additional thanks to Justin Richer and Annabelle Richard Backman for
	their strong critique of earlier drafts.		their strong critique of earlier drafts.
	12. IANA Considerations		12. IANA Considerations
	skipping to change at page 34, line 5 ¶		skipping to change at page 35, line 28 ¶
	A.4. draft-hardt-xauth-protocol-03		A.4. draft-hardt-xauth-protocol-03
	* fixed RO definition		* fixed RO definition
	* improved language in Rationals		* improved language in Rationals
	* added user code interaction method, and aligned qrcode interaction		* added user code interaction method, and aligned qrcode interaction
	method		method
	* added completion_uri for code flows		* added information_uri for code flows
	A.5. draft-hardt-xauth-protocol-04		A.5. draft-hardt-xauth-protocol-04
	* renamed interaction uris to have purpose specific names		* renamed interaction uris to have purpose specific names
	A.6. draft-hardt-xauth-protocol-05		A.6. draft-hardt-xauth-protocol-05
	* separated claims from identifiers in request user object		* separated claims from identifiers in request user object
	* simplified reciprocal grant flow		* simplified reciprocal grant flow
	skipping to change at page 35, line 4 ¶		skipping to change at page 36, line 29 ¶
	* changed Authorizations to be key / value pairs (aka dictionary)		* changed Authorizations to be key / value pairs (aka dictionary)
	instead of a JSON array		instead of a JSON array
	A.9. draft-hardt-xauth-protocol-08		A.9. draft-hardt-xauth-protocol-08
	* split document into three documents: core, advanced, and JOSE		* split document into three documents: core, advanced, and JOSE
	authentication.		authentication.
	* grouped access granted into "access" object in Authorization JSON		* grouped access granted into "access" object in Authorization JSON
	* added warnings object to the Grant Response JSON		* added warnings object to the Grant Response JSON
	A.10. draft-hardt-xauth-protocol-09		A.10. draft-hardt-xauth-protocol-09
	* added editorial note that this document should be referred to as		* added editorial note that this document should be referred to as
	XAuth		XAuth
	A.11. draft-hardt-xauth-protocol-10		A.11. draft-hardt-xauth-protocol-10
	* added example of RAR authorization request		* added example of RAR authorization request
	* fixed typos		* 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
	Appendix B. Comparison with OAuth 2.0 and OpenID Connect		Appendix B. Comparison with OAuth 2.0 and OpenID Connect
	*Changed Features*		*Changed Features*
	The major changes between GNAP and OAuth 2.0 and OpenID Connect are:		The major changes between GNAP and OAuth 2.0 and OpenID Connect are:
	* The Client always uses a private asymetric key to authenticate to		* The Client always uses a private asymetric key to authenticate to
	the GS. There is no client secret. i		the GS. There is no client secret. i
	* The Client initiates the protocol by making a signed request		* The Client initiates the protocol by making a signed request
End of changes. 89 change blocks.
	272 lines changed or deleted		371 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/