Network Working Group D. Hardt, Ed.
Internet-Draft SignIn.Org
Intended status: Standards Track 6 June 2020
Expires: 8 December 2020
The Grant Negotiation and Authorization Protocol
draft-hardt-xauth-protocol-07
draft-hardt-xauth-protocol-08
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 can 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 8 December 2020.
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
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 . . . . . . . . . . . . . . . . . . . . . . . . 4 3
1.1. Parties . . . . . . . . . . . . . . . . . . . . . . . . . 5 4
1.2. Reused Terms . . . . . . . . . . . . . . . . . . . . . . 6 5
1.3. New Terms . . . . . . . . . . . . . . . . . . . . . . . . 6
1.4. Notational Conventions . . . . . . . . . . . . . . . . . 7 6
2. Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . 8 7
2.1. Create and Verify Grant "redirect" Interaction . . . . . . . . . . . . . . . . . 8 7
2.2. Create and Read Grant - Redirect . . . . . . . . . . . . 9
2.3. Create and Read Grant - Indirect . . . . . . . . . . . . 10
2.4. Reciprocal Grant . . . . . . . . . . . . . . . . . . . . 11
2.5. GS Initiated Grant . . . . . . . . . . . . . . . . . . . 12
2.6. Create and Update . . . . . . . . . . . . . . . . . . . . 12
2.7. Create and Delete . . . . . . . . . . . . . . . . . . . . 14
2.8. Create, Discover, and Delete . . . . . . . . . . . . . . 16
2.9. Create and Wait . . . . . . . . . . . . "user_code" Interaction . . . . . . . . . 16
2.10. Read Grant . . . . . . . . . 8
2.3. Independent RO Authorization . . . . . . . . . . . . . . 17
2.11. 10
2.4. Resource Server Access . . . . . . . . . . . . . . . . . 18
2.12. GS API Table . . . . . . . . . . . . . . . . . . . . . . 19 11
3. Grant and AuthZ Life Cycle . . . . . . . . . . . . . . . . . 19
4. GS APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.1. Create Grant 11
3.1. GS API Table . . . . . . . . . . . . . . . . . . . . . . 20
4.2. Verify 12
3.2. Create Grant . . . . . . . . . . . . . . . . . . . . . . 23
4.3. 12
3.3. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 24
4.4. Update Grant . . . . . . . . . . . . . . . . . . . . . . 24
4.5. Delete Grant . . . . . . . . . . . . . . . . . . . . . . 25
4.6. 14
3.4. Request JSON . . . . . . . . . . . . . . . . . . . . . . 25
4.6.1. 14
3.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 25
4.6.2. 14
3.4.2. "interaction" Object . . . . . . . . . . . . . . . . 26
4.6.3. 15
3.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 26
4.6.4. 15
3.4.4. "authorization" Object . . . . . . . . . . . . . . . 27
4.6.5. 16
3.4.5. "authorizations" Object . . . . . . . . . . . . . . . 27
4.6.6. 16
3.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 27
4.6.7. "verification" Object . . . . . . . . . . . . . . . . 28
4.7. 16
3.5. Read Authorization . . . . . . . . . . . . . . . . . . . 28
4.8. Update Authorization . . . . . . . . . . . . . . . . . . 28
4.9. Delete Authorization . . . . . . . . . . . . . . . . . . 29
4.10. 17
3.6. GS Options . . . . . . . . . . . . . . . . . . . . . . . 29
4.11. Grant Options . . . . . . . . . . . . . . . . . . . . . . 30
4.12. AuthZ Options . . . . . . . . . . . . . . . . . . . . . . 30
4.13. Request Verification . . . . . . . . . . . . . . . . . . 30
5. GS Initiated Grant . . . . . . . . . . . . . . . . . . . . . 31
6. 17
4. GS Responses . . . . . . . . . . . . . . . . . . . . . . . . 31
6.1. 18
4.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 31
6.2. 18
4.2. Interaction Response . . . . . . . . . . . . . . . . . . 32
6.3. 19
4.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 33
6.4. 20
4.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 34
6.4.1. 21
4.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 34
6.4.2. 21
4.4.2. "interaction" Object . . . . . . . . . . . . . . . . 34
6.4.3. 21
4.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 34
6.4.4. 21
4.4.4. "authorization" Object . . . . . . . . . . . . . . . 34
6.4.5. 21
4.4.5. "authorizations" Object . . . . . . . . . . . . . . . 34
6.4.6. 22
4.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 35
6.5. Authorization 22
4.4.7. "warnings" JSON Array . . . . . . . . . . . . . . . . 22
4.5. Authorization JSON . . . . 35
6.5.1. Signing and Encryption . . . . . . . . . . . . . . . 36
6.6. 23
4.6. Response Verification . . . . . . . . . . . . . . . . . . 36
7. interaction mode Objects . . . . 24
5. Interaction Modes . . . . . . . . . . . . . . 36
7.1. "redirect" mode . . . . . . . . 24
5.1. "redirect" . . . . . . . . . . . . . 37
7.1.1. request "interaction" object contains: . . . . . . . 37
7.1.2. response "interaction" object contains: . . . . . . . 37
7.2. 24
5.2. "indirect" mode . . . . . . . . . . . . . . . . . . . . . 37
7.2.1. request "interaction" object contains: . . . . . . . 37
7.2.2. response "interaction" object contains: . . . . . . . 37
7.3. 24
5.3. "user_code" mode . . . . . . . . . . . . . . . . . . . . 37
7.3.1. request "interaction" object contains: . . . . . . . 38
7.3.2. response "interaction" object contains: . . . . . . . 38
8. 25
6. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 38
8.1. Bearer Token . . . . . . . . . . . . . . . . . . . . . . 38
9. 25
7. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 38
10. JOSE Authentication . . . . . . . . . . . . . . . . . . . . . 38
10.1. GS Access . . . . . . . . . . . . . . . . . . . . . . . 39
10.1.1. Authorization Header . . . . . . . . . . . . . . . . 40
10.1.2. Signed Body . . . . . . . . . . . . . . . . . . . . 41
10.1.3. Public Key Resolution . . . . . . . . . . . . . . . 42
10.2. RS Access . . . . . . . . . . . . . . . . . . . . . . . 42
10.2.1. JOSE header . . . . . . . . . . . . . . . . . . . . 43
10.2.2. "jose" Mechanism . . . . . . . . . . . . . . . . . . 43
10.2.3. "jose+body" Mechanism . . . . . . . . . . . . . . . 44
10.2.4. Public Key Resolution . . . . . . . . . . . . . . . 45
10.3. Request Encryption . . . . . . . . . . . . . . . . . . . 45
10.4. Response Signing . . . . . . . . . . . . 26
8. Warnings . . . . . . . . 45
10.5. Response Encryption . . . . . . . . . . . . . . . . . . 46
11. 26
9. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 46
12. 26
10. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 47
13. 27
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 51
14. 29
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51
15. 29
13. Security Considerations . . . . . . . . . . . . . . . . . . . 51
16. 29
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 51
16.1. 29
14.1. Normative References . . . . . . . . . . . . . . . . . . 51
16.2. 29
14.2. Informative References . . . . . . . . . . . . . . . . . 53 31
Appendix A. Document History . . . . . . . . . . . . . . . . . . 54 31
A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 54 31
A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 54 31
A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 55 32
A.4. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 55 32
A.5. draft-hardt-xauth-protocol-04 . . . . . . . . . . . . . . 55 32
A.6. draft-hardt-xauth-protocol-05 . . . . . . . . . . . . . . 55 32
A.7. draft-hardt-xauth-protocol-06 . . . . . . . . . . . . . . 55 33
A.8. draft-hardt-xauth-protocol-07 . . . . . . . . . . . . . . 56 33
A.9. draft-hardt-xauth-protocol-08 . . . . . . . . . . . . . . 33
Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 56 33
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 57 34
1. Introduction
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], and OpenID Connect [OIDC], [OIDC] -
an extension of OAuth 2.0, as well as other extensions, extensions. Related
documents include: GNAP - Advanced Features [GNAP_Advanced] and other use
cases JOSE
Authentication [JOSE_Authentication] that are not supported, such as acquiring multiple access
tokens at the same time, and updating describes the request during user
interaction. This protocol also addresses many of the security
issues in OAuth 2.0 by having parameters securely sent directly
between parties, rather than via a browser redirection. 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.
Additional use cases are now being served with extensions to OAuth
2.0: OpenID Connect added support for authentication and releasing
identity claims; [RFC8252] added support for native apps; [RFC8628]
added support for smart devices; and support for [browser_based_apps]
is being worked on. There are numerous efforts on adding proof-of-
possession to resource access.
This protocol
GNAP simplifies the overall architectural model, takes advantage of
today's technology landscape, provides support for all the widely
deployed use cases, and offers numerous extension points. 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 this protocol GNAP is not backwards compatible with OAuth 2.0, it strives to
minimize the migration effort.
This protocol
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.
[Editor: 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!]
[Editor: suggestions for other names than XAuth are welcome!] welcome!]_
1.1. Parties
The parties and their relationships to each other:
+--------+ +------------+
| 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 Client can create, verify, retrieve, update, and delete a
Grant. When a Grant is created, the Client receives from the GS
the granted may include access token(s) for the RS(s), and identity claims
about tokens that the User. The Client uses an access token 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, and to requests of requests. The GS MAY return a Resource Server that require proof-
of-possession access. 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.
* *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.
* *Authorization* - the access granted by the RO to the Client.
Contains 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 read, update, and
delete refresh an access
token.
* *Interaction* - how the Client directs the User to interact with
the GS. This document defines the interaction modes redirect,
indirect, modes: "redirect",
"indirect", and user_code "user_code" in Section 7 5
* *Client Handle* - a GS 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
}
}
2. Sequences
Before any sequence, the Client needs to be manually or
programmatically configured for the GS. See GS Options Section 4.10 3.6
for details on programmatically acquiring GS metadata.
[Editor: a plethora of sequences are included to illustrate all the
different use cases that are supported. Many sequences are similar,
and show a slightly different sequence that can support different use
cases. These could potentially be moved to a use case document in
the future.]
2.1. Create and Verify Grant
A Dynamic "redirect" Interaction
The Client is a web application and wants a Grant from the User using a Redirect
Interaction: User:
+--------+ +-------+
| Client | | GS |
| |--(1)--- Create Grant ----------->| |
| | | |
| |<--- Interaction Response ---(2)--| | +------+
| | | | | User |
| |--(3)--- Interaction Transfer --- | - - - | ------->| |
| | | |<--(4)-->| |
| | | | authN | |<--(4)-->| |
| | | | authN | |
| | | |<--(5)-->| |
| | | | authZ | |
| |<--- Interaction Transfer ---(6)- | - - - | --------| |
| | | | | |
| |--(7)--- Verify Read Grant ----------->| ------------->| | +------+
| | | |
| |<--------- Grant Response ---(8)--| |
| | | |
+--------+ +-------+
1. *Create Grant* The Client creates a Request JSON document
Section 4.6 3.4 containing an interaction.redirect object and makes a
Create Grant request (Section 4.1) 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 6.2) 4.2) containing the Grant URI and an interaction
interaction.redirect object.
3. *Interaction Transfer* The Client redirects the User to the
Redirect URI
authorization_uri at the GS.
4. *User Authentication* The GS authenticates the User.
5. *User Authorization* If required, the GS interacts with the User
to determine which identity claims and/or authorizations in the
Grant Request are to be granted.
6. *Interaction Transfer* The GS redirects the User to the
Completion URI
redirect_uri at the Client, passing an Interaction Nonce. Client.
7. *Read Grant* The Client creates a JSON document containing a
verification object Section 4.6.7 and does a Verify Grant
Section 4.2 request by makes an HTTP PATCH with the document GET request to the Grant
URI.
8. *Grant Response* The GS responds with a Grant Response
(Section 6.1). 4.1).
2.2. Create and Read Grant - Redirect "user_code" Interaction
A Registered Client is on a device wants a Grant from the User using a Redirect
Interaction: User:
+--------+ +-------+
| Client | | GS |
| |--(1)--- Create Grant ----------->| |
| | | |
| |<--- Interaction Response ---(2)--| |
| | | |
| |--(3)--- Read Grant ------------->| | +------+
| | | | | User |
| |--(4)--- Interaction Transfer --- | - - - | ------->| |
| | | | | |
| | | |<--(5)-->| |
| | | | authN | |
| | | |<--(6)-->| |
| | | | authZ | |
| |<--------- Grant Response ---(7)--| | | |
| | | | | |
| |<--- Interaction Transfer ---(8)- | - - - | --------| |
| | | | | |
+--------+ +-------+ +------+
1. *Create Grant* The Client makes a Create Grant request
(Section 4.1) to the GS URI.
2. *Interaction Response* The GS determines that interaction with
the User is required and sends an Interaction Response
(Section 6.2) containing the Grant URI and an interaction object.
3. *Read Grant* The Client does an HTTP GET of the Grant URI
(Section 4.3).
4. *Interaction Transfer* The Client transfers User interaction to
the GS.
5. *User Authentication* The GS authenticates the User.
6. *User Authorization* If required, the GS interacts with the User
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 6.1).
8. *Interaction Transfer* The GS redirects the User to the
Completion URI of the Client. The Client verifies it is the same
User that it transferred to the GS.
2.3. Create and |--(3)--- Read Grant - Indirect
A Registered Client wants a Grant from the User using an Indirect
Interaction:
+--------+ +-------+ ------------->| | Client | | GS |
| |--(1)--- Create Grant ----------->|
| | | |<--(4)-->| |
| | |<--- Interaction Response ---(2)--| | | authN | |
| | |--(3)--- Read Grant ------------->| | +------+ | | |
| | User | |<--(5)---| | |--(4)--- Interaction Transfer ---
| - - - | ------->| | | code | |
| | | | | | |<--(5)-->|
| | | |<--(6)-->| |
| authN | | | | authZ | |<--(6)-->| |
| | | | authZ | |
| |<--------- Grant Response ---(7)--| | | |
+--------+ | |
| | | | | |
+--------+ | | | |
| Info |<--- Interaction Transfer ---(8)- | - - - | --------| |
| Server | | | | |
+--------+ +-------+ +------+
The sequence is the same except:
* In step (4) the User either scans a bar code or uses a separate
device to navigate to the Code URI and enters the User Code.
* In step (8) the GS redirects the User to the Information URI
provided by the Client.
2.4. Reciprocal Grant
Party A and Party B are both a Client and a GS, and each Client would
like a Grant for the other GS. The sequence starts off the same as
in Section 2.2, but Party B makes a Create Grant Request before
sending a Grant Response:
Party A Party B
+--------+ +--------+ | Client | | GS |
~ ~ ~ ~ ~ ~ Same as steps 1 - 6 of ~ ~ ~ ~ ~ ~
+------+ | | Create and Read Grant above | |
| User | |
| | |
| | | GS |<--------- Create Grant ---(1)---| Client |
| | | | | |
| | | |<------- Grant Response ---(2)---| |
| | | | | |
| |<----- | - - - | -- Interaction Transfer --(3)---| |
| | | | | |
| |<-(4)->| | | |
| | AuthZ | | | |
+------+ | GS |--(5)--- Grant Response -------->| Client |
| | | |
+--------+ +--------+
1. *Create Grant* Party B creates a Grant Request (Section 4.1) with
user.reciprocal set to the Party B Grant URI that will be in the
step (2) Grant Response, and sends it with an HTTP POST to the
Party A GS URI. This enables Party A to link the reciprocal
Grants.
2. *Grant Response* Party B responds to Party A's Create Grant
Request with a Grant Response that includes the Party B Grant
URI.
3. *Interaction Transfer* Party B redirects the User to the Completion URI at Party A.
4. *User Authorization* If required, Party A interacts with the User
to determine which identity claims and/or authorizations in Party
B's Create Grant Request are to be granted.
5. *Grant Response* Party A responds with a Grant Response
(Section 6.1).
2.5. GS Initiated Grant
The User is at the GS, and wants to interact with a Registered
Client. The GS can redirect the User to the Client:
+--------+ +-------+ +------+
| Client | | GS | | User |
| | | |<--(1)-->| |
| | | | | |
| |<----- GS Initiation Redirect --- -- | - - - | --(2)---| |
| (3) | | | --(8)---| |
|
| verify |--(4)--- Read Grant ------------->| | +------+
| | | |
| |<--------- Grant Response --(5)---| Server | | | | |
+--------+ +-------+
1. *User Interaction* The GS interacts with the User to determine
the Client and what identity claims and authorizations to
provide. The GS creates a Grant and corresponding Grant URI.
2. *GS Initiated Redirect* The GS redirects the User to the Client's
interaction_uri, adding a query parameter with the name "Grant
URI" and the value being the URL encoded Grant URI.
3. *Client Verification* The Client verifies the Grant URI is from
an GS the Client trusts, and starts with the GS GS URI.
4. *Read Grant* The Client does an HTTP GET of the Grant URI
(Section 4.3).
5. *Grant Response* The GS responds with a Grant Response
(Section 6.1).
See Section 5 for more details.
2.6. Create and Update
The Client requests an identity claim to determine who the User is.
Once the Client learns who the User is, and the Client updates the
Grant for additional identity claims which the GS prompts the User
for and returns to the Client. Once those are received, the Client
updates the Grant with the remaining identity claims required.
+--------+ +-------+
| Client | | GS |
| |--(1)--- Create Grant ----------->| |
| | interaction.keep:true | |
| | | |
| |<--- Interaction Response ---(2)--| |
| | | |
| |--(3)--- Read Grant ------------->| | +------+
| | | | | User |
| |--(4)--- Interaction Transfer --- | - - - | ------->| |
| | | | | |
| | | |<--(5)-->| |
| | | | authN | |
| |<--------- Grant Response ---(6)--| | | |
| (7) | | | | |
| eval |--(8)--- Update Grant ----------->| | | |
| | interaction.keep:true | |<--(9)-->| |
| | | | authZ | |
| |<--------- Grant Response --(10)--| | | |
| (11) | | | | |
| eval |--(12)-- Update Grant ----------->| | | |
| | interaction.keep:false | |<--(13)->| |
| | | | authZ | |
| | | | | |
| |<--- Interaction Transfer --(14)- | - - - | --------| |
| | | | | |
| |<--------- Grant Response --(15)--| | +------+
| | | |
+--------+ +-------+
1. *Create Grant* The Client creates a Grant Request (Section 4.1)
including JSON document
Section 3.4 containing an identity claim and interaction.keep:true, interaction.user_code object and sends
it makes
a Create Grant request (Section 3.2) by sending the JSON with an
HTTP POST to the GS GS URI.
2. *Interaction Response* The GS determines that interaction with
the User is required and sends an Interaction Response
(Section 6.2) 4.2) containing the Grant URI, an interaction object, URI and interaction.keep:true. an
interaction.user_code object.
3. *Read Grant* The Client does makes an HTTP GET of request to the Grant URI
(Section 4.3).
URI.
4. *Interaction Transfer* The Client transfers User interaction to
the GS.
5. *User Authentication* The GS authenticates the User.
6. *Grant Response* The GS responds with a Grant Response
(Section 6.1) including the identity claim from User
authentication and interaction.keep:true.
7. *Grant Evaluation* The Client queries its User database and does
not find a User record matching the identity claim.
8. *Update Grant* The Client creates an Update Grant Request
(Section 4.4) including the initial identity claims required and
interaction.keep:true, loads display_uri in their
browser, and sends it with an HTTP PUT to the
Grant URI.
9. *User AuthN* The GS interacts with the User to determine which
identity claims in the Update Grant Request are to be granted.
10. *Grant Response* The GS responds with a Grant Response
(Section 6.1) including the identity claims released by authenticates the User
and interaction.keep:true.
11. *Grant Evaluation* User.
5. *User Code* The Client evaluates the identity claims in
the Grant Response and determines the remaining User identity
claim required.
12. *Update Grant* The Client creates an Update Grant Request
(Section 4.4) including enters the remaining required identity claims
and interaction.keep:false, and sends it with an HTTP PUT to code at the
Grant URI.
13. GS.
6. *User AuthZ* The Authorization* If required, the GS interacts with the User
to determine which identity claims and/or authorizations in the Update
Grant Request are to be granted.
14. *Interaction Transfer* The GS transfers User interaction to the
Client.
15. *Grant Response* The GS responds with a Grant Response
(Section 6.1) including the identity claims released by the
User.
2.7. Create and Delete
The Client requests an identity claim to determine who the User is.
Once the Client learns who the User is, and the Client knows it
already has all the identity claims and authorizations needed for the
User, the Client deletes the Grant which prompts the GS to transfer
the interaction back to the Client. (If the Client did not already
have what was needed, the Client would follow the Create and Update
sequence Section 2.6 )
+--------+ +-------+
| Client | | GS |
| |--(1)--- Create Grant ----------->| |
| | interaction.keep:true | |
| | | |
| |<--- Interaction Response ---(2)--| |
| | | |
| |--(3)--- Read Grant ------------->| | +------+
| | | | | User |
| |--(4)--- Interaction Transfer --- | - - - | ------->| |
| | | | | |
| | | |<--(5)-->| |
| | | | authN | |
| |<--------- Grant Response ---(6)--| | | |
| (7) | | | | |
| eval |--(8)--- Delete Grant ----------->| | | |
| |<------- Delete Response ---------| | | |
| | | | | |
| |<--- Interaction Transfer ---(9)- | - - - | --------| |
| | | | | |
+--------+ +-------+ +------+
1. *Create Grant* The Client creates a Grant Request (Section 4.1)
including an identity claim and interaction.keep:true, and sends
it with an HTTP POST to the GS GS URI.
2. *Interaction Response* The GS sends an Interaction Response
(Section 6.2) containing the Grant URI, an interaction object,
and interaction.keep:true.
3. *Read Grant* The Client does an HTTP GET of the Grant URI
(Section 4.3).
4. *Interaction Transfer* The Client transfers User interaction to
the GS.
5. *User Authentication* The GS authenticates the User.
6.
7. *Grant Response* The GS responds with a Grant Response
(Section 6.1) including the identity claim from User
authentication and interaction.keep:true.
7. *Grant Evaluation* The Client queries its User database and finds
the User record matching the identity claim, and that no
additional claims or authorizations are required. 4.1).
8. *Delete Grant* *Completion URI Redirect* The Client no longer needs the Grant and decides
to Delete Grant (Section 4.5) by sending an HTTP DELETE to the
Grant URI. If the GS responds with success the Grant no longer
exists.
2.8. Create, Discover, and Delete
The Client wants to discover if redirects the GS has a User with a given
identifier. If not, it will abort the request and not transfer
interaction to the GS.
+--------+ +-------+
| Client | | GS |
| |--(1)--- Create Grant ----------->| |
| | user.exists:true | |
| | | |
| |<--- Interaction Response ---(2)--| |
| | user.exists:false | |
| | | |
| |--(3)--- Delete Grant ----------->| |
| |<------- Delete Response ---------| |
| | | |
+--------+ +-------+
1. *Create Grant* The Client creates a Grant Request (Section 4.1)
including an identity claim request, a User identifier, and
user.exists:true. The Client sends it with an HTTP POST to the
GS GS URI.
2. *Interaction Response* The GS sends an Interaction Response
(Section 6.2) containing the Grant URI, an interaction object,
and user.exists:false.
3. *Delete Grant* The Client determines the GS cannot fulfil its
Grant Request, and decides to Delete Grant (Section 4.5)
completion_uri provided by
sending an HTTP DELETE to the Grant URI. If the GS responds with
success the Grant no longer exists.
2.9. Create and Wait Client.
2.3. Independent RO Authorization
The Client wants access to resources that require the GS to interact
with the RO, which may who is not happen immediately, 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 4.1) 3.2)
and sends it with an HTTP POST to the GS GS URI.
2. *Wait Response* The GS sends an Interaction Wait Response (Section 6.3) 4.3)
containing the Grant URI and wait time. the "wait" attribute.
3. *Client Waits* The Client waits for the wait time. time specified in the
"wait" attribute.
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 4.3). 3.3).
6. *Grant Response* The GS responds with a Grant Response
(Section 6.1).
2.10. Read Grant
The Client wants to re-acquire the identity claims and authorizations
in the Grant. No User or RO interaction is required as no new
consent or authorization is required.
+--------+ +-------+
| Client | | GS |
| |--(1)--- Read Grant ------------->| |
| | | |
| |<--------- Grant Response --(2)---| |
| | | |
+--------+ +-------+
1. *Read Grant* The Client does an HTTP GET of the Grant URI
(Section 4.3).
2. *Grant Response* The GS responds with a Grant Response
(Section 6.1) containing updated identity claims and
authorizations.
2.11. 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 | | GS |
| |--(1)--- Read AuthZ ---------------------->| |
| |<------- AuthZ Response -------------------| |
| | | |
| | +----------+ | |
| | | Resource | | GS |
| |--(2)--- |--(1)--- Access Resource --->| Server | | |
| |<------- Resource Response --| (RS) | | |
| | | | | |
| |--(3)--- |--(2)--- Access Resource --->| | | |
| |<------- Error Response -----| | | |
| | | | | |
| | +----------+ | |
| | | |
| |--(4)--- |--(3)--- Read AuthZ ---------------------->| |
| |<------- AuthZ Response -------------------| |
| | | |
+--------+ +-------+
1. *Read AuthZ* The Client makes a Read AuthZ (Section 4.7) with an
HTTP GET to the AZ URI and receives an Response JSON
"authorization" object (Section 6.4.4) with a fresh access token.
2. *Resource Request* The Client accesses the RS with the access
token per Section 8 6 and receives a response from the RS.
3.
2. *Resource Request* The Client attempts to access the RS, but
receives an error indicating the access token has expired.
4. needs to be
refreshed.
3. *Read AuthZ* The Client makes another a Read AuthZ (Section 4.7) 3.5) with an
HTTP GET to the AZ URI and receives an Response JSON
"authorization" object (Section 6.4.4) 4.4.4) with a fresh access token.
2.12.
3. GS APIs
*Client Authentication*
All GS APIs except for GS Options require the Client to authenticate.
Authentication mechanisms include:
* JOSE Authentication [JOSE_Authentication]
* [Others TBD]*
3.1. GS API Table
+--------------+-----------+--------+-----------------------------+
| request | http verb | uri | response |
+==============+===========+========+=============================+
| Create Grant GS Options | POST OPTIONS | GS URI | interaction, wait, or grant metadata |
+--------------+-----------+--------+-----------------------------+
| Verify Grant | PATCH | Create Grant | grant |
| | POST | GS URI | |
+--------------+-----------+--------+-----------------------------+
| Read Grant | GET | Grant | interaction, wait, or grant |
| | | URI | |
+--------------+-----------+--------+-----------------------------+
| Update Read Grant | PUT GET | Grant | interaction, wait, or grant |
| | | URI | |
+--------------+-----------+--------+-----------------------------+
| Delete Grant | DELETE | Grant | success |
| | | URI | |
+--------------+-----------+--------+-----------------------------+
| Read AuthZ | GET | AZ URI | authorization |
+--------------+-----------+--------+-----------------------------+
| Update AuthZ | PUT | AZ URI | authorization |
+--------------+-----------+--------+-----------------------------+
| Delete AuthZ | DELETE | AZ URI | success |
+--------------+-----------+--------+-----------------------------+
| GS Options | OPTIONS | GS URI | metadata |
+--------------+-----------+--------+-----------------------------+
| Grant | OPTIONS | Grant | metadata |
| Options | | URI | |
+--------------+-----------+--------+-----------------------------+
| AuthZ | OPTIONS | AZ URI | metadata |
| Options | | | |
+--------------+-----------+--------+-----------------------------+
Table 1
[ Editor: is there value in an API for listing a Client's Grants?
eg:]
List Grants GET GS URI JSON array of Grant URIs
3. Grant and AuthZ Life Cycle
[Editor: straw man for life cycles.]
*Grant life Cycle*
The Client MAY create, read, update, and delete Grants. A Grant
persists until it has expired, is deleted, or another Grant is
created for the same GS, Client, and User tuple.
At any point in time, there can only be one Grant for the GS, Client,
and User tuple. When a Client creates a Grant at the same GS for the
same User, the GS MUST invalidate a previous Grant for the Client at
that GS for that User.
*Authorization Life Cycle*
An Authorization are represented by an AZ URI and are MAY be included
in a Grant Response "authorization" Object (Section 6.4.4) or as a
member of the Grant Response "authorizations" list. If a Client
receives an Authorization, the Client MUST be able to do a Read AuthZ
request Section 4.7, and MAY be able to update Section 4.8 and delete
Section 4.9 depending on GS policy.
An Authorization will persist independent of the Grant, and persist
until invalidated by the GS per GS policy, or deleted by the Client.
4. GS APIs
*Client Authentication*
All APIs except for GS Options require the Client to authenticate.
This document defines the JOSE Authentication mechanism in
Section 10. Other mechanisms include [TBD].
4.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 Greant Request.
The JSON document MUST include the following from the Request JSON
Section 4.6: 3.4:
* iat
* nonce
* uri set to the GS URI
* client
and MAY include the following from Request JSON Section 4.6 3.4
* user
* interaction
* authorization or authorizations
* claims
The GS MUST respond with one of Grant Response Section 6.1, 4.1,
Interaction Response Section 6.2, 4.2, Wait Response Section 6.3, 4.3, or one
of the following errors:
* TBD
from Error Responses Section 9. 7.
Following is a non-normative example where the of a web application Client is
requesting identity claims about the User and read access to the
User's contacts:
Example 1
{
"iat" : 15790460234,
"uri" : "https://as.example/endpoint",
"nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4",
"client": {
"display": {
"name" : "SPA Display Name",
"uri" : "https://spa.example/about"
}
},
"interaction": {
"redirect": {
"redirect_uri" : "https://web.example/return"
},
"global" : {
"ui_locals" : "de"
}
},
"authorization": {
"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 where the of a device Client is requesting
the GS
access to keep the interaction with the User after returning the ID
Token so the Client can update the Grant, and is also asking if the
user exists: play music:
Example 2
{
"iat" : 15790460234,
"uri" : "https://as.example/endpoint",
"nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6",
"client": {
"id" : "di3872h34dkJW"
},
"interaction": {
"indirect": {
"completion_uri": "https://device.example/completion" "https://device.example/c/indirect"
},
"user_code": {
"completion_uri": "https://device.example/completion" "https://device.example/c/user_code"
}
},
"user": {
"identifiers":
"authorization": {
"email" : "jane.doe@example.com"
},
"exists" : true
},
"claims"
"type" : { "oidc": { "id_token" "oauth_scope",
"scope" : {} } }
}
4.2. Verify Grant
The Client verifies a Grant by doing an HTTP PATCH of a JSON document
to the corresponding Grant URI.
The JSON document MUST contain verification.nonce per Section 4.6.7.
Following is a non-normative example:
{
"verification": { "nonce":"55e8a90f-a563-426d-8c35-d6d8ed54afeb" "play_music"
}
}
The GS MUST respond with one of Grant Response Section 6.1 or one of
the following errors:
* TBD
from Error Responses Section 9.
4.3.
3.3. Read Grant
The Client reads a Grant by doing an HTTP GET of the corresponding
Grant URI. The GS MUST respond with one of Grant Response Section 6.1, Wait
Response Section 6.3, or one of the following errors:
* TBD
from Error Responses Section 9.
4.4. Update Grant
The Client updates a Grant by doing an HTTP PUT of MAY read a JSON document to
the corresponding Grant URI.
The JSON document MUST include the following from the Request JSON
Section 4.6
* iat
* uri set to the Grant URI
and MAY include the following from Request JSON Section 4.6
* user
* interaction
* authorization until it expires or authorizations
* claims has been
invalidated.
The GS MUST respond with one of Grant Response Section 6.1,
Interaction Response Section 6.2, 4.1, Wait
Response Section 6.3, 4.3, or one of the following errors:
* TBD
from Error Responses Section 9.
Following is a non-normative example where the Client made an
interaction.keep:true request, and now wants to update the request
with additional claims:
Example 3
{
"iat" : 15790460234,
"uri" : "https://as.example/endpoint/grant/example3",
"claims": {
"oidc": {
"userinfo" : {
"email" : { "essential" : true },
"name" : { "essential" : true },
"picture" : null
}
}
}
}
4.5. Delete Grant
The Client deletes a Grant by doing an HTTP DELETE of the
corresponding Grant URI.
The GS MUST respond with OK 200, or one of the following errors:
* TBD
from Error Responses Section 9.
4.6.
3.4. Request JSON
[Editor: do we want to reuse the JWT claims "iat", "jti", etc.? ]
* *iat* - the time of the request as a NumericDate.
* *nonce* - a unique identifier for this request. Note the Grant
Response MUST contain a matching nonce "nonce" attribute value.
* *uri* - the GS URI if in a Create Grant Section 4.1, or the Grant
URI if in an Update Grant Section 4.4.
4.6.1.
3.4.1. "client" Object
The client object MUST contain only one of: the "id" attribute for a
Registered Client, the "handle" attribute for a Dynamic Client, or of the "display" object for Dynamic Clients. 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 name and uri GS will be displayed by show the GS the User the display.name and display.uri values
when prompting for authorization.
[Editor:
_[Editor: a max length for the name and URI so a GS can reserve
appropriate space?]
4.6.2. space?]_
3.4.2. "interaction" Object
The interaction object contains one or more interaction mode objects
per Section 7 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* - and an optional object containing parameters that are
applicable for all types of interactions. 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: why
_[Editor: ui_locales is this taken from OIDC. Why space-separated and not
a JSON array? Why space-separated?]
4.6.3. array?]_
3.4.3. "user" Object
* *exists* - if present, MUST contain the JSON true value.
Indicates the Client requests the GS to return a user.exists value
in an Interaction Response Section 6.2. This attribute is
OPTIONAL, and MAY be ignored by the GS.
* *identifiers* - REQUIRED if the exists attribute is present. The
values identifiers MAY be used by the GS to improve
the User experience.
Contains 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.
* *reciprocal* - indicates this Grant Request or Update is the
reciprocal of another Grant. Contains the Grant URI of the
reciprocal Grant.
4.6.4.
3.4.4. "authorization" Object
* *type* - one of the following values: "oauth_scope" or
"oauth_rich". This attribute is REQUIRED.
* *scope* - a string containing the OAuth 2.0 scope per [RFC6749]
section 3.3. MUST be included if type is "oauth_scope" or
"oauth_rich".
* *authorization_details* - an authorization_details object per
[RAR]. MUST be included if type is "oauth_rich".
[Editor:
_[Editor: details may change as the [RAR] RAR document evolves]
4.6.5. evolves]_
3.4.5. "authorizations" Object
One or more key / value pairs, where each unique key is created by
the client, and the value is an authorization object.
4.6.6. object per
Section 3.4.4.
3.4.6. "claims" Object
Includes one or more of the following:
* *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: _[Editor: define how W3C Verifiable Credentials [W3C_VC] can be requested.]
4.6.7. "verification" Object
The verification Object is used with the Verify Grant Section 4.2.
* *nonce* the Interaction Nonce received from the GS via the
Completion URI. This attribute MUST only be used in the Verify
Grant Section 4.2.
[Editor: parameters for the Client to request it wants the Grant
Response signed and/or encrypted?]
4.7.
requested.]_[W3C_VC]
3.5. 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 6.5,
or one of the following errors:
* TBD
from Error Responses Section 9.
4.8. Update Authorization
The Client updates an Authorization by doing an HTTP PUT to the
corresponding AZ URI of the following JSON. All of the following
MUST be included.
* *iat* - the time of the response as a NumericDate.
* *uri* - the AZ URI.
* *authorization* - the new authorization requested per the Request
JSON "authorization" object Section 4.6.4.
The GS MUST respond with a Authorization JSON document Section 6.5, 4.5,
or one of the following errors:
* TBD
from Error Responses Section 9.
4.9. Delete Authorization
The Client deletes an Authorization by doing an HTTP DELETE to the
corresponding AZ URI.
The GS MUST respond with OK 200, or one of the following errors:
* TBD
from Error Responses Section 9.
4.10. 7.
3.6. 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:
[Editor: this section is a work in progress]
* *uri* - the GS URI.
* *client_authentication* - an a JSON array of the Client
Authentication mechanisms supported by the GS
* *interactions* - an 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.
- 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 list JSON array of the cryptographic algorithms
supported by the GS. [details TBD]*
* *features* - an object containing feature support
- *user_exists* - boolean indicating if user.exists is supported.
- *authorizations* - boolean indicating if a request for more
than one authorization in a request is supported.
[Editor: keys used by Client to encrypt requests, or verify signed
responses?]
[Editor: namespace metadata for extensions?]
or one of the following errors:
* TBD
from Error Responses Section 9.
4.11. Grant Options
The Client can get the metadata for the Grant by doing an HTTP
OPTIONS of the corresponding Grant URI.
The GS MUST respond with the the following JSON document:
* *verbs* - an array of the HTTP verbs supported at the GS URI.
or one of the following errors:
* TBD
from Error Responses Section 9.
4.12. AuthZ Options
The Client can get the metadata for the AuthZ by doing an HTTP
OPTIONS of the corresponding AZ URI.
The GS MUST respond with the the following JSON document:
* *verbs* - an array of the HTTP verbs supported at the GS URI.
or one of the following errors:
* TBD
from Error Responses Section 9.
4.13. Request Verification
On receipt of a request, the GS MUST verify the following:
* TBD
5. GS Initiated Grant
[Editor: In OAuth 2.0, all flows are initiated at the Client. If the
AS wanted to initiate a flow, it redirected to the Client, that
redirected back to the AS to initiate a flow.
Here is a proposal to support GS initiated: authentication; just-in-
time (JIT) provisioning; and authorization]
*initiation_uri* A URI at the Client that contains no query or
fragment. How the GS learns the Client initiation_uri is out of
scope.
The GS creates a Grant and Grant URI, and redirects the User to the
initiation_uri with the query parameter "grant" and the value of
Grant URI.
See Section 2.5 for the sequence diagram.
6. 7.
4. GS Responses
There are three successful responses to a grant request: Grant Request: Grant
Response, Interaction Response, or Wait Response.
6.1.
4.1. Grant Response
The Grant Response MUST include the following from the Response JSON
Section 6.4 4.4
* iat
* nonce
* uri
and MAY include the following from the Response JSON Section 6.4 4.4
* client.handle
* authorization or authorizations
* claims
* expires_in
* warnings
Example non-normative Grant Response JSON document for Example 1 in
Section 4.1: 3.2:
{
"iat" : 15790460234,
"nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4",
"uri" : "https://as.example/endpoint/grant/example1",
"expires_in" : 300
"authorization": {
"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 4.1: 3.2:
{
"iat" : 15790460234,
"nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6",
"uri" : "https://as.example/endpoint/grant/example2",
"authorization": {
"uri" : "https://as.example/endpoint/authz/example2"
}
}
6.2.
Note in this example the GS only provided the AZ URI, and Client must
acquire the Authorization per Section 3.5
4.2. Interaction Response
The Interaction Response MUST include the following from the Response
JSON Section 6.4 4.4
* iat
* nonce
* uri
* interaction
and MAY include the following from the Response JSON Section 6.4 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" : {
"authorization_uri" : "https://as.example/i/example4"
}
},
"user": {
"exists" : true
}
}
6.3.
4.3. Wait Response
The Wait Response MUST include the following from the Response JSON
Section 6.4 4.4
* iat
* nonce
* uri
* 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
}
6.4.
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 4.6. 3.4.
* *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.
6.4.1.
4.4.1. "client" Object
The GS may
6.4.2.
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 7 5 to one or more of the interaction mode
requests provided by the Client.
6.4.3.
4.4.3. "user" Object
* *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 4.6.3
6.4.4. 3.4.3
4.4.4. "authorization" Object
The authorization object contains MUST contain only a "uri" attribute or the
following from Authorization JSON Section 6.5.
See Grant Response 4.5:
* mechanism
* token
The authorization object MAY contain any of the following from
Authorization JSON Section 6.1 for non-normative examples.
6.4.5. 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.5
4.4.5. "authorizations" Object
A key / value pair for each key in the client's request
authorizations Grant Request "authorizations"
object, and the value is Authorization JSON per Section 6.5.
6.4.6. 4.4.4.
4.4.6. "claims" Object
The claims object is a response to the Grant Request "claims" object
Section 4.6.4. 3.4.4.
* *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.
* *oidc4ia* - OpenID Connect for Identity Assurance claims response
per [OIDC4IA].
* *vc*
The verified claims the user consented to be released. [Editor: _[Editor:
details TBD]
6.5. TBD]_
4.4.7. "warnings" JSON Array
Includes zero or more warnings from Section 8,
4.5. Authorization JSON
The Authorization JSON is the contents of a Grant Response
"authorization" object Section 4.4.5 or the response to a Read AuthZ
request by the Client Section 4.7. A subset of 3.5.
* *type* - the Authorization JSON is included
in type of claim request: "oauth_scope" or "oauth_rich".
See the "authorization" "type" object in Section 4.6.4 and "authorizations" list
members 3.4.4 for details
* *mechanism* - the RS access mechanism. This document defines the
"bearer" mechanism as defined in Section 6.4.5. 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 4.6.4 3.4.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]. Included if type is "oauth_rich".
* *mechanism* - one of the access mechanisms: "bearer", "jose", or
"jose+body". See Section 8 for details. This attribute is
REQUIRED.
* *token* - the access token for accessing an RS. This attribute is
REQUIRED.
* *expires_in* - a numeric value specifying how many seconds until
the access token expires. This attribute is OPTIONAL.
* *certificate* - MUST be included OPTIONAL if the mechanism is "jose" or
"jose+body". Contains the jwk header values for the Client to
include in the JWS header when calling the RS using the "jose" or
"jose+body" mechanisms. See Section 10.2.1.
* *uri* - the AZ URI. Used to refresh an authorization. This
attribute "type" is OPTIONAL.
[Editor: "oauth_rich".
_[Editor: would an optional expiry for the Authorization be useful?] useful?]_
The following is a non-normative example of an Authorization JSON
document: JSON:
{
"type" : "oauth_scope",
"scope" : "read_calendar write_calendar",
"mechanism" : "jose", "bearer",
"token" : "eyJJ2D6.example.access.token.mZf9p"
"expires_in" : 3600,
"certificate":
"uri" : "https://as.example/endpoint/authz/example2",
"access": {
"x5u"
"type" : "https://as.example/cert/example2"
},
"uri" "oauth_scope",
"scope" : "https://as.example/endpoint/authz/example2" "read_calendar write_calendar"
}
6.5.1. Signing and Encryption
[Editor: TBD - how response is signed and/or encrypted by the GS. Is
there a generalized description, or is it mechanism specific?]
6.6.
}
4.6. Response Verification
On receipt of a response, the Client MUST verify the following:
* TBD
7. interaction mode Objects
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.
7.1.
5.1. "redirect" mode
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 authorization_uri, and
the Client correlates the Grant Request with the unique redirect_uri.
7.1.1.
*The request "interaction" object contains: contains:*
* *redirect_uri* a grant request request 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.
7.1.2.
*The response "interaction" object contains: contains:*
* *authorization_uri* a grant request request 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.
7.2.
5.2. "indirect" mode
An Indirect Interaction is characterized by the Client causing the
User's browser to load the short_uri at GS, the GS interacting with
the User, and then the GS MAY optionally redirecting redirect the User's Browser
to a completion_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 short_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.
7.2.1.
*The request "interaction" object contains: contains:*
* *completion_uri* an OPTIONAL URI that the GS will redirect the
User's browser to after GS interaction.
7.2.2.
*The response "interaction" object contains: contains:*
* *short_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. [Editor: The URI MUST not contain the "nonce" from the
Grant Request, and MUST not be guessable. _[Editor: recommend a length?]
7.3.
maximum length?]_
5.3. "user_code" mode
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.
7.3.1. _[Editor: recommend a minimum entropy?]_
*The request "interaction" object contains: contains:*
* *completion_uri* an OPTIONAL URI that the GS will redirect the
User's browser to after GS interaction.
7.3.2.
*The response "interaction" object contains: 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.
8.
6. RS Access
This document specifies three different mechanisms for
The mechanism the Client MUST use to access an RS ("bearer", "jose", and "jose+body"). is in the
Authorization JSON "mechanism" attribute Section 4.4.4.
The "bearer" mechanism is defined in {BearerToken}. Section 2.1 of [RFC6750]
The "jose" and "jose+body" mechanisms are proof-of-possession mechanisms and are defined in
Section 10.2.2 and Section 10.2.3 respectively. Additional proof-of-
possession mechanisms may be defined in other documents. The
mechanism the Client is to use with an RS is the Response JSON
authorization.mechanism attribute Section 6.4.4.
8.1. Bearer Token
If the access mechanism is "bearer", then the Client accesses the RS
per Section 2.1 of [RFC6750]
[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
9.
7. Error Responses
* TBD
10. JOSE Authentication
How the Client authenticates to the GS and RS are independent of each
other. One mechanism can be used to authenticate to the GS, and a
different mechanism to authenticate to the RS.
Other documents that specify other Client authentication mechanisms
will replace this section.
In the JOSE Authentication Mechanism, the Client authenticates by
using its private key to sign a JSON document with JWS per [RFC7515]
which results in a token using JOSE compact serialization.
[Editor: are there advantages to using JSON serialization in the
body?]
Different instances of a Registered Client MAY have different private
keys, but each instance has a certificate to bind its private key to
to a public key the GS has for the Client ID. An instance of a
Client will use the same private key for all signing operations.
The Client and the GS MUST both use HTTP/2 ([RFC7540]) or later, and
TLS 1.3 ([RFC8446]) or later, when communicating with each other.
[Editor: too aggressive to mandate HTTP/2 and TLS 1.3?]
The token may be included in an HTTP header, or as the HTTP message
body.
The following sections specify how the Client uses JOSE to
authenticate to the GS and RS.
10.1. GS Access
The Client authenticates to the GS by passing either a signed header
parameter, or a signed message body. The following table shows the
verb, uri and token location for each Client request to the GS:
+---------------+-----------+-----------+----------+
| request | http verb | uri | token in |
+===============+===========+===========+==========+
| Create Grant | POST | GS URI | body |
+---------------+-----------+-----------+----------+
| Verify Grant | PATCH | Grant URI | body |
+---------------+-----------+-----------+----------+
| Read Grant | GET | Grant URI | header |
+---------------+-----------+-----------+----------+
| Update Grant | PUT | Grant URI | body |
+---------------+-----------+-----------+----------+
| Delete Grant | DELETE | Grant URI | header |
+---------------+-----------+-----------+----------+
| Read AuthZ | GET | AZ URI | header |
+---------------+-----------+-----------+----------+
| Update AuthZ | PUT | AZ URI | body |
+---------------+-----------+-----------+----------+
| Delete AuthZ | DELETE | AZ URI | header |
+---------------+-----------+-----------+----------+
| GS Options | OPTIONS | GS URI | header |
+---------------+-----------+-----------+----------+
| Grant Options | OPTIONS | Grant URI | header |
+---------------+-----------+-----------+----------+
| AuthZ Options | OPTIONS | AZ URI | header |
+---------------+-----------+-----------+----------+
Table 2
10.1.1. Authorization Header
For requests with the token in the header, the JWS payload MUST
contain the following attributes:
*iat* - the time the token was created as a NumericDate.
*jti* - a unique identifier for the token per [RFC7519] section
4.1.7.
*uri* - the value of the URI being called (GS URI, Grant URI, or AZ
URI).
*verb* - the HTTP verb being used in the call ("GET", "DELETE",
"OPTIONS")
The HTTP authorization header is set to the "jose" parameter followed
by one or more white space characters, followed by the resulting
token.
A non-normative example of a JWS payload and the HTTP request
follows:
{
"iat" : 15790460234,
"jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1",
"uri" : "https://as.example/endpoint/grant/example6",
"verb" : "GET"
}
GET /endpoint/example.grant HTTP/2
Host: as.example
Authorization: jose eyJhbGciOiJIUzI1NiIsIn ...
[Editor: make a real example token]
*GS Verification*
The GS MUST verify the token by:
* TBD
10.1.2. Signed Body
For requests with the token in the body, the Client uses the Request
JSON as the payload in a JWS. The resulting token is sent with the
content-type set to "application/jose".
A non-normative example (line breaks added to the body for
readability):
POST /endpoint HTTP/2
Host: as.example
Content-Type: application/jose
Content-Length: 155
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyzdWIiOiIxMjM0NTY3ODkwIiwibmF
tZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMe
Jf36POk6yJV_adQssw5c
[Editor: make a real example token]
*GS Verification*
The GS MUST verify the token by:
* TBD
10.1.3. Public Key Resolution
* *Registered Clients* can use any of the JWS header values to
direct the GS to resolve the public key matching the private key
used to the Client ID. The GS MAY restrict with JWS headers a
Client can use.
[Editor: would examples help here so that implementors understand the
full range of options, and how an instance can have its own asymetric
key pair]
A non-normative example of a JOSE header for a Registered Client with
a key identifier of "12":
{
"alg" : "ES256",
"typ" : "JOSE",
"kid" : "12"
}
* *Dynamic Clients* include their public key in the "jwk" JWS
header.
A non-normative example of a JOSE header for a Dynamic Client:
{
"alg" : "ES256",
"typ" : "JOSE",
"jwk" : {
"kty" : "EC",
"crv" : "P-256",
"x" : "Kgl5DJSgLyV-G32osmLhFKxJ97FoMW0dZVEqDG-Cwo4",
"y" : "GsL4mOM4x2e6iON8BHvRDQ6AgXAPnw0m0SfdlREV7i4"
}
}
10.2. RS Access
In the "jose" mechanism Section 10.2.2, all Client requests to the RS
include a proof-of-possession token in the HTTP authorization header.
In the "jose+body" mechanism Section 10.2.3, the Client signs the
JSON document in the request if the POST or PUT verbs are used,
otherwise it is the same as the "jose" mechanism.
10.2.1. JOSE header
The GS provides the Client one or more JWS header parameters and
values for a a certificate, or a reference to a certificate or
certificate chain, that the RS can use to resolve the public key
matching the private key being used by the Client.
A non-normative examples JOSE header:
{
"alg" : "ES256",
"typ" : "JOSE",
"x5u" : "https://as.example/cert/example2"
}
[Editor: this enables Dynamic Clients to make proof-of-possession API
calls the same as Registered Clients.]
10.2.2. "jose" Mechanism
The JWS payload MUST contain the following attributes:
*iat* - the time the token was created as a NumericDate.
*jti* -
8. Warnings
Warnings assist a unique identifier for the token per [RFC7519] section
4.1.7.
*uri* - the value of the RS URI being called.
*verb* - the HTTP verb being used in the call
*token* - the access token provided by the GS to the Client
The HTTP authorization header is set to the "jose" parameter followed
by one or more white space characters, followed by the resulting
token.
A non-normative example of a JWS payload and the HTTP request
follows:
{
"iat" : 15790460234,
"jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1",
"uri" : "https://calendar.example/calendar",
"verb" : "GET",
"token" : "eyJJ2D6.example.access.token.mZf9pTSpA"
}
GET /calendar HTTP/2
Host: calendar.example
Authorization: jose eyJhbG.example.jose.token.adks
[Editor: make a real example token]
*RS Verification*
The RS MUST verify the token by:
* verify access token is bound to the public key - include key
fingerprint in access token?
* TBD
10.2.3. "jose+body" Mechanism
The "jose+body" mechanism can only be used if the content being sent
to the RS is a JSON document.
Any requests not sending a message body will use the "jose" mechanism
Section 10.2.2.
Requests sending a message body MUST have the following JWS payload:
*iat* - the time the token was created as a NumericDate.
*jti* - a unique identifier for the token per [RFC7519] section
4.1.7.
*uri* - the value of the RS URI being called.
*verb* - the HTTP verb being used in the call
*token* - the access token provided by the GS to the Client
*body* - the message body being sent to the RS
A non-normative example of a JWS payload and the HTTP request
follows:
{
"iat" : 15790460234,
"jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1",
"uri" : "https://calendar.example/calendar",
"verb" : "POST",
"token" : "eyJJ2D6.example.access.token.mZf9pTSpA",
"payload" : {
"event" : {
"title" : "meeting with joe",
"start_date_utc" : "2020-02-21 11:00:00",
"end_date_utc" : "2020-02-21 11:00:00"
}
}
}
POST /calendar HTTP/2
Host: calendar.example
Content-Type: application/jose
Content-Length: 155
eyJhbGciOi.example.jose+body.adasdQssw5c
[Editor: make a real example token]
*RS Verification*
The RS MUST verify the token by: detecting non-fatal errors.
* TBD
10.2.4. Public Key Resolution
The RS has a public key for the GS that it uses to verify the
certificate or certificate chain the Client includes in the JWS
header.
10.3. Request Encryption
[Editor: to be fleshed out]
The Client encrypts a request when ??? using the GS public key
returned as the ??? attribute in GS Options Section 4.10.
10.4. Response Signing
[Editor: to be fleshed out]
The Client verifies a signed response ??? using the GS public key
returned as the ??? attribute in GS Options Section 4.10.
10.5. Response Encryption
[Editor: to be fleshed out]
The Client decrypts a response when ??? using the private key
matching the public key included in the request as the ??? attribute
in Section 4.6.
11.
9. Extensibility
This standard can be extended in a number of areas:
* *Client Authentication Mechanisms*
- 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. 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.
[Editor:
_[Editor: do we specify access token / handle introspection in this document,
or leave that to an extension?]
[Editor: do we specify access token / handle revocation in this
document, or leave that to an extension?]
12. extension?]_
10. Rational
1. *Why is there only one mechanism for the Client to authenticate
with the GS? Why not support other mechanisms?*
Having choices requires implementers to understand which choice
is preferable for them. Having one default mechanism in the
document for the Client to authenticate simplifies most
implementations. Deployments that have unique characteristics
can select other mechanisms that are preferable in specific
environments.
2. *Why is the default both Client authentication JOSE rather than
MTLS?*
MTLS cannot be used today by a Dynamic Client. MTLS requires
the application to have access below what is typically the
application layer, that is often not available on some
platforms. JOSE is done at the application layer. Many GS
deployments will be an application behind a proxy performing
TLS, ID and there are risks in the proxy passing on the results of
MTLS.
3. *Why is the default Client authentication JOSE rather than HTTP
signing?*
There is currently no widely deployed open standard for HTTP
signing. Additionally, HTTP signing requires passing all the
relevant parts of the HTTP request to downstream services within
an GS that may need Handle?*
While they both refer to independently verify the a Client identity.
4. *What are in the advantages of using JOSE for protocol, the Client ID
refers to
authenticate to the GS and a resource?*
Both Registered Clients and Dynamic Clients can have a private
key, eliminating pre-registered client,and the public Client issues in OAuth 2.0, as a
Dynamic Client can create Handle is
specific to an ephemeral key pair. Using
asymetric cryptography also allows each instance of a Registered
Client to have its own private key if it can obtain a
certificate binding its public key to the public key the GS has
for the Dynamic Client. Signed tokens can be passed to downstream
components in a GS or RS to enable independent verification of
the Client and its request. The GS Initiated Sequence Section 5
requires a URL safe parameter, and JOSE Using separate
terms clearly differentiates which identifier is URL safe.
5. *Why does the GS not return parameters being presented
to the GS.
2. *Why allow Client in the
redirect url?*
Passing parameters via a browser redirection is the source of
many of the security risks in OAuth 2.0. It also presents a
challenge for smart devices. In this protocol, the redirection
from the Client to the GS is to enable the GS to interact with
the User, and the redirection back GS to negotiate the Client is to hand back user interaction control to the Client if the redirection was a full
browser redirect. Unlike OAuth 2.0, the identity of the mode?*
The Client knows what interaction modes it is independent of the URI capable of, and the
GS redirects to.
6. *Why is there not a UserInfo endpoint as there is with OpenID
Connect?*
Since the Client can Read Grant at any time, knows which interaction modes it get the same
functionality as the UserInfo endpoint, without the Client
having to manage will permit for a separate access token and refresh token. If
the given Grant
Request. The Client would like additional claims, it can Update Grant,
and the GS will let then present the Client know if an interaction is
required intersection to get any of the additional claims, which the Client
can then start.
[Editor: is there some other reason
User to have the UserInfo
endpoint?]
7. *Why choose which one is there still a Client ID?*
The GS needs an identifier to fetch the meta data associated
with preferred. For example, while a
device based Client such as the name and image to display may be willing to the User, do both "indirect" and the policies on what
"user_code", a Client is allowed to do. The Client
ID was used in OAuth 2.0 for the same purpose, which simplifies
migration. Dynamic Clients do GS may not have 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 ID.
8. and GS as each adds additional interaction modes.
3. *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. :)
9. *Why specify HTTP/2 or later and TLS 1.3 or later for Client and
GS communication in ?*Section 10
Knowing the GS supports HTTP/2 enables a Client to set up a
connection faster. HTTP/2 will be more efficient when Clients
have large numbers of access tokens and are frequently
refreshing them at the GS as there will be less network traffic.
Mandating TLS 1.3 similarly improves the performance and
security of Clients and GS when setting up a TLS connection.
10.
4. *Why do some of the JSON objects only have one child, such as the
identifiers object in the user object in the Grant Request?*
It is difficult to forecast future use cases. Having more
resolution may mean the difference between a simple extension,
and a convoluted extension.
11. 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?
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.
12.
6. *Why complicate things with interaction.keep?*
The common sequence has is there not a back and forth between the Client and
the GS, and UserInfo endpoint as there is with OpenID
Connect?*
Since the Client can update the Read Grant and have a new
interaction. Keeping at any time, it get the interaction provides a more seamless
user experience where same
functionality as the results from UserInfo endpoint, without the first request
determine subsequent requests. For example, a common pattern is Client having
to use manage a GS to authenticate the User at the Client, separate access token and to
register the User at refresh token. If the
Client using would like additional claims from claims, it can Update Grant, and the
GS will let the
GS. The Client does not know a priori if the User is a new
User, or a returning User. Asking a returning User to consent
releasing claims they have already provided is a poor User
experience, as an interaction is sending the User back to the GS. The Client
requesting identity first enables the Client required to get a response
from the GS while the GS is still interacting with the User, so
that the Client can request additional claims only if needed.
Additionally,
any of the claims a Client may want about a User may be
dependent on some initial Claims. For example, if a User is in
a particular country, additional or different Claims my be
required by the Client.
There are also benefits for the GS. Today, a GS usually keeps
track of claims, which claims a Client has requested for a User.
Storing this information for all Clients a User uses may be
undesirable for a GS that does not want to have that information
about the User. Keeping the interaction allows the Client to
track what information it has about the User, and the GS can
remain stateless.
13. *Why then start.
_[Editor: is there a "jose+body" RS access mechanism method for the
Client?*Section 10.2.3
There are numerous use cases where the RS wants non-repudiation
and providence of the contents of an API call. For example, some other reason to have the
UGS Service Supplier Framework for Authentication and
Authorization [UTM].
14. UserInfo
endpoint?]_
7. *Why use URIs to instead of handles for the Grant and Authorization?*
A URI is an identifier just like a handle that can contain GS
information that is opaque to the Client - so it has all the
features of a handle, plus it can be the URL that is resolved to
manipulate a Grant or an Authorization. As the
* Grant URI and AZ URI are defined to start with the GS URI,
allowing the Client (and GS)
can easily Client, and GS to determine which GS a Grant or
Authorization belong belongs to.
* URIs also enable a RESTful interface to the GS functionality.
15.
* 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 verb. This allows a
separation of concerns, independent deployment, and
resiliency.
8. *Why use the OPTIONS verb 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 what the advertised metadata,
and the actual metadata. A .well-known discovery mechanism may
be defined to resolve from a hostname to the GS URI.
16. *Why support UPDATE, DELETE, and OPTIONS verbs on the AZ URI?*
Maybe there are no use cases for them [that the editor knows
of], but the GS can not implement, and they are available if use
cases come up.
17. *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.
13.
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.
14.
12. IANA Considerations
[ JOSE parameter for Authorization HTTP header ]
TBD
15.
13. Security Considerations
TBD
16.
14. References
16.1.
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>.
[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>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <https://www.rfc-editor.org/info/rfc7515>.
[RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
RFC 7516, DOI 10.17487/RFC7516, May 2015,
<https://www.rfc-editor.org/info/rfc7516>.
[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>.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
DOI 10.17487/RFC7540, May 2015,
<https://www.rfc-editor.org/info/rfc7540>.
[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>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>.
[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>.
16.2.
[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/>.
[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>.
[RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps",
BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017,
<https://www.rfc-editor.org/info/rfc8252>.
[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>.
[RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig,
"OAuth 2.0 Device Authorization Grant", RFC 8628,
DOI 10.17487/RFC8628, August 2019,
<https://www.rfc-editor.org/info/rfc8628>.
[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>.
[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/>.
[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>.
[UTM] Rios, J., Smith, I., and P. Venkatesen, "UGS Service
Supplier Framework for Authentication and AuthN",
September 2019, <https://utm.arc.nasa.gov/docs/2019-
UTM_Framework-NGSA-TM220364.pdf>.
Appendix A. Document History
A.1. draft-hardt-xauth-protocol-00
* Initial version
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 completion_uri for code flows
A.5. draft-hardt-xauth-protocol-04
* renamed interaction uris to have purpose specific names
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
Appendix B. Comparison with OAuth 2.0 and OpenID Connect
*Changed Features*
The major changes between this protocol GNAP and OAuth 2.0 and OpenID Connect are:
* The Client allows always uses a private asymetric key to authenticate in this
protocol instead of to
the GS. There is no client secret in OAuth 2.0 and OpenID
Connect. 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, and optionally only receives an interaction nonce in the
redirection back from the GS.
* The refresh_token has been replaced with a 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. There is no UserInfo endpoint to query claims as
there is in OpenID Connect.
* The GS URI is the token endpoint.
*Preserved Features*
* This protocol GNAP reuses the OAuth 2.0 scopes, Client IDs, and access tokens of OAuth
2.0.
* This protocol 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.
* The Client can verify, update, retrieve, and delete a Grant.
* The GS can initiate a flow by creating a Grant and redirecting the
User to the Client with the Grant URI.
* The Client can discovery if a GS has a User with an identifier
before the GS interacts with the User.
* The Client can request the GS to first authenticate the User and
return User identity claims, and then the Client can update Grant
request based on the User identity.
* Support for scannable code initiated interactions.
* Each Client instance can have its own private / public key pair.
* Highly extensible per Section 11. 9.
Author's Address
Dick Hardt (editor)
SignIn.Org
United States
Email: dick.hardt@gmail.com