< draft-hardt-xauth-protocol-01.txt   draft-hardt-xauth-protocol-02.txt >
Network Working Group D. Hardt, Ed. Network Working Group D. Hardt, Ed.
Internet-Draft SignIn.Org Internet-Draft SignIn.Org
Intended status: Standards Track 29 January 2020 Intended status: Standards Track 8 February 2020
Expires: 1 August 2020 Expires: 11 August 2020
The XAuth Protocol The XAuth Protocol
draft-hardt-xauth-protocol-01 draft-hardt-xauth-protocol-02
Abstract Abstract
Client software often desires resources or identity claims that are Client software often desires resources or identity claims that are
managed independent of the client. This protocol allows a user and/ independent of the client. This protocol allows a user and/or
or resource owner to delegate resource authorization and/or release resource owner to delegate resource authorization and/or release of
of identity claims to an authorization server. Client software can identity claims to a server. Client software can then request access
then request access to resources and/or identity claims by calling to resources and/or identity claims by calling the server. The
the authorization server. The authorization server acquires consent server acquires consent and authorization from the user and/or
and authorization from the user and/or resource owner if required, resource owner if required, and then returns to the client software
and then returns the authorization and identity claims that were the authorization and identity claims that were approved. This
approved. This protocol can be extended to support alternative protocol can be extended to support alternative authorizations,
client authentication mechanisms, authorizations, claims, and claims, interactions, and client authentication mechanisms.
interactions.
[Editor: suggestions on how to improve this are welcome!]
[Editor: suggestions for other names than XAuth are welcome!]
Note to Readers Note to Readers
Source for this draft and an issue tracker can be found at Source for this draft and an issue tracker can be found at
https://github.com/dickhardt/hardt-xauth-protocol https://github.com/dickhardt/hardt-xauth-protocol
(https://github.com/dickhardt/hardt-xauth-protocol). (https://github.com/dickhardt/hardt-xauth-protocol).
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 2, line 4 skipping to change at page 1, line 44
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on 1 August 2020.
This Internet-Draft will expire on 11 August 2020.
Copyright Notice Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components and restrictions with respect to this document. Code Components
extracted from this document must include Simplified BSD License text extracted from this document must include Simplified BSD License text
as described in Section 4.e of the Trust Legal Provisions and are as described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Simplified BSD License. provided without warranty as described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Parties . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Parties . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2. Handles . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2. Reused Terms . . . . . . . . . . . . . . . . . . . . . . 6
2.3. Reused Terms . . . . . . . . . . . . . . . . . . . . . . 5 2.3. New Terms . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4. Sequence . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3. AS Request JSON . . . . . . . . . . . . . . . . . . . . . . . 8 3.1. Create Grant . . . . . . . . . . . . . . . . . . . . . . 7
3.1. Top Level Attributes . . . . . . . . . . . . . . . . . . 11 3.2. Reciprocal Grant . . . . . . . . . . . . . . . . . . . . 8
3.2. "client" Object . . . . . . . . . . . . . . . . . . . . . 11 3.3. GS Initiated Grant . . . . . . . . . . . . . . . . . . . 10
3.3. "user" Object . . . . . . . . . . . . . . . . . . . . . . 12 3.4. Create and Update . . . . . . . . . . . . . . . . . . . . 10
3.4. "authentication" Object . . . . . . . . . . . . . . . . . 13 3.5. Create and Delete . . . . . . . . . . . . . . . . . . . . 12
3.5. "authorizations" Object . . . . . . . . . . . . . . . . . 13 3.6. Create, Discover, and Delete . . . . . . . . . . . . . . 14
3.6. "claims" Object . . . . . . . . . . . . . . . . . . . . . 14 3.7. Create and Wait . . . . . . . . . . . . . . . . . . . . . 14
3.7. Authorization Types . . . . . . . . . . . . . . . . . . . 14 3.8. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 15
4. Interaction Response JSON . . . . . . . . . . . . . . . . . . 14 3.9. Access Token Refresh . . . . . . . . . . . . . . . . . . 16
4.1. "user" Object . . . . . . . . . . . . . . . . . . . . . . 15 3.10. GS API Table . . . . . . . . . . . . . . . . . . . . . . 16
4.2. "interaction" Object . . . . . . . . . . . . . . . . . . 15 4. Grant and AuthZ Life Cycle . . . . . . . . . . . . . . . . . 17
4.3. "authorization" Object . . . . . . . . . . . . . . . . . 16 5. GS APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.4. "authentication" Object . . . . . . . . . . . . . . . . . 16 5.1. Create Grant . . . . . . . . . . . . . . . . . . . . . . 18
5. Interaction Types . . . . . . . . . . . . . . . . . . . . . . 16 5.2. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 20
5.1. "popup" Type . . . . . . . . . . . . . . . . . . . . . . 16 5.3. Update Grant . . . . . . . . . . . . . . . . . . . . . . 20
5.2. "redirect" Type . . . . . . . . . . . . . . . . . . . . . 17 5.4. Delete Grant . . . . . . . . . . . . . . . . . . . . . . 21
5.3. "qrcode" Type . . . . . . . . . . . . . . . . . . . . . . 17 5.5. Request JSON . . . . . . . . . . . . . . . . . . . . . . 22
6. AS Response JSON . . . . . . . . . . . . . . . . . . . . . . 17 5.5.1. "client" Object . . . . . . . . . . . . . . . . . . . 22
6.1. Top Level Attributes . . . . . . . . . . . . . . . . . . 18 5.5.2. "interaction" Object . . . . . . . . . . . . . . . . 22
6.2. "authorizations" Object . . . . . . . . . . . . . . . . . 18 5.5.3. "user" Object . . . . . . . . . . . . . . . . . . . . 23
6.3. "claims" Object . . . . . . . . . . . . . . . . . . . . . 19 5.5.4. "authorization" Object . . . . . . . . . . . . . . . 23
6.4. Access Methods . . . . . . . . . . . . . . . . . . . . . 20 5.5.5. "authorizations" Object . . . . . . . . . . . . . . . 24
7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.5.6. "claims" Object . . . . . . . . . . . . . . . . . . . 24
8. JOSE Client Authentication . . . . . . . . . . . . . . . . . 20 5.5.7. "reciprocal" Object . . . . . . . . . . . . . . . . . 24
8.1. JOSE Headers . . . . . . . . . . . . . . . . . . . . . . 21 5.6. Refresh Authorization . . . . . . . . . . . . . . . . . . 25
8.2. Authentication Request Token . . . . . . . . . . . . . . 23 5.7. Update Authorization . . . . . . . . . . . . . . . . . . 25
8.3. Authorization Request Token . . . . . . . . . . . . . . . 24 5.8. Delete Authorization . . . . . . . . . . . . . . . . . . 25
8.4. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 25 5.9. GS Options . . . . . . . . . . . . . . . . . . . . . . . 26
8.5. JOSE Access Token . . . . . . . . . . . . . . . . . . . . 25 5.10. Grant Options . . . . . . . . . . . . . . . . . . . . . . 27
8.6. HTTP Authorization JOSE Header . . . . . . . . . . . . . 26 5.11. AuthZ Options . . . . . . . . . . . . . . . . . . . . . . 27
8.7. JOSE Token Verification . . . . . . . . . . . . . . . . . 26 5.12. Request Verification . . . . . . . . . . . . . . . . . . 27
8.8. AS Request . . . . . . . . . . . . . . . . . . . . . . . 26 6. GS Initiated Grant . . . . . . . . . . . . . . . . . . . . . 28
8.9. Interaction Response . . . . . . . . . . . . . . . . . . 26 7. GS API Responses . . . . . . . . . . . . . . . . . . . . . . 28
8.10. Deletion Request . . . . . . . . . . . . . . . . . . . . 27 7.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 28
8.11. Authentication Request . . . . . . . . . . . . . . . . . 27 7.2. Interaction Response . . . . . . . . . . . . . . . . . . 29
8.12. Authentication Response . . . . . . . . . . . . . . . . . 27 7.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 30
8.13. Authorization Request . . . . . . . . . . . . . . . . . . 27 7.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 31
8.14. AS Response . . . . . . . . . . . . . . . . . . . . . . . 28 7.4.1. "interaction" Object . . . . . . . . . . . . . . . . 31
8.15. Bearer Token RS Access . . . . . . . . . . . . . . . . . 28 7.4.2. "user" Object . . . . . . . . . . . . . . . . . . . . 31
8.16. Proof-of-possession RS Access . . . . . . . . . . . . . . 29 7.4.3. "authorization" Object . . . . . . . . . . . . . . . 32
8.17. JOSE Body RS Access . . . . . . . . . . . . . . . . . . . 29 7.4.4. "authorizations" Object . . . . . . . . . . . . . . . 32
8.18. Access Refresh . . . . . . . . . . . . . . . . . . . . . 29 7.4.5. "claims" Object . . . . . . . . . . . . . . . . . . . 32
9. Error Messages . . . . . . . . . . . . . . . . . . . . . . . 30 7.4.6. "reciprocal" Object . . . . . . . . . . . . . . . . . 33
10. AS Initiated Sequence . . . . . . . . . . . . . . . . . . . . 30 7.4.7. Interaction Types . . . . . . . . . . . . . . . . . . 33
10.1. Initiation Token . . . . . . . . . . . . . . . . . . . . 32 7.4.8. Signing and Encryption . . . . . . . . . . . . . . . 34
11. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 32 7.5. Response Verification . . . . . . . . . . . . . . . . . . 34
12. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 33 8. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 34
13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 36 8.1. Bearer Token . . . . . . . . . . . . . . . . . . . . . . 34
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 9. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 35
15. Security Considerations . . . . . . . . . . . . . . . . . . . 36 10. JOSE Authentication . . . . . . . . . . . . . . . . . . . . . 35
16. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 10.1. GS Access . . . . . . . . . . . . . . . . . . . . . . . 35
16.1. Normative References . . . . . . . . . . . . . . . . . . 36 10.1.1. Authorization Header . . . . . . . . . . . . . . . . 36
16.2. Informative References . . . . . . . . . . . . . . . . . 38 10.1.2. Signed Body . . . . . . . . . . . . . . . . . . . . 37
Appendix A. Document History . . . . . . . . . . . . . . . . . . 39 10.1.3. Public Key Resolution . . . . . . . . . . . . . . . 37
A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 39 10.2. RS Access . . . . . . . . . . . . . . . . . . . . . . . 38
A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 39 10.2.1. JOSE header . . . . . . . . . . . . . . . . . . . . 38
Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 39 10.2.2. "jose" Mechanism . . . . . . . . . . . . . . . . . . 39
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 40 10.2.3. "jose+body" Mechanism . . . . . . . . . . . . . . . 40
10.2.4. Public Key Resolution . . . . . . . . . . . . . . . 41
10.3. Request Encryption . . . . . . . . . . . . . . . . . . . 41
10.4. Response Signing . . . . . . . . . . . . . . . . . . . . 41
10.5. Response Encryption . . . . . . . . . . . . . . . . . . 42
11. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 42
12. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 43
13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47
15. Security Considerations . . . . . . . . . . . . . . . . . . . 47
16. References . . . . . . . . . . . . . . . . . . . . . . . . . 47
16.1. Normative References . . . . . . . . . . . . . . . . . . 47
16.2. Informative References . . . . . . . . . . . . . . . . . 48
Appendix A. Document History . . . . . . . . . . . . . . . . . . 49
A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 49
A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 50
A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 50
Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 50
Appendix C. Open Questions . . . . . . . . . . . . . . . . . . . 51
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 51
1. Introduction 1. Introduction
This protocol supports the widely deployed use cases supported by This protocol supports the widely deployed use cases supported by
OAuth 2.0 [RFC6749] & [RFC6750], and OpenID Connect [OIDC], an OAuth 2.0 [RFC6749] & [RFC6750], and OpenID Connect [OIDC], an
extension of OAuth 2.0, as well as other extensions, and other use extension of OAuth 2.0, as well as other extensions, and other use
cases that are not supported, such as requesting multiple cases that are not supported, such as acquiring multiple access
authorizations in one request. This protocol also addresses many of tokens at the same time, and updating the request during user
the security issues in OAuth 2.0 by having parameters securely sent interaction. This protocol also addresses many of the security
directly between parties, rather than via a browser redirection. issues in OAuth 2.0 by having parameters securely sent directly
between parties, rather than via a browser redirection.
The technology landscape has changed since OAuth 2.0 was initially The technology landscape has changed since OAuth 2.0 was initially
drafted. More interactions happen on mobile devices than PCs. drafted. More interactions happen on mobile devices than PCs.
Modern browsers now directly support asymetric cryptographic Modern browsers now directly support asymetric cryptographic
functions. Standards have emerged for signing and encrypting tokens functions. Standards have emerged for signing and encrypting tokens
with rich payloads (JOSE) that are widely deployed. with rich payloads (JOSE) that are widely deployed.
Additional use cases are now being served with extensions to OAuth Additional use cases are now being served with extensions to OAuth
2.0: OpenID Connect added support for authentication and releasing 2.0: OpenID Connect added support for authentication and releasing
identity claims; [RFC8252] added support for native apps; [RFC8628] identity claims; [RFC8252] added support for native apps; [RFC8628]
added support for smart devices; and support for [browser_based_apps] added support for smart devices; and support for [browser_based_apps]
is being worked on. There are numerous efforts on adding proof-of- is being worked on. There are numerous efforts on adding proof-of-
possession to resource access. possession to resource access.
This protocol simplifies the overall architectural model, takes This protocol simplifies the overall architectural model, takes
advantage of today's technology landscape, provides support for all advantage of today's technology landscape, provides support for all
the widely deployed use cases, and offers numerous extension points. the widely deployed use cases, and offers numerous extension points.
The
While this protocol is not backwards compatible with OAuth 2.0, it While this protocol is not backwards compatible with OAuth 2.0, it
strives to minimize the migration effort. strives to minimize the migration effort.
2. Protocol This protocol 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: suggestions on how to improve this are welcome!]
[Editor: suggestions for other names than XAuth are welcome!]
2. Terminology
2.1. Parties 2.1. Parties
* *Authorization Server* (AS) - manages Client authorization to API The parties and their relationships to each other:
resources and release of identity claims about the User. The AS
may require explicit consent from the RO or User to provide these
to the Client.
* *Client* - requests authorization to API resources, and/or +--------+ +------------+
identity claims about the User. There are two types of Clients: | User | | Resource |
Registered Clients and Dynamic Clients. An AS may support only | | | Owner (RO) |
one or both types. All Clients have a key to authenticate with +--------+ +------------+
the AS. | \ / |
| \ / |
| \ / |
| \ / |
+--------+ +---------------+ +------------+
| Client |---->| Grant | _ _ | Resource |
| |<----| Server (GS) | | Server |
| | +---------------+ | (RS) |
| |-------------------------->| |
| |<--------------------------| |
+--------+ +------------+
* *Registered Client* - a Client that has registered with the AS and * *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, retrieve, update, and delete a Grant. When
a Grant is created, the Client receives from the GS the granted
access token(s) for the RS(s), and identity claims about 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 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 has a Client ID to identify itself, and can prove it possesses a
key that is linked to the Client ID. The AS may have different key that is linked to the Client ID. The GS may have different
policies for what different Registered Clients can request. The policies for what different Registered Clients can request. A
Client MAY be interacting with a User. Registered Client MAY be interacting with a User.
* *Dynamic Client* - a Client that has not been registered with the * *Dynamic Client* - a Client that has not been registered with the
AS, and each instance will generate it's own key pair so it can GS, and each instance will generate it's own key pair so it can
prove it is the same instance of the Client on subsequent prove it is the same instance of the Client on subsequent
requests. A single-page application with no server is an example requests, and to requests of a Resource Server. A single-page
of a Dynamic Client. The Client MUST be interacting with a User. application with no server is an example of a Dynamic Client. A
Dynamic Client MUST be interacting with a User.
* *User* - the person who has delegated making identity claims about * *Grant Server* (GS) - manages Grants for access to APIs at RSs and
themselves to the AS, and is interacting with the Client. release of identity claims about the User. The GS may require
explicit consent from the RO or User to provide these to the
Client. An 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 * *Resource Server* (RS) - has API resources that require an access
token from the AS for access. token from the GS. Owned by the Resource Owner.
* *Resource Owner* (RO) - owns the RS, and has delegated RS access * *Resource Owner* (RO) - owns the RS, and has delegated RS access
token creation to the AS. The RO may be the same entity as the management to the GS. The RO may be the same entity as the User,
User, or may be a different entity that the AS interacts with or may be a different entity that the GS interacts with
independent of the Client. independently. GS and RO interactions are out of scope of this
document.
2.2. Handles 2.2. Reused Terms
Handles are strings issued by the AS to the Client that are opaque to * *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.
2.3. New Terms
* *GS URI* - the endpoint at the GS the Client calls to create a
Grant. The unique identifier for the GS.
* *Grant* - the user identity claims and/or RS authorizations the GS
has granted to the Client.
* *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 an access token.
* *AuthZ URI* - the URI that represents the Authorization the Client
was granted by the RO. The AuthZ URI MUST start with the GS URI.
The AuthZ URI is used to refresh, update, and delete an access
token.
* *interaction* - [Editor: what do we really mean by this term?]
3. Sequences
Before any sequence, the Client needs to be manually or
programmatically configured for the GS. See GS Options Section 5.9
for details on acquiring GS metadata.
[Editor: a plethora of sequences are included to illustrate all the
different actions. Many of these could potentially be moved to a use
case document in the future.]
3.1. Create Grant
The Client requests a Grant from the GS that requires User
interaction:
+--------+ +-------+
| Client | | GS |
| |--(1)--- Create Grant ----------->| |
| | | (2) |
| |<--- Interaction Response ---(3)--| eval |
| | | |
| |--(4)--- Read Grant ------------->| | +------+
| | | | | User |
| |--(5)--- Interaction Transfer --- | - - - | ------->| |
| | | |<--(6)-->| |
| | | | authN | |
| | | |<--(7)-->| |
| | | | authZ | |
| |<--- Interaction Transfer ---(8)- | - - - | --------| |
| | | | | |
| |<--------- Grant Response ---(9)--| | +------+
| | | |
+--------+ +-------+
1. *Create Grant* The Client creates a Grant Request (Section 5.1)
and sends it with an HTTP POST to the GS GS URI.
2. *Grant Request Evaluation* The GS processes the request to
determine if it will send a Interaction Response, Wait Response,
or a Grant Response. The GS determines that interaction with the
User is required and sends an Interaction Response. (For
readability, this step is not described in the following
sequences)
3. *Interaction Response* The GS sends an Interaction Response
(Section 7.2) containing the Grant URI and an interaction object.
4. *Read Grant* The Client does an HTTP GET of the Grant URI
(Section 5.2).
5. *Interaction Transfer* The Client transfers User interaction to
the GS.
6. *User Authentication* The GS authenticates the User.
7. *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.
8. *Interaction Transfer* The GS transfers User interaction to the
Client.
9. *Grant Response* The GS responds with a Grant Response
(Section 7.1).
3.2. 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. Party A starts off being the Client
per Create Grant Section 3.1. Party B then includes a Reciprocal
Request in its Grant Response. Party A then gets authorization from
the User and returns a Grant URI to Party B. Party A and B swap
roles, and Party B's Client obtains the Grant from Party A's GS.
Party A Party B
+--------+ +--------+
| Client | | GS |
~ ~ ~ ~ ~ ~ Same as steps 1 - 8 of ~ ~ ~ ~ ~ ~
+------+ | | Create Grant above | |
| User | | | | |
| |<----- | - - - | -- Interaction Transfer ------- | |
| | | | | |
| | | |<------- Grant Response ---(1)---| |
| | | | Reciprocal Grant Request | |
| |<-(2)->| | | |
| | AuthZ | |---(3)--- Update Grant --------->| |
+------+ | | Reciprocal Grant Response | |
| | | |
| |<-- Empty Grant Response ---(4)--| |
| | | |
+--------+ (5) Swap Roles +--------+
| GS | | Client |
| |<------------ Read Grant ---(6)--| |
| | | |
| |--(7)--- Grant Response -------->| |
| | | |
+--------+ +--------+
1. *Grant Response* Party B responds with a Grant Response including
a Reciprocal Object Section 7.4.6 requesting its own Grant.
2. *User Authorization* If required, Party A interacts with the User
to determine which identity claims and/or authorizations in the
Grant Request are to be granted to Party B.
3. *Update Grant* Party A sends an Update Grant request containing
the Grant URI in the Reciprocal object Section 5.5.7.
4. *Grant Response* Party B responds with an Empty Grant Response as
there were no other requests in the Update Grant.
5. *Swap Roles* Party A now acts as a GS, Party B as a Client.
6. *Read Grant* Party B does an HTTP GET of the Grant URI
(Section 5.2).
7. *Grant Response* Party A responds with a Grant Response
(Section 7.1).
3.3. 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) | | | | |
| verify |--(4)--- Read Grant ------------->| | +------+
| | | |
| |<--------- Grant Response --(5)---| |
| | | |
+--------+ +-------+
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 5.2).
5. *Grant Response* The GS responds with a Grant Response
(Section 7.1).
See Section 6 for more details.
3.4. 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 5.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 7.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 5.2).
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 7.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 5.3) including the initial identity claims required and
"interaction"."keep":true, 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 7.1) including the identity claims released by the User
and "interaction"."keep":true.
11. *Grant Evaluation* 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 5.3) including the remaining required identity claims
and "interaction"."keep":false, and sends it with an HTTP PUT to
the Grant URI.
13. *User AuthZ* The GS interacts with the User to determine which
identity claims 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 7.1) including the identity claims released by the
User.
3.5. 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 has
all the identity claims and authorizations needed, the Client deletes
the Grant which prompts the GS to transfer the interaction back to
the Client. the Client.
* *authorization handle* - represents the client request. Presented +--------+ +-------+
back to the AS in an Authorization Request. | 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)- | - - - | --------| |
| | | | | |
+--------+ +-------+ +------+
* *authentication handle* - represents the client request for 1. *Create Grant* The Client creates a Grant Request (Section 5.1)
authentication first. Presented back to the AS in an including an identity claim and "interaction"."keep":true, and
Authentication Request, or in the subsequent AS Request. sends it with an HTTP POST to the GS GS URI.
* *access handle* - represents the access the AS has granted the 2. *Interaction Response* The GS sends an Interaction Response
Client to the RS. The Client proves possession of its key when (Section 7.2) containing the Grant URI, an interaction object,
presenting an access handle to access an RS. The RS is able to and "interaction"."keep":true.
understand the authorizations represented by the access handle
directly, or through an introspection call. The RS is able to
verify the access handle was issued to the Client that presented
it.
* *refresh handle* - represents the access the AS has granted the 3. *Read Grant* The Client does an HTTP GET of the Grant URI
Client to a RS. Presented back to the AS when the Client wants a (Section 5.2).
fresh access token or access handle.
When presenting any of the above handles, the Client always proves 4. *Interaction Transfer* The Client transfers User interaction to
possession of its key. the GS.
2.3. Reused Terms 5. *User Authentication* The GS authenticates the User.
* *access token* - an access token as defined in [RFC6749] 6. *Grant Response* The GS responds with a Grant Response
Section 1.4. (Section 7.1) including the identity claim from User
authentication and "interaction"."keep":true.
* *Claims* - Claims as defined in [OIDC] Section 5. 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.
* *Client ID* - an AS unique identifier for a Registered Client as 8. *Delete Grant* The Client no longer needs the Grant and decides
defined in [RFC6749] Section 2.2. to Delete Grant (Section 5.4) by sending an HTTP DELETE to the
Grant URI. If the GS responds with success the Grant no longer
exists.
* *ID Token* - an ID Token as defined in [OIDC] Section 2. 3.6. Create, Discover, and Delete
* *NumericDate* - a NumericDate as defined in [RFC7519] Section 2. The Client wants to discover if the GS has a User with a given
identifier. If not, it will abort the request and not transfer
interaction to the GS.
2.4. Sequence +--------+ +-------+
| Client | | GS |
| |--(1)--- Create Grant ----------->| |
| | "user"."exists":true | |
| | | |
| |<--- Interaction Response ---(2)--| |
| | "user"."exists":false | |
| | | |
| |--(3)--- Delete Grant ----------->| |
| |<------- Delete Response ---------| |
| | | |
+--------+ +-------+
1. *AS Discovery* (Section 7) The Client discovers the AS end 1. *Create Grant* The Client creates a Grant Request (Section 5.1)
point, keys, supported claims and authorizations, and other including an identity claim request, a User identifier, and
capabilities. Some, or all of this information could be "user"."exists":true. The Client sends it with an HTTP POST to
manually preconfigured, or dynamically obtained. Dynamic AS the GS GS URI.
discovery is out of scope of this document.
2. *AS Request* (Section 8.8) The Client creates an AS Request 2. *Interaction Response* The GS sends an Interaction Response
(Section 3) for authorization to API resources and/or identity (Section 7.2) containing the Grant URI, an interaction object,
claims about the User and sends it with an HTTP POST to the AS and "user"."exists":false.
endpoint. The Client includes requests authentication first if
the Client wants the AS to authenticate the User prior to
requesting additional claims and authorizations.
3. *AS Request Evaluation* The AS processes the request and 3. *Delete Grant* The Client determines the GS cannot fulfil its
determines if it needs to interact with the RO or User. If Grant Request, and decides to Delete Grant (Section 5.4) by
interaction is required, the AS returns an Interaction Response sending an HTTP DELETE to the Grant URI. If the GS responds with
(Section 4), if no interaction is required it returns an AS success the Grant no longer exists.
Response (Section 6).
4. *Interaction Response* (Section 8.9) The AS will send an 3.7. Create and Wait
authentication object unless the Client sent authentication
first, in which case the AS will send an authentication object.
If the AS wants the Client to initiate the User interaction, it
will include an interaction object. If authentication first,
the Client will next send (6) Authentication Request, otherwise
an Authorization Request.
5. *Authorization Request* (Section 8.13) The Client creates an The Client wants access to resources that require the GS to interact
authorization request token Section 8.3 and does a GET of the with the RO, which may not happen immediately, so the GS instructs
authorization uri, after waiting for any authorization wait the Client to wait and check back later.
time. The Client then listens for (13) AS Response.
6. *Authentication Request* (Section 8.11) The Client creates an +--------+ +-------+
authentication request token and does a GET of the | Client | | GS |
authentication uri. The Client then listens for (9) | |--(1)--- Create Grant ----------->| |
Authentication Response. | | | |
| |<---------- Wait Response ---(2)--| | +------+
| (3) | | | | RO |
| Wait | | |<--(4)-->| |
| | | | authZ | |
| |--(5)--- Read Grant ------------->| | +------+
| | | |
| |<--------- Grant Response --(6)---| |
| | | |
+--------+ +-------+
7. *Interaction* If the AS sent interaction instructions to the 1. *Create Grant* The Client creates a Grant Request (Section 5.1)
Client, the Client executes them. and sends it with an HTTP POST to the GS GS URI.
8. *User Authentication* The AS authenticates the User. If Client 2. *Wait Response* The GS sends an Interaction Response
requested authentication first, the AS responds to the (Section 7.3) containing the Grant URI and wait time.
Authentication Request with an (9) Authentication Response,
otherwise the AS performs any needed authorizations per step
(10).
9. *Authentication Response* (Section 8.12) The AS sends an AS 3. *Client Waits* The Client waits the wait time.
Response containing the identity claims the Client requested.
10. *AS Request 2* The Client uses the returned identity claims to 4. *RO AuthZ* The GS interacts with the RO to determine which
look up the User in its internal database and determines what, identity claims in the Grant Request are to be granted.
if any, claims and/or authorizations it would like to request
and includes them in a new AS Request, as well as the
authentication handle. If Client wants not additional claims
and/or authorizations, the Client sets the claims object to the
JSON null value. The Client then listens for (13) AS Response.
11. *Authorization* If required, the AS interacts with the User and/ 5. *Read Grant* The Client does an HTTP GET of the Grant URI
or RO to determine which of any of the authorizations and (Section 5.2).
identity claims requests made by the Client are to be granted.
12. *Redirect* If the Client did a full browser redirect to the AS, 6. *Grant Response* The GS responds with a Grant Response
the AS redirects the User back to the redirect_uri supplied by (Section 7.1).
the Client, otherwise the AS closes its popup window, or informs
the User the interaction is complete.
13. *AS Response* (Section 8.14) The AS responds to the Client with 3.8. Read Grant
a AS Response (Section 6) containing authorized RS access tokens
and User identity claims. The AS may provide refresh handles
and uris for each access token if they are authorized. If
proof-of-possession is required for accessing the RS, the AS
will provide access handles instead of access tokens. If the AS
has not completed the interaction, it will instead return a
retry response for the Client to make a new Authorization
Request.
14. *Resource Request* (Section 8.15, Section 8.16, & Section 8.17) The Client wants to acquire fresh identity claims and authorizations
The Client access the RS using a bearer token, a proof-of- in the Grant. No User or RO interaction is required as no new
possession token, or a signed request. consent or authorization is required.
15. *Access Refresh* (Section 8.18) If the Client received a refresh +--------+ +-------+
handle and uri, it sends the refresh handle to the refresh uri, | Client | | GS |
and receives a fresh access token or handle. | |--(1)--- Read Grant ------------->| |
| | | |
| |<--------- Grant Response --(2)---| |
| | | |
+--------+ +-------+
*Sequence Diagram* 1. *Read Grant* The Client does an HTTP GET of the Grant URI
+--------+ +---------------+ (Section 5.2).
| |<-(1)------- Discovery ------------------->| Authorization |
| | | Server |
| |--(2)------- AS Request ------------------>| |
| | | (3) Request |
| | | Evaluation |
| |<-(4)------- Interaction Response ---------| |
| | | |
| |--(5)------- Authorization Request ------->| -------+ |
| | or | | |
| |--(6)------- Authentication Request ------>| ---+ | |
| | | | | |
| | +--------+ | | | |
| |--(7)--------->| User |<------------(8)--| | | |
| | Interaction +--------+ Authentication | | | |
| Client | | | | |
| | | | | |
| |<-(9)------- Authentication Response ------|<---+ | |
| | | | |
| |--(10)------ AS Request 2 ---------------->| -------+ |
| | | | |
| | +--------+ | | |
| |<-(12)---------| User |<-----------(11)--| | |
| | Redirect | / RO | Authorization | | |
| | +--------+ | | |
| | | | |
| |<-(13)------ AS Response ------------------|<-------+ |
| | | |
| | +----------+ | |
| |--(14)-- Resource Request -->| Resource | | |
| |<------ Resource Response ---| Server | | |
| | +----------+ | |
| | | |
| |--(15)------- Refresh Request ------------>| |
| |<----------- Refresh Response -------------| |
+--------+ +---------------+
3. AS Request JSON 2. *Grant Response* The GS responds with a Grant Response
(Section 7.1) containing updated identity claims and
authorizations.
Following is a non-normative JSON [RFC8259] document example where 3.9. Access Token Refresh
the Client wants to interact with the User with a popup and is
requesting identity claims about the User and read access to the The Client has an access token and uses it to access resources at an
User's contacts: RS. The access token expires, and the Client acquires a fresh access
token from the GS.
+--------+ +----------+
| Client | | Resource |
| |--(1)--- Access Resource --->| Server |
| |<------- Resource Response --| (RS) |
| | | |
| |--(2)--- Access Resource --->| |
| |<------- Error Response -----| |
| | | |
| | +----------+ +-------+
| | | GS |
| |--(3)--- Refresh AuthZ ------------------->| |
| |<------- AuthZ Response -------------------| |
| | | |
+--------+ +-------+
1. *Resource Request* The Client accesses the RS with the access
token per Section 8 and receives a response from the RS.
2. *Resource Request* The Client attempts to access the RS, but
receives an error indicating the access token has expired.
3. *Refresh AuthZ* If the Client received an AuthZ URI in the
Response JSON "authorization" object (Section 7.4.3), the Client
can Refresh AuthZ (Section 5.6) with an HTTP GET to the AuthZ URI
and receive an Response JSON "authorization" object"
(Section 7.4.3) with a fresh access token.
3.10. GS API Table
+--------------+-----------+--------+-----------------------------+
| request | http verb | uri | response |
+==============+===========+========+=============================+
| Create Grant | POST | GS URI | interaction, wait, or grant |
+--------------+-----------+--------+-----------------------------+
| Read Grant | GET | Grant | wait, or grant |
| | | URI | |
+--------------+-----------+--------+-----------------------------+
| Update Grant | PUT | Grant | interaction, wait, or grant |
| | | URI | |
+--------------+-----------+--------+-----------------------------+
| Delete Grant | DELETE | Grant | success |
| | | URI | |
+--------------+-----------+--------+-----------------------------+
| Refresh | GET | AuthZ | authorization |
| AuthZ | | URI | |
+--------------+-----------+--------+-----------------------------+
| Update AuthZ | PUT | AuthZ | authorization |
| | | URI | |
+--------------+-----------+--------+-----------------------------+
| Delete AuthZ | DELETE | AuthZ | success |
| | | URI | |
+--------------+-----------+--------+-----------------------------+
| GS Options | OPTIONS | GS URI | metadata |
+--------------+-----------+--------+-----------------------------+
| Grant | OPTIONS | Grant | metadata |
| Options | | URI | |
+--------------+-----------+--------+-----------------------------+
| AuthZ | OPTIONS | AuthZ | metadata |
| Options | | URI | |
+--------------+-----------+--------+-----------------------------+
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
4. 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*
Authorizations are OPTIONALLY included in a Grant Response
"authorization" Object (Section 7.4.3), and are represented by an
AuthZ URI. If an AuthZ URI is included, the Client MAY refresh,
update, and delete Authorizations.
An Authorization will persist independent of the Grant, and persist
until invalidated by the GS per GS policy, or deleted by the Client.
5. 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].
5.1. Create Grant
The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259]
document to the GS URI.
The JSON document MUST include the following from the Request JSON
Section 5.5:
* iat
* nonce
* uri set to the GS URI
* client
and MAY include the following from Request JSON Section 5.5
* user
* interaction
* authorization or authorizations
* claims
* reciprocal
The GS MUST respond with one of Grant Response Section 7.1,
Interaction Response Section 7.2, Wait Response Section 7.3, or one
of the following errors:
* TBD
from Error Responses Section 9.
Following is a non-normative example where the Client wants to
interact with the User with a popup and is requesting identity claims
about the User and read access to the User's contacts:
Example 1 Example 1
{ {
"as" :"https://as.example", "iat" : 15790460234,
"iat" :"1579046092", "uri" : "https://as.example/endpoint",
"nonce" :"f6a60810-3d07-41ac-81e7-b958c0dd21e4", "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4",
"client": { "client": {
"display": { "display": {
"name" :"SPA Display Name", "name" : "SPA Display Name",
"uri" :"https://spa.example/about" "uri" : "https://spa.example/about"
},
"interaction": {
"type" :"popup"
} }
}, },
"authorizations": { "interaction": {
"type" :"oauth_scope", "type" : "popup"
"scope" :"read_contacts" },
"authorization": {
"type" : "oauth_scope",
"scope" : "read_contacts"
}, },
"claims": { "claims": {
"oidc": { "oidc": {
"id_token" : { "id_token" : {
"email" : { "essential" : true }, "email" : { "essential" : true },
"email_verified" : { "essential" : true } "email_verified" : { "essential" : true }
}, },
"userinfo" : { "userinfo" : {
"name" : { "essential" : true }, "name" : { "essential" : true },
"picture" : null "picture" : null
} }
} }
} }
} }
Following is a non-normative example where the Client has previously Following is a non-normative example where the Client is requesting
authenticated the User, and is requesting additional authorization: the GS 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:
Example 2 Example 2
{ {
"as" :"https://as.example", "iat" : 15790460234,
"iat" :"1579046092", "uri" : "https://as.example/endpoint",
"nonce" :"0d1998d8-fbfa-4879-b942-85a88bff1f3b", "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6",
"client": { "client": {
"id" : "di3872h34dkJW", "id" : "di3872h34dkJW"
"interaction": { },
"type" : "redirect", "interaction": {
"uri" : "https://web.example/return" "keep" : true,
} "type" : "redirect",
"uri" : "https://web.example/return"
}, },
"user": { "user": {
"identifiers": { "identifiers": {
"oidc": { "email" : "jane.doe@example.com"
"iss" :"https://as.example", },
"sub" :"123456789" "exists" : true
}
}
}, },
"authorizations": { "claims" : { "oidc": { "id_token" : {} } }
"type" :"oauth_scope",
"scope" :"read_calendar write_calendar"
}
} }
Following is a non-normative example where the Client is requesting 5.2. Read Grant
authorization first:
Example 3 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 7.1,
"as" :"https://as.example", Interaction Response Section 7.2, Wait Response Section 7.3, or one
"iat" :"1579046092", of the following errors:
"nonce" :"5c9360a5-9065-4f7b-a330-5713909e06c6",
"client": {
"id" : "di3872h34dkJW",
"interaction": {
"type" : "redirect",
"uri" : "https://web.example/return"
}
},
"authentication": {
"first": true
},
"claims": { "oidc": { "id_token" : {} } }
}
Following is a non-normative example where the Client previously
requested authorization first (Example 3), the response was a new
User, and now makes the following AS Request:
Example 4 * TBD
from Error Responses Section 9.
5.3. Update Grant
The Client updates a Grant by doing an HTTP PUT of a JSON document to
the corresponding Grant URI.
The JSON document MUST include the following from the Request JSON
Section 5.5
* iat
* uri set to the Grant URI
and MAY include the following from Request JSON Section 5.5
* user
* interaction
* authorization or authorizations
* claims
* reciprocal
The GS MUST respond with one of Grant Response Section 7.1,
Interaction Response Section 7.2, Wait Response Section 7.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
{ {
"as" :"https://as.example", "iat" : 15790460234,
"iat" :"1579046092", "uri" : "https://as.example/endpoint/grant/example3",
"nonce" :"0a74f51f-514a-4821-b71f-01c252223f2f",
"authentication": {
"handle": "eyJhb958.example.authentication.handle.9yf3szM"
},
"claims": { "claims": {
"oidc": { "oidc": {
"userinfo" : { "userinfo" : {
"email" : { "essential" : true }, "email" : { "essential" : true },
"phone_number" : { "essential" : true },
"name" : { "essential" : true }, "name" : { "essential" : true },
"picture" : null "picture" : null
} }
} }
} }
} }
3.1. Top Level Attributes 5.4. Delete Grant
*as* - the unique string identifier for the AS. This attribute is The Client deletes a Grant by doing an HTTP DELETE of the
REQUIRED. corresponding Grant URI.
*iat* - the time of the request as a NumericDate. The GS MUST respond with OK 200, or one of the following errors:
*nonce* - a unique identifier for this request. This attribute is * TBD
REQUIRED. Note the AS Response MUST contain a matching nonce from Error Responses Section 9.
attribute.
3.2. "client" Object 5.5. Request JSON
The client object MUST contain either the client_id attribute for [Editor: do we want to reuse the JWT claims "iat", "jti", etc.? ]
Registered Clients, or the display object for Dynamic Clients. If
the Client can interact with the User, then an interaction object
MUST be included. If there is an authentication handle, then the
client object MUST not be included.
*client_id* - the identifier the AS has for the Registered Client. * *iat* - the time of the request as a NumericDate.
*display* - the display object contains the following attributes: * *nonce* - a unique identifier for this request. Note the Grant
Response MUST contain a matching nonce attribute value.
* *name* - a string that represents the Dynamic Client * *uri* - the GS URI if in a Create Grant Section 5.1, or the Grant
URI if in an Update Grant Section 5.3.
[Editor: a max length for the name?] 5.5.1. "client" Object
* *uri* - a URI representing the Dynamic Client The client object MUST contain either the id attribute for Registered
Clients, or the display object for Dynamic Clients.
[Editor: a max length for the URI?] * *id* - the Client ID the GS has for the Registered Client.
The name and uri will be displayed by the AS when prompting for * *display* - the display object contains the following attributes:
- *name* - a string that represents the Dynamic Client
- *uri* - a URI representing the Dynamic Client
[Editor: a max length for the name?] [Editor: a max length for the
URI?]
The name and uri will be displayed by the GS when prompting for
authorization. authorization.
*interaction* - the interaction object contains the type of 5.5.2. "interaction" Object
interaction the Client will provide the User. Other attributes are
dependent on the interaction type value.
* *type* - contains one of the following values: "popup", The interaction object contains the type of interaction the Client
"redirect", or "qrcode". Details in Section 5. will provide the User. Other attributes
* *redirect_uri* - this attribute is included if the type is * *keep* - a JSON boolean. If set to the JSON value true, the GS
"redirect". It is the URI that the Client requests the AS to will not transfer the User interaction back to the Client after
redirect the User to after the AS has completed interacting with processing the Grant request. The JSON value false is equivalent
the User. If the Client manages session state in URIs, then the to the attribute not being present, and the GS will transfer the
redirect_uri should contain that state. User interaction back to the Client after processing the request.
This attribute is OPTIONAL
* *ui_locales* - End-User's preferred languages and scripts for the - *type* - contains one of the following values: "popup",
user interface, represented as a space-separated list of [RFC5646] "redirect", or "qrcode". Details in Section 7.4.7. This
language tag values, ordered by preference. attribute is REQUIRED.
- *redirect_uri* - this attribute is REQUIRED if the type is
"redirect". It is the URI that the Client requests the GS to
redirect the User to after the GS has completed interacting
with the User. If the Client manages session state in URIs,
then the redirect_uri SHOULD contain that state.
- *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: do we need max pixels or max chars for qrcode interaction? [Editor: do we need max pixels or max chars for qrcode interaction?
Either passed to AS, or max specified values here?] Either passed to GS, or max specified values here?]
[Editor: other possible interaction models could be a "webview", [Editor: other possible interaction models could be a "webview",
where the Client can display a web page, or just a "message", where where the Client can display a web page, or just a "message", where
the client can only display a text message] the client can only display a text message]
[Editor: we may need to include interaction types for iOS and Android [Editor: we may need to include interaction types for iOS and Android
as the mobile OS APIs evolve.] as the mobile OS APIs evolve.]
[Editor: does the Client include parameters if it wants the AS 5.5.3. "user" Object
Response signed and/or encrypted?]
3.3. "user" Object
The user object is optional.
*identifiers* - the identifiers 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 per [OIDC] Section 2.
The user and identifiers objects MAY be included to improve the user
experience by the AS. The AS MUST authenticate the User independent
of these values. The user object MUST not be included if there is an
authentication handle.
*discovery* - MUST contain the JSON true value. Indicates the Client
requests the AS to return a "discovered" attribute in the Interaction
Response if the AS has a User at the AS with one or more of the
identifiers. This attribute is OPTIONAL. Support of the discovery
attribute by the AS is OPTIONAL. The AS MAY return the [TBD] error
if discovery is not supported, or ignore the request.
3.4. "authentication" Object * *exists* - MUST contain the JSON true value. Indicates the Client
requests the GS to return a "user"."exists" value in an
Interaction Response Section 7.2. This attribute is OPTIONAL, and
MAY be ignored by the GS.
This OPTIONAL object MUST contain one of the following attributes: * *identifiers* - REQUIRED if the exists attribute is present. The
values MAY be used by the GS to improve the User experience.
Contains one or more of the following identifiers for the User:
* *first* - Must have the JSON value true. Indicates the Client is - *phone_number* - contains a phone number per Section 5 of
requesting authentication first, and an authentication object in [RFC3966].
the Interaction Response. If present, the AS will ignore the
authorizations object. [Editor: any use case where the Client
needs an authorization at Authentication?] The Client SHOULD
limit the claims requested to only those needed to identify the
User at the Client. [Editor: this works if it is only a directed
identifier, but consent would be required to return a verified
phone or email. Hmmm.]
* *handle* - the authentication handle. MUST be included in the AS - *email* - contains an email address per [RFC5322].
Request following an Authentication Response.
3.5. "authorizations" Object - *oidc* - is an object containing both the "iss" and "sub"
attributes from an OpenID Connect ID Token per [OIDC]
Section 2.
The optional authorizations object contains a dictionary of resource 5.5.4. "authorization" Object
objects the Client is requesting authorization to access. The
authorizations object may contain one or more of:
* *type* - one of the following values: "oauth_scope", "oauth_rich", * *type* - one of the following values: "oauth_scope" or
or "oauth_rich_list". See Section 3.7 for details. "oauth_rich". This attribute is REQUIRED.
* *scope* - a string containing the OAuth 2.0 scope per [RFC6749] * *scope* - a string containing the OAuth 2.0 scope per [RFC6749]
section 3.3. Present if type is "oauth_scope" or "oauth_rich". section 3.3. MUST be included if type is "oauth_scope" or
"oauth_rich".
* *authorization_details* - an authorization_details object per * *authorization_details* - an authorization_details object per
[RAR]. Present if type is "oauth_rich". [RAR]. MUST be included if type is "oauth_rich".
* *list* - an array of objects containing "scope" and
"authorization_details". Present if type is "oauth_rich_list".
Used when requesting multiple access tokens and/or handles.
[Editor: details may change as the [RAR] document evolves] [Editor: details may change as the [RAR] document evolves]
3.6. "claims" Object 5.5.5. "authorizations" Object
The optional claims object contains one or more identity claims being A JSON array of "authorization" objects. Only one of "authorization"
requested. The claims may contain: or "authorizations" may be in the Request JSON.
[Editor: instead of an array, we could have a Client defined
dictionary of "authorization" objects]
5.5.6. "claims" Object
Includes one or more of the following:
* *oidc* - an object that contains one or both of the following * *oidc* - an object that contains one or both of the following
objects: objects:
- *userinfo* - Claims that will be returned as a JSON object - *userinfo* - Claims that will be returned as a JSON object
- *id_token* - Claims that will be included in the returned ID - *id_token* - Claims that will be included in the returned ID
Token. If the null value, an ID Token will be returned Token. If the null value, an ID Token will be returned
containing no additional Claims. containing no additional Claims.
The contents of the userinfo and id_token objects are Claims as The contents of the userinfo and id_token objects are Claims as
defined in [OIDC] Section 5. defined in [OIDC] Section 5.
* *oidc4ia* - OpenID Connect for Identity Assurance claims request * *oidc4ia* - OpenID Connect for Identity Assurance claims request
per [OIDC4IA]. per [OIDC4IA].
* *vc* - [Editor: define how W3C Verifiable Credentials [W3C_VC] can * *vc* - [Editor: define how W3C Verifiable Credentials [W3C_VC] can
be requested.] be requested.]
3.7. Authorization Types 5.5.7. "reciprocal" Object
* *oauth_scope* - an OAuth 2.0 authorization request per [RFC6749] * *uri* - the Grant URI for the Reciprocal Grant. This attribute is
section 3.3 REQUIRED.
* *oauth_rich* - a rich authorization request per [RAR] * *client* - the client object must contain the "id" attribute with
the Client ID the Grant was issued to. This attribute is
REQUIRED.
* *oauth_rich_list* - a list of rich authorization requests * *authorization* - an authorization object per Section 7.4.3 in the
Response JSON.
4. Interaction Response JSON * *authorizations* - an authorizations object per Section 7.4.4 in
the Response JSON.
A non-normative example of an Interaction Response follows: * *claims* - a claims object per Section 7.4.5 in the Response JSON.
{ [Editor: parameters for the Client to request it wants the Grant
"user": { Response signed and/or encrypted?]
"discovered": true
},
"interaction": {
"type" : "popup",
"uri" : "https://as.example/endpoint/ey5gs32..."
},
"authorization": {
"handle" : "eyJhb958.example.authorization.handle.9yf3szM",
"uri" : "https://as.example/authorization/ey7snHGs",
"wait" : "10"
}
}
4.1. "user" Object 5.6. Refresh Authorization
MUST contain one of "authorization" object, or "authentication" The Client updates an Authorization by doing an HTTP GET to the
object. corresponding AuthZ URI.
* *discovery* - if the AS Request included a discovery attribute, The GS MUST respond with an Response JSON "authorization" object
then the AS MAY return a "user" object with the "discovered" Section 7.4.3, or one of the following errors:
property set to the JSON value true if one or more of the
identifiers provided in the AS Request identify a User at the AS,
or the JSON value false if not. If the Client received a false
return, it may
[Editor: reference a security consideration for this functionality.] * TBD
4.2. "interaction" Object from Error Responses Section 9.
If the AS wants the Client to start the interaction, the AS MUST 5.7. Update Authorization
select one of the interaction mechanisms provided by the Client in
the AS Request, and include the matching attribute in the interaction
object:
* *type* - this MUST match the type provided by the Client in the AS The Client updates an Authorization by doing an HTTP PUT to the
Request client.interaction object. corresponding AuthZ URI of the following JSON. All of the following
MUST be included.
* *uri* - the URI to interact with the User per the type. This may * *iat* - the time of the response as a NumericDate.
be a temporary short URL if the type is qrcode so that it is easy
to scan.
* *message* - a text string to display to the User if type is * *uri* - the AuthZ URI.
qrcode.
[Editor: do we specify a maximum length for the uri and message so * *authorization* - the new authorization requested per the Request
that a device knows the maximum it needs to support? A smart device JSON "authorization" object Section 5.5.4.
may have limited screen real estate.]
4.3. "authorization" Object The GS MUST respond with an Response JSON "authorization" object
Section 7.4.3, or one of the following errors:
The authorization object has the following attributes: * TBD
* *handle* - the authorization handle. This attribute is REQUIRED. from Error Responses Section 9.
* *uri* - the authorization URI. This attribute is REQUIRED. 5.8. Delete Authorization
* *wait* - the amount of time in integer seconds the Client MUST The Client deletes an Authorization by doing an HTTP DELETE to the
wait before making the Authorization Request. This attribute is corresponding AuthZ URI.
OPTIONAL.
4.4. "authentication" Object The GS MUST respond with OK 200, or one of the following errors:
Returned if the Client requested authentication first. The * TBD
authentication object has the following attributes:
* *handle* - the authentication handle. This attribute is REQUIRED. from Error Responses Section 9.
* *uri* - the authentication URI. This attribute is REQUIRED. 5.9. GS Options
5. Interaction Types 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.
If the AS wants the Client to initiate the interaction with the User, The GS MUST respond with the the following JSON document:
then the AS will return an interaction object Section 4.2 so that the
Client can can hand off interactions with the User to the AS. The
Client will initiate the interaction with the User in one of the
following ways:
5.1. "popup" Type [Editor: this section is a work in progress]
The Client will create a new popup child browser window containing * *uri* - the GS URI.
the value of the uri attribute of the interaction object. [Editor:
more details on how to do this]
The AS will close the window when the interactions with the User are * *client_authentication* - an array of the Client Authentication
complete. [Editor: confirm AS can do this still on all browsers, or mechanisms supported by the GS
does Client need to close]
The AS MAY respond to an outstanding Authorization Request * *interactions* - an array of the interaction types supported by
Section 8.13 before the popup window has been closed. the GS.
5.2. "redirect" Type * *authorization* - an object containing the authorizations the
Client may request from the GS, if any.
The Client will redirect the User to the value of the uri attribute - Details TBD
of the interaction object. When the AS interactions with the User
are complete, the AS will redirect the User to the redirect_uri the
Client provided in the AS Request.
If the Client made a Authorization Request when starting the * *claims* - an object containing the identity claims the Client may
interaction, the AS MAY respond to the Authorization Request request from the GS, if any, and what public keys the claims will
Section 8.13 before the User has been redirected back to the Client. be signed with.
5.3. "qrcode" Type - Details TBD
The Client will create a [QR_Code] of the uri attribute of the * *algorithms* - a list of the cryptographic algorithms supported by
interaction object and display the resulting graphic and the message the GS.
attribute of the interaction object as a text string.
6. AS Response JSON * *features* - an object containing feature support
Example non-normative AS Response JSON document for Example 1 in - *user_exists* - boolean indicating if "user"."exists" is
Section 3: supported.
- *authorizations* - boolean indicating if a request for multiple
authorizations 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.
5.10. 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.
5.11. AuthZ Options
The Client can get the metadata for the AuthZ by doing an HTTP
OPTIONS of the corresponding AuthZ 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.
5.12. Request Verification
On receipt of a request, the GS MUST verify the following:
* TBD
6. 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 3.3 for the sequence diagram.
7. GS API Responses
7.1. Grant Response
The Grant Response MUST include the following from the Response JSON
Section 7.4
* iat
* nonce
* uri
* expires_in
and MAY include the following from the Response JSON Section 7.4
* authorization or authorizations
* claims
* reciprocal
Example non-normative Grant Response JSON document for Example 1 in
Section 3.1:
{ {
"iat":"15790460234", "iat" : 15790460234,
"nonce":"f6a60810-3d07-41ac-81e7-b958c0dd21e4", "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4",
"authorizations": { "uri" : "https://as.example/endpoint/grant/example1",
"expires_in" : 300
"authorization": {
"type" : "oauth_scope", "type" : "oauth_scope",
"scope" : "read_contacts", "scope" : "read_contacts",
"expires_in" : "3600", "expires_in" : 3600,
"method" : "bearer", "mechanism" : "bearer",
"token" : "eyJJ2D6.example.access.token.mZf9p" "token" : "eyJJ2D6.example.access.token.mZf9p"
}, },
"claims": { "claims": {
"oidc": { "oidc": {
"id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW",
"userinfo" : { "userinfo" : {
"name" : "John Doe", "name" : "John Doe",
"picture" : "https://photos.example/p/eyJzdkiO" "picture" : "https://photos.example/p/eyJzdkiO"
} }
} }
} }
} }
Example non-normative AS Response JSON document for Example 2 in Example non-normative Grant Response JSON document for Example 2 in
Section 3: Section 3.1:
{ {
"iat" :"15790460234", "iat" : 15790460234,
"nonce" :"0d1998d8-fbfa-4879-b942-85a88bff1f3b", "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6",
"authorizations": { "uri" : "https://as.example/endpoint/grant/example2",
"authorization": {
"type" : "oauth_scope", "type" : "oauth_scope",
"scope" : "read_calendar write_calendar", "scope" : "read_calendar write_calendar",
"expires_in" : "3600", "expires_in" : 3600,
"method" : "pop", "mechanism" : "jose",
"access": { "token" : "eyJJ2D6.example.access.token.mZf9p"
"handle" : "ey.example.access.handle.9yf3szM", "certificate": {
"jwk": { "x5u" : "https://as.example/cert/example2"
"x5u" : "https://as.example/jwk/VBUEOIQA82"
}
}, },
"refresh": { "uri" : "https://as.example/endpoint/authz/example2"
"handle" : "ey.example.refresh.handle.Jl4FzM",
"uri" : "https://as.example/refresh/eyj34"
}
} }
} }
Details of the JSON document: 7.2. Interaction Response
6.1. Top Level Attributes
*iat* - the time of the response as a NumericDate.
*nonce* - the nonce that was included in the AS Request JSON
Section 3.
6.2. "authorizations" Object The Interaction Response MUST include the following from the Response
JSON Section 7.4
* iat
There is an authorizations object in the AS Response if there was an * nonce
authorizations object in the AS Request.
* *type* - the type of claim request: "oauth_scope", "oauth_rich", * uri
or "oauth_rich_list". See Section 3.7 for details.
* *list* - an array of objects if the type was "oauth_rich_list". * interaction
The objects have the following attributes just as if the type was
"oauth_rich"
* *scope* - the scopes the Client was granted authorization for. and MAY include the following from the Response JSON Section 7.4
This will be all, or a subset, of what was requested.
* *authorization_details* - the authorization details granted. Only * user
returned for "oauth_rich" and "oauth_rich_list".
* *method* - the access method: "bearer", "pop", or "jws". See * wait
Section 6.4 for details.
* *token* - an access token for accessing the resource(s). Included A non-normative example of an Interaction Response follows:
if the access method is "bearer".
* *expires_in* - an optional value specifying how many seconds until {
the access token or handle expire. "iat" : 15790460234,
"nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b",
"uri" : "https://as.example/endpoint/grant/example4",
"interaction" : {
"type" : "popup",
"uri" : "https://as.example/popup/example4"
},
"user": {
"exists" : true
}
}
* *refresh* - an optional object containing parameters required to 7.3. Wait Response
refresh an access token or handle. See refresh request
Section 8.18.
- *handle* - an refresh handle used to create the JSON refresh The Wait Response MUST include the following from the Response JSON
token. Section 7.4
- *uri* - the refresh uri the Client will use to refresh. * iat
* *access* - an object containing the parameters needed to access * nonce
resources requiring proof-of-possession. Included if the access
method is "pop".
- *handle* - the access handle. * uri
- *jwk* - the jwk object to use. * wait
6.3. "claims" Object A non-normative example of an Wait Response follows:
There is a claims object in the AS Response if there was a claims {
object in the AS Request. "iat" : 15790460234,
"nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b",
"uri" : "https://as.example/endpoint/grant/example5",
"wait" : 300
}
* *oidc* 7.4. Response JSON
- *id_token* - an OpenID Connect ID Token containing the Claims Details of the JSON document:
the User consented to be released.
- *userinfo* - the Claims the User consented to be released. * *iat* - the time of the response as a NumericDate.
Claims are defined in [OIDC] Section 5. * *nonce* - the nonce that was included in the Request JSON
Section 5.5.
* *oidc4ia* - OpenID Connect for Identity Assurance claims response * *uri* - the Grant URI.
per [OIDC4IA].
* *vc* * *wait* - a numeric value representing the number of seconds the
Client should want before making a Read Grant request to the Grant
URI.
The verified claims the user consented to be released. [Editor: * *expires_in* - a numeric value specifying how many seconds until
details TBD] the Grant expires. This attribute is OPTIONAL.
6.4. Access Methods 7.4.1. "interaction" Object
The are three different methods for the Client to access an RS: If the GS wants the Client to start the interaction, the GS MUST
select one of the interaction mechanisms provided by the Client in
the Grant Request, and include the matching attribute in the
interaction object:
* *bearer* - the AS provides a bearer access token that the Client * *type* - this MUST match the type provided by the Client in the
can use to access an RS per Section 8.15. Grant Request client.interaction object.
* *pop* - the AS provides an access handle that the Client presents * *uri* - the URI to interact with the User per the type. This may
in a proof-of-possession RS access request per Section 8.16. be a temporary short URL if the type is qrcode so that it is easy
to scan.
* *pop_body* - the Client signs the JSON payload sent to the RS per * *message* - a text string to display to the User if type is
Section 8.17. qrcode.
In the AS Response, the AS will return the method the Client MUST use [Editor: do we specify a maximum length for the uri and message so
when accessing the RS. that a device knows the maximum it needs to support? A smart device
may have limited screen real estate.]
7. Discovery 7.4.2. "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 5.5.3
The Client obtains the following metadata about the AS prior to 7.4.3. "authorization" Object
initiating a request:
*Endpoint* - the endpoint of the AS. The "authorization" object is a response to the Request
"authorization" object Section 5.5.4, the Refresh Authorization
Section 5.6, or the Update Authorization Section 5.7.
*"as"* - the unique string identifier for the AS. * *type* - the type of claim request: "oauth_scope" or "oauth_rich".
See the "type" object in Section 5.5.4 for details.
*Algorithms* - the asymetric cryptographic algorithms supported by * *scope* - the scopes the Client was granted authorization for.
the AS. This will be all, or a subset, of what was requested. This
attribute is OPTIONAL.
*Authorizations* - the authorizations the Client may request, if any. * *authorization_details* - the authorization details granted per
[RAR]. Included if type is "oauth_rich".
*Identity Claims* - the identity claims the Client may request, if * *mechanism* - one of the access mechanisms: "bearer", "jose", or
any, and what public keys the claims will be signed with. "jose+body". See Section 8 for details.
The client may also obtain information about how the AS will sign * *token* - the access token for accessing an RS. This attribute is
and/or encrypt the AS Response, as well as any other metadata REQUIRED.
required for extensions to this protocol, as defined in those
extension specifications.
8. JOSE Client Authentication * *expires_in* - a numeric value specifying how many seconds until
the access token expires. This attribute is OPTIONAL.
The default mechanism for the Client to authenticate to the AS and * *certificate* - MUST be included if the mechanism is "jose" or
the RS is signing a JSON document with JWS per [RFC7515]. The "jose+body". Contains the jwk header values for the Client to
resulting tokens always use compact serialization. include in the JWS header when calling the RS using the "jose" or
"jose+body" mechanisms. See Section 10.2.1.
It is expected that extensions to this protocol that specify a * *uri* - the AuthZ URI. Used to refresh, update, and delete the
different mechanism for the Client to authenticate, would over ride authorization. This attribute is OPTIONAL.
this section.
The Authorization Request JSON is signed with JWS and passed as the [Editor: any value in an expiry for the Authorization?]
body of the POST.
The authorization, refresh, and access handles are signed with JWS 7.4.4. "authorizations" Object
resulting in authorization request, refresh, and access tokens
respectively. These JOSE tokens are passed in the HTTP Authorization
header with the "JOSE" parameter per Section 8.6.
The Client will use the same private key to create all tokens. A JSON array of authorization objects. Support for the
authorizations object is OPTIONAL.
The Client and the AS MUST both use HTTP/2 ([RFC7540]) or later, and 7.4.5. "claims" Object
TLS 1.3 ([RFC8446]) or later, when communicating with each other.
[Editor: too aggressive to mandate HTTP/2 and TLS 1.3?] The claims object is a response to the Request "claims" object
Section 5.5.4.
8.1. JOSE Headers * *oidc*
A non-normative example of a JOSE header for a Registered Client - *id_token* - an OpenID Connect ID Token containing the Claims
using a key id to identify the Client's public key: the User consented to be released.
{ - *userinfo* - the Claims the User consented to be released.
"alg":"ES256",
"typ":"JOSE",
"kid":"1"
}
A non-normative example of a JOSE header for a Registered Client Claims are defined in [OIDC] Section 5.
using a certificate to assert the Client's public key:
{ * *oidc4ia* - OpenID Connect for Identity Assurance claims response
"alg":"ES256", per [OIDC4IA].
"typ":"JOSE",
"jwk":
{"kty":"RSA",
"use":"sig",
"kid":"1b94c",
"n":"vrjOfz9Ccdgx5nQudyhdoR17V-IubWMeOZCwX_jj0hgAsz2J_pqYW08
PLbK_PdiVGKPrqzmDIsLI7sA25VEnHU1uCLNwBuUiCO11_-7dYbsr4iJmG0Q
u2j8DsVyT1azpJC_NG84Ty5KKthuCaPod7iI7w0LK9orSMhBEwwZDCxTWq4a
YWAchc8t-emd9qOvWtVMDC2BXksRngh6X5bUYLy6AyHKvj-nUy1wgzjYQDwH
MTplCoLtU-o-8SNnZ1tmRoGE9uJkBLdh5gFENabWnU5m1ZqZPdwS-qo-meMv
VfJb6jJVWRpl2SUtCnYG2C32qvbWbjZ_jBPD5eunqsIo1vQ",
"e":"AQAB",
"x5c":
["MIIDQjCCAiqgAwIBAgIGATz/FuLiMA0GCSqGSIb3DQEBBQUAMGIxCzAJB
gNVBAYTAlVTMQswCQYDVQQIEwJDTzEPMA0GA1UEBxMGRGVudmVyMRwwGgYD
VQQKExNQaW5nIElkZW50aXR5IENvcnAuMRcwFQYDVQQDEw5CcmlhbiBDYW1
wYmVsbDAeFw0xMzAyMjEyMzI5MTVaFw0xODA4MTQyMjI5MTVaMGIxCzAJBg
NVBAYTAlVTMQswCQYDVQQIEwJDTzEPMA0GA1UEBxMGRGVudmVyMRwwGgYDV
QQKExNQaW5nIElkZW50aXR5IENvcnAuMRcwFQYDVQQDEw5CcmlhbiBDYW1w
YmVsbDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAL64zn8/QnH
YMeZ0LncoXaEde1fiLm1jHjmQsF/449IYALM9if6amFtPDy2yvz3YlRij66
s5gyLCyO7ANuVRJx1NbgizcAblIgjtdf/u3WG7K+IiZhtELto/A7Fck9Ws6
SQvzRvOE8uSirYbgmj6He4iO8NCyvaK0jIQRMMGQwsU1quGmFgHIXPLfnpn
fajr1rVTAwtgV5LEZ4Iel+W1GC8ugMhyr4/p1MtcIM42EA8BzE6ZQqC7VPq
PvEjZ2dbZkaBhPbiZAS3YeYBRDWm1p1OZtWamT3cEvqqPpnjL1XyW+oyVVk
aZdklLQp2Btgt9qr21m42f4wTw+Xrp6rCKNb0CAwEAATANBgkqhkiG9w0BA
QUFAAOCAQEAh8zGlfSlcI0o3rYDPBB07aXNswb4ECNIKG0CETTUxmXl9KUL
+9gGlqCz5iWLOgWsnrcKcY0vXPG9J1r9AqBNTqNgHq2G03X09266X5CpOe1
zFo+Owb1zxtp3PehFdfQJ610CDLEaS9V9Rqp17hCyybEpOGVwe8fnk+fbEL
2Bo3UPGrpsHzUoaGpDftmWssZkhpBJKVMJyf/RuP2SmmaIzmnw9JiSlYhzo
4tpzd5rFXhjRbg4zW9C+2qok+2+qDM1iJ684gPHMIY8aLWrdgQTxkumGmTq
gawR+N5MDtdPTEQ0XfIBc2cJEUyMTY5MPvACWpkA6SdS4xSvdXK3IVfOWA=="]
}
}
[Editor: the jwk above was copy and pasted from the JWK example. * *vc*
Replace? ]
The certificate could be signed by the AS, allowing the AS to verify The verified claims the user consented to be released. [Editor:
the signature using the AS public key, or the certificate could be details TBD]
signed by a private key the AS has bound to the Registered Client,
allowing each instance of the Registered Client to have its own
asymetric key pair.
A non-normative example of a JOSE header for a Dynamic Client 7.4.6. "reciprocal" Object
including the public key generated by the Client that matches its its
private key:
{ The following MUST be included
"alg":"ES256",
"typ":"JOSE",
"jwk":{
"kty":"EC",
"crv":"P-256",
"x":"Kgl5DJSgLyV-G32osmLhFKxJ97FoMW0dZVEqDG-Cwo4",
"y":"GsL4mOM4x2e6iON8BHvRDQ6AgXAPnw0m0SfdlREV7i4"
}
}
A non-normative example of a JOSE header for a JOSE access token for * *nonce* - a unique identifier for this request. Note the Grant
a Client accessing an RS that requires proof-of-possession: Response MUST contain a matching nonce attribute value.
{ * *client*
"alg":"ES256",
"typ":"JOSE",
"jwk":{
"x5u":"https://as.example/jwk/VBUEOIQA82"
}
}
The "jwk" object in a JOSE access token Section 8.5 MUST be the AS - *id* - the Client ID making the request
jwk object the AS provided with the access handle.
This decouples how the AS communicates the Client's public key to the One or more of the following objects from the Request JSON
RS from how the AS asserts the Client's public key. The RS can have Section 5.5 are included:
a consistent mechanism assert the Client's public key across all
Clients.
One advantage of this is the AS can create a certificate of a Dynamic * *authorization* Section 7.4.3
Client's public key, and pass it by value or reference to the Client
to present to the RS.
All JOSE headers MUST have: + the "alg" attribute. + the "typ" * *authorizations* Section 7.4.4
attribute set to "jose". + either a "kid" or "jwk" attribute.
[Editor: should we use indicate the type of token (authorization, * *claims* Section 7.4.5
refresh, access) using "typ" or "cty"?]
8.2. Authentication Request Token 7.4.7. Interaction Types
A non-normative example of a payload follows: If the GS wants the Client to initiate the interaction with the User,
then the GS will return an Interaction Response. The Client will
initiate the interaction with the User in one of the following ways:
{ * *popup* The Client will create a new popup child browser window
"as" :"https://as.example", containing the "interaction"."uri" attribute. [Editor: more
"type" :"authentication", details on how to do this]
"iat" :"1579046092",
"jti" :"f6d72254-4f23-417f-b55e-14ad323b1dc1",
"handle":"eyJhb958.example.authentication.handle.9yf3szM"
}
The payload of the authentication token contains: The GS will close the popup window when the interactions with the
User are complete. [Editor: confirm GS can do this still on all
browsers, or does Client need to close]
*as* - the unique string identifier for the AS. * *redirect* The Client will redirect the User to the
"interaction"."uri" attribute. When the GS interactions with the
User are complete, the GS will redirect the User to the
"interaction"."redirect_uri" attribute the Client provided in the
Grant Request.
*type* - the string "authentication", indicating the type of token. * *qrcode* The Client will create a [QR_Code] of the
"interaction"."uri" attribute and display the resulting graphic
and the "interaction"."message" attribute as a character string.
*iat* - the time the authentication token was created as a An GS MUST support the "popup", "redirect", and "qrcode" interaction
NumericDate. types.
*jti* - a unique identifier for the authentication token per 7.4.8. Signing and Encryption
[RFC7519] section 4.1.7.
*handle* the authentication handle the AS provided the Client in the [Editor: TBD - how response is signed and/or encrypted by the GS. Is
Interaction Response Section 4. there a generalized description, or is it mechanism specific?]
8.3. Authorization Request Token 7.5. Response Verification
A non-normative example of a payload follows: On receipt of a response, the Client MUST verify the following:
{ * TBD
"as" :"https://as.example",
"type" :"authorization",
"iat" :"1579046092",
"jti" :"f6d72254-4f23-417f-b55e-14ad323b1dc1",
"handle":"eyJhb958.example.authorization.handle.9yf3szM"
}
The payload of the authorization token contains: 8. RS Access
*as* - the unique string identifier for the AS. This document specifies three different mechanisms for the Client to
access an RS ("bearer", "jose", and "jose+body"). The "bearer"
mechanism is defined in {BearerToken}. 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 7.4.3.
*type* - the string "authorization", indicating the type of token. 8.1. Bearer Token
*iat* - the time the authorization token was created as a If the access mechanism is "bearer", then the Client accesses the RS
NumericDate. per Section 2.1 of [RFC6750]
*jti* - a unique identifier for the authorization token per [RFC7519] A non-normative example of the HTTP request headers follows:
section 4.1.7.
*handle* the authorization handle the AS provided the Client in the GET /calendar HTTP/2
Interaction Response Section 4. Host: calendar.example
Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA
8.4. Refresh Token 9. Error Responses
A non-normative example of a payload follows: * TBD
{ 10. JOSE Authentication
"as" :"https://as.example",
"type" :"refresh",
"iat" :"1579049876",
"jti" :"4342046d-83c4-4725-8c72-e9a49245f791",
"handle":"eyJhb958.example.refresh.handle.9yf3szM"
}
The payload of the authorization token contains: 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.
*as* - the unique string identifier for the AS. Other documents that specify other Client authentication mechanisms
will replace this section.
*type* - the string "refresh", indicating the type of token. 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.
*iat* - the time the refresh request token was created as a [Editor: are there advantages to using JSON serialization in the
NumericDate. body?]
*jti* - a unique identifier for the refresh request token. Different instances of a Registered Clients MAY have different
private keys, but certificates bind them 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.
*handle* the refresh handle the AS provided the Client in the AS The Client and the GS MUST both use HTTP/2 ([RFC7540]) or later, and
Response Section 6 or access refresh response Section 8.18. TLS 1.3 ([RFC8446]) or later, when communicating with each other.
8.5. JOSE Access Token [Editor: too aggressive to mandate HTTP/2 and TLS 1.3?]
The "jwk" object in a JOSE access token header MUST be set to the The token may be included in an HTTP header, or as the HTTP message
"jwk" value the AS provided for the access handle. body.
A non-normative example of a payload follows: The following sections specify how the Client uses JOSE to
authenticate to the GS and RS.
{ 10.1. GS Access
"type" :"access",
"iat" :"1579046092",
"jti" :"5ef47057-08f9-4763-be8d-162824d43dfb",
"handle":"eyJhb958.example.access.handle.9yf3szM"
}
The payload of the JOSE access token contains: 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:
*type* - the string "access", indicating the type of token. +---------------+-----------+-----------+----------+
| request | http verb | uri | token in |
+===============+===========+===========+==========+
| Create Grant | POST | GS URI | body |
+---------------+-----------+-----------+----------+
| Read Grant | GET | Grant URI | header |
+---------------+-----------+-----------+----------+
| Update Grant | PUT | Grant URI | body |
+---------------+-----------+-----------+----------+
| Delete Grant | DELETE | Grant URI | success |
+---------------+-----------+-----------+----------+
| Refresh AuthZ | GET | AuthZ URI | body |
+---------------+-----------+-----------+----------+
| Update AuthZ | PUT | AuthZ URI | body |
+---------------+-----------+-----------+----------+
| Delete AuthZ | DELETE | AuthZ URI | header |
+---------------+-----------+-----------+----------+
| GS Options | OPTIONS | GS URI | header |
+---------------+-----------+-----------+----------+
| Grant Options | OPTIONS | Grant URI | header |
+---------------+-----------+-----------+----------+
| AuthZ Options | OPTIONS | AuthZ URI | header |
+---------------+-----------+-----------+----------+
*iat* - the time the JOSE access token was created as a NumericDate. Table 2
*jti* - a unique identifier for the JOSE access token. 10.1.1. Authorization Header
*handle* the access handle the AS provided the Client in the AS For requests with the token in the header, the JWS payload MUST
Response Section 6 or access refresh response Section 8.18. contain the following attributes:
[Editor: should we include the called URI in the token?] *iat* - the time the token was created as a NumericDate.
8.6. HTTP Authorization JOSE Header *jti* - a unique identifier for the token per [RFC7519] section
4.1.7.
The Client authenticates requests by setting the HTTP Authorization *uri* - the value of the URI being called (GS URI, Grant URI, or
header to include the "JOSE" parameter, followed by one or more space AuthZ URI).
characters, followed by the appropriate JOSE token.
A non-normative example: *verb* - the HTTP verb being used in the call ("GET", "DELETE",
"OPTIONS")
Authorization: JOSE eyJhb.example.authorization.token.haDwskpFDBW The HTTP authorization header is set to the "jose" parameter followed
by one or more white space characters, followed by the resulting
token.
The authorization request token, refresh request token, and the JOSE A non-normative example of a JWS payload and the HTTP request
access token are all passed in this manner. follows:
8.7. JOSE Token Verification {
"iat" : 15790460234,
"jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1",
"uri" : "https://as.example/endpoint/grant/example6",
"verb" : "GET"
}
TBD GET /endpoint/example.grant HTTP/2
Host: as.example
Authorization: jose eyJhbGciOiJIUzI1NiIsIn ...
8.8. AS Request [Editor: make a real example token]
The Client creates a JSON document per Section 3, signs it using JWS *GS Verification*
[RFC7515], and sends the JWS token to the AS end point using HTTP
POST, with a content-type of application/jose.
* *Payload Encryption* The GS MUST verify the token by:
The AS may require the AS Request to be encrypted. If so, the JWS * TBD
token is encrypted per JWE [RFC7516] using the public key and
algorithm specified by the AS.
8.9. Interaction Response 10.1.2. Signed Body
If the Client set the authenticate_first flag, the response includes For requests with the token in the body, the Client uses the Request
an authentication object, otherwise it includes an authorization JSON as the payload in a JWS. The resulting token is sent with the
object. If the AS wants the Client to initiate the User interaction, content-type set to "application/jose".
it sends an interaction object.
If no interaction is required the AS will return an AS Response per A non-normative example (line breaks added to the body for
Section 8.14, otherwise the AS will return an Interaction Response readability):
per Section 4.
If the AS wants the Client to start the interaction, an interaction POST /endpoint HTTP/2
object will be returned in the response. Host: as.example
Content-Type: application/jose
Content-Length: 155
* *Error Responses* eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyzdWIiOiIxMjM0NTY3ODkwIiwibmF
tZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMe
Jf36POk6yJV_adQssw5c
The AS MAY respond with one of the following errors defined in [Editor: make a real example token]
Section 9:
TBD *GS Verification*
8.10. Deletion Request The GS MUST verify the token by:
The Client MAY delete an outstanding request using the authorization * TBD
token by making an HTTP DELETE call to the authorization uri, setting
the HTTP Authorization header per Section 8.6 with the authorization
request token.
A non-normative deletion request example: 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.
DELETE /authorization/ey7snHGs HTTP/2 [Editor: would examples help here so that implementors understand the
Host: as.example full range of options, and how an instance can have its own asymetric
Authorization: JOSE eyJhb.example.authorization.token.haDwskpFDBW key pair]
* *Error Responses* A non-normative example of a JOSE header for a Registered Client with
a key identifier of "12":
The AS MAY respond with one of the following errors defined in {
Section 9: "alg" : "ES256",
"typ" : "JOSE",
"kid" : "12"
}
TBD * *Dynamic Clients* include their public key in the "jwk" JWS
header.
8.11. Authentication Request A non-normative example of a JOSE header for a Dynamic Client:
Section 8.2 {
"alg" : "ES256",
"typ" : "JOSE",
"jwk" : {
"kty" : "EC",
"crv" : "P-256",
"x" : "Kgl5DJSgLyV-G32osmLhFKxJ97FoMW0dZVEqDG-Cwo4",
"y" : "GsL4mOM4x2e6iON8BHvRDQ6AgXAPnw0m0SfdlREV7i4"
}
}
8.12. Authentication Response 10.2. RS Access
8.13. Authorization Request 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.
The Client makes an HTTP GET call to the authorization uri, setting 10.2.1. JOSE header
the HTTP Authorization header per Section 8.6 with the authorization
request token.
A non-normative Authorization Request example: 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.
GET /authorization/ey7snHGs HTTP/2 A non-normative examples JOSE header:
Host: as.example
Authorization: JOSE eyJhb.example.authorization.token.haDwskpFDBW
8.14. AS Response {
"alg" : "ES256",
"typ" : "JOSE",
"x5u" : "https://as.example/cert/example2"
}
The AS verifies the authorization request token, and then provides a [Editor: this enables Dynamic Clients to make proof-of-possession API
response according to what the User and/or RO have authorized if calls the same as Registered Clients.]
required. If no signature or encryption was required, the AS will
respond with a JSON document with content-type set to application/
json.
* *Response Signing* 10.2.2. "jose" Mechanism
The AS MAY sign the response with a JWS per [RFC7515] and the private The JWS payload MUST contain the following attributes:
key matching the public key the AS defined as its AS Response signing
key. The AS will respond with the content-type set to application/
jose.
* *Response Encryption* *iat* - the time the token was created as a NumericDate.
The AS MAY encrypt the response using the public key provided by the *jti* - a unique identifier for the token per [RFC7519] section
Client, using JWE per [RFC7516]. The AS will respond with the 4.1.7.
content-type set to application/jose.
* *Error Responses* *uri* - the value of the RS URI being called.
The AS MAY respond with one of the following errors defined in *verb* - the HTTP verb being used in the call
Section 9:
TBD *token* - the access token provided by the GS to the Client
8.15. Bearer Token RS Access The HTTP authorization header is set to the "jose" parameter followed
by one or more white space characters, followed by the resulting
token.
If the access method in the AS Response authorizations object A non-normative example of a JWS payload and the HTTP request
Section 6.2 was "bearer", then the Client accesses the RS per follows:
Section 2.1 of [RFC6750]
A non-normative example of the HTTP request headers 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 GET /calendar HTTP/2
Host: calendar.example Host: calendar.example
Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA Authorization: jose eyJhbG.example.jose.token.adks
* *Error Responses*
TBD [Editor: make a real example token]
8.16. Proof-of-possession RS Access *RS Verification*
The RS MUST verify the token by:
If the access method in the AS Response authorizations object * verify access token is bound to the public key - include key
Section 6.2 was "pop", then the Client creates a JOSE access token fingerprint in access token?
per Section 8.5 for each call to the RS, setting the HTTP
Authorization header per Section 8.6 with the JOSE access token.
A non-normative example of the HTTP request headers follows: * TBD
GET /calendar HTTP/2 10.2.3. "jose+body" Mechanism
Host: calendar.example
Authorization: JOSE eyJhbG.example.JOSE.access.token.kwwQb958
* *Error Responses* The "jose+body" mechanism can only be used if the content being sent
to the RS is a JSON document.
TBD Any requests not sending a message body will use the "jose" mechanism
Section 10.2.2.
8.17. JOSE Body RS Access Requests sending a message body MUST have the following JWS payload:
If the access method in the AS Response authorizations object *iat* - the time the token was created as a NumericDate.
Section 6.2 was "pop_body", then the Client creates a JOSE access
token per Section 8.5 for each call to the RS, setting the HTTP
Authorization header per Section 8.6 with the JOSE access token.
The Client creates a JSON document per the RS requirements. The *jti* - a unique identifier for the token per [RFC7519] section
document MUST include the access handle. The CLient then signs the 4.1.7.
document using JWS [RFC7515], and sends the resulting compact
notation JWS token to the RS end point using HTTP POST, with a
content-type of application/jose. Note this is similar to the AS
Request Section 8.8.
[Editor: any isues here? Anything missing that MUST be in the *uri* - the value of the RS URI being called.
payload? Would an HTTP Authorization header make sense?]
8.18. Access Refresh *verb* - the HTTP verb being used in the call
If the Client received a refresh handle and uri from the AS in the *token* - the access token provided by the GS to the Client
Interaction Response, and it wants a fresh access token or handle, it
creates a refresh request token per Section 8.4. setting the HTTP
Authorization header per Section 8.6 with the refresh request token.
The AS will then respond with a refresh response.
* *Refresh Response* *body* - the message body being sent to the RS
A non-normative example refresh response with an access handle: A non-normative example of a JWS payload and the HTTP request
follows:
{ {
"type" : "oauth_scope", "iat" : 15790460234,
"scope" : "read_calendar write_calendar", "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1",
"expires_in" : "3600", "uri" : "https://calendar.example/calendar",
"method" : "pop", "verb" : "POST",
"access": { "token" : "eyJJ2D6.example.access.token.mZf9pTSpA",
"handle" : "ey.example.access.handle.9yf3iWszM", "payload" : {
"jwk": { "event" : {
"x5u" : "https://as.example/jwk/VBUEOIQA82" "title" : "meeting with joe",
"start_date_utc" : "2020-02-21 11:00:00",
"end_date_utc" : "2020-02-21 11:00:00"
} }
},
"refresh": {
"handle" : "ey.example.refresh.handle.4SkjIi",
"uri" : "https://as.example/refresh/eyJl4FzM"
} }
} }
The refresh response is the same as the authorizations object POST /calendar HTTP/2
Section 6.2 in the AS Response. Host: calendar.example
Content-Type: application/jose
If a new refresh handle and/or refresh uri is returned, the Client Content-Length: 155
MUST use the new refresh handle and/or refresh uri
[Editor: are there other results relevant for [RAR]?]
* *Error Responses*
The AS MAY respond with one of the following errors defined in
Section 9:
TBD
9. Error Messages
[Editor: return "wait" time in AS Response when AS wants Client to
wait before retying a Authorization Request. The Client MUST
generate a fresh authorization token when retrying the Authorization
Request. ]
TBD
10. AS Initiated Sequence
[Editor: AS initiated flows have been challenging to implement as
OAuth 2.0 did not directly support them, so deployments bounced back
and forth between the Client and AS to create a Client initiated
flow. Here is a proposal to support AS initiated: authentication;
just-in-time (JIT) provisioning; and authorization]
In this sequence the User starts at the AS, and then based on User
input, the AS redirects the User to a Client, passing an initiation
token Section 10.1, and then the Client retrieves authorizations and/
or identity claims about the User. The Client MUST be a Registered
Client. The sequence follows:
1. The User is interacting at the AS and wants to use the Client,
and provide the Client identity claims and/or authorizations from
the AS that the Client has pre-configured.
2. The AS creates a authorization handle and uri representing the
identity claims and authorizations to be provided to the Client.
The AS creates an initiation token containing the AS identifier,
the authorization handle, and the authorization uri.
3. The AS redirects the User to a URI the Client has configured to eyJhbGciOi.example.jose+body.adasdQssw5c
accept initiation tokens, passing the initiation token as a query
parameters with the name "token".
4. The Client verifies the initiation token. [Editor: make a real example token]
5. The Client makes an Authorization Request per Section 8.13. *RS Verification*
6. The AS responds with an AS Response JSON document Section 6 per The RS MUST verify the token by:
Section 8.14.
The Client now has the User identity claims and/or authorizations. * TBD
If Client policy permits, the Client can perform JIT provisioning if
the User is new to the Client.
*AS Initiated Sequence Diagram* 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
| | | User |-------(1)-->| | header.
| | | | | |
| | +-------------+ | (2) |
| | /\ | |
| Client |<--- initiation ---/ \-------------(3)---| Authorization |
| | token | Server |
| (4) | | |
| | | |
| |--(5)------- Authorization Request ------>| |
| | | |
| |<-(6)------- AS Response -----------------| |
| | | |
+--------+ +---------------+
10.1. Initiation Token 10.3. Request Encryption
A non-normative example of an initiation token payload follows: [Editor: to be fleshed out]
{ The Client encrypts a request when ??? using the GS public key
"as": "https://as.example", returned as the ??? attribute in GS Options Section 5.9.
"authorization": {
"handle" : "eyJhb958.example.authorization.handle.9yf3szM",
"uri" : "https://as.example/authorization/ey7snHGs"
}
}
* *as* - the "as" identifier for the AS. This attribute is 10.4. Response Signing
REQUIRED.
* *authorization* - the authorization object has the following [Editor: to be fleshed out]
attributes: The Client verifies a signed response ??? using the GS public key
returned as the ??? attribute in GS Options Section 5.9.
- *handle* - the authorization handle. This attribute is 10.5. Response Encryption
REQUIRED.
- *uri* - the authorization URI. This attribute is REQUIRED. [Editor: to be fleshed out]
The initiation token is signed with JWS and uses the compact The Client decrypts a response when ??? using the private key
serialization. matching the public key included in the request as the ??? attribute
in Section 5.5.
11. Extensibility 11. Extensibility
This standard can be extended in a number of areas: This standard can be extended in a number of areas:
* *Client Authentication Mechanisms* * *Client Authentication Mechanisms*
An extension could define other mechanisms for the Client to - An extension could define other mechanisms for the Client to
authenticate and replace JOSE in Section 8 with Mutual TLS or HTTP authenticate to the GS and/or RS such as Mutual TLS or HTTP
Signing. Constrained environments could use CBOR [RFC7049] instead Signing. Constrained environments could use CBOR [RFC7049]
of JSON, and COSE [RFC8152] instead of JOSE, and CoAP [RFC8323] instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP
instead of HTTP/2. [RFC8323] instead of HTTP/2.
* *AS Request* * *Grant*
An additional top level object could be added to the AS Request - An extension can define new objects in the Grant Request and
payload if the AS can manage delegations other than authorizations or Grant Response JSON.
claims, or some other functionality.
* *Top Level*
- Top level objects SHOULD only be defined to represent
functionality other the existing top level objects and
attributes.
* *"client" Object* * *"client" Object*
Additional information about the Client that the AS would require - Additional information about the Client that the GS would
related to an extension. require related to an extension.
* *"user" Object* * *"user" Object*
Additional information about the Client that the AS would require - Additional information about the User that the GS would require
related to an extension. related to an extension.
* *"authorizations" Object* * *"authorization" Object*
Additional types of authorizations in addition to OAuth 2.0 scopes - Additional types of authorizations in addition to OAuth 2.0
and RAR. scopes and RAR.
* *"claims" Object* * *"claims" Object*
Additional types of identity claims in addition to OpenID Connect - Additional types of identity claims in addition to OpenID
claims and Verified Credentials. Connect claims and Verified Credentials.
* *Interaction*
Additional mechanisms for the Client to start an interaction with the
User.
* *Access Methods* * *Interaction types*
Additional mechanisms for the Client to present authorization to a - Additional types of interactions a Client can start with the
resource. User.
* *Continuous Authentication* * *Continuous Authentication*
An extension could define a new handle for the Client to use to - An extension could define a mechanism for the Client to
regularly provide continuous authentication signals and receive regularly provide continuous authentication signals and receive
responses. responses.
[Editor: do we specify access token / handle introspection in this [Editor: do we specify access token / handle introspection in this
document, or leave that to an extension?] document, or leave that to an extension?]
[Editor: do we specify access token / handle revocation in this [Editor: do we specify access token / handle revocation in this
document, or leave that to an extension?] document, or leave that to an extension?]
12. Rational 12. Rational
1. *Why is there only one mechanism for the Client to authenticate 1. *Why is there only one mechanism for the Client to authenticate
with the AS? Why not support other mechanisms?* with the GS? Why not support other mechanisms?*
Having choices requires implementers to understand which choice Having choices requires implementers to understand which choice
is preferable for them. Having one default mechanism in the is preferable for them. Having one default mechanism in the
document for the Client to authenticate simplifies most document for the Client to authenticate simplifies most
implementations. Extensions can specify other mechanisms that implementations. Deployments that have unique characteristics
are preferable in specific environments. can select other mechanisms that are preferable in specific
environments.
2. *Why is the default Client authentication JOSE rather than 2. *Why is the default Client authentication JOSE rather than
MTLS?* MTLS?*
MTLS cannot be used today by a Dynamic Client. MTLS requires MTLS cannot be used today by a Dynamic Client. MTLS requires
the application to have access below what is typically the the application to have access below what is typically the
application layer, that is often not available on some application layer, that is often not available on some
platforms. JOSE is done at the application layer. Many AS platforms. JOSE is done at the application layer. Many GS
deployments will be an application behind a proxy performing deployments will be an application behind a proxy performing
TLS, and there are risks in the proxy passing on the results of TLS, and there are risks in the proxy passing on the results of
MTLS. MTLS.
3. *Why is the default Client authentication JOSE rather than HTTP 3. *Why is the default Client authentication JOSE rather than HTTP
signing?* signing?*
There is currently no widely deployed open standard for HTTP There is currently no widely deployed open standard for HTTP
signing. Additionally, HTTP signing requires passing all the signing. Additionally, HTTP signing requires passing all the
relevant parts of the HTTP request to downstream services within relevant parts of the HTTP request to downstream services within
an AS that may need to independently verify the Client identity. an GS that may need to independently verify the Client identity.
4. *What are the advantages of using JOSE for the Client to 4. *What are the advantages of using JOSE for the Client to
authenticate to the AS and a resource?* authenticate to the GS and a resource?*
Both Registered Clients and Dynamic Clients can have a private Both Registered Clients and Dynamic Clients can have a private
key, eliminating the public Client issues in OAuth 2.0, as a key, eliminating the public Client issues in OAuth 2.0, as a
Dynamic Client can create an ephemeral key pair. Using Dynamic Client can create an ephemeral key pair. Using
asymetric cryptography also allows each instance of a Registered asymetric cryptography also allows each instance of a Registered
Client to have its own private key if it can obtain a Client to have its own private key if it can obtain a
certificate binding its public key to the public key the AS has certificate binding its public key to the public key the GS has
for the Client. Signed tokens can be passed to downstream for the Client. Signed tokens can be passed to downstream
components in a AS or RS to enable independent verification of components in a GS or RS to enable independent verification of
the Client and its request. The AS Initiated Sequence the Client and its request. The GS Initiated Sequence Section 6
Section 10 requires a URL safe parameter, and JOSE is URL safe. requires a URL safe parameter, and JOSE is URL safe.
5. *Why does the AS not return parameters to the Client in the 5. *Why does the GS not return parameters to the Client in the
redirect url?* redirect url?*
Passing parameters via a browser redirection is the source of Passing parameters via a browser redirection is the source of
many of the security risks in OAuth 2.0. It also presents a many of the security risks in OAuth 2.0. It also presents a
challenge for smart devices. In this protocol, the redirection challenge for smart devices. In this protocol, the redirection
from the Client to the AS is to enable the AS to interact with from the Client to the GS is to enable the GS to interact with
the User, and the redirection back to the Client is to hand back the User, and the redirection back to the Client is to hand back
interaction control to the Client if the redirection was a full interaction control to the Client if the redirection was a full
browser redirect. Unlike OAuth 2.0, the identity of the Client browser redirect. Unlike OAuth 2.0, the identity of the Client
is independent of the URI the AS redirects to. is independent of the URI the GS redirects to.
6. *Why is there not a UserInfo endpoint as there is with OpenID 6. *Why is there not a UserInfo endpoint as there is with OpenID
Connect?* Connect?*
In OpenID Connect, obtaining claims over the redirect or the
Token Endpoint are problematic. The redirect is limited in
size, and is not secure. The Token Endpoint is intended to
return tokens, and is limited by the "application/x-www-form-
urlencoded" format. A UserInfo endpoint returns "application/
json", and can return rich claims, just as the authorization uri
in this protocol.
[Editor: is there some other reason to have the UserInfo Since the Client can Read Grant at any time, it get the same
endpoint? What are industry best practices now? ] functionality as the UserInfo endpoint, without the Client
having to manage a separate access token and refresh token. If
the Client would like additional claims, it can Update Grant,
and the GS will let the Client know if an interaction is
required to get any of the additional claims, which the Client
can then start.
7. *Why is there still a Client ID? Could we not use a fingerprint [Editor: is there some other reason to have the UserInfo
of the public key to identify the Client?* endpoint?]
Some AS deployments do not allow calls from Registered Clients, 7. *Why is there still a Client ID?*
and provide different functionality to different Clients. A The GS needs an identifier to fetch the meta data associated
permanent identifier for the Client is needed for the Client with a Client such as the name and image to display to the User,
developer and the AS admin to ensure they are referring to the and the policies on what a Client is allowed to do. The Client
same Client. The Client ID was used in OAuth 2.0, and it served ID was used in OAuth 2.0 for the same purpose, which simplifies
the same purpose. migration. Dynamic Clients do not have a Client ID.
8. *Why have both claims and authorizations?* 8. *Why have both claims and authorizations?*
There are use cases for each that are independent: There are use cases for each that are independent:
authenticating a user vs granting access to a resource. A authenticating a user vs granting access to a resource. A
request for an authorization returns an access token or handle, request for an authorization returns an access token or handle,
while a request for a claim returns the claim. while a request for a claim returns the claim.
9. *Why specify HTTP/2 or later and TLS 1.3 or later for Client and 9. *Why specify HTTP/2 or later and TLS 1.3 or later for Client and
AS communication in ?*Section 8 GS communication in ?*Section 10
Knowing the AS supports HTTP/2 enables a Client to set up a Knowing the GS supports HTTP/2 enables a Client to set up a
connection faster. HTTP/2 will be more efficient when Clients connection faster. HTTP/2 will be more efficient when Clients
have large numbers of access tokens and are frequently have large numbers of access tokens and are frequently
refreshing them at the AS as there will be less network traffic. refreshing them at the GS as there will be less network traffic.
Mandating TLS 1.3 similarly improves the performance and Mandating TLS 1.3 similarly improves the performance and
security of Clients and AS when setting up a TLS connection. security of Clients and GS when setting up a TLS connection.
10. *Why do some of the JSON objects only have one child, such as 10. *Why do some of the JSON objects only have one child, such as
the identifiers object in the user object in the AS Request?* the identifiers object in the user object in the Grant Request?*
It is difficult to forecast future use cases. Having more It is difficult to forecast future use cases. Having more
resolution may mean the difference between a simple extension, resolution may mean the difference between a simple extension,
and a convoluted extension. and a convoluted extension.
11. *Why is the "iss" included in the "oidc" identifier object? 11. *Why is the "iss" included in the "oidc" identifier object?
Would the "sub" not be enough for the AS to identify the User?* Would the "sub" not be enough for the GS to identify the User?*
The AS may use another AS to authenticate Users. The "iss" and
"sub" combination is required to uniquely identify the User for
any AS.
12. *Why complicate the sequence with authentication first?* 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.
A common pattern is to use an AS to authenticate the User at the 12. *Why complicate the sequence with "interaction"."keep"?*
A common pattern is to use an GS to authenticate the User at the
Client. The Client does not know a priori if the User is a new Client. The Client does not know a priori if the User is a new
User, or a returning User. Asking a returning User to consent User, or a returning User. Asking a returning User to consent
releasing identity claims and/or authorizations they have releasing identity claims and/or authorizations they have
already provided is a poor User experience, as is sending the already provided is a poor User experience, as is sending the
User back to the AS. The Client requesting identity first User back to the GS. The Client requesting identity first
enables the Client to get a response from the AS while the AS is enables the Client to get a response from the GS while the GS is
still interacting with the User, so that the Client can request still interacting with the User, so that the Client can request
any identity claims/or authorizations required or desired. any identity claims/or authorizations required or desired.
Additionally, 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
13. *Why is there a JOSE Body access method for the 13. *Why is there a "jose+body" RS access mechanism method for the
Client?*Section 8.17 Client?*Section 10.2.3
There are numerous use cases where the RS wants non-repudiation There are numerous use cases where the RS wants non-repudiation
and providence of API calls. For example, the UAS Service and providence of the contents of an API call. For example, the
Supplier Framework for Authentication and Authorization [UTM]. UGS Service Supplier Framework for Authentication and
Authorization [UTM].
14. *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
AuthZ URI are defined to start with the GS URI, the Client (and
GS) can easily determine which GS a Grant or Authorization
belong to. URIs also enable a RESTful interface to the GS
functionality.
15. *Why have an 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 have an UPDATE, DELETE, and OPTIONS verbs on the AuthZ
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 list explicit interactions, instead of the Client and GS
negotiating interaction capabilities?*
The Client knows what interactions it is capable of, and
prefers. Telling the GS the interaction allows the GS to know
what interaction the User will have. Knowing how the Client
will transition the interaction will enable the GS to provider a
better User experience. For example, the GS may want to provide
a short URL if it knows the Client will be showing a QR code vs
a redirect, or have a different layout if it is a popup vs a
redirect.
13. Acknowledgments 13. Acknowledgments
This draft derives many of its concepts from Justin Richer's This draft derives many of its concepts from Justin Richer's
Transactional Authorization draft [TxAuth]. Transactional Authorization draft [TxAuth].
Additional thanks to Justin Richer for his strong critique of earlier Additional thanks to Justin Richer for his strong critique of earlier
drafts. drafts.
14. IANA Considerations 14. IANA Considerations
skipping to change at page 39, line 5 skipping to change at page 49, line 38
[W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable
Credentials Data Model 1.0", November 2019, Credentials Data Model 1.0", November 2019,
<https://w3c.github.io/vc-data-model/>. <https://w3c.github.io/vc-data-model/>.
[QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic
identification and data capture techniques - QR Code bar identification and data capture techniques - QR Code bar
code symbology specification", February 2015, code symbology specification", February 2015,
<https://www.iso.org/standard/62021.html>. <https://www.iso.org/standard/62021.html>.
[TxAuth] Richer, J., "Transactional Authorization", December 2019, [TxAuth] Richer, J., "Transactional AuthN", December 2019,
<https://tools.ietf.org/html/draft-richer-transactional- <https://tools.ietf.org/html/draft-richer-transactional-
authz-04>. authz-04>.
[UTM] Rios, J., Smith, I., and P. Venkatesen, "UAS Service [UTM] Rios, J., Smith, I., and P. Venkatesen, "UGS Service
Supplier Framework for Authentication and Authorization", Supplier Framework for Authentication and AuthN",
September 2019, <https://utm.arc.nasa.gov/docs/2019- September 2019, <https://utm.arc.nasa.gov/docs/2019-
UTM_Framework-NASA-TM220364.pdf>. UTM_Framework-NGSA-TM220364.pdf>.
Appendix A. Document History Appendix A. Document History
A.1. draft-hardt-xauth-protocol-00 A.1. draft-hardt-xauth-protocol-00
* Initial version * Initial version
A.2. draft-hardt-xauth-protocol-01 A.2. draft-hardt-xauth-protocol-01
* text clean up * text clean up
* added OIDC4IA claims * added OIDC4IA claims
* added "jws" method for accessing a resource. * added "jws" method for accessing a resource.
* renamed Initiation Request -> AS Request * renamed Initiation Request -> Grant Request
* renamed Initiation Response -> Interaction Response * renamed Initiation Response -> Interaction Response
* renamed Completion Request -> Authorization Request * renamed Completion Request -> Authorization Request
* renamed Completion Response -> AS Request * renamed Completion Response -> Grant Request
* renamed completion handle -> authorization handle * renamed completion handle -> authorization handle
* added Authentication Request, Authentication Response, * added Authentication Request, Authentication Response,
authentication handle authentication handle
A.3. draft-hardt-xauth-protocol-02
* handles are now URIs
* the
* the collection of claims and authorizations are a Grant
Appendix B. Comparison with OAuth 2.0 and OpenID Connect Appendix B. Comparison with OAuth 2.0 and OpenID Connect
*Changed Features* *Changed Features*
The major differences between this protocol and OAuth 2.0 and OpenID The major changes between this protocol and OAuth 2.0 and OpenID
Connect are: Connect are:
* The Client uses a private key to authenticate in this protocol * The Client uses a private key to authenticate in this protocol
instead of the client secret in OAuth 2.0 and OpenID Connect. instead of the client secret in OAuth 2.0 and OpenID Connect.
* The Client initiates the protocol by making a signed request * The Client initiates the protocol by making a signed request
directly to the AS instead of redirecting the User to the AS. directly to the GS instead of redirecting the User to the GS.
* The Client does not receive any parameters from a redirection of * The Client does not pass any parameters in redirecting the User to
the User back from the AS. the GS, nor receive any parameters in the redirection back from
the GS.
* Refreshing an access token requires creating a refresh token from * The refresh_token has been replaced with a AuthZ URI that both
a refresh handle, rather than an authenticated call with a refresh represents the access, and is the URI to call to refresh access.
token.
* The Client can request identity claims to be returned independent * The Client can request identity claims to be returned independent
of the ID Token. There is no UserInfo endpoint to query claims as of the ID Token. There is no UserInfo endpoint to query claims as
there is in OpenID Connect. there is in OpenID Connect.
* The GS URI is the token endpoint. CHECK!!!s
*Preserved Features* *Preserved Features*
* This protocol reuses the OAuth 2.0 scopes, Client IDs, and access * This protocol reuses the OAuth 2.0 scopes, Client IDs, and access
tokens of OAuth 2.0. tokens of OAuth 2.0.
* This protocol reuses the Client IDs, Claims and ID Token of OpenID * This protocol reuses the Client IDs, Claims and ID Token of OpenID
Connect. Connect.
* No change is required by the Client or the RS for existing APIs. * No change is required by the Client or the RS for existing bearer
token protected APIs.
Author's Address *New Features*
* A Grant represents the user identity claims and RS access granted
to the Client.
* The Client can 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 an 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 QR Code initiated interactions.
* Each Client instance can have its own private / public key pair.
* More Extensibility dimensions.
Appendix C. Open Questions
Author's Address
Dick Hardt (editor) Dick Hardt (editor)
SignIn.Org SignIn.Org
United States United States
Email: dick.hardt@gmail.com Email: dick.hardt@gmail.com
 End of changes. 369 change blocks. 
1068 lines changed or deleted 1598 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/