< draft-hardt-xauth-protocol-09.txt   draft-hardt-xauth-protocol-10.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 7 June 2020 Intended status: Standards Track 8 June 2020
Expires: 9 December 2020 Expires: 10 December 2020
The Grant Negotiation and Authorization Protocol The Grant Negotiation and Authorization Protocol
draft-hardt-xauth-protocol-09 draft-hardt-xauth-protocol-10
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 9 December 2020. This Internet-Draft will expire on 10 December 2020.
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 25 skipping to change at page 2, line 25
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. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 15
3.4. Request JSON . . . . . . . . . . . . . . . . . . . . . . 15 3.4. Request JSON . . . . . . . . . . . . . . . . . . . . . . 16
3.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 15 3.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 16
3.4.2. "interaction" Object . . . . . . . . . . . . . . . . 16 3.4.2. "interaction" Object . . . . . . . . . . . . . . . . 16
3.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 16 3.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 17
3.4.4. "authorization" Object . . . . . . . . . . . . . . . 17 3.4.4. "authorization" Object . . . . . . . . . . . . . . . 17
3.4.5. "authorizations" Object . . . . . . . . . . . . . . . 17 3.4.5. "authorizations" Object . . . . . . . . . . . . . . . 17
3.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 17 3.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 17
3.5. Read Authorization . . . . . . . . . . . . . . . . . . . 18 3.5. Read Authorization . . . . . . . . . . . . . . . . . . . 18
3.6. GS Options . . . . . . . . . . . . . . . . . . . . . . . 18 3.6. GS Options . . . . . . . . . . . . . . . . . . . . . . . 18
4. GS Responses . . . . . . . . . . . . . . . . . . . . . . . . 19 4. GS Responses . . . . . . . . . . . . . . . . . . . . . . . . 19
4.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 19 4.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 19
4.2. Interaction Response . . . . . . . . . . . . . . . . . . 20 4.2. Interaction Response . . . . . . . . . . . . . . . . . . 21
4.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 21 4.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 21
4.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 22 4.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 22
4.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 22 4.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 22
4.4.2. "interaction" Object . . . . . . . . . . . . . . . . 22 4.4.2. "interaction" Object . . . . . . . . . . . . . . . . 22
4.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 22 4.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 22
4.4.4. "authorization" Object . . . . . . . . . . . . . . . 22 4.4.4. "authorization" Object . . . . . . . . . . . . . . . 23
4.4.5. "authorizations" Object . . . . . . . . . . . . . . . 23 4.4.5. "authorizations" Object . . . . . . . . . . . . . . . 23
4.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 23 4.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 23
4.4.7. "warnings" JSON Array . . . . . . . . . . . . . . . . 23 4.4.7. "warnings" JSON Array . . . . . . . . . . . . . . . . 24
4.5. Authorization JSON . . . . . . . . . . . . . . . . . . . 24 4.5. Authorization JSON . . . . . . . . . . . . . . . . . . . 24
4.6. Response Verification . . . . . . . . . . . . . . . . . . 25 4.6. Response Verification . . . . . . . . . . . . . . . . . . 25
5. Interaction Modes . . . . . . . . . . . . . . . . . . . . . . 25 5. Interaction Modes . . . . . . . . . . . . . . . . . . . . . . 25
5.1. "redirect" . . . . . . . . . . . . . . . . . . . . . . . 25 5.1. "redirect" . . . . . . . . . . . . . . . . . . . . . . . 25
5.2. "indirect" . . . . . . . . . . . . . . . . . . . . . . . 25 5.2. "indirect" . . . . . . . . . . . . . . . . . . . . . . . 26
5.3. "user_code" . . . . . . . . . . . . . . . . . . . . . . . 26 5.3. "user_code" . . . . . . . . . . . . . . . . . . . . . . . 26
6. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 26 6. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 27
7. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 27 7. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 27
8. Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . 27 8. Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . 27
9. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 27 9. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 27
10. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 28 10. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 28
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30
13. Security Considerations . . . . . . . . . . . . . . . . . . . 30 13. Security Considerations . . . . . . . . . . . . . . . . . . . 30
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 30
14.1. Normative References . . . . . . . . . . . . . . . . . . 30 14.1. Normative References . . . . . . . . . . . . . . . . . . 30
14.2. Informative References . . . . . . . . . . . . . . . . . 32 14.2. Informative References . . . . . . . . . . . . . . . . . 32
Appendix A. Document History . . . . . . . . . . . . . . . . . . 32 Appendix A. Document History . . . . . . . . . . . . . . . . . . 33
A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 32 A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 33
A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 32 A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 33
A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 33 A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 33
A.4. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 33 A.4. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 33
A.5. draft-hardt-xauth-protocol-04 . . . . . . . . . . . . . . 33 A.5. draft-hardt-xauth-protocol-04 . . . . . . . . . . . . . . 34
A.6. draft-hardt-xauth-protocol-05 . . . . . . . . . . . . . . 33 A.6. draft-hardt-xauth-protocol-05 . . . . . . . . . . . . . . 34
A.7. draft-hardt-xauth-protocol-06 . . . . . . . . . . . . . . 34 A.7. draft-hardt-xauth-protocol-06 . . . . . . . . . . . . . . 34
A.8. draft-hardt-xauth-protocol-07 . . . . . . . . . . . . . . 34 A.8. draft-hardt-xauth-protocol-07 . . . . . . . . . . . . . . 34
A.9. draft-hardt-xauth-protocol-08 . . . . . . . . . . . . . . 34 A.9. draft-hardt-xauth-protocol-08 . . . . . . . . . . . . . . 34
Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 34 A.10. draft-hardt-xauth-protocol-09 . . . . . . . . . . . . . . 35
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 35 A.11. draft-hardt-xauth-protocol-10 . . . . . . . . . . . . . . 35
Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 35
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 36
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 14, line 44 skipping to change at page 14, line 44
}, },
"userinfo" : { "userinfo" : {
"name" : { "essential" : true }, "name" : { "essential" : true },
"picture" : null "picture" : null
} }
} }
} }
} }
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: 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",
"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" "completion_uri": "https://device.example/c/indirect"
}, },
"user_code": { "user_code": {
"completion_uri": "https://device.example/c/user_code" "completion_uri": "https://device.example/c/user_code"
} }
}, },
"authorization": { "authorization": {
"type" : "oauth_scope", "type" : "oauth_rich",
"scope" : "play_music" "scope" : "play_music",
"authorization_details" [
{
"type": "customer_information",
"locations": [
"https://example.com/customers",
]
"actions": [
"read"
],
"datatypes": [
"contacts",
"photos"
]
}
]
} }
} }
3.3. Read Grant 3.3. 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
skipping to change at page 17, line 14 skipping to change at page 17, line 28
* *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.4.4. "authorization" Object
* *type* - one of the following values: "oauth_scope" or * *type* - one of the following values: "oauth_scope" or
"oauth_rich". This attribute is REQUIRED. "oauth_rich". Extensions MAY define additional types, and the
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" or section 3.3. MUST be included if type is "oauth_scope". MAY be
"oauth_rich". included if type is "oauth_rich".
* *authorization_details* - an authorization_details object per * *authorization_details* - an authorization_details JSON array of
[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"
_[Editor: details may change as the RAR document evolves]_ _[Editor: details may change as the RAR document evolves]_
3.4.5. "authorizations" Object 3.4.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.4.4.
3.4.6. "claims" Object 3.4.6. "claims" Object
skipping to change at page 19, line 36 skipping to change at page 20, line 4
* 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": {
"type" : "oauth_scope", "access": {
"scope" : "read_contacts", "type" : "oauth_scope",
"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"
skipping to change at page 24, line 12 skipping to change at page 24, line 21
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.5.
* *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.4.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.
skipping to change at page 34, line 37 skipping to change at page 35, line 4
* 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
* added editorial note that this document should be referred to as
XAuth
A.11. draft-hardt-xauth-protocol-10
* added example of RAR authorization request
* fixed typos
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. 23 change blocks. 
32 lines changed or deleted 62 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/