The Grant Negotiation and Authorization Protocol

1.1. Parties

The parties and their relationships to each other:¶

+--------+                           +------------+
|  User  |                           |  Resource  |
|        |                           | Owner (RO) |
+--------+                           +------------+
    |      \                       /      |
    |       \                     /       |
    |        \                   /        |
    |         \                 /         |
+--------+     +---------------+     +------------+
| Client |---->|     Grant     | _ _ |  Resource  |
|        |<----|  Server (GS)  |     |   Server   |
|        |     +---------------+     |    (RS)    |
|        |-------------------------->|            |
|        |<--------------------------|            |
+--------+                           +------------+

• User - the person interacting with the Client who has delegated access to identity claims about themselves to the Grant Server (GS), and can authenticate at the GS.¶
• Client - requests a Grant from the GS to access one or more Resource Servers (RSs), and/or identity claims about the User. The Client can create, verify, retrieve, update, and delete a Grant. When a Grant is created, the Client receives from the GS the granted 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 key that is linked to the Client ID. The GS may have different policies for what different Registered Clients can request. A Registered Client MAY be interacting with a User.¶
• Dynamic Client - a Client that has not been registered with the 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 requests, and to requests of a Resource Server that require proof-of-possession access. A single-page application with no active server component is an example of a Dynamic Client. A Dynamic Client MUST be interacting with a User.¶
• Grant Server (GS) - manages Grants for access to APIs at RSs and release of identity claims about the User. The GS may require explicit consent from the RO or User to provide these to the Client. A GS may support Registered Clients and/or Dynamic Clients. The GS is a combination of the Authorization Server (AS) in OAuth 2.0, and the OpenID Provider (OP) in OpenID Connect.¶
• Resource Server (RS) - has API resources that require an access token from the GS. Some, or all of the resources are owned by the Resource Owner.¶
• Resource Owner (RO) - owns resources at the RS, and has delegated RS access management to the GS. The RO may be the same entity as the User, or may be a different entity that the GS interacts with independently. GS and RO interactions are out of scope of this document.¶

1.2. Reused Terms

• access token - an access token as defined in [RFC6749] Section 1.4.¶
• Claim - a Claim as defined in [OIDC] Section 5. Claims may be issued by the GS, or by other issuers.¶
• Client ID - a GS unique identifier for a Registered Client as defined in [RFC6749] Section 2.2.¶
• ID Token - an ID Token as defined in [OIDC] Section 2.¶
• NumericDate - a NumericDate as defined in [RFC7519] Section 2.¶
• authN - short for authentication.¶
• authZ - short for authorization.¶

1.3. New Terms

• GS URI - the endpoint at the GS the Client calls to create a Grant, and is the unique identifier for the GS.¶
• Grant - the user identity claims and/or RS authorizations the GS has granted to the Client.¶
• 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.¶
• Authorization URI (AZ URI) - the URI that represents the Authorization the Client was granted by the RO. The AZ URI MUST start with the GS URI. The AZ URI is used to read, update, and delete an access token.¶
• Interaction - how the Client directs the User to interact with the GS. This document defines the interaction modes redirect, indirect, and user_code in Section 7¶
• Client Handle - a GS unique identifier for a Dynamic Client for the Dynamic Client to refer to itself in subsequent requests.¶

1.4. Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC2119].¶

Certain security-related terms are to be understood in the sense defined in [RFC4949]. These terms include, but are not limited to, "attack", "authentication", "authorization", "certificate", "confidentiality", "credential", "encryption", "identity", "sign", "signature", "trust", "validate", and "verify".¶

Unless otherwise noted, all the protocol parameter names and values are case sensitive.¶

Some protocol parameters are parts of a JSON document, and are referred to in JavaScript notation. For example, foo.bar refers to the "bar" boolean attribute in the "foo" object in the following example JSON document:¶

{
    "foo" : {
        "bar": true
    }
}

2.1. Create and Verify Grant

A Dynamic Client wants a Grant from the User using a Redirect Interaction:¶

+--------+                                  +-------+
| Client |                                  |  GS   |
|        |--(1)--- Create Grant ----------->|       |
|        |                                  |       |
|        |<--- Interaction Response ---(2)--|       |         +------+
|        |                                  |       |         | User |
|        |--(3)--- Interaction Transfer --- | - - - | ------->|      |
|        |                                  |       |         |      |
|        |                                  |       |<--(4)-->|      |
|        |                                  |       |  authN  |      |
|        |                                  |       |<--(5)-->|      |
|        |                                  |       |  authZ  |      |
|        |<--- Interaction Transfer ---(6)- | - - - | --------|      |
|        |                                  |       |         |      |
|        |--(7)--- Verify Grant ----------->|       |         +------+
|        |                                  |       |
|        |<--------- Grant Response ---(8)--|       |
|        |                                  |       |
+--------+                                  +-------+

1. Create Grant The Client creates a Request JSON document Section 4.6 and makes a Create Grant request (Section 4.1) by sending the JSON with an HTTP POST to the GS URI.¶
2. Interaction Response The GS determines that interaction with the User is required and sends an Interaction Response (Section 6.2) containing the Grant URI and an interaction object.¶
3. Interaction Transfer The Client redirects the User to the Redirect URI at the GS.¶
4. User Authentication The GS authenticates the User.¶
5. User Authorization If required, the GS interacts with the User to determine which identity claims and/or authorizations in the Grant Request are to be granted.¶
6. Interaction Transfer The GS redirects the User to the Completion URI at the Client, passing an Interaction Nonce.¶
7. Read Grant The Client creates a JSON document containing a verification object Section 4.6.7 and does a Verify Grant Section 4.2 request by HTTP PATCH with the document to the Grant URI.¶
8. Grant Response The GS responds with a Grant Response (Section 6.1).¶

2.2. Create and Read Grant - Redirect

A Registered Client wants a Grant from the User using a Redirect Interaction:¶

+--------+                                  +-------+
| Client |                                  |  GS   |
|        |--(1)--- Create Grant ----------->|       |
|        |                                  |       |
|        |<--- Interaction Response ---(2)--|       |
|        |                                  |       |
|        |--(3)--- Read Grant ------------->|       |         +------+
|        |                                  |       |         | User |
|        |--(4)--- Interaction Transfer --- | - - - | ------->|      |
|        |                                  |       |         |      |
|        |                                  |       |<--(5)-->|      |
|        |                                  |       |  authN  |      |
|        |                                  |       |<--(6)-->|      |
|        |                                  |       |  authZ  |      |
|        |<--------- Grant Response ---(7)--|       |         |      |
|        |                                  |       |         |      |
|        |<--- Interaction Transfer ---(8)- | - - - | --------|      |
|        |                                  |       |         |      |
+--------+                                  +-------+         +------+

1. Create Grant The Client makes a Create Grant request (Section 4.1) to the GS URI.¶
2. Interaction Response The GS determines that interaction with the User is required and sends an Interaction Response (Section 6.2) containing the Grant URI and an interaction object.¶
3. Read Grant The Client does an HTTP GET of the Grant URI (Section 4.3).¶
4. Interaction Transfer The Client transfers User interaction to the GS.¶
5. User Authentication The GS authenticates the User.¶
6. User Authorization If required, the GS interacts with the User to determine which identity claims and/or authorizations in the Grant Request are to be granted.¶
7. Grant Response The GS responds with a Grant Response (Section 6.1).¶
8. Interaction Transfer The GS redirects the User to the Completion URI of the Client. The Client verifies it is the same User that it transferred to the GS.¶

2.3. Create and Read Grant - Indirect

A Registered Client wants a Grant from the User using an Indirect Interaction:¶

+--------+                                  +-------+
| Client |                                  |  GS   |
|        |--(1)--- Create Grant ----------->|       |
|        |                                  |       |
|        |<--- Interaction Response ---(2)--|       |
|        |                                  |       |
|        |--(3)--- Read Grant ------------->|       |         +------+
|        |                                  |       |         | User |
|        |--(4)--- Interaction Transfer --- | - - - | ------->|      |
|        |                                  |       |         |      |
|        |                                  |       |<--(5)-->|      |
|        |                                  |       |  authN  |      |
|        |                                  |       |<--(6)-->|      |
|        |                                  |       |  authZ  |      |
|        |<--------- Grant Response ---(7)--|       |         |      |
+--------+                                  |       |         |      |
                                            |       |         |      |
+--------+                                  |       |         |      |
|  Info  |<--- Interaction Transfer ---(8)- | - - - | --------|      |
| Server |                                  |       |         |      |
+--------+                                  +-------+         +------+

The sequence is the same except:¶

• In step (4) the User either scans a bar code or uses a separate device to navigate to the Code URI and enters the User Code.¶
• In step (8) the GS redirects the User to the Information URI provided by the Client.¶

2.4. Reciprocal Grant

Party A and Party B are both a Client and a GS, and each Client would like a Grant for the other GS. The sequence starts off the same as in Section 2.2, but Party B makes a Create Grant Request before sending a Grant Response:¶

                Party A                                    Party B
               +--------+                                 +--------+
               | Client |                                 |   GS   |
               ~ ~ ~ ~ ~ ~     Same as steps 1 - 6 of    ~ ~ ~ ~ ~ ~
+------+       |        |   Create and Read Grant above   |        |
| User |       |        |                                 |        |
|      |       |   GS   |<--------- Create Grant ---(1)---| Client |
|      |       |        |                                 |        |
|      |       |        |<------- Grant Response ---(2)---|        |
|      |       |        |                                 |        |
|      |<----- | - - -  | -- Interaction Transfer --(3)---|        |
|      |       |        |                                 |        |
|      |<-(4)->|        |                                 |        |
|      | AuthZ |        |                                 |        |
+------+       |   GS   |--(5)--- Grant Response -------->| Client |
               |        |                                 |        |
               +--------+                                 +--------+

1. Create Grant Party B creates a Grant Request (Section 4.1) with user.reciprocal set to the Party B Grant URI that will be in the step (2) Grant Response, and sends it with an HTTP POST to the Party A GS URI. This enables Party A to link the reciprocal Grants.¶
2. Grant Response Party B responds to Party A's Create Grant Request with a Grant Response that includes the Party B Grant URI.¶
3. Interaction Transfer Party B redirects the User to the Completion URI at Party A.¶
4. User Authorization If required, Party A interacts with the User to determine which identity claims and/or authorizations in Party B's Create Grant Request are to be granted.¶
5. Grant Response Party A responds with a Grant Response (Section 6.1).¶

2.5. GS Initiated Grant

The User is at the GS, and wants to interact with a Registered Client. The GS can redirect the User to the Client:¶

+--------+                                  +-------+         +------+
| Client |                                  |  GS   |         | User |
|        |                                  |       |<--(1)-->|      |
|        |                                  |       |         |      |
|        |<----- GS Initiation Redirect --- | - - - | --(2)---|      |
|   (3)  |                                  |       |         |      |
| 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 4.3).¶
5. Grant Response The GS responds with a Grant Response (Section 6.1).¶

See Section 5 for more details.¶

2.6. Create and Update

The Client requests an identity claim to determine who the User is. Once the Client learns who the User is, and the Client updates the Grant for additional identity claims which the GS prompts the User for and returns to the Client. Once those are received, the Client updates the Grant with the remaining identity claims required.¶

+--------+                                  +-------+
| Client |                                  |  GS   |
|        |--(1)--- Create Grant ----------->|       |
|        |      interaction.keep:true       |       |
|        |                                  |       |
|        |<--- Interaction Response ---(2)--|       |
|        |                                  |       |
|        |--(3)--- Read Grant ------------->|       |         +------+
|        |                                  |       |         | User |
|        |--(4)--- Interaction Transfer --- | - - - | ------->|      |
|        |                                  |       |         |      |
|        |                                  |       |<--(5)-->|      |
|        |                                  |       |  authN  |      |
|        |<--------- Grant Response ---(6)--|       |         |      |
|  (7)   |                                  |       |         |      |
|  eval  |--(8)--- Update Grant ----------->|       |         |      |
|        |      interaction.keep:true       |       |<--(9)-->|      |
|        |                                  |       |  authZ  |      |
|        |<--------- Grant Response --(10)--|       |         |      |
|  (11)  |                                  |       |         |      |
|  eval  |--(12)-- Update Grant ----------->|       |         |      |
|        |  interaction.keep:false          |       |<--(13)->|      |
|        |                                  |       |  authZ  |      |
|        |                                  |       |         |      |
|        |<--- Interaction Transfer --(14)- | - - - | --------|      |
|        |                                  |       |         |      |
|        |<--------- Grant Response --(15)--|       |         +------+
|        |                                  |       |
+--------+                                  +-------+

1. Create Grant The Client creates a Grant Request (Section 4.1) including an identity claim and interaction.keep:true, and sends it with an HTTP POST to the GS GS URI.¶
2. Interaction Response The GS sends an Interaction Response (Section 6.2) containing the Grant URI, an interaction object, and interaction.keep:true.¶
3. Read Grant The Client does an HTTP GET of the Grant URI (Section 4.3).¶
4. Interaction Transfer The Client transfers User interaction to the GS.¶
5. User Authentication The GS authenticates the User.¶
6. Grant Response The GS responds with a Grant Response (Section 6.1) including the identity claim from User authentication and interaction.keep:true.¶
7. Grant Evaluation The Client queries its User database and does not find a User record matching the identity claim.¶
8. Update Grant The Client creates an Update Grant Request (Section 4.4) including the initial identity claims required and interaction.keep:true, and sends it with an HTTP PUT to the Grant URI.¶
9. User AuthN The GS interacts with the User to determine which identity claims in the Update Grant Request are to be granted.¶
10. Grant Response The GS responds with a Grant Response (Section 6.1) including the identity claims released by 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 4.4) 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 6.1) including the identity claims released by the User.¶

2.7. Create and Delete

The Client requests an identity claim to determine who the User is. Once the Client learns who the User is, and the Client knows it already has all the identity claims and authorizations needed for the User, the Client deletes the Grant which prompts the GS to transfer the interaction back to the Client. (If the Client did not already have what was needed, the Client would follow the Create and Update sequence Section 2.6 )¶

+--------+                                  +-------+
| Client |                                  |  GS   |
|        |--(1)--- Create Grant ----------->|       |
|        |      interaction.keep:true       |       |
|        |                                  |       |
|        |<--- Interaction Response ---(2)--|       |
|        |                                  |       |
|        |--(3)--- Read Grant ------------->|       |         +------+
|        |                                  |       |         | User |
|        |--(4)--- Interaction Transfer --- | - - - | ------->|      |
|        |                                  |       |         |      |
|        |                                  |       |<--(5)-->|      |
|        |                                  |       |  authN  |      |
|        |<--------- Grant Response ---(6)--|       |         |      |
|  (7)   |                                  |       |         |      |
|  eval  |--(8)--- Delete Grant ----------->|       |         |      |
|        |<------- Delete Response ---------|       |         |      |
|        |                                  |       |         |      |
|        |<--- Interaction Transfer ---(9)- | - - - | --------|      |
|        |                                  |       |         |      |
+--------+                                  +-------+         +------+

1. Create Grant The Client creates a Grant Request (Section 4.1) including an identity claim and interaction.keep:true, and sends it with an HTTP POST to the GS GS URI.¶
2. Interaction Response The GS sends an Interaction Response (Section 6.2) containing the Grant URI, an interaction object, and interaction.keep:true.¶
3. Read Grant The Client does an HTTP GET of the Grant URI (Section 4.3).¶
4. Interaction Transfer The Client transfers User interaction to the GS.¶
5. User Authentication The GS authenticates the User.¶
6. Grant Response The GS responds with a Grant Response (Section 6.1) including the identity claim from User authentication and interaction.keep:true.¶
7. Grant Evaluation The Client queries its User database and finds the User record matching the identity claim, and that no additional claims or authorizations are required.¶
8. Delete Grant The Client no longer needs the Grant and decides to Delete Grant (Section 4.5) by sending an HTTP DELETE to the Grant URI. If the GS responds with success the Grant no longer exists.¶

2.8. Create, Discover, and Delete

The Client wants to discover if the GS has a User with a given identifier. If not, it will abort the request and not transfer interaction to the GS.¶

+--------+                                  +-------+
| Client |                                  |  GS   |
|        |--(1)--- Create Grant ----------->|       |
|        |      user.exists:true            |       |
|        |                                  |       |
|        |<--- Interaction Response ---(2)--|       |
|        |         user.exists:false        |       |
|        |                                  |       |
|        |--(3)--- Delete Grant ----------->|       |
|        |<------- Delete Response ---------|       |
|        |                                  |       |
+--------+                                  +-------+

1. Create Grant The Client creates a Grant Request (Section 4.1) including an identity claim request, a User identifier, and user.exists:true. The Client sends it with an HTTP POST to the GS GS URI.¶
2. Interaction Response The GS sends an Interaction Response (Section 6.2) containing the Grant URI, an interaction object, and user.exists:false.¶
3. Delete Grant The Client determines the GS cannot fulfil its Grant Request, and decides to Delete Grant (Section 4.5) by sending an HTTP DELETE to the Grant URI. If the GS responds with success the Grant no longer exists.¶

2.9. Create and Wait

The Client wants access to resources that require the GS to interact with the RO, which may not happen immediately, so the GS instructs the Client to wait and check back later.¶

+--------+                                  +-------+
| Client |                                  |  GS   |
|        |--(1)--- Create Grant ----------->|       |
|        |                                  |       |
|        |<---------- Wait Response ---(2)--|       |         +------+
|  (3)   |                                  |       |         |  RO  |
|  Wait  |                                  |       |<--(4)-->|      |
|        |                                  |       |  AuthZ  |      |
|        |--(5)--- Read Grant ------------->|       |         +------+
|        |                                  |       |
|        |<--------- Grant Response --(6)---|       |
|        |                                  |       |
+--------+                                  +-------+

1. Create Grant The Client creates a Grant Request (Section 4.1) and sends it with an HTTP POST to the GS GS URI.¶
2. Wait Response The GS sends an Interaction Response (Section 6.3) containing the Grant URI and wait time.¶
3. Client Waits The Client waits the wait time.¶
4. RO AuthZ The GS interacts with the RO to determine which identity claims in the Grant Request are to be granted.¶
5. Read Grant The Client does an HTTP GET of the Grant URI (Section 4.3).¶
6. Grant Response The GS responds with a Grant Response (Section 6.1).¶

2.10. Read Grant

The Client wants to re-acquire the identity claims and authorizations in the Grant. No User or RO interaction is required as no new consent or authorization is required.¶

+--------+                                  +-------+
| Client |                                  |  GS   |
|        |--(1)--- Read Grant ------------->|       |
|        |                                  |       |
|        |<--------- Grant Response --(2)---|       |
|        |                                  |       |
+--------+                                  +-------+

1. Read Grant The Client does an HTTP GET of the Grant URI (Section 4.3).¶
2. Grant Response The GS responds with a Grant Response (Section 6.1) containing updated identity claims and authorizations.¶

2.11. Resource Server Access

The Client received an AZ URI from the GS. The Client acquires an access token, calls the RS, and later the access token expires. The Client then gets a fresh access token.¶

+--------+                                           +-------+
| Client |                                           |  GS   |
|        |--(1)--- Read AuthZ ---------------------->|       |
|        |<------- AuthZ Response -------------------|       |
|        |                                           |       |
|        |                             +----------+  |       |
|        |                             | Resource |  |       |
|        |--(2)--- Access Resource --->|  Server  |  |       |
|        |<------- Resource Response --|   (RS)   |  |       |
|        |                             |          |  |       |
|        |--(3)--- Access Resource --->|          |  |       |
|        |<------- Error Response -----|          |  |       |
|        |                             |          |  |       |
|        |                             +----------+  |       |
|        |                                           |       |
|        |--(4)--- Read AuthZ ---------------------->|       |
|        |<------- AuthZ Response -------------------|       |
|        |                                           |       |
+--------+                                           +-------+

1. Read AuthZ The Client makes a Read AuthZ (Section 4.7) with an HTTP GET to the AZ URI and receives an Response JSON "authorization" object (Section 6.4.4) with a fresh access token.¶
2. Resource Request The Client accesses the RS with the access token per Section 8 and receives a response from the RS.¶
3. Resource Request The Client attempts to access the RS, but receives an error indicating the access token has expired.¶
4. Read AuthZ The Client makes another Read AuthZ (Section 4.7) with an HTTP GET to the AZ URI and receives an Response JSON "authorization" object (Section 6.4.4) with a fresh access token.¶

2.12. GS API Table

[ 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.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 4.6:¶

• iat¶
• nonce¶
• uri set to the GS URI¶
• client¶

and MAY include the following from Request JSON Section 4.6¶

• user¶
• interaction¶
• authorization or authorizations¶
• claims¶

The GS MUST respond with one of Grant Response Section 6.1, Interaction Response Section 6.2, Wait Response Section 6.3, or one of the following errors:¶

• TBD¶

from Error Responses Section 9.¶

Following is a non-normative example where the Client is requesting identity claims about the User and read access to the User's contacts:¶

Example 1

{
    "iat"       : 15790460234,
    "uri"       : "https://as.example/endpoint",
    "nonce"     : "f6a60810-3d07-41ac-81e7-b958c0dd21e4",
    "client": {
        "display": {
            "name"  : "SPA Display Name",
            "uri"   : "https://spa.example/about"
        }
    },
    "interaction": {
        "redirect": {
            "redirect_uri"    : "https://web.example/return"
        },
        "global" : {
            "ui_locals" : "de"
        }
    },
    "authorization": {
        "type"      : "oauth_scope",
        "scope"     : "read_contacts"
    },
    "claims": {
        "oidc": {
            "id_token" : {
                "email"          : { "essential" : true },
                "email_verified" : { "essential" : true }
            },
            "userinfo" : {
                "name"           : { "essential" : true },
                "picture"        : null
            }
        }
    }
}

Following is a non-normative example where the Client is requesting 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

{
    "iat"       : 15790460234,
    "uri"       : "https://as.example/endpoint",
    "nonce"     : "5c9360a5-9065-4f7b-a330-5713909e06c6",
    "client": {
        "id"        : "di3872h34dkJW"
    },
    "interaction": {
        "indirect": {
            "completion_uri": "https://device.example/completion"
        },
        "user_code": {
            "completion_uri": "https://device.example/completion"
         }
    },
    "user": {
        "identifiers": {
            "email" : "jane.doe@example.com"
        },
        "exists"    : true
    },
    "claims"    : { "oidc": { "id_token" : {} } }
}

4.2. Verify Grant

The Client verifies a Grant by doing an HTTP PATCH of a JSON document to the corresponding Grant URI.¶

The JSON document MUST contain verification.nonce per Section 4.6.7. Following is a non-normative example:¶

{
    "verification": { "nonce":"55e8a90f-a563-426d-8c35-d6d8ed54afeb" }
}

The GS MUST respond with one of Grant Response Section 6.1 or one of the following errors:¶

• TBD¶

from Error Responses Section 9.¶

4.3. Read Grant

The Client reads a Grant by doing an HTTP GET of the corresponding Grant URI.¶

The GS MUST respond with one of Grant Response Section 6.1, Wait Response Section 6.3, or one of the following errors:¶

• TBD¶

from Error Responses Section 9.¶

4.4. Update Grant

The Client updates a Grant by doing an HTTP PUT of a JSON document to the corresponding Grant URI.¶

The JSON document MUST include the following from the Request JSON Section 4.6¶

• iat¶
• uri set to the Grant URI¶

and MAY include the following from Request JSON Section 4.6¶

• user¶
• interaction¶
• authorization or authorizations¶
• claims¶

The GS MUST respond with one of Grant Response Section 6.1, Interaction Response Section 6.2, Wait Response Section 6.3, or one of the following errors:¶

• TBD¶

from Error Responses Section 9.¶

Following is a non-normative example where the Client made an interaction.keep:true request, and now wants to update the request with additional claims:¶

Example 3

{
    "iat"       : 15790460234,
    "uri"       : "https://as.example/endpoint/grant/example3",
    "claims": {
        "oidc": {
            "userinfo" : {
                "email"          : { "essential" : true },
                "name"           : { "essential" : true },
                "picture"        : null
            }
        }
    }
}

4.5. Delete Grant

The Client deletes a Grant by doing an HTTP DELETE of the corresponding Grant URI.¶

The GS MUST respond with OK 200, or one of the following errors:¶

• TBD¶

from Error Responses Section 9.¶

4.6. Request JSON

[Editor: do we want to reuse the JWT claims "iat", "jti", etc.? ]¶

• iat - the time of the request as a NumericDate.¶
• nonce - a unique identifier for this request. Note the Grant Response MUST contain a matching nonce attribute value.¶
• uri - the GS URI if in a Create Grant Section 4.1, or the Grant URI if in an Update Grant Section 4.4.¶

4.7. Read Authorization

The Client acquires an Authorization by doing an HTTP GET to the corresponding AZ URI.¶

The GS MUST respond with a Authorization JSON document Section 6.5, or one of the following errors:¶

• TBD¶

from Error Responses Section 9.¶

4.8. Update Authorization

The Client updates an Authorization by doing an HTTP PUT to the corresponding AZ URI of the following JSON. All of the following MUST be included.¶

• iat - the time of the response as a NumericDate.¶
• uri - the AZ URI.¶
• authorization - the new authorization requested per the Request JSON "authorization" object Section 4.6.4.¶

The GS MUST respond with a Authorization JSON document Section 6.5, or one of the following errors:¶

• TBD¶

from Error Responses Section 9.¶

4.9. Delete Authorization

The Client deletes an Authorization by doing an HTTP DELETE to the corresponding AZ URI.¶

The GS MUST respond with OK 200, or one of the following errors:¶

• TBD¶

from Error Responses Section 9.¶

4.10. GS Options

The Client can get the metadata for the GS by doing an HTTP OPTIONS of the corresponding GS URI. This is the only API where the GS MAY respond to an unauthenticated request.¶

The GS MUST respond with the the following JSON document:¶

[Editor: this section is a work in progress]¶

• uri - the GS URI.¶
• client_authentication - an array of the Client Authentication mechanisms supported by the GS¶
• interactions - an array of the interaction modes supported by the GS.¶

• authorization - an object containing the authorizations the Client may request from the GS, if any.¶

  • Details TBD¶

• claims - an object containing the identity claims the Client may request from the GS, if any, and what public keys the claims will be signed with.¶

  • Details TBD¶
• algorithms - a list of the cryptographic algorithms supported by the GS.¶

• features - an object containing feature support¶

  • user_exists - boolean indicating if user.exists is supported.¶
  • authorizations - boolean indicating if a request for more than one authorization in a request is supported.¶

[Editor: keys used by Client to encrypt requests, or verify signed responses?]¶

[Editor: namespace metadata for extensions?]¶

or one of the following errors:¶

• TBD¶

from Error Responses Section 9.¶

4.11. Grant Options

The Client can get the metadata for the Grant by doing an HTTP OPTIONS of the corresponding Grant URI.¶

The GS MUST respond with the the following JSON document:¶

• verbs - an array of the HTTP verbs supported at the GS URI.¶

or one of the following errors:¶

• TBD¶

from Error Responses Section 9.¶

4.12. AuthZ Options

The Client can get the metadata for the AuthZ by doing an HTTP OPTIONS of the corresponding AZ URI.¶

The GS MUST respond with the the following JSON document:¶

• verbs - an array of the HTTP verbs supported at the GS URI.¶

or one of the following errors:¶

• TBD¶

from Error Responses Section 9.¶

4.13. Request Verification

On receipt of a request, the GS MUST verify the following:¶

• TBD¶

6.1. Grant Response

The Grant Response MUST include the following from the Response JSON Section 6.4¶

• iat¶
• nonce¶
• uri¶

and MAY include the following from the Response JSON Section 6.4¶

• client.handle¶
• authorization or authorizations¶
• claims¶
• expires_in¶

Example non-normative Grant Response JSON document for Example 1 in Section 4.1:¶

{
    "iat"           : 15790460234,
    "nonce"         : "f6a60810-3d07-41ac-81e7-b958c0dd21e4",
    "uri"           : "https://as.example/endpoint/grant/example1",
    "expires_in"    : 300
    "authorization": {
        "type"          : "oauth_scope",
        "scope"         : "read_contacts",
        "expires_in"    : 3600,
        "mechanism"     : "bearer",
        "token"         : "eyJJ2D6.example.access.token.mZf9p"
    },
    "claims": {
        "oidc": {
            "id_token"      : "eyJhbUzI1N.example.id.token.YRw5DFdbW",
            "userinfo" : {
                "name"      : "John Doe",
                "picture"   : "https://photos.example/p/eyJzdkiO"
            }
        }
    }
}

Example non-normative Grant Response JSON document for Example 2 in Section 4.1:¶

{
    "iat"   : 15790460234,
    "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6",
    "uri"   : "https://as.example/endpoint/grant/example2",
    "authorization": {
        "uri"   : "https://as.example/endpoint/authz/example2"
    }
}

6.2. Interaction Response

The Interaction Response MUST include the following from the Response JSON Section 6.4¶

• iat¶
• nonce¶
• uri¶
• interaction¶

and MAY include the following from the Response JSON Section 6.4¶

• user¶
• wait¶

A non-normative example of an Interaction Response follows:¶

{
    "iat"       : 15790460234,
    "nonce"     : "0d1998d8-fbfa-4879-b942-85a88bff1f3b",
    "uri"       : "https://as.example/endpoint/grant/example4",
    "interaction" : {
        ""redirect" : {
            "authorization_uri"     : "https://as.example/i/example4"
        }
    },
    "user": {
        "exists" : true
    }
}

6.3. Wait Response

The Wait Response MUST include the following from the Response JSON Section 6.4¶

• iat¶
• nonce¶
• uri¶
• wait¶

A non-normative example of Wait Response follows:¶

{
    "iat"       : 15790460234,
    "nonce"     : "0d1998d8-fbfa-4879-b942-85a88bff1f3b",
    "uri"       : "https://as.example/endpoint/grant/example5",
    "wait"      : 300
}

6.4. Response JSON

Details of the JSON document:¶

• iat - the time of the response as a NumericDate.¶
• nonce - the nonce that was included in the Request JSON Section 4.6.¶
• uri - the Grant URI.¶
• wait - a numeric value representing the number of seconds the Client should want before making a Read Grant request to the Grant URI.¶
• expires_in - a numeric value specifying how many seconds until the Grant expires. This attribute is OPTIONAL.¶

6.5. Authorization JSON

The Authorization JSON is a response to a Read AuthZ request by the Client Section 4.7. A subset of the Authorization JSON is included in the "authorization" object Section 4.6.4 and "authorizations" list members Section 6.4.5.¶

• type - the type of claim request: "oauth_scope" or "oauth_rich". See the "type" object in Section 4.6.4 for details. This attribute is REQUIRED.¶
• scope - the scopes the Client was granted authorization for. This will be all, or a subset, of what was requested. This attribute is OPTIONAL.¶
• authorization_details - the authorization details granted per [RAR]. Included if type is "oauth_rich".¶
• mechanism - one of the access mechanisms: "bearer", "jose", or "jose+body". See Section 8 for details. This attribute is REQUIRED.¶
• token - the access token for accessing an RS. This attribute is REQUIRED.¶
• expires_in - a numeric value specifying how many seconds until the access token expires. This attribute is OPTIONAL.¶
• certificate - MUST be included if the mechanism is "jose" or "jose+body". Contains the jwk header values for the Client to include in the JWS header when calling the RS using the "jose" or "jose+body" mechanisms. See Section 10.2.1.¶
• uri - the AZ URI. Used to refresh an authorization. This attribute is OPTIONAL.¶

[Editor: would an optional expiry for the Authorization be useful?]¶

The following is a non-normative example of an Authorization JSON document:¶

{
    "type"          : "oauth_scope",
    "scope"         : "read_calendar write_calendar",
    "mechanism"     : "jose",
    "token"         : "eyJJ2D6.example.access.token.mZf9p"
    "expires_in"    : 3600,
    "certificate": {
        "x5u"   : "https://as.example/cert/example2"
    },
    "uri"       : "https://as.example/endpoint/authz/example2"
}

6.6. Response Verification

On receipt of a response, the Client MUST verify the following:¶

• TBD¶

7.1. "redirect" mode

A Redirect Interaction is characterized by the Client redirecting the User's browser to the GS, the GS interacting with the User, and then GS redirecting the User's browser back to the Client. The GS correlates the Grant Request with the unique authorization_uri, and the Client correlates the Grant Request with the unique redirect_uri.¶

7.2. "indirect" mode

An Indirect Interaction is characterized by the Client causing the User's browser to load the short_uri at GS, the GS interacting with the User, and then the GS MAY optionally redirecting the User's Browser to a completion_uri. There is no mechanism for the GS to redirect the User's browser back to the Client. Examples of how the Client may initiate the interaction are encoding the short_uri as a code scannable by the User's mobile device, or launching a system browser from a command line interface (CLI) application.¶

The "indirect" mode is susceptible to session fixation attacks. See TBD in the Security Considerations for details.¶

7.3. "user_code" mode

An Indirect Interaction is characterized by the Client displaying a code and a URI for the User to load in a browser and then enter the code.¶

8.1. Bearer Token

If the access mechanism is "bearer", then the Client accesses the RS per Section 2.1 of [RFC6750]¶

A non-normative example of the HTTP request headers follows:¶

GET /calendar HTTP/2
Host: calendar.example
Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA

10.1. GS Access

The Client authenticates to the GS by passing either a signed header parameter, or a signed message body. The following table shows the verb, uri and token location for each Client request to the GS:¶

{
    "iat"   : 15790460234,
    "jti"   : "f6d72254-4f23-417f-b55e-14ad323b1dc1",
    "uri"   : "https://as.example/endpoint/grant/example6",
    "verb"  : "GET"
}

GET /endpoint/example.grant HTTP/2
Host: as.example
Authorization: jose eyJhbGciOiJIUzI1NiIsIn ...

POST /endpoint HTTP/2
Host: as.example
Content-Type: application/jose
Content-Length: 155

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyzdWIiOiIxMjM0NTY3ODkwIiwibmF
tZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMe
Jf36POk6yJV_adQssw5c

{
    "alg"   : "ES256",
    "typ"   : "JOSE",
    "kid"   : "12"
}

{
    "alg"   : "ES256",
    "typ"   : "JOSE",
    "jwk"   : {
        "kty"   : "EC",
        "crv"   : "P-256",
        "x"     : "Kgl5DJSgLyV-G32osmLhFKxJ97FoMW0dZVEqDG-Cwo4",
        "y"     : "GsL4mOM4x2e6iON8BHvRDQ6AgXAPnw0m0SfdlREV7i4"
    }
}

10.2. RS Access

In the "jose" mechanism Section 10.2.2, all Client requests to the RS include a proof-of-possession token in the HTTP authorization header. In the "jose+body" mechanism Section 10.2.3, the Client signs the JSON document in the request if the POST or PUT verbs are used, otherwise it is the same as the "jose" mechanism.¶

{
    "alg"   : "ES256",
    "typ"   : "JOSE",
    "x5u"   : "https://as.example/cert/example2"
}

{
    "iat"   : 15790460234,
    "jti"   : "f6d72254-4f23-417f-b55e-14ad323b1dc1",
    "uri"   : "https://calendar.example/calendar",
    "verb"  : "GET",
    "token" : "eyJJ2D6.example.access.token.mZf9pTSpA"
}

GET /calendar HTTP/2
Host: calendar.example
Authorization: jose eyJhbG.example.jose.token.adks

{
    "iat"   : 15790460234,
    "jti"   : "f6d72254-4f23-417f-b55e-14ad323b1dc1",
    "uri"   : "https://calendar.example/calendar",
    "verb"  : "POST",
    "token" : "eyJJ2D6.example.access.token.mZf9pTSpA",
    "payload" : {
        "event" : {
            "title"             : "meeting with joe",
            "start_date_utc"    : "2020-02-21 11:00:00",
            "end_date_utc"      : "2020-02-21 11:00:00"
        }
    }
}

POST /calendar HTTP/2
Host: calendar.example
Content-Type: application/jose
Content-Length: 155

eyJhbGciOi.example.jose+body.adasdQssw5c

10.3. Request Encryption

[Editor: to be fleshed out]¶

The Client encrypts a request when ??? using the GS public key returned as the ??? attribute in GS Options Section 4.10.¶

10.4. Response Signing

[Editor: to be fleshed out]¶

The Client verifies a signed response ??? using the GS public key returned as the ??? attribute in GS Options Section 4.10.¶

10.5. Response Encryption

[Editor: to be fleshed out]¶

The Client decrypts a response when ??? using the private key matching the public key included in the request as the ??? attribute in Section 4.6.¶

A.1. draft-hardt-xauth-protocol-00

• Initial version¶

A.2. draft-hardt-xauth-protocol-01

• text clean up¶
• added OIDC4IA claims¶
• added "jws" method for accessing a resource.¶
• renamed Initiation Request -> Grant Request¶
• renamed Initiation Response -> Interaction Response¶
• renamed Completion Request -> Authorization Request¶
• renamed Completion Response -> Grant Request¶
• renamed completion handle -> authorization handle¶
• added Authentication Request, Authentication Response, authentication handle¶

A.3. draft-hardt-xauth-protocol-02

• major rewrite¶
• handles are now URIs¶
• the collection of claims and authorizations are a Grant¶
• an Authorization is its own type¶
• lots of sequences added¶

A.4. draft-hardt-xauth-protocol-03

• fixed RO definition¶
• improved language in Rationals¶
• added user code interaction method, and aligned qrcode interaction method¶
• added completion_uri for code flows¶

A.5. draft-hardt-xauth-protocol-04

• renamed interaction uris to have purpose specific names¶

A.6. draft-hardt-xauth-protocol-05

• separated claims from identifiers in request user object¶
• simplified reciprocal grant flow¶
• reduced interactions to redirect and indirect¶
• simplified interaction parameters¶
• added in language for Client to verify interaction completion¶
• added Verify Grant API and Interaction Nonce¶
• replaced Refresh AuthZ with Read AuthZ. Read and refresh are same operation.¶

A.7. draft-hardt-xauth-protocol-06

• fixup examples to match specification¶

A.8. draft-hardt-xauth-protocol-07

• refactored interaction request and response syntax, and enabled interaction mode negotiation¶
• generation of client handle by GS for dynamic clients¶
• renamed title to Grant Negotiation and Authorization Protocol. Preserved draft-hardt-xauth-protocol filename to ease tracking changes.¶
• changed Authorizations to be key / value pairs (aka dictionary) instead of a JSON array¶