Grant Negotiation and Authorization Protocol

1.1. Roles

The parties in the GNAP protocol perform actions under different roles. Roles are defined by the actions taken and the expectations leveraged on the role by the overall protocol.¶

Authorization Server (AS)

Manages the requested delegations for the RO. The AS issues tokens and directly delegated information to the RC. The AS is defined by its grant endpoint, a single URL that accepts a POST request with a JSON payload. The AS could also have other endpoints, including interaction endpoints and user code endpoints, and these are introduced to the RC as needed during the delegation process.¶

Resource Client (RC, aka "client")

Requests tokens from the AS and uses tokens at the RS. An instance of the RC software is identified by its key, which can be known to the AS prior to the first request. The AS determines which policies apply to a given RC, including what it can request and on whose behalf.¶

Resource Server (RS, aka "API")

Accepts tokens from the RC issued by the AS and serves delegated resources on behalf of the RO. There could be multiple RSs protected by the AS that the RC will call.¶

Resource Owner (RO)

Authorizes the request from the RC to the RS, often interactively at the AS.¶

Requesting Party (RQ, aka "user")

Operates and interacts with the RC.¶

The GNAP protocol design does not assume any one deployment architecture, but instead attempts to define roles that can be fulfilled in a number of different ways for different use cases. As long as a given role fulfills all of its obligations and behaviors as defined by the protocol, GNAP does not make additional requirements on its structure or setup.¶

Multiple roles can be fulfilled by the same party, and a given party can switch roles in different instances of the protocol. For example, the RO and RQ in many instances are the same person, where a user is authorizing the RC to act on their own behalf at the RS. In this case, one party fulfills both of the RO and RQ roles, but the roles themselves are still defined separately from each other to allow for other use cases where they are fulfilled by different parties.¶

For another example, in some complex scenarios, an RS receiving requests from one RC can act as an RC for a downstream secondary RS in order to fulfill the original request. In this case, one piece of software is both an RS and an RC from different perspectives, and it fulfills these roles separately as far as the overall protocol is concerned.¶

A single role need not be deployed as a monolithic service. For example, An RC could have components that are installed on the RQ's device as well as a back-end system that it communicates with. If both of these components participate in the delegation protocol, they are both considered part of the RC.¶

For another example, an AS could likewise be built out of many constituent components in a distributed architecture. The component that the RC calls directly could be different from the component that the the RO interacts with to drive consent, since API calls and user interaction have different security considerations in many environments. Furthermore, the AS could need to collect identity claims about the RO from one system that deals with user attributes while generating access tokens at another system that deals with security rights. From the perspective of GNAP, all of these are pieces of the AS and together fulfill the role of the AS as defined by the protocol.¶

[[ Editor's note: The names for the roles are an area of ongoing discussion within the working group, as is the appropriate precision of what activities and expectations a particular role covers. In particular, the AS might be formally decomposed into delegation components, that the client talks to, and interaction components, that the user talks to. Several alternative names have been proposed for different roles and components, including:¶

• Grant Server (for Authorization Server)¶
• Grant Client (for Resource Client)¶
• Operator (for Requesting Party)¶

]]¶

1.2. Elements

In addition to the roles above, the protocol also involves several elements that are acted upon by the roles throughout the process.¶

Access Token

A credential representing a set of access rights delegated to the RC. The access token is created by the AS, consumed and verified by the RS, and issued to and carried by the RC. The contents and format of the access token are opaque to the RC.¶

Grant

The process by which a the RC requests and is given delegated access to the RS by the AS through the authority of the RO.¶

Key

A cryptographic element binding a request to the holder of the key. Access tokens and RC instances can be associated with specific keys.¶

Resource

A protected API served by the RS and accessed by the RC. Access to this resource is delegated by the RO as part of the grant process.¶

Subject Information

Information about the RO that is returned directly to the RC from the AS without the RC making a separate call to an RS. Access to this information is delegated by the RO as part of the grant process.¶

[[ Editor's note: What other core elements need an introduction here? These aren't roles to be taken on by different parties, nor are they descriptions of the possible configurations of parties, but these are still important moving parts within the protocol. ]]¶

1.3. Sequences

The GNAP protocol can be used in a variety of ways to allow the core delegation process to take place. Many portions of this process are conditionally present depending on the context of the deployments, and not every step in this overview will happen in all circumstances.¶

Note that a connection between roles in this process does not necessarily indicate that a specific protocol message is sent across the wire between the components fulfilling the roles in question, or that a particular step is required every time. For example, for an RC interested in only getting subject information directly, and not calling an RS, all steps involving the RS below do not apply.¶

In some circumstances, the information needed at a given stage is communicated out-of-band or is pre-configured between the components or entities performing the roles. For example, one entity can fulfil multiple roles, and so explicit communication between the roles is not necessary within the protocol flow.¶

        +------------+             +------------+
        | Requesting | ~ ~ ~ ~ ~ ~ |  Resource  |
        | Party (RQ) |             | Owner (RO) |
        +------------+             +------------+
            +                            +
            +                            +
           (A)                          (B)
            +                            +
            +                            +
        +--------+                       +       +------------+
        |Resource|--------------(1)------+------>|  Resource  |
        | Client |                       +       |   Server   |
        |  (RC)  |       +---------------+       |    (RS)    |
        |        |--(2)->| Authorization |       |            |
        |        |<-(3)--|     Server    |       |            |
        |        |       |      (AS)     |       |            |
        |        |--(4)->|               |       |            |
        |        |<-(5)--|               |       |            |
        |        |--------------(6)------------->|            |
        |        |       |               |<~(7)~~|            |
        |        |<-------------(8)------------->|            |
        |        |--(9)->|               |       |            |
        |        |<-(10)-|               |       |            |
        |        |--------------(11)------------>|            |
        |        |       |               |<~(12)~|            |
        |        |-(13)->|               |       |            |
        |        |       |               |       |            |
        +--------+       +---------------+       +------------+

    Legend
    + + + indicates a possible interaction with a human
    ----- indicates an interaction between protocol roles
    ~ ~ ~ indicates a potential equivalence or out-of-band communication between roles

• (A) The RQ interacts with the RC to indicate a need for resources on behalf of the RO. This could identify the RS the RC needs to call, the resources needed, or the RO that is needed to approve the request. Note that the RO and RQ are often the same entity in practice.¶
• (1) The RC attempts to call the RS (Section 10.4) to determine what access is needed. The RS informs the RC that access can be granted through the AS. Note that for most situations, the RC already knows which AS to talk to and which kinds of access it needs.¶
• (2) The RC requests access at the AS (Section 2).¶
• (3) The AS processes the request and determines what is needed to fulfill the request. The AS sends its response to the RC (Section 3).¶
• (B) If interaction is required, the AS interacts with the RO (Section 4) to gather authorization. The interactive component of the AS can function using a variety of possible mechanisms including web page redirects, applications, challenge/response protocols, or other methods. The RO approves the request for the RC being operated by the RQ. Note that the RO and RQ are often the same entity in practice.¶
• (4) The RC continues the grant at the AS (Section 5).¶
• (5) If the AS determines that access can be granted, it returns a response to the RC (Section 3) including an access token (Section 3.2) for calling the RS and any directly returned information (Section 3.4) about the RO.¶
• (6) The RC uses the access token (Section 7) to call the RS.¶
• (7) The RS determines if the token is sufficient for the request by examining the token, potentially calling the AS (Section 10.1). Note that the RS could also examine the token directly, call an internal data store, execute a policy engine request, or any number of alternative methods for validating the token and its fitness for the request.¶
• (8) The RC to call the RS (Section 7) using the access token until the RS or RC determine that the token is no longer valid.¶
• (9) When the token no longer works, the RC fetches an updated access token (Section 6.1) based on the rights granted in (5).¶
• (10) The AS issues a new access token (Section 3.2) to the RC.¶
• (11) The RC uses the new access token (Section 7) to call the RS.¶
• (12) The RS determines if the new token is sufficient for the request by examining the token, potentially calling the AS (Section 10.1).¶
• (13) The RC disposes of the token (Section 6.2) once the RC has completed its access of the RS and no longer needs the token.¶

The following sections and Appendix C contain specific guidance on how to use the GNAP protocol in different situations and deployments.¶

    +--------+                                  +--------+         +------+
    |   RC   |                                  |   AS   |         |  RO  |
    |        |                                  |        |         |  +   |
    |        |< (1) + Start Session + + + + + + + + + + + + + + + +|  RQ  |
    |        |                                  |        |         |(User)|
    |        |--(2)--- Request Access --------->|        |         |      |
    |        |                                  |        |         |      |
    |        |<-(3)-- Interaction Needed -------|        |         |      |
    |        |                                  |        |         |      |
    |        |+ (4) + Redirect for Interaction + + + + + + + + + > |      |
    |        |                                  |        |         |      |
    |        |                                  |        |<+ (5) +>|      |
    |        |                                  |        |  AuthN  |      |
    |        |                                  |        |         |      |
    |        |                                  |        |<+ (6) +>|      |
    |        |                                  |        |  AuthZ  |      |
    |        |                                  |        |         |      |
    |        |< (7) + Redirect for Continuation + + + + + + + + + +|      |
    |        |                                  |        |         +------+
    |        |--(8)--- Continue Request ------->|        |
    |        |                                  |        |
    |        |<-(9)----- Grant Access ----------|        |
    |        |                                  |        |
    +--------+                                  +--------+

    +--------+                                  +--------+         +------+
    |   RC   |                                  |   AS   |         |  RO  |
    |        |--(1)--- Request Access --------->|        |         |  +   |
    |        |                                  |        |         |  RQ  |
    |        |<-(2)-- Interaction Needed -------|        |         |(User)|
    |        |                                  |        |         |      |
    |        |+ (3) + + Display User Code + + + + + + + + + + + + >|      |
    |        |                                  |        |         |      |
    |        |                                  |        |<+ (4) + |      |
    |        |                                  |        |Open URI |      |
    |        |                                  |        |         |      |
    |        |                                  |        |<+ (5) +>|      |
    |        |                                  |        |  AuthN  |      |
    |        |--(9)--- Continue Request (A) --->|        |         |      |
    |        |                                  |        |<+ (6) +>|      |
    |        |<-(10)- Not Yet Granted (Wait) ---|        |  Code   |      |
    |        |                                  |        |         |      |
    |        |                                  |        |<+ (7) +>|      |
    |        |                                  |        |  AuthZ  |      |
    |        |                                  |        |         |      |
    |        |                                  |        |<+ (8) +>|      |
    |        |                                  |        |Completed|      |
    |        |                                  |        |         |      |
    |        |--(11)-- Continue Request (B) --->|        |         +------+
    |        |                                  |        |
    |        |<-(12)----- Grant Access ---------|        |
    |        |                                  |        |
    +--------+                                  +--------+

    +--------+                                  +--------+         +------+
    |   RC   |                                  |   AS   |         |  RO  |
    |        |--(1)--- Request Access --------->|        |         |      |
    |        |                                  |        |         |      |
    |        |<-(2)-- Not Yet Granted (Wait) ---|        |         |      |
    |        |                                  |        |<+ (3) +>|      |
    |        |                                  |        |  AuthN  |      |
    |        |--(6)--- Continue Request (A) --->|        |         |      |
    |        |                                  |        |<+ (4) +>|      |
    |        |<-(7)-- Not Yet Granted (Wait) ---|        |  AuthZ  |      |
    |        |                                  |        |         |      |
    |        |                                  |        |<+ (5) +>|      |
    |        |                                  |        |Completed|      |
    |        |                                  |        |         |      |
    |        |--(8)--- Continue Request (B) --->|        |         +------+
    |        |                                  |        |
    |        |<-(9)------ Grant Access ---------|        |
    |        |                                  |        |
    +--------+                                  +--------+

    +--------+                                  +--------+
    |   RC   |                                  |   AS   |
    |        |--(1)--- Request Access --------->|        |
    |        |                                  |        |
    |        |<-(2)---- Grant Access -----------|        |
    |        |                                  |        |
    +--------+                                  +--------+

    +--------+                                          +--------+
    |   RC   |                                          |   AS   |
    |        |--(1)--- Request Access ----------------->|        |
    |        |                                          |        |
    |        |<-(2)--- Grant Access --------------------|        |
    |        |                                          |        |
    |        |                             +--------+   |        |
    |        |--(3)--- Access Resource --->|   RS   |   |        |
    |        |                             |        |   |        |
    |        |<-(4)--- Error Response -----|        |   |        |
    |        |                             +--------+   |        |
    |        |                                          |        |
    |        |--(5)--- Rotate Token ------------------->|        |
    |        |                                          |        |
    |        |<-(6)--- Rotated Token -------------------|        |
    |        |                                          |        |
    +--------+                                          +--------+

2.1. Requesting Resources

If the RC is requesting one or more access tokens for the purpose of accessing an API, the RC MUST include a resources field. This field MUST be an array (for a single access token (Section 2.1.1)) or an object (for multiple access tokens (Section 2.1.3)), as described in the following sections.¶

    "resources": [
        {
            "type": "photo-api",
            "actions": [
                "read",
                "write",
                "dolphin"
            ],
            "locations": [
                "https://server.example.net/",
                "https://resource.local/other"
            ],
            "datatypes": [
                "metadata",
                "images"
            ]
        },
        {
            "type": "financial-transaction",
            "actions": [
                "withdraw"
            ],
            "identifier": "account-14-32-32-3",
            "currency": "USD"
        }
    ]

    "resources": [
        "read", "dolphin-metadata", "some other thing"
    ]

    "resources": [
        {
            "type": "photo-api",
            "actions": [
                "read",
                "write",
                "dolphin"
            ],
            "locations": [
                "https://server.example.net/",
                "https://resource.local/other"
            ],
            "datatypes": [
                "metadata",
                "images"
            ]
        },
        "read",
        "dolphin-metadata",
        {
            "type": "financial-transaction",
            "actions": [
                "withdraw"
            ],
            "identifier": "account-14-32-32-3",
            "currency": "USD"
        },
        "some other thing"
    ]

    "resources": {
        "token1": [
          {
              "type": "photo-api",
              "actions": [
                  "read",
                  "write",
                  "dolphin"
              ],
              "locations": [
                  "https://server.example.net/",
                  "https://resource.local/other"
              ],
              "datatypes": [
                  "metadata",
                  "images"
              ]
          },
          "dolphin-metadata"
      ],
      "token2": [
            {
                "type": "walrus-access",
                "actions": [
                    "foo",
                    "bar"
                ],
                "locations": [
                    "https://resource.other/"
                ],
                "datatypes": [
                    "data",
                    "pictures",
                    "walrus whiskers"
                ]
            }
        ]
    }

    "resources": [
        {
            "type": "photo-api",
            "actions": [
                "read",
                "write",
                "dolphin"
            ],
            "locations": [
                "https://server.example.net/",
                "https://resource.local/other"
            ],
            "datatypes": [
                "metadata",
                "images"
            ]
        },
        "read",
        "bind_token",
        "multi_token"
    ]

resources: [
    {
        type: "gnap-flags",
        flag1: true,
        flag2: false,
        flag3: true ...
    },
    "reference1",
    "scope2", ...
]

resources: [
    "reference1",
    "scope2",
    ["flag1", "flag2", "flag3"] ...
]

2.2. Requesting User Information

If the RC is requesting information about the RO from the AS, it sends a subject field as a JSON object. This object MAY contain the following fields (or additional fields defined in a registry TBD (Section 12)).¶

sub_ids

An array of subject identifier subject types requested for the RO, as defined by [I-D.ietf-secevent-subject-identifiers].¶

assertions

An array of requested assertion formats. Possible values include id_token for an [OIDC] ID Token and saml2 for a SAML 2 assertion. Additional assertion values are defined by a registry TBD (Section 12). [[ Editor's note: These values are lifted from [RFC8693]'s "token type identifiers" list, but is there a better source?]]¶

"subject": {
   "sub_ids": [ "iss-sub", "email" ],
   "assertions": [ "id_token", "saml2" ]
}

The AS can determine the RO's identity and permission for releasing this information through interaction with the RO (Section 4), AS policies, or assertions presented by the RC (Section 2.4). If this is determined positively, the AS MAY return the RO's information in its response (Section 3.4) as requested.¶

Subject identifiers requested by the RC serve only to identify the RO in the context of the AS and can't be used as communication channels by the RC, as discussed in Section 3.4. One method of requesting communication channels and other identity claims are discussed in Section 2.8.¶

The AS SHOULD NOT re-use subject identifiers for multiple different ROs.¶

[[ Editor's Note: What we're really saying here is that "even if the AS gives you an email address to identify the user, that isn't a claim that this is a valid email address for that current user, so don't try to email them." In order to get a workable email address, or anything that you can use to contact them, you'd need a full identity protocol and not just this. Also, subject identifiers are asserted by the AS and therefore naturally scoped to the AS. Would changing the name to "as_sub_ids" or "local_sub_ids" help convey that point? ]]¶

Note: the "sub_ids" and "assertions" request fields are independent of each other, and a returned assertion MAY omit a requested subject identifier.¶

[[ Editor's note: we're potentially conflating these two types in the same structure, so perhaps these should be split. There's also a difference between user information and authentication event information. ]]¶

2.3. Identifying the RC

When sending a non-continuation request to the AS, the RC MUST identify itself by including the client field of the request and by signing the request as described in Section 8. Note that for a continuation request (Section 5), the RC instance is identified by its association with the request being continued and so this field is not sent under those circumstances.¶

When RC information is sent by value, the client field of the request consists of a JSON object with the following fields.¶

key

The public key of the RC to be used in this request as described in Section 2.3.2. This field is REQUIRED.¶

class_id

An identifier string that the AS can use to identify the software comprising this instance of the RC. The contents and format of this field are up to the AS. This field is OPTIONAL.¶

display

An object containing additional information that the AS MAY display to the RO during interaction, authorization, and management. This field is OPTIONAL.¶

"client": {
    "key": {
        "proof": "httpsig",
        "jwk": {
                    "kty": "RSA",
                    "e": "AQAB",
                    "kid": "xyz-1",
                    "alg": "RS256",
                    "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..."
        },
        "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..."
    },
    "class_id": "web-server-1234",
    "display": {
        "name": "My Client Display Name",
        "uri": "https://example.net/client"
    }
}

Additional fields are defined in a registry TBD (Section 12).¶

The RC MUST prove possession of any presented key by the proof mechanism associated with the key in the request. Proof types are defined in a registry TBD (Section 12) and an initial set of methods is described in Section 8.¶

Note that the AS MAY know the RC's public key ahead of time, and the AS MAY apply different policies to the request depending on what has been registered against that key. If the same public key is sent by value on subsequent access requests, the AS SHOULD treat these requests as coming from the same RC software instance for purposes of identification, authentication, and policy application. If the AS does not know the RC's public key ahead of time, the AS MAY accept or reject the request based on AS policy, attestations within the client request, and other mechanisms.¶

[[ Editor's note: additional client attestation frameworks will eventually need to be addressed here. For example, the organization the client represents, or a family of client software deployed in a cluster, or the posture of the device the client is installed on. These all need to be separable from the client's key and potentially the instance identifier. ]]¶

"client": {
    "instance_id": "client-541-ab"
}

"client": "client-541-ab"

    "key": {
        "proof": "jwsd",
        "jwk": {
                    "kty": "RSA",
                    "e": "AQAB",
                    "kid": "xyz-1",
                    "alg": "RS256",
                    "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..."
        },
        "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..."
    }

    "display": {
        "name": "My Client Display Name",
        "uri": "https://example.net/client"
    }

2.4. Identifying the User

If the RC knows the identity of the RQ through one or more identifiers or assertions, the RC MAY send that information to the AS in the "user" field. The RC MAY pass this information by value or by reference.¶

sub_ids

An array of subject identifiers for the RQ, as defined by [I-D.ietf-secevent-subject-identifiers].¶

assertions

An object containing assertions as values keyed on the assertion type defined by a registry TBD (Section 12). Possible keys include id_token for an [OIDC] ID Token and saml2 for a SAML 2 assertion. Additional assertion values are defined by a registry TBD (Section 12). [[ Editor's note: These keys are lifted from [RFC8693]'s "token type identifiers" list, but is there a better source? Additionally: should this be an array of objects with internal typing like the sub_ids? Do we expect more than one assertion per user anyway? ]]¶

"user": {
   "sub_ids": [ {
     "subject_type": "email",
     "email": "user@example.com"
   } ],
   "assertions": {
     "id_token": "eyj..."
   }
}

Subject identifiers are hints to the AS in determining the RO and MUST NOT be taken as declarative statements that a particular RO is present at the RC and acting as the RQ. Assertions SHOULD be validated by the AS. [[ editor's note: is this a MUST? Assertion validation is extremely specific to the kind of assertion in place, what other guidance and requirements can we put in place here? ]]¶

If the identified RQ does not match the RO present at the AS during an interaction step, the AS SHOULD reject the request with an error.¶

[[ Editor's note: we're potentially conflating identification (sub_ids) and provable presence (assertions and a trusted reference handle) in the same structure, so perhaps these should be split. The security parameters are pretty different here. ]]¶

If the AS trusts the RC to present verifiable assertions, the AS MAY decide, based on its policy, to skip interaction with the RO, even if the RC provides one or more interaction modes in its request.¶

"user": "XUT2MFM1XBIKJKSDU8QM"

2.5. Interacting with the User

Many times, the AS will require interaction with the RO in order to approve a requested delegation to the RC for both resources and direct claim information. Many times the RQ using the RC is the same person as the RO, and the RC can directly drive interaction with the AS by redirecting the RQ on the same device, or by launching an application. Other times, the RC can provide information to start the RO's interaction on a secondary device, or the RC will wait for the RO to approve the request asynchronously. The RC could also be signaled that interaction has completed by the AS making callbacks. To facilitate all of these modes, the RC declares the means that it can interact using the interact field.¶

The interact field is a JSON object with keys that declare different interaction modes. A RC MUST NOT declare an interaction mode it does not support. The RC MAY send multiple modes in the same request. There is no preference order specified in this request. An AS MAY respond to any, all, or none of the presented interaction modes (Section 3.3) in a request, depending on its capabilities and what is allowed to fulfill the request. This specification defines the following interaction modes:¶

redirect

Indicates that the RC can direct the RQ to an arbitrary URL at the AS for interaction. Section 2.5.1¶

app

Indicates that the RC can launch an application on the RQ's device for interaction. Section 2.5.2¶

callback

Indicates that the RC can receive a callback from the AS after interaction with the RO has concluded. Section 2.5.3¶

user_code

Indicates that the RC can communicate a human-readable short code to the RQ for use with a stable URL at the AS. Section 2.5.4¶

ui_locales

Indicates the RQ's preferred locales that the AS can use during interaction, particularly before the RO has authenticated. Section 2.5.5¶

The following sections detail requests for interaction modes. Additional interaction modes are defined in a registry TBD (Section 12).¶

[[ Editor's note: there need to be more examples (Appendix C) that knit together the interaction modes into common flows, like an authz-code equivalent. But it's important for the protocol design that these are separate pieces to allow such knitting to take place. ]]¶

In this non-normative example, the RC is indicating that it can redirect (Section 2.5.1) the RQ to an arbitrary URL and can receive a callback (Section 2.5.3) through a browser request.¶

    "interact": {
        "redirect": true,
        "callback": {
            "method": "redirect",
            "uri": "https://client.example.net/return/123455",
            "nonce": "LKLTI25DK82FX4T4QFZC"
        }
    }

In this non-normative example, the RC is indicating that it can display a use code (Section 2.5.4) and direct the RQ to an arbitrary URL of maximum length (Section 2.5.1.1) 255 characters, but it cannot accept a callback.¶

    "interact": {
        "redirect": 255,
        "user_code": true
    }

If the RC does not provide a suitable interaction mechanism, the AS cannot contact the RO asynchronously, and the AS determines that interaction is required, then the AS SHOULD return an error since the RC will be unable to complete the request without authorization.¶

The AS SHOULD apply suitable timeouts to any interaction mechanisms provided, including user codes and redirection URLs. The RC SHOULD apply suitable timeouts to any callback URLs.¶

"interact": {
   "redirect": true
}

"interact": {
   "redirect": 255
}

"interact": {
   "app": true
}

"interact": {
    "callback": {
       "method": "redirect",
       "uri": "https://client.example.net/return/123455",
       "nonce": "LKLTI25DK82FX4T4QFZC"
    }
}

"interact" {
    "redirect": {
       "method": "redirect",
       "uri": "https://client.example.net/return/123455",
       "nonce": "LKLTI25DK82FX4T4QFZC"
    }
}

"interact": [
  {
    "redirect": true,
    "callback": {
       "method": "redirect",
       "uri": "https://client.example.net/return/123455",
       "nonce": "LKLTI25DK82FX4T4QFZC"
    }
  },
  {
    "redirect": 255,
    "user_code": true
  }
]

"interact": {
    "callback": {
       "method": "redirect",
       "uri": "https://client.example.net/return/123455",
       "nonce": "LKLTI25DK82FX4T4QFZC"
    }
}

"interact": {
    "callback": {
       "method": "push",
       "uri": "https://client.example.net/return/123455",
       "nonce": "LKLTI25DK82FX4T4QFZC"
    }
}

"interact": {
    "user_code": true
}

"interact": {
    "ui_locales": ["en-US", "fr-CA"]
}

2.6. Declaring RC Capabilities

If the RC supports extension capabilities, it MAY present them to the AS in the "capabilities" field. This field is an array of strings representing specific extensions and capabilities, as defined by a registry TBD (Section 12).¶

"capabilities": ["ext1", "ext2"]

2.7. Referencing an Existing Grant Request

If the RC has a reference handle from a previously granted request, it MAY send that reference in the "existing_grant" field. This field is a single string consisting of the value of the access_token returned in a previous request's continuation response (Section 3.1).¶

"existing_grant": "80UPRY5NM33OMUKMKSKU"

The AS MUST dereference the grant associated with the reference and process this request in the context of the referenced one. The AS MUST NOT alter the existing grant associated with the reference.¶

[[ Editor's note: this basic capability is to allow for both step-up authorization and downscoped authorization, but by explicitly creating a new request and not modifying an existing one. What's the best guidance for how an AS should process this? What are the use cases that help differentiate this from modification of an existing request? ]]¶

2.8. Requesting OpenID Connect Claims

If the RC and AS both support OpenID Connect's claims query language as defined in [OIDC] Section 5.5, the RC sends the value of the OpenID Connect claims authorization request parameter as a JSON object under the name claims in the root of the request.¶

        "claims": {
                "id_token" : {
                    "email"          : { "essential" : true },
                    "email_verified" : { "essential" : true }
                },
                "userinfo" : {
                    "name"           : { "essential" : true },
                    "picture"        : null
                }
        }

The contents of the claims parameter have the same semantics as they do in OpenID Connect's claims authorization request parameter, including all extensions such as [OIDC4IA]. The AS MUST process the claims object in the same way that it would with an OAuth 2 based authorization request.¶

Note that because this is an independent query object, the claims value can augment or alter other portions of the request, namely the resources and subject fields. This query language uses the fields in the top level of the object to indicate the target for any requested claims. For instance, the userinfo target indicates that a returned access token would grant access to the given claims at the UserInfo Endpoint, while the id_token target indicates that the claims would be returned in an ID Token as described in Section 3.4.¶

[[ Editor's note: in order to use the "claims" parameter as defined in OIDC, we have to violate the principle of orthogonality in Section 2.9. An alternative approach would be to split up the portions of the claims request, so that "id_token" claims would go into the "subject" field and "userinfo" claims would go into the "resources" request, but this violates the original field definition from OIDC and gets into the territory of defining an identity schema request. This approach would also invalidate extensions to the "claims" standard as each "target" would need to have its own separate mapping to some part of the GNAP protocol. ]]¶

[[ Editor's note: I'm not a fan of GNAP defining how OIDC would work at all and would rather that work be done by the OIDF in an extension. However, I think it is important for discussion to see this kind of thing in context with the rest of the protocol, for now. In the future, I would anticipate this would be defined by the OIDF as a relatively small but robust identity layer on top of GNAP. ]]¶

2.9. Extending The Grant Request

The request object MAY be extended by registering new items in a registry TBD (Section 12). Extensions SHOULD be orthogonal to other parameters. Extensions MUST document any aspects where the extension item affects or influences the values or behavior of other request and response objects.¶

[[ Editor's note: we should have more guidance and examples on what possible top-level extensions would look like. ]]¶

3.1. Request Continuation

If the AS determines that the request can be continued with additional requests, it responds with the "continue" field. This field contains a JSON object with the following properties.¶

uri

REQUIRED. The URI at which the RC can make continuation requests. This URI MAY vary request, or MAY be stable at the AS if the AS includes an access token. The RC MUST use this value exactly as given when making a continuation request (Section 5).¶

wait

RECOMMENDED. The amount of time in integer seconds the RC SHOULD wait after receiving this continuation handle and calling the URI.¶

access_token

RECOMMENDED. A unique access token for continuing the request, in the format specified in Section 3.2.1. This access token MUST be bound to the RC's key used in the request and MUST NOT be a bearer token. This access token MUST NOT be usable at resources outside of the AS. [[ Editor's note: Is this a restriction we want to enforce? ]] If the AS includes an access token, the RC MUST present the access token in all requests to the continuation URI as described in Section 7.¶

{
    "continue": {
        "access_token": {
            "value": "80UPRY5NM33OMUKMKSKU",
            "key": true
        },
        "uri": "https://server.example.com/continue",
        "wait": 60
    }
}

The RC can use the values of this field to continue the request as described in Section 5. Note that the RC MUST sign all continuation requests with its key as described in Section 8. If the AS includes an access_token, the RC MUST present the access token in its continuation request.¶

This field SHOULD be returned when interaction is expected, to allow the RC to follow up after interaction has been concluded.¶

[[ Editor's note: The AS can use the optional "access_token" as a credential for the client to manage the grant request itself over time. This is in parallel with access token management as well as RS access in general. If the AS uses the access token, the continuation URL can be static, and potentially even the same as the initial request URL. If the AS does not use an access token here, it needs to use unique URLs in its response and bind the client's key to requests to those URLs - or potentially only allow one request per client at a time. The optionality adds a layer of complexity, but the client behavior is deterministic in all possible cases and it re-uses existing functions and structures instead of inventing something special just to talk to the AS. The optional access token represents a design compromise, but the working group can decide to either require the access token on all requests or to remove the access token functionality and require the security of the continuation requests be based on unique URLs. ]]¶

3.2. Access Tokens

If the AS has successfully granted one or more access tokens to the RC, the AS responds with either the access_token or the multiple_access_token field. The AS MUST NOT respond with both the access_token and multiple_access_token fields.¶

[[ Editor's note: I really don't like the dichotomy between "access_token" and "multiple_access_tokens" and their being mutually exclusive, and I think we should design away from this pattern toward something less error-prone. ]]¶

    "access_token": {
        "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
        "key": false,
        "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L",
        "resources": [
            {
                "type": "photo-api",
                "actions": [
                    "read",
                    "write",
                    "dolphin"
                ],
                "locations": [
                    "https://server.example.net/",
                    "https://resource.local/other"
                ],
                "datatypes": [
                    "metadata",
                    "images"
                ]
            },
            "read", "dolphin-metadata"
        ]
    }

    "access_token": {
        "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
        "key": true,
        "resources": [
            "finance", "medical"
        ]
    }

    "multiple_access_tokens": {
        "token1": {
            "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
            "key": false,
            "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L"
        },
        "token2": {
            "value": "UFGLO2FDAFG7VGZZPJ3IZEMN21EVU71FHCARP4J1",
            "key": false
        }
    }

3.3. Interaction Modes

If the RC has indicated a capability to interact with the RO in its request (Section 2.5), and the AS has determined that interaction is both supported and necessary, the AS responds to the RC with any of the following values in the interact field of the response. There is no preference order for interaction modes in the response, and it is up to the RC to determine which ones to use. All supported interaction methods are included in the same interact object.¶

redirect

Redirect to an arbitrary URL. Section 3.3.1¶

app

Launch of an application URL. Section 3.3.2¶

callback

Callback to an RC URL after interaction is completed. Section 3.3.3¶

user_code

Display a short user code. Section 3.3.4¶

Additional interaction mode responses can be defined in a registry TBD (Section 12).¶

The AS MUST NOT respond with any interaction mode that the RC did not indicate in its request. The AS MUST NOT respond with any interaction mode that the AS does not support. Since interaction responses include secret or unique information, the AS SHOULD respond to each interaction mode only once in an ongoing request, particularly if the RC modifies its request (Section 5.3).¶

    "interact": {
        "redirect": "https://interact.example.com/4CF492MLVMSW9MKMXKHQ"
    }

    "interact": {
        "app": "https://app.example.com/launch?tx=4CF492MLV"
    }

    "interact": {
        "callback": "MBDOFXG4Y5CVJCX821LH"
    }

    "interact": {
        "user_code": {
            "code": "A1BC-3DFF",
            "url": "https://srv.ex/device"
        }
    }

3.4. Returning User Information

If information about the RO is requested and the AS grants the RC access to that data, the AS returns the approved information in the "subject" response field. This field is an object with the following OPTIONAL properties.¶

sub_ids

An array of subject identifiers for the RO, as defined by [I-D.ietf-secevent-subject-identifiers]. [[ Editor's note: privacy considerations are needed around returning identifiers. ]]¶

assertions

An object containing assertions as values keyed on the assertion type defined by a registry TBD (Section 12). [[ Editor's note: should this be an array of objects with internal typing like the sub_ids? Do we expect more than one assertion per user anyway? ]]¶

updated_at

Timestamp in integer seconds indicating when the identified account was last updated. The RC MAY use this value to determine if it needs to request updated profile information through an identity API. The definition of such an identity API is out of scope for this specification.¶

"subject": {
   "sub_ids": [ {
     "subject_type": "email",
     "email": "user@example.com",
   } ],
   "assertions": {
     "id_token": "eyj..."
   }
}

The AS MUST return the subject field only in cases where the AS is sure that the RO and the RQ are the same party. This can be accomplished through some forms of interaction with the RO (Section 4).¶

Subject identifiers returned by the AS SHOULD uniquely identify the RO at the AS. Some forms of subject identifier are opaque to the RC (such as the subject of an issuer and subject pair), while others forms (such as email address and phone number) are intended to allow the RC to correlate the identifier with other account information at the RC. The RC MUST NOT request or use any returned subject identifiers for communication purposes (see Section 2.2). That is, a subject identifier returned in the format of an email address or a phone number only identifies the RO to the AS and does not indicate that the AS has validated that the represented email address or phone number in the identifier is suitable for communication with the current user. To get such information, the RC MUST use an identity protocol to request and receive additional identity claims. While Section 2.8 specifies one such method, other identity protocols could also be used on top of GNAP to convey this information and the details of an identity protocol and associated schema are outside the scope of this specification.¶

[[ Editor's note: subject identifiers here are naturally scoped to the AS; even though using an external identifier like an email address or phone number implies a global namespace in use, the association of that identifier to the current user is still under the view of the AS. Would changing the name to "as_sub_ids" or "local_sub_ids" help convey that point? Would it also be desirable to have an identifier that's globally unique by design? The "iss_sub" type almost gets us there by explicitly calling out the issuer URL, but tuples are hard to deal with in practice and so tend to get ignored in practice in the OIDC space. ]]¶

[[ Editor's note: This will need substantial privacy considerations, as this is releasing information about the current user that could be tied to other information at the RC or elsewhere. To facilitate this, should we have another form of identifier that's a globally unique identifier of some form? DIDs could facilitate that kind of namespace. ]]¶

Extensions to this specification MAY define additional response properties in a registry TBD (Section 12).¶

3.5. Returning Dynamically-bound Reference Handles

Many parts of the RC's request can be passed as either a value or a reference. The use of a reference in place of a value allows for a client to optimize requests to the AS.¶

Some references, such as for the RC instance's identity (Section 2.3.1) or the requested resources (Section 2.1.2), can be managed statically through an admin console or developer portal provided by the AS or RS. The developer of the RC can include these values in their code for a more efficient and compact request.¶

If desired, the AS MAY also generate and return some of these references dynamically to the RC in its response to facilitate multiple interactions with the same software. The RC SHOULD use these references in future requests in lieu of sending the associated data value. These handles are intended to be used on future requests.¶

Dynamically generated handles are string values that MUST be protected by the RC as secrets. Handle values MUST be unguessable and MUST NOT contain any sensitive information. Handle values are opaque to the RC.¶

[[ Editor's note: these constructs used to be objects to allow for expansion to future fields, like a management URI or different presentation types or expiration, but those weren't used in practice. Is that desirable anymore or is collapsing them like this the right direction? ]]¶

All dynamically generated handles are returned as fields in the root JSON object of the response. This specification defines the following dynamic handle returns, additional handles can be defined in a registry TBD (Section 12).¶

instance_id

A string value used to represent the information in the client object that the RC can use in a future request, as described in Section 2.3.1.¶

user_handle

A string value used to represent the current user. The RC can use in a future request, as described in Section 2.4.1.¶

This non-normative example shows two handles along side an issued access token.¶

{
    "user_handle": "XUT2MFM1XBIKJKSDU8QM",
    "instance_id": "7C7C4AZ9KHRS6X63AJAO",
    "access_token": {
        "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
        "key": false
    }
}

[[ Editor's note: the ability to dynamically return reference handles allows for an inline version of dynamic registration without needing to go through a discrete registration step, for clients where that makes sense. Currently this is entirely up to the AS to decide when to issue these, but maybe the client should signal that it can receive these handles as part of the request? The new "token flags" construct in Section 2.1.4 almost gets at that, but for a different part of the request structure. Since the client is the component that will know if it's in a position to make use of such reference handles in the future (like a mobile app) or if it's just going to evaporate at the end of a session (like an SPA). Ultimately we need to deal with a range of dynamism, not just the "pre-registered" vs. "non-registered" use cases that OAuth forces us in to. ]]¶

[[ Editor's note: The client-bound "instance_id" could serve as the hook we would need for RFC7592 style dynamic client management, including additional components like key rotation. If the AS returns an object instead of a string here, that could include everything that the client would need in order to make REST-style management calls, similar to token management.¶

{
    "client": {
        "instance_id": "7C7C4AZ9KHRS6X63AJAO",
        "manage": "https://example.server.com/client/7C7C4AZ9KHRS6X63AJAO",
        "access_token": {
            "value": "4TB8N6BW7OZB8CDFONP219RP1LT0OS9M2PMHKUR6",
            "key": true
        }
    }
}

The client would sign all requests with its key and use the presented access token. A "POST" or "PATCH" request would update client information, including having a method for key rotation using nested signatures. A "DELETE" request would un-register the client, etc. ]]¶

3.6. Error Response

If the AS determines that the request cannot be issued for any reason, it responds to the RC with an error message.¶

error

The error code.¶

{

  "error": "user_denied"

}

The error code is one of the following, with additional values available in a registry TBD (Section 12):¶

user_denied

The RO denied the request.¶

too_fast

The RC did not respect the timeout in the wait response.¶

unknown_request

The request referenced an unknown ongoing access request.¶

[[ Editor's note: I think we will need a more robust error mechanism, and we need to be more clear about what error states are allowed in what circumstances. Additionally, is the "error" parameter exclusive with others in the return? ]]¶

3.7. Extending the Response

Extensions to this specification MAY define additional fields for the grant response in a registry TBD (Section 12).¶

[[ Editor's note: what guidance should we give to designers on this? ]]¶

4.1. Interaction at a Redirected URI

When the RO is directed to the AS through the "redirect" (Section 3.3.1) mode, the AS can interact with the RO through their web browser to authenticate the user as an RO and gather their consent. Note that since the RC does not add any parameters to the URL, the AS MUST determine the grant request being referenced from the URL value itself. If the URL cannot be associated with a currently active request, the AS MUST display an error to the RO and MUST NOT attempt to redirect the RO back to any RC even if a callback is supplied (Section 2.5.3).¶

The interaction URL MUST be reachable from the RO's browser, though note that the RO MAY open the URL on a separate device from the RC itself. The interaction URL MUST be accessible from an HTTP GET request, and MUST be protected by HTTPS or equivalent means.¶

With this method, it is common for the RO to be the same party as the RQ, since the RC has to communicate the redirection URI to the RQ.¶

4.2. Interaction at the User Code URI

When the RO is directed to the AS through the "user_code" (Section 3.3.4) mode, the AS can interact with the RO through their web browser to collect the user code, authenticate the user as an RO, and gather their consent. Note that since the URL itself is static, the AS MUST determine the grant request being referenced from the user code value itself. If the user code cannot be associated with a currently active request, the AS MUST display an error to the RO and MUST NOT attempt to redirect the RO back to any RC even if a callback is supplied (Section 2.5.3).¶

The user code URL MUST be reachable from the RO's browser, though note that the RO MAY open the URL on a separate device from the RC itself. The user code URL MUST be accessible from an HTTP GET request, and MUST be protected by HTTPS or equivalent means.¶

While it is common for the RO to be the same party as the RQ, since the RC has to communicate the user code to someone, there are cases where the RQ and RO are separate parties and the authorization happens asynchronously.¶

4.3. Interaction through an Application URI

When the RC successfully launches an application through the "app" mode (Section 3.3.2), the AS interacts with the RO through that application to authenticate the user as the RO and gather their consent. The details of this interaction are out of scope for this specification.¶

[[ Editor's note: Should we have anything to say about an app sending information to a back-end to get details on the pending request? ]]¶

4.4. Post-Interaction Completion

Upon completing an interaction with the RO, if a "callback" (Section 3.3.3) mode is available with the current request, the AS MUST follow the appropriate method at the end of interaction to allow the RC to continue. If this mode is not available, the AS SHOULD instruct the RO to return to their RC software upon completion. Note that these steps still take place in most error cases, such as when the RO has denied access. This pattern allows the RC to potentially recover from the error state without restarting the request from scratch by modifying its request or providing additional information directly to the AS.¶

[[ Editor's note: there might be some other kind of push-based notification or callback that the client can use, or an out-of-band non-HTTP protocol. The AS would know about this if supported and used, but the guidance here should be written in such a way as to not be too restrictive in the next steps that it can take. Still, it's important that the AS not expect or even allow clients to poll if the client has stated it can take a callback of some form, otherwise that sets up a potential session fixation attack vector that the client is trying to and able to avoid. There has also been a call for post-interaction that doesn't tie into the security of the protocol, like redirecting to a static webpage hosted by the client's company. Would this fit here? ]]¶

The AS MUST create an interaction reference and associate that reference with the current interaction and the underlying pending request. This value MUST be sufficiently random so as not to be guessable by an attacker. The interaction reference MUST be one-time-use.¶

The AS MUST calculate a hash value based on the RC and AS nonces and the interaction reference, as described in Section 4.4.3. The RC will use this value to validate the return call from the AS.¶

The AS then MUST send the hash and interaction reference based on the interaction finalization mode as described in the following sections.¶

https://client.example.net/return/123455
  ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A
  &interact_ref=4IFWWIKYBC2PQ6U56NL1

POST /push/554321 HTTP/1.1
Host: client.example.net
Content-Type: application/json

{
  "hash": "p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A",
  "interact_ref": "4IFWWIKYBC2PQ6U56NL1"
}

VJLO6A4CAYLBXHTR0KRO
MBDOFXG4Y5CVJCX821LH
4IFWWIKYBC2PQ6U56NL1

p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A

62SbcD3Xs7L40rjgALA-ymQujoh2LB2hPJyX9vlcr1H6ecChZ8BNKkG_HrOKP_Bpj84rh4mC9aE9x7HPBFcIHw

5.1. Continuing After a Completed Interaction

When the AS responds to the RC's callback parameter as in Section 4.4.1, this response includes an interaction reference. The RC MUST include that value as the field interact_ref in a POST request to the continuation URI.¶

POST /continue/80UPRY5NM33OMUKMKSKU HTTP/1.1
Host: server.example.com
Content-type: application/json
Detached-JWS: ejy0...

{
  "interact_ref": "4IFWWIKYBC2PQ6U56NL1"
}

Since the interaction reference is a one-time-use value as described in Section 4.4.1, if the RC needs to make additional continuation calls after this request, the RC MUST NOT include the interaction reference. If the AS detects an RC submitting the same interaction reference multiple times, the AS MUST return an error and SHOULD invalidate the ongoing request.¶

The Section 3 MAY contain any newly-created access tokens (Section 3.2) or newly-released subject claims (Section 3.4). The response MAY contain a new "continue" response (Section 3.1) as described above. The response SHOULD NOT contain any interaction responses (Section 3.3). [[ Editor's note: This last one might be overly restrictive, since some kinds of interaction could require multiple round trips. We need more examples and experience beyond redirect-based interaction here. ]]¶

For example, if the request is successful in causing the AS to issue access tokens and release subject claims, the response could look like this:¶

{
    "access_token": {
        "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
        "key": false,
        "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L"
    },
    "subject": {
        "sub_ids": [ {
           "subject_type": "email",
           "email": "user@example.com",
        } ]
    }
}

With this example, the RC can not make an additional continuation request because a continue field is not included.¶

[[ Editor's note: other interaction methods, such as a challenge-response cryptographic protocol, would use a similar construct as here, but have different rules. Would it be reasonable to allow them to be combined? Could this be combined further with the "update" method in Section 5.3? ]]¶

5.2. Continuing During Pending Interaction

When the RC does not include a callback parameter, the RC will often need to poll the AS until the RO has authorized the request. To do so, the RC makes a POST request to the continuation URI as in Section 5.1, but does not include a message body.¶

POST /continue HTTP/1.1
Host: server.example.com
Content-type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Detached-JWS: ejy0...

The Section 3 MAY contain any newly-created access tokens (Section 3.2) or newly-released subject claims (Section 3.4). The response MAY contain a new "continue" response (Section 3.1) as described above. If a continue field is included, it SHOULD include a wait field to facilitate a reasonable polling rate by the RC. The response SHOULD NOT contain interaction responses (Section 3.3).¶

For example, if the request has not yet been authorized by the RO, the AS could respond by telling the RC to make another continuation request in the future. In this example, a new, unique access token has been issued for the call, which the RC will use in its next continuation request.¶

{
    "continue": {
        "access_token": {
            "value": "33OMUKMKSKU80UPRY5NM",
            "key": true
        },
        "uri": "https://server.example.com/continue",
        "wait": 30
    }
}

[[ Editor's note: Do we want to be more precise about what's expected inside the "continue" object? I think that at least the URI is required, access token required IF used, etc. This is even if they haven't changed since last time, and the client will use whatever value comes back. ]]¶

[[ Editor's note: extensions to this might need to communicate to the client what the current state of the user interaction is. This has been done in similar proprietary protocols, but the details of that information tend to be highly application specific. Like "user hasn't logged in yet", "user has logged in but is still sitting at the page", or "user seems to have wandered off". We might be able to provide a decent framework for hanging this kind of stuff on. ]]¶

If the request is successful in causing the AS to issue access tokens and release subject claims, the response could look like this example:¶

{
    "access_token": {
        "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
        "key": false,
        "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L"
    },
    "subject": {
        "sub_ids": [ {
           "subject_type": "email",
           "email": "user@example.com",
        } ]
    }
}

5.3. Modifying an Existing Request

The RC might need to modify an ongoing request, whether or not tokens have already been issued or claims have already been released. In such cases, the RC makes an HTTP PATCH request to the continuation URI and includes any fields it needs to modify. Fields that aren't included in the request are considered unchanged from the original request.¶

The RC MAY include the resources and subject fields as described in Section 2.1 and Section 2.2. Inclusion of these fields override any values in the initial request, which MAY trigger additional requirements and policies by the AS. For example, if the RC is asking for more access, the AS could require additional interaction with the RO to gather additional consent. If the RC is asking for more limited access, the AS could determine that sufficient authorization has been granted to the RC and return the more limited access rights immediately. [[ Editor's note: We could state something like "resources and subject MUST NOT be the same as in the initial or previous request" to enforce that this really is a change, but is there value in calling that out here? Somehow we do probably want to tell the AS to not let a client simply post the same request here to rotate access tokens now that we've got an explicit function for that, right? ]]¶

The RC MAY include the interact field as described in Section 2.5. Inclusion of this field indicates that the RC is capable of driving interaction with the RO, and this field replaces any values from a previous request. The AS MAY respond to any of the interaction responses as described in Section 3.3, just like it would to a new request.¶

The RC MAY include the user field as described in Section 2.4 to present new assertions or information about the RQ. [[ Editor's note: This would allow the client to do things like gather the user's identifiers post-request, or gather an assertion from an on-device element that the AS can verify. It opens up potential avenues for trouble if the user here is different from the RO that's already showed up at the AS or race conditions if the RQ's identity changes mid-stream. But that said, this seems important for multi-log-in cases and the like, probably. ]]¶

The RC MUST NOT include the client section of the request. [[ Editor's note: We do not want the client to be able to get swapped out from underneath the user, especially post-consent. However, including this field in a PATCH update request might be the place to define key rotation for the grant request itself, but we'd need to be very careful of how that works. And it feels like it might have consequences outside of the request, such as rotating the key for all ongoing grants for a given client instance, which isn't really desirable here. We need a lot more discussion and engineering on this before including it. ]]¶

The RC MAY include post-interaction responses such as described in Section 5.1. [[ Editor's note: it seems a little odd to include this in a request but I can't see a reason to not allow it. ]]¶

Modification requests MUST NOT alter previously-issued access tokens. Instead, any access tokens issued from a continuation are considered new, separate access tokens. The AS MAY revoke existing access tokens after a modification has occurred. [[ Editor's note: this might be subject to the "multi_token" flag, but since we're creating a NEW access token and not rotating an existing one, this seems to be a different use case. ]]¶

Modification requests MAY result in previously-issued access tokens being revoked. [[ Editor's note: there is a solid argument to be made for always revoking old access tokens here, but we need more discussion on the boundaries for such a requirement. If they stick around, it does make a "read" request weird because now we've got multiple access tokens sticking around associated with a grant request and no good place to put them. ]]¶

If the modified request can be granted immediately by the AS, the Section 3 MAY contain any newly-created access tokens (Section 3.2) or newly-released subject claims (Section 3.4). The response MAY contain a new "continue" response (Section 3.1) as described above. If interaction can occur, the response SHOULD contain interaction responses (Section 3.3) as well.¶

For example, an RC initially requests a set of resources using references:¶

POST /tx HTTP/1.1
Host: server.example.com
Content-type: application/json
Detached-JWS: ejy0...

{
    "resources": [
        "read", "write"
    ],
    "interact": {
        "redirect": true,
        "callback": {
            "method": "redirect",
            "uri": "https://client.example.net/return/123455",
            "nonce": "LKLTI25DK82FX4T4QFZC"
        }
    },
    "client": "987YHGRT56789IOLK"
}

Access is granted by the RO, and a token is issued by the AS. In its final response, the AS includes a continue field:¶

{
    "continue": {
        "access_token": {
            "value": "80UPRY5NM33OMUKMKSKU",
            "key": true
        },
        "uri": "https://server.example.com/continue",
        "wait": 30
    },
    "access_token": ...
}

This allows the RC to make an eventual continuation call. The RC realizes that it no longer needs "write" access and therefore modifies its ongoing request, here asking for just "read" access instead of both "read" and "write" as before.¶

PATCH /continue HTTP/1.1
Host: server.example.com
Content-type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Detached-JWS: ejy0...

{
    "resources": [
        "read"
    ]
    ...
}

The AS replaces the previous resources from the first request, allowing the AS to determine if any previously-granted consent already applies. In this case, the AS would likely determine that reducing the breadth of the requested access means that new access tokens can be issued to the RC. The AS would likely revoke previously-issued access tokens that had the greater access rights associated with them.¶

{
    "continue": {
        "access_token": {
            "value": "M33OMUK80UPRY5NMKSKU",
            "key": true
        },
        "uri": "https://server.example.com/continue",
        "wait": 30
    },
    "access_token": ...
}

For another example, the RC initially requests read-only access but later needs to step up its access. The initial request could look like this example.¶

POST /tx HTTP/1.1
Host: server.example.com
Content-type: application/json
Detached-JWS: ejy0...

{
    "resources": [
        "read"
    ],
    "interact": {
        "redirect": true,
        "callback": {
            "method": "redirect",
            "uri": "https://client.example.net/return/123455",
            "nonce": "LKLTI25DK82FX4T4QFZC"
        }
    },
    "client": "987YHGRT56789IOLK"
}

Access is granted by the RO, and a token is issued by the AS. In its final response, the AS includes a continue field:¶

{
    "continue": {
        "access_token": {
            "value": "80UPRY5NM33OMUKMKSKU",
            "key": true
        },
        "uri": "https://server.example.com/continue",
        "wait": 30
    },
    "access_token": ...
}

This allows the RC to make an eventual continuation call. The RC later realizes that it now needs "write" access in addition to the "read" access. Since this is an expansion of what it asked for previously, the RC also includes a new interaction section in case the AS needs to interact with the RO again to gather additional authorization. Note that the RC's nonce and callback are different from the initial request. Since the original callback was already used in the initial exchange, and the callback is intended for one-time-use, a new one needs to be included in order to use the callback again.¶

[[ Editor's note: the net result of this is that interaction requests are really only meant to be responded to exactly once by the AS. This isn't spelled out explicitly, but could be included in Section 2.5 and/or Section 3.3. ]]¶

PATCH /continue HTTP/1.1
Host: server.example.com
Content-type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Detached-JWS: ejy0...

{
    "resources": [
        "read", "write"
    ],
    "interact": {
        "redirect": true,
        "callback": {
            "method": "redirect",
            "uri": "https://client.example.net/return/654321",
            "nonce": "K82FX4T4LKLTI25DQFZC"
        }
    }
}

From here, the AS can determine that the RC is asking for more than it was previously granted, but since the RC has also provided a mechanism to interact with the RO, the AS can use that to gather the additional consent. The protocol continues as it would with a new request. Since the old access tokens are good for a subset of the rights requested here, the AS might decide to not revoke them. However, any access tokens granted after this update process are new access tokens and do not modify the rights of existing access tokens.¶

5.4. Getting the Current State of a Grant Request

If the RC needs to get the current state of an ongoing grant request, it makes an HTTP GET request to the continuation URI. This request MUST NOT alter the grant request in any fashion, including causing the issuance of new access tokens or modification of interaction parameters.¶

The AS MAY include existing access tokens and previously-released subject claims in the response. The AS MUST NOT issue a new access token or release a new subject claim in response to this request.¶

GET /continue HTTP/1.1
Host: server.example.com
Content-type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Detached-JWS: ejy0...

The response MAY include any fields described Section 3 that are applicable to this ongoing request, including the most recently issued access tokens, any released subject claims, and any currently active interaction modes. The response MAY contain a new "continue" response (Section 3.1) as described above.¶

[[ Editor's note: I'm a little dubious about the need for this particular function in reality, but including it for completeness sake. There are a lot of questions we need to answer, such as whether it's safe to include access tokens and claims in the response of this kind of "read" at all, and whether it makes sense to include items like interaction nonces in the response. This discussion should be driven by the use cases calling for this "read" functionality. There have been similar functions within proprietary protocols where the client calls an endpoint at the AS to figure out where the user is in the interaction process at the AS, letting the client provide a smarter UI. It doesn't seem like we could do that in depth here since it would be highly application specific, but that might be a good example of how to extend a response and give a client extra information. ]]¶

5.5. Canceling a Grant Request

If the RC wishes to cancel an ongoing grant request, it makes an HTTP DELETE request to the continuation URI.¶

DELETE /continue HTTP/1.1
Host: server.example.com
Content-type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Detached-JWS: ejy0...

If the request is successfully cancelled, the AS responds with an HTTP 202. The AS MUST revoke all associated access tokens, if possible.¶

6.1. Rotating the Access Token

The RC makes an HTTP POST to the token management URI, sending the access token in the appropriate header and signing the request with the appropriate key.¶

POST /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1
Host: server.example.com
Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0
Detached-JWS: eyj0....

[[ Editor's note: This could alternatively be an HTTP PUT verb, since we are telling the AS that we want to replace the token. However, we are not providing the information we want to replace the token with, and in fact that's up to the AS entirely, not the client. For that reason, I think a POST still makes the most sense. ]]¶

The AS validates that the token presented is associated with the management URL, that the AS issued the token to the given RC, and that the presented key is appropriate to the token.¶

If the access token has expired, the AS SHOULD honor the rotation request to the token management URL since it is likely that the RC is attempting to refresh the expired token. To support this, the AS MAY apply different lifetimes for the use of the token in management vs. its use at an RS. An AS MUST NOT honor a rotation request for an access token that has been revoked, either by the AS or by the RC through the token management URI (Section 6.2).¶

If the token is validated and the key is appropriate for the request, the AS MUST invalidate the current access token associated with this URL, if possible, and return a new access token response as described in Section 3.2.1, unless the multi_token flag is specified in the request. [[ Editor's note: We could also use different verbs to signal whether or not the old token should be kept around or not, instead of using a token flag to do this. ]] The value of the access token MUST NOT be the same as the current value of the access token used to access the management API. The response MAY include an updated access token management URL as well, and if so, the RC MUST use this new URL to manage the new access token.¶

[[ Editor's note: the net result is that the client's always going to use the management URL that comes back. But should we let the server omit it from the response if it doesn't change? That seems like an odd optimization that doesn't help the client. ]]¶

{
    "access_token": {
        "value": "FP6A8H6HY37MH13CK76LBZ6Y1UADG6VEUPEER5H2",
        "key": false,
        "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L",
        "resources": [
            {
                "type": "photo-api",
                "actions": [
                    "read",
                    "write",
                    "dolphin"
                ],
                "locations": [
                    "https://server.example.net/",
                    "https://resource.local/other"
                ],
                "datatypes": [
                    "metadata",
                    "images"
                ]
            },
            "read", "dolphin-metadata"
        ]
    }
}

[[ Editor's note: If the client is using its own key as the proof, like with a bearer access token, the AS is going to need to know if the client's key has been rotated. We don't have a mechanism for rotating the token's key or the client's key yet either - so that could occur through this management function as well. ]]¶

6.2. Revoking the Access Token

If the RC wishes to revoke the access token proactively, such as when a user indicates to the RC that they no longer wish for it to have access or the RC application detects that it is being uninstalled, the RC can use the token management URI to indicate to the AS that the AS should invalidate the access token for all purposes.¶

The RC makes an HTTP DELETE request to the token management URI, presenting the access token and signing the request with the appropriate key.¶

DELETE /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1
Host: server.example.com
Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0
Detached-JWS: eyj0....

If the key presented is associated with the token (or the RC, in the case of a bearer token), the AS MUST invalidate the access token, if possible, and return an HTTP 204 response code.¶

204 No Content

Though the AS MAY revoke an access token at any time for any reason, the token management function is specifically for the RC's use. If the access token has already expired or has been revoked through other means, the AS SHOULD honor the revocation request to the token management URL as valid, since the end result is still the token not being usable.¶

8.1. Detached JWS

This method is indicated by jwsd in the proof field. A JWS [RFC7515] signature object is created as follows:¶

The header of the JWS MUST contain the kid field of the key bound to this RC for this request. The JWS header MUST contain an alg field appropriate for the key identified by kid and MUST NOT be none. The b64 field MUST be set to false and the crit field MUST contain at least b64 as specified in [RFC7797]¶

To protect the request, the JWS header MUST contain the following additional fields.¶

htm

The HTTP Method used to make this request, as an uppercase ASCII string.¶

htu

The HTTP URI used for this request, including all path and query components.¶

ts

A timestamp of the request in integer seconds¶

at_hash

When to bind a request to an access token, the access token hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg header parameter of the JWS's JOSE Header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them.¶

[[ Editor's note: It's not the usual practice to put additional information into the header of a JWS, but this keeps us from having to normalize the body serialization. Alternatively, we could add all these fields to the body of the request, but then it gets awkward for non-body requests like GET/DELETE. ]]¶

The payload of the JWS object is the serialized body of the request, and the object is signed according to detached JWS [RFC7797].¶

The RC presents the signature in the Detached-JWS HTTP Header field. [[ Editor's Note: this is a custom header field, do we need this? It seems like the best place to put this. ]]¶

POST /tx HTTP/1.1
Host: server.example.com
Content-Type: application/json
Detached-JWS: eyJiNjQiOmZhbHNlLCJhbGciOiJSUzI1NiIsImtpZCI6Inh5ei0xIn0.
  .Y287HMtaY0EegEjoTd_04a4GC6qV48GgVbGKOhHdJnDtD0VuUlVjLfwne8AuUY3U7e8
  9zUWwXLnAYK_BiS84M8EsrFvmv8yDLWzqveeIpcN5_ysveQnYt9Dqi32w6IOtAywkNUD
  ZeJEdc3z5s9Ei8qrYFN2fxcu28YS4e8e_cHTK57003WJu-wFn2TJUmAbHuqvUsyTb-nz
  YOKxuCKlqQItJF7E-cwSb_xULu-3f77BEU_vGbNYo5ZBa2B7UHO-kWNMSgbW2yeNNLbL
  C18Kv80GF22Y7SbZt0e2TwnR2Aa2zksuUbntQ5c7a1-gxtnXzuIKa34OekrnyqE1hmVW
  peQ

{
    "resources": [
        "dolphin-metadata"
    ],
    "interact": {
        "redirect": true,
        "callback": {
            "method": "redirect",
            "uri": "https://client.foo",
            "nonce": "VJLO6A4CAYLBXHTR0KRO"
        }
    },
    "client": {
      "proof": "jwsd",
      "key": {
        "jwk": {
                    "kty": "RSA",
                    "e": "AQAB",
                    "kid": "xyz-1",
                    "alg": "RS256",
                    "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8
xYJCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD-y6jnD1u9YhBOCWObNPF
vpkTM8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5-ejCywKRBfctRcnhTTGNztbbDBUyD
SWmFMVCHe5mXT4cL0BwrZC6S-uu-LAx06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS
63WYPHi_Ap2B7_8Wbw4ttzbMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFe
kpdfWdiPQddQ6Y1cK2U3obvUg7w"
        }
      }
      "display": {
        "name": "My Client Display Name",
        "uri": "https://example.net/client"
      },
    }
}

If the request being made does not have a message body, such as an HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated over an empty payload.¶

When the server (AS or RS) receives the Detached-JWS header, it MUST parse its contents as a detached JWS object. The HTTP Body is used as the payload for purposes of validating the JWS, with no transformations.¶

[[ Editor's note: this is a potentially fragile signature mechanism. It doesn't protect arbitrary headers or other specific aspects of the request, but it's simple to calculate and useful for body-driven requests, like the client to the AS. Additionally it is potentially fragile since a multi-tier system could parse the payload and pass the parsed payload downstream with potential transformations, making downstream signature validation impossible. We might want to remove this in favor of general-purpose HTTP signing, or at least provide guidance on its use. ]]¶

8.2. Attached JWS

This method is indicated by jws in the proof field. A JWS [RFC7515] signature object is created as follows:¶

The header of the JWS MUST contain the kid field of the key bound to this RC for this request. The JWS header MUST contain an alg field appropriate for the key identified by kid and MUST NOT be none.¶

To protect the request, the JWS header MUST contain the following additional fields.¶

htm

The HTTP Method used to make this request, as an uppercase ASCII string.¶

htu

The HTTP URI used for this request, including all path and query components.¶

ts

A timestamp of the request in integer seconds¶

at_hash

When to bind a request to an access token, the access token hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg header parameter of the JWS's JOSE Header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them.¶

[[ Editor's note: It's not the usual practice to put additional information into the header of a JWS, but this keeps us from having to modify the body to use this signature method. Alternatively, we could add all these fields to the body of the request, but then it gets awkward for non-body requests like GET/DELETE. ]]¶

The payload of the JWS object is the JSON serialized body of the request, and the object is signed according to JWS and serialized into compact form [RFC7515].¶

The RC presents the JWS as the body of the request along with a content type of application/jose. The AS MUST extract the payload of the JWS and treat it as the request body for further processing.¶

POST /tx HTTP/1.1
Host: server.example.com
Content-Type: application/jose

eyJiNjQiOmZhbHNlLCJhbGciOiJSUzI1NiIsImtpZCI6Inh5ei0xIn0.ewogICAgIm
NsaWVudCI6IHsKICAgICAgICAibmFtZSI6ICJNeSBDbGllbnQgRGlzcGxheSBOYW1l
IiwKICAgICAgICAidXJpIjogImh0dHBzOi8vZXhhbXBsZS5uZXQvY2xpZW50IgogIC
AgfSwKICAgICJyZXNvdXJjZXMiOiBbCiAgICAgICAgImRvbHBoaW4tbWV0YWRhdGEi
CiAgICBdLAogICAgImludGVyYWN0IjogewogICAgICAgICJyZWRpcmVjdCI6IHRydW
UsCiAgICAgICAgImNhbGxiYWNrIjogewogICAgCQkidXJpIjogImh0dHBzOi8vY2xp
ZW50LmZvbyIsCiAgICAJCSJub25jZSI6ICJWSkxPNkE0Q0FZTEJYSFRSMEtSTyIKIC
AgIAl9CiAgICB9LAogICAgImtleXMiOiB7CgkJInByb29mIjogImp3c2QiLAogICAg
ICAgICJqd2tzIjogewogICAgICAgICAgICAia2V5cyI6IFsKICAgICAgICAgICAgIC
AgIHsKICAgICAgICAgICAgICAgICAgICAia3R5IjogIlJTQSIsCiAgICAgICAgICAg
ICAgICAgICAgImUiOiAiQVFBQiIsCiAgICAgICAgICAgICAgICAgICAgImtpZCI6IC
J4eXotMSIsCiAgICAgICAgICAgICAgICAgICAgImFsZyI6ICJSUzI1NiIsCiAgICAg
ICAgICAgICAgICAgICAgIm4iOiAia09CNXJSNEp2MEdNZUxhWTZfSXRfcjNPUndkZj
hjaV9KdGZmWHlhU3g4eFlKQ0NOYU9LTkpuX096MFloZEhiWFRlV081QW95c3BEV0pi
TjV3XzdiZFdEeGdwRC15NmpuRDF1OVloQk9DV09iTlBGdnBrVE04TEM3U2RYR1JLeD
JrOE1lMnJfR3NzWWx5UnBxdnBCbFk1LWVqQ3l3S1JCZmN0UmNuaFRUR056dGJiREJV
eURTV21GTVZDSGU1bVhUNGNMMEJ3clpDNlMtdXUtTEF4MDZhS3dRT1B3WU9HT3NsSz
hXUG0xeUdka2FBMXVGX0ZwUzZMUzYzV1lQSGlfQXAyQjdfOFdidzR0dHpiTVNfZG9K
dnVEYWdXOEExSXAzZlhGQUh0UkFjS3c3cmRJNF9YbG42NmhKeEZla3BkZldkaVBRZG
RRNlkxY0syVTNvYnZVZzd3IgogICAgICAgICAgICAgICAgfQogICAgICAgICAgICBd
CiAgICAgICAgfQogICAgfQp9.Y287HMtaY0EegEjoTd_04a4GC6qV48GgVbGKOhHdJ
nDtD0VuUlVjLfwne8AuUY3U7e89zUWwXLnAYK_BiS84M8EsrFvmv8yDLWzqveeIpcN
5_ysveQnYt9Dqi32w6IOtAywkNUDZeJEdc3z5s9Ei8qrYFN2fxcu28YS4e8e_cHTK5
7003WJu-wFn2TJUmAbHuqvUsyTb-nzYOKxuCKlqQItJF7E-cwSb_xULu-3f77BEU_v
GbNYo5ZBa2B7UHO-kWNMSgbW2yeNNLbLC18Kv80GF22Y7SbZt0e2TwnR2Aa2zksuUb
ntQ5c7a1-gxtnXzuIKa34OekrnyqE1hmVWpeQ

If the request being made does not have a message body, such as an HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated over an empty payload and passed in the Detached-JWS header as described in Section 8.1.¶

[[ Editor's note: A downside to this method is that it requires the content type to be something other than application/json, and it doesn't work against an RS without additional profiling since it takes over the request body - plus we have to specify different delivery locations for a GET vs. a POST, for example. Additionally it is potentially fragile like a detached JWS since a multi-tier system could parse the payload and pass the parsed payload downstream with potential transformations. We might want to remove this in favor of general-purpose HTTP signing, or at least provide guidance on its use. ]]¶

8.3. Mutual TLS

This method is indicated by mtls in the proof field. The RC presents its client certificate during TLS negotiation with the server (either AS or RS). The AS or RS takes the thumbprint of the client certificate presented during mutual TLS negotiation and compares that thumbprint to the thumbprint presented by the RC application as described in [RFC8705] section 3.¶

POST /tx HTTP/1.1
Host: server.example.com
Content-Type: application/json
SSL_CLIENT_CERT: MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFADCBmjE3MDUGA1UEAwwuQmVz
 cG9rZSBFbmdpbmVlcmluZyBSb290IENlcnRpZmljYXRlIEF1dGhvcml0eTELMAkG
 A1UECAwCTUExCzAJBgNVBAYTAlVTMRkwFwYJKoZIhvcNAQkBFgpjYUBic3BrLmlv
 MRwwGgYDVQQKDBNCZXNwb2tlIEVuZ2luZWVyaW5nMQwwCgYDVQQLDANNVEkwHhcN
 MTkwNDEwMjE0MDI5WhcNMjQwNDA4MjE0MDI5WjB8MRIwEAYDVQQDDAlsb2NhbGhv
 c3QxCzAJBgNVBAgMAk1BMQswCQYDVQQGEwJVUzEgMB4GCSqGSIb3DQEJARYRdGxz
 Y2xpZW50QGJzcGsuaW8xHDAaBgNVBAoME0Jlc3Bva2UgRW5naW5lZXJpbmcxDDAK
 BgNVBAsMA01USTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMmaXQHb
 s/wc1RpsQ6Orzf6rN+q2ijaZbQxD8oi+XaaN0P/gnE13JqQduvdq77OmJ4bQLokq
 sd0BexnI07Njsl8nkDDYpe8rNve5TjyUDCfbwgS7U1CluYenXmNQbaYNDOmCdHww
 UjV4kKREg6DGAx22Oq7+VHPTeeFgyw4kQgWRSfDENWY3KUXJlb/vKR6lQ+aOJytk
 vj8kVZQtWupPbvwoJe0na/ISNAOhL74w20DWWoDKoNltXsEtflNljVoi5nqsmZQc
 jfjt6LO0T7O1OX3Cwu2xWx8KZ3n/2ocuRqKEJHqUGfeDtuQNt6Jz79v/OTr8puLW
 aD+uyk6NbtGjoQsCAwEAAaOBiTCBhjAJBgNVHRMEAjAAMAsGA1UdDwQEAwIF4DBs
 BgNVHREEZTBjgglsb2NhbGhvc3SCD3Rsc2NsaWVudC5sb2NhbIcEwKgBBIERdGxz
 Y2xpZW50QGJzcGsuaW+GF2h0dHA6Ly90bHNjbGllbnQubG9jYWwvhhNzc2g6dGxz
 Y2xpZW50LmxvY2FsMA0GCSqGSIb3DQEBCwUAA4IBAQCKKv8WlLrT4Z5NazaUrYtl
 TF+2v0tvZBQ7qzJQjlOqAcvxry/d2zyhiRCRS/v318YCJBEv4Iq2W3I3JMMyAYEe
 2573HzT7rH3xQP12yZyRQnetdiVM1Z1KaXwfrPDLs72hUeELtxIcfZ0M085jLboX
 hufHI6kqm3NCyCCTihe2ck5RmCc5l2KBO/vAHF0ihhFOOOby1v6qbPHQcxAU6rEb
 907/p6BW/LV1NCgYB1QtFSfGxowqb9FRIMD2kvMSmO0EMxgwZ6k6spa+jk0IsI3k
 lwLW9b+Tfn/daUbIDctxeJneq2anQyU2znBgQl6KILDSF4eaOqlBut/KNZHHazJh

{
    "resources": [
        "dolphin-metadata"
    ],
    "interact": {
        "redirect": true,
        "callback": {
            "method": "redirect",
            "uri": "https://client.foo",
            "nonce": "VJLO6A4CAYLBXHTR0KRO"
        }
    },
    "client": {
      "display": {
        "name": "My Client Display Name",
        "uri": "https://example.net/client"
      },
      "key": {
        "proof": "mtls",
        "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFADCBmjE3
MDUGA1UEAwwuQmVzcG9rZSBFbmdpbmVlcmluZyBSb290IENlcnRpZmljYXRlIEF1d
Ghvcml0eTELMAkGA1UECAwCTUExCzAJBgNVBAYTAlVTMRkwFwYJKoZIhvcNAQkBFg
pjYUBic3BrLmlvMRwwGgYDVQQKDBNCZXNwb2tlIEVuZ2luZWVyaW5nMQwwCgYDVQQ
LDANNVEkwHhcNMTkwNDEwMjE0MDI5WhcNMjQwNDA4MjE0MDI5WjB8MRIwEAYDVQQD
DAlsb2NhbGhvc3QxCzAJBgNVBAgMAk1BMQswCQYDVQQGEwJVUzEgMB4GCSqGSIb3D
QEJARYRdGxzY2xpZW50QGJzcGsuaW8xHDAaBgNVBAoME0Jlc3Bva2UgRW5naW5lZX
JpbmcxDDAKBgNVBAsMA01USTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggE
BAMmaXQHbs/wc1RpsQ6Orzf6rN+q2ijaZbQxD8oi+XaaN0P/gnE13JqQduvdq77Om
J4bQLokqsd0BexnI07Njsl8nkDDYpe8rNve5TjyUDCfbwgS7U1CluYenXmNQbaYND
OmCdHwwUjV4kKREg6DGAx22Oq7+VHPTeeFgyw4kQgWRSfDENWY3KUXJlb/vKR6lQ+
aOJytkvj8kVZQtWupPbvwoJe0na/ISNAOhL74w20DWWoDKoNltXsEtflNljVoi5nq
smZQcjfjt6LO0T7O1OX3Cwu2xWx8KZ3n/2ocuRqKEJHqUGfeDtuQNt6Jz79v/OTr8
puLWaD+uyk6NbtGjoQsCAwEAAaOBiTCBhjAJBgNVHRMEAjAAMAsGA1UdDwQEAwIF4
DBsBgNVHREEZTBjgglsb2NhbGhvc3SCD3Rsc2NsaWVudC5sb2NhbIcEwKgBBIERdG
xzY2xpZW50QGJzcGsuaW+GF2h0dHA6Ly90bHNjbGllbnQubG9jYWwvhhNzc2g6dGx
zY2xpZW50LmxvY2FsMA0GCSqGSIb3DQEBCwUAA4IBAQCKKv8WlLrT4Z5NazaUrYtl
TF+2v0tvZBQ7qzJQjlOqAcvxry/d2zyhiRCRS/v318YCJBEv4Iq2W3I3JMMyAYEe2
573HzT7rH3xQP12yZyRQnetdiVM1Z1KaXwfrPDLs72hUeELtxIcfZ0M085jLboXhu
fHI6kqm3NCyCCTihe2ck5RmCc5l2KBO/vAHF0ihhFOOOby1v6qbPHQcxAU6rEb907
/p6BW/LV1NCgYB1QtFSfGxowqb9FRIMD2kvMSmO0EMxgwZ6k6spa+jk0IsI3klwLW
9b+Tfn/daUbIDctxeJneq2anQyU2znBgQl6KILDSF4eaOqlBut/KNZHHazJh"
    }
}

[[ Editor's note: This method requires no changes to the HTTP message itself, since the security relies on the TLS layer. However, the application level will need to validate that the certificate key used in the request is the one expected for the specific request. ]]¶

8.4. Demonstration of Proof-of-Possession (DPoP)

This method is indicated by dpop in the proof field. The RC creates a Demonstration of Proof-of-Possession signature header as described in [I-D.ietf-oauth-dpop] section 2. In addition to the required fields, the DPoP body MUST also contain a digest of the request body:¶

digest

Digest of the request body as the value of the Digest header defined in [RFC3230].¶

POST /tx HTTP/1.1
Host: server.example.com
Content-Type: application/json
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IlJTMjU2IiwiandrIjp7Imt0eSI6Il
JTQSIsImUiOiJBUUFCIiwia2lkIjoieHl6LWNsaWVudCIsImFsZyI6IlJTMjU2Iiwibi
I6Inp3Q1RfM2J4LWdsYmJIcmhlWXBZcFJXaVk5SS1uRWFNUnBablJySWpDczZiX2VteV
RrQmtEREVqU3lzaTM4T0M3M2hqMS1XZ3hjUGRLTkdaeUlvSDNRWmVuMU1LeXloUXBMSk
cxLW9MTkxxbTdwWFh0ZFl6U2RDOU8zLW9peXk4eWtPNFlVeU5aclJSZlBjaWhkUUNiT1
9PQzhRdWdtZzlyZ05ET1NxcHBkYU5lYXMxb3Y5UHhZdnhxcnoxLThIYTdna0QwMFlFQ1
hIYUIwNXVNYVVhZEhxLU9fV0l2WVhpY2c2STVqNlM0NFZOVTY1VkJ3dS1BbHluVHhRZE
1BV1AzYll4VlZ5NnAzLTdlVEpva3ZqWVRGcWdEVkRaOGxVWGJyNXlDVG5SaG5oSmd2Zj
NWakRfbWFsTmU4LXRPcUs1T1NEbEhUeTZnRDlOcWRHQ20tUG0zUSJ9fQ.eyJodHRwX21
ldGhvZCI6IlBPU1QiLCJodHRwX3VyaSI6Imh0dHA6XC9cL2hvc3QuZG9ja2VyLmludGV
ybmFsOjk4MzRcL2FwaVwvYXNcL3RyYW5zYWN0aW9uIiwiaWF0IjoxNTcyNjQyNjEzLCJ
qdGkiOiJIam9IcmpnbTJ5QjR4N2pBNXl5RyJ9.aUhftvfw2NoW3M7durkopReTvONng1
fOzbWjAlKNSLL0qIwDgfG39XUyNvwQ23OBIwe6IuvTQ2UBBPklPAfJhDTKd8KHEAfidN
B-LzUOzhDetLg30yLFzIpcEBMLCjb0TEsmXadvxuNkEzFRL-Q-QCg0AXSF1h57eAqZV8
SYF4CQK9OUV6fIWwxLDd3cVTx83MgyCNnvFlG_HDyim1Xx-rxV4ePd1vgDeRubFb6QWj
iKEO7vj1APv32dsux67gZYiUpjm0wEZprjlG0a07R984KLeK1XPjXgViEwEdlirUmpVy
T9tyEYqGrTfm5uautELgMls9sgSyE929woZ59elg

{
    "resources": [
        "dolphin-metadata"
    ],
    "interact": {
        "redirect": true,
        "callback": {
            "method": "redirect",
            "uri": "https://client.foo",
            "nonce": "VJLO6A4CAYLBXHTR0KRO"
        }
    },
    "client": {
      "display": {
        "name": "My Client Display Name",
        "uri": "https://example.net/client"
      },
      "proof": "dpop",
      "key": {
        "jwk": {
                    "kty": "RSA",
                    "e": "AQAB",
                    "kid": "xyz-1",
                    "alg": "RS256",
                    "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xYJ
CCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD-y6jnD1u9YhBOCWObNPFvpkTM
8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5-ejCywKRBfctRcnhTTGNztbbDBUyDSWmFMVCH
e5mXT4cL0BwrZC6S-uu-LAx06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS63WYPHi_Ap2
B7_8Wbw4ttzbMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFekpdfWdiPQddQ6Y
1cK2U3obvUg7w"
        }
      }
    }
}

[[ Editor's note: this method requires duplication of the key in the header and the request body, which is redundant and potentially awkward. The signature also doesn't protect the body of the request. ]]¶

8.5. HTTP Signing

This method is indicated by httpsig in the proof field. The RC creates an HTTP Signature header as described in [I-D.ietf-httpbis-message-signatures] section 4. The RC MUST calculate and present the Digest header as defined in [RFC3230] and include this header in the signature.¶

POST /tx HTTP/1.1
Host: server.example.com
Content-Type: application/json
Content-Length: 716
Signature: keyId="xyz-client", algorithm="rsa-sha256",
 headers="(request-target) digest content-length",
 signature="TkehmgK7GD/z4jGkmcHS67cjVRgm3zVQNlNrrXW32Wv7d
u0VNEIVI/dMhe0WlHC93NP3ms91i2WOW5r5B6qow6TNx/82/6W84p5jqF
YuYfTkKYZ69GbfqXkYV9gaT++dl5kvZQjVk+KZT1dzpAzv8hdk9nO87Xi
rj7qe2mdAGE1LLc3YvXwNxuCQh82sa5rXHqtNT1077fiDvSVYeced0UEm
rWwErVgr7sijtbTohC4FJLuJ0nG/KJUcIG/FTchW9rd6dHoBnY43+3Dzj
CIthXpdH5u4VX3TBe6GJDO6Mkzc6vB+67OWzPwhYTplUiFFV6UZCsDEeu
Sa/Ue1yLEAMg=="]}
Digest: SHA=oZz2O3kg5SEFAhmr0xEBbc4jEfo=

{
    "resources": [
        "dolphin-metadata"
    ],
    "interact": {
        "redirect": true,
        "callback": {
            "method": "push",
            "uri": "https://client.foo",
            "nonce": "VJLO6A4CAYLBXHTR0KRO"
        }
    },
    "client": {
      "display": {
        "name": "My Client Display Name",
        "uri": "https://example.net/client"
      },
      "proof": "httpsig",
      "key": {
        "jwk": {
                    "kty": "RSA",
                    "e": "AQAB",
                    "kid": "xyz-1",
                    "alg": "RS256",
                    "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_J
tffXyaSx8xYJCCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD-
y6jnD1u9YhBOCWObNPFvpkTM8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5-
ejCywKRBfctRcnhTTGNztbbDBUyDSWmFMVCHe5mXT4cL0BwrZC6S-uu-LAx
06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS63WYPHi_Ap2B7_8Wbw4ttz
bMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFekpdfWdiPQddQ6
Y1cK2U3obvUg7w"
        }
      }
    }
}

When used to present an access token as in Section 7, the Authorization header MUST be included in the signature.¶

8.6. OAuth Proof of Possession (PoP)

This method is indicated by oauthpop in the proof field. The RC creates an HTTP Authorization PoP header as described in [I-D.ietf-oauth-signed-http-request] section 4, with the following additional requirements:¶

• The at (access token) field MUST be omitted unless this method is being used in conjunction with an access token as in Section 7. [[ Editor's note: this is in contradiction to the referenced spec which makes this field mandatory. ]]¶
• The b (body hash) field MUST be calculated and supplied, unless there is no entity body (such as a GET, OPTIONS, or DELETE request).¶
• All components of the URL MUST be calculated and supplied¶
• The m (method) field MUST be supplied¶

POST /tx HTTP/1.1
Host: server.example.com
Content-Type: application/json
PoP: eyJhbGciOiJSUzI1NiIsImp3ayI6eyJrdHkiOiJSU0EiLCJlIjoi
QVFBQiIsImtpZCI6Inh5ei1jbGllbnQiLCJhbGciOiJSUzI1NiIsIm4iO
iJ6d0NUXzNieC1nbGJiSHJoZVlwWXBSV2lZOUktbkVhTVJwWm5ScklqQ3
M2Yl9lbXlUa0JrRERFalN5c2kzOE9DNzNoajEtV2d4Y1BkS05HWnlJb0g
zUVplbjFNS3l5aFFwTEpHMS1vTE5McW03cFhYdGRZelNkQzlPMy1vaXl5
OHlrTzRZVXlOWnJSUmZQY2loZFFDYk9fT0M4UXVnbWc5cmdORE9TcXBwZ
GFOZWFzMW92OVB4WXZ4cXJ6MS04SGE3Z2tEMDBZRUNYSGFCMDV1TWFVYW
RIcS1PX1dJdllYaWNnNkk1ajZTNDRWTlU2NVZCd3UtQWx5blR4UWRNQVd
QM2JZeFZWeTZwMy03ZVRKb2t2allURnFnRFZEWjhsVVhicjV5Q1RuUmhu
aEpndmYzVmpEX21hbE5lOC10T3FLNU9TRGxIVHk2Z0Q5TnFkR0NtLVBtM
1EifX0.eyJwIjoiXC9hcGlcL2FzXC90cmFuc2FjdGlvbiIsImIiOiJxa0
lPYkdOeERhZVBTZnc3NnFjamtqSXNFRmxDb3g5bTU5NFM0M0RkU0xBIiw
idSI6Imhvc3QuZG9ja2VyLmludGVybmFsIiwiaCI6W1siQWNjZXB0Iiwi
Q29udGVudC1UeXBlIiwiQ29udGVudC1MZW5ndGgiXSwiVjQ2OUhFWGx6S
k9kQTZmQU5oMmpKdFhTd3pjSGRqMUloOGk5M0h3bEVHYyJdLCJtIjoiUE
9TVCIsInRzIjoxNTcyNjQyNjEwfQ.xyQ47qy8bu4fyK1T3Ru1Sway8wp6
5rfAKnTQQU92AUUU07I2iKoBL2tipBcNCC5zLH5j_WUyjlN15oi_lLHym
fPdzihtt8_Jibjfjib5J15UlifakjQ0rHX04tPal9PvcjwnyZHFcKn-So
Y3wsARn-gGwxpzbsPhiKQP70d2eG0CYQMA6rTLslT7GgdQheelhVFW29i
27NcvqtkJmiAG6Swrq4uUgCY3zRotROkJ13qo86t2DXklV-eES4-2dCxf
cWFkzBAr6oC4Qp7HnY_5UT6IWkRJt3efwYprWcYouOVjtRan3kEtWkaWr
G0J4bPVnTI5St9hJYvvh7FE8JirIg

{
    "resources": [
        "dolphin-metadata"
    ],
    "interact": {
        "redirect": true,
        "callback": {
            "method": "redirect",
            "uri": "https://client.foo",
            "nonce": "VJLO6A4CAYLBXHTR0KRO"
        }
    },
    "client": {
      "display": {
        "name": "My Client Display Name",
        "uri": "https://example.net/client"
      },
      "proof": "oauthpop",
      "key": {
        "jwk": {
                    "kty": "RSA",
                    "e": "AQAB",
                    "kid": "xyz-1",
                    "alg": "RS256",
                    "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_J
tffXyaSx8xYJCCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD-
y6jnD1u9YhBOCWObNPFvpkTM8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5-
ejCywKRBfctRcnhTTGNztbbDBUyDSWmFMVCHe5mXT4cL0BwrZC6S-uu-LAx
06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS63WYPHi_Ap2B7_8Wbw4ttz
bMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFekpdfWdiPQddQ6
Y1cK2U3obvUg7w"
        }
      }
    }
}

[[ Editor's note: This is a stale draft from the OAuth working group, but it does at least provide some basic functionality for protecting HTTP messages with a signature. This work is likely to be subsumed by the general-purpose HTTP message signature mechanism in Section 8.5. ]]¶

10.1. Introspecting a Token

When the RS receives an access token, it can call the introspection endpoint at the AS to get token information. [[ Editor's note: this isn't super different from the token management URIs, but the RS has no way to get that URI, and it's bound to the RS's keys instead of the RC's or token's keys. ]]¶

+------+       +------+       +------+
|  RC  |--(1)->|  RS  |       |  AS  |
|      |       |      |--(2)->|      |
|      |       |      |<-(3)--|      |
|      |       |      |       +------+
|      |<-(4)--|      |
+------+       +------+

1. The RC calls the RS with its access token.¶
2. The RS introspects the access token value at the AS. The RS signs the request with its own key (not the RC's key or the token's key).¶
3. The AS validates the token value and the RC's request and returns the introspection response for the token.¶
4. The RS fulfills the request from the RC.¶

The RS signs the request with its own key and sends the access token as the body of the request.¶

POST /introspect HTTP/1.1
Host: server.example.com
Content-type: application/json
Detached-JWS: ejy0...

{
    "access_token": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
}

The AS responds with a data structure describing the token's current state and any information the RS would need to validate the token's presentation, such as its intended proofing mechanism and key material.¶

Content-type: application/json

{
    "active": true,
    "resources": [
        "dolphin-metadata", "some other thing"
    ],
    "client": {
      "key": {
        "proof": "httpsig",
        "jwk": {
                    "kty": "RSA",
                    "e": "AQAB",
                    "kid": "xyz-1",
                    "alg": "RS256",
                    "n": "kOB5rR4Jv0GMeL...."
        }
      }
    }
}

10.2. Deriving a downstream token

Some architectures require an RS to act as an RC and request a derived access token for a secondary RS. This internal token is issued in the context of the incoming access token.¶

+------+       +-------+       +------+       +-------+
|  RC  |--(1)->|  RS1  |       |  AS  |       |  RS2  |
|      |       |       |--(2)->|      |       |       |
|      |       |       |<-(3)--|      |       |       |
|      |       |       |       +------+       |       |
|      |       |       |                      |       |
|      |       |       |-----------(4)------->|       |
|      |       |       |<----------(5)--------|       |
|      |<-(6)--|       |                      |       |
+------+       +-------+                      +-------+

1. The RC calls RS1 with an access token.¶
2. RS1 presents that token to the AS to get a derived token for use at RS2. RS1 indicates that it has no ability to interact with the RO. RS1 signs its request with its own key, not the token's key or the RC's key.¶
3. The AS returns a derived token to RS1 for use at RS2.¶
4. RS1 calls RS2 with the token from (3).¶
5. RS2 fulfills the call from RS1.¶
6. RS1 fulfills the call from RC.¶

If the RS needs to derive a token from one presented to it, it can request one from the AS by making a token request as described in Section 2 and presenting the existing access token's value in the "existing_access_token" field.¶

The RS MUST identify itself with its own key and sign the request.¶

[[ Editor's note: this is similar to Section 2.7 but based on the access token and not the grant. We might be able to re-use that function: the fact that the keys presented are not the ones used for the access token should indicate that it's a different party and a different kind of request, but there might be some subtle security issues there. ]]¶

POST /tx HTTP/1.1
Host: server.example.com
Content-type: application/json
Detached-JWS: ejy0...

{
    "resources": [
        {
            "actions": [
                "read",
                "write",
                "dolphin"
            ],
            "locations": [
                "https://server.example.net/",
                "https://resource.local/other"
            ],
            "datatypes": [
                "metadata",
                "images"
            ]
        },
        "dolphin-metadata"
    ],
    "client": "7C7C4AZ9KHRS6X63AJAO",
    "existing_access_token": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0"
}

The AS responds with a token as described in Section 3.¶

10.3. Registering a Resource Handle

If the RS needs to, it can post a set of resources as described in Section 2.1.1 to the AS's resource registration endpoint.¶

The RS MUST identify itself with its own key and sign the request.¶

POST /resource HTTP/1.1
Host: server.example.com
Content-type: application/json
Detached-JWS: ejy0...

{
    "resources": [
        {
            "actions": [
                "read",
                "write",
                "dolphin"
            ],
            "locations": [
                "https://server.example.net/",
                "https://resource.local/other"
            ],
            "datatypes": [
                "metadata",
                "images"
            ]
        },
        "dolphin-metadata"
    ],
    "client": "7C7C4AZ9KHRS6X63AJAO"

}

The AS responds with a handle appropriate to represent the resources list that the RS presented.¶

Content-type: application/json

{
    "resource_handle": "FWWIKYBQ6U56NL1"
}

The RS MAY make this handle available as part of a response (Section 10.4) or as documentation to developers.¶

[[ Editor's note: It's not an exact match here because the "resource_handle" returned now represents a collection of objects instead of a single one. Perhaps we should let this return a list of strings instead? Or use a different syntax than the resource request? Also, this borrows heavily from UMA 2's "distributed authorization" model and, like UMA, might be better suited to an extension than the core protocol. ]]¶

10.4. Requesting a Resources With Insufficient Access

If the RC calls an RS without an access token, or with an invalid access token, the RS MAY respond to the RC with an authentication header indicating that GNAP. The address of the GNAP endpoint MUST be sent in the "as_uri" parameter. The RS MAY additionally return a resource reference that the RC MAY use in its resource request (Section 2.1). This resource reference handle SHOULD be sufficient for at least the action the RC was attempting to take at the RS. The RS MAY use the dynamic resource handle request (Section 10.3) to register a new resource handle, or use a handle that has been pre-configured to represent what the AS is protecting. The content of this handle is opaque to the RS and the RC.¶

WWW-Authenticate: GNAP as_uri=http://server.example/tx,resource=FWWIKYBQ6U56NL1

The RC then makes a call to the "as_uri" as described in Section 2, with the value of "resource" as one of the members of a "resources" array Section 2.1.1. The RC MAY request additional resources and other information, and MAY request multiple access tokens.¶

[[ Editor's note: this borrows heavily from UMA 2's "distributed authorization" model and, like UMA, might be better suited to an extension than the core protocol. ]]¶

C.1. Redirect-Based User Interaction

In this scenario, the user is the RO and has access to a web browser, and the client can take front-channel callbacks on the same device as the user. This combination is analogous to the OAuth 2 Authorization Code grant type.¶

The client initiates the request to the AS. Here the client identifies itself using its public key.¶

POST /tx HTTP/1.1
Host: server.example.com
Content-type: application/json
Detached-JWS: ejy0...

{
    "resources": [
        {
            "actions": [
                "read",
                "write",
                "dolphin"
            ],
            "locations": [
                "https://server.example.net/",
                "https://resource.local/other"
            ],
            "datatypes": [
                "metadata",
                "images"
            ]
        }
    ],
    "client": {
      "key": {
        "proof": "jwsd",
        "jwk": {
            "kty": "RSA",
            "e": "AQAB",
            "kid": "xyz-1",
            "alg": "RS256",
            "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..."
        }
      }
    },
    "interact": {
        "redirect": true,
        "callback": {
            "method": "redirect",
            "uri": "https://client.example.net/return/123455",
            "nonce": "LKLTI25DK82FX4T4QFZC"
        }
    }
}

The AS processes the request and determines that the RO needs to interact. The AS returns the following response giving the client the information it needs to connect. The AS has also indicated to the client that it can use the given instance identifier to identify itself in future requests (Section 2.3.1).¶

Content-type: application/json

{
    "interact": {
       "redirect": "https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ",
       "callback": "MBDOFXG4Y5CVJCX821LH"
    }
    "continue": {
        "access_token": {
            "value": "80UPRY5NM33OMUKMKSKU",
            "key": true
        },
        "uri": "https://server.example.com/continue"
    },
    "instance_id": "7C7C4AZ9KHRS6X63AJAO"
}

The client saves the response and redirects the user to the interaction_url by sending the following HTTP message to the user's browser.¶

HTTP 302 Found
Location: https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ

The user's browser fetches the AS's interaction URL. The user logs in, is identified as the RO for the resource being requested, and approves the request. Since the AS has a callback parameter, the AS generates the interaction reference, calculates the hash, and redirects the user back to the client with these additional values added as query parameters.¶

HTTP 302 Found
Location: https://client.example.net/return/123455
  ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A
  &interact_ref=4IFWWIKYBC2PQ6U56NL1

The client receives this request from the user's browser. The client ensures that this is the same user that was sent out by validating session information and retrieves the stored pending request. The client uses the values in this to validate the hash parameter. The client then calls the continuation URL and presents the handle and interaction reference in the request body. The client signs the request as above.¶

POST /continue HTTP/1.1
Host: server.example.com
Content-type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Detached-JWS: ejy0...

{
    "interact_ref": "4IFWWIKYBC2PQ6U56NL1"
}

The AS retrieves the pending request based on the handle and issues a bearer access token and returns this to the client.¶

Content-type: application/json

{
    "access_token": {
        "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
        "key": false,
        "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L",
        "resources": [{
            "actions": [
                "read",
                "write",
                "dolphin"
            ],
            "locations": [
                "https://server.example.net/",
                "https://resource.local/other"
            ],
            "datatypes": [
                "metadata",
                "images"
            ]
        }]
    },
    "continue": {
        "access_token": {
            "value": "80UPRY5NM33OMUKMKSKU",
            "key": true
        },
        "uri": "https://server.example.com/continue"
    }
}

C.2. Secondary Device Interaction

In this scenario, the user does not have access to a web browser on the device and must use a secondary device to interact with the AS. The client can display a user code or a printable QR code. The client prefers a short URL if one is available, with a maximum of 255 characters in length. The is not able to accept callbacks from the AS and needs to poll for updates while waiting for the user to authorize the request.¶

The client initiates the request to the AS.¶

POST /tx HTTP/1.1
Host: server.example.com
Content-type: application/json
Detached-JWS: ejy0...

{
    "resources": [
        "dolphin-metadata", "some other thing"
    ],
    "client": "7C7C4AZ9KHRS6X63AJAO",
    "interact": {
        "redirect": 255,
        "user_code": true
    }
}

The AS processes this and determines that the RO needs to interact. The AS supports both long and short redirect URIs for interaction, so it includes both. Since there is no "callback" the AS does not include a nonce, but does include a "wait" parameter on the continuation section because it expects the client to poll for results.¶

Content-type: application/json

{
    "interact": {
        "redirect": "https://srv.ex/MXKHQ",
        "user_code": {
            "code": "A1BC-3DFF",
            "url": "https://srv.ex/device"
        }
    },
    "continue": {
        "uri": "https://server.example.com/continue/80UPRY5NM33OMUKMKSKU",
        "wait": 60
    }
}

The client saves the response and displays the user code visually on its screen along with the static device URL. The client also displays the short interaction URL as a QR code to be scanned.¶

If the user scans the code, they are taken to the interaction endpoint and the AS looks up the current pending request based on the incoming URL. If the user instead goes to the static page and enters the code manually, the AS looks up the current pending request based on the value of the user code. In both cases, the user logs in, is identified as the RO for the resource being requested, and approves the request. Once the request has been approved, the AS displays to the user a message to return to their device.¶

Meanwhile, the client periodically polls the AS every 60 seconds at the continuation URL. The client signs the request using the same key and method that it did in the first request.¶

POST /continue/80UPRY5NM33OMUKMKSKU HTTP/1.1
Host: server.example.com
Detached-JWS: ejy0...

The AS retrieves the pending request based on the handle and determines that it has not yet been authorized. The AS indicates to the client that no access token has yet been issued but it can continue to call after another 60 second timeout.¶

Content-type: application/json

{
    "continue": {
        "uri": "https://server.example.com/continue/BI9QNW6V9W3XFJK4R02D",
        "wait": 60
    }
}

Note that the continuation URL has been rotated since it was used by the client to make this call. The client polls the continuation URL after a 60 second timeout using the new handle.¶

POST /continue/BI9QNW6V9W3XFJK4R02D HTTP/1.1
Host: server.example.com
Authorization: GNAP
Detached-JWS: ejy0...

The AS retrieves the pending request based on the URL, determines that it has been approved, and issues an access token.¶

Content-type: application/json

{
    "access_token": {
        "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
        "key": false,
        "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L",
        "resources": [
            "dolphin-metadata", "some other thing"
        ]
    }
}

D.1. Asynchronous Authorization

In this scenario, the client is requesting on behalf of a specific RO, but has no way to interact with the user. The AS can asynchronously reach out to the RO for approval in this scenario.¶

The client starts the request at the AS by requesting a set of resources. The client also identifies a particular user.¶

POST /tx HTTP/1.1
Host: server.example.com
Content-type: application/json
Detached-JWS: ejy0...

{
    "resources": [
        {
            "type": "photo-api",
            "actions": [
                "read",
                "write",
                "dolphin"
            ],
            "locations": [
                "https://server.example.net/",
                "https://resource.local/other"
            ],
            "datatypes": [
                "metadata",
                "images"
            ]
        },
        "read", "dolphin-metadata",
        {
            "type": "financial-transaction",
            "actions": [
                "withdraw"
            ],
            "identifier": "account-14-32-32-3",
            "currency": "USD"
        },
        "some other thing"
    ],
    "client": "7C7C4AZ9KHRS6X63AJAO",
    "user": {
        "sub_ids": [ {
            "subject_type": "email",
            "email": "user@example.com"
        } ]
   }
}

The AS processes this and determines that the RO needs to interact. The AS determines that it can reach the identified user asynchronously and that the identified user does have the ability to approve this request. The AS indicates to the client that it can poll for continuation.¶

Content-type: application/json

{
    "continue": {
        "access_token": {
            "value": "80UPRY5NM33OMUKMKSKU",
            "key": true
        },
        "uri": "https://server.example.com/continue",
        "wait": 60
    }
}

The AS reaches out to the RO and prompts them for consent. In this example, the AS has an application that it can push notifications in to for the specified account.¶

Meanwhile, the client periodically polls the AS every 60 seconds at the continuation URL.¶

POST /continue HTTP/1.1
Host: server.example.com
Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Detached-JWS: ejy0...

The AS retrieves the pending request based on the handle and determines that it has not yet been authorized. The AS indicates to the client that no access token has yet been issued but it can continue to call after another 60 second timeout.¶

Content-type: application/json

{
    "continue": {
        "access_token": {
            "value": "BI9QNW6V9W3XFJK4R02D",
            "key": true
        },
        "uri": "https://server.example.com/continue",
        "wait": 60
    }
}

Note that the continuation handle has been rotated since it was used by the client to make this call. The client polls the continuation URL after a 60 second timeout using the new handle.¶

POST /continue HTTP/1.1
Host: server.example.com
Authorization: GNAP BI9QNW6V9W3XFJK4R02D
Detached-JWS: ejy0...

The AS retrieves the pending request based on the handle and determines that it has been approved and it issues an access token.¶

Content-type: application/json

{
    "access_token": {
        "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
        "key": false,
        "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L",
        "resources": [
            "dolphin-metadata", "some other thing"
        ]
    }
}

D.2. Applying OAuth 2 Scopes and Client IDs

While the GNAP protocol is not designed to be directly compatible with OAuth 2 [RFC6749], considerations have been made to enable the use of OAuth 2 concepts and constructs more smoothly within the GNAP protocol.¶

In this scenario, the client developer has a client_id and set of scope values from their OAuth 2 system and wants to apply them to the new protocol. Traditionally, the OAuth 2 client developer would put their client_id and scope values as parameters into a redirect request to the authorization endpoint.¶

HTTP 302 Found
Location: https://server.example.com/authorize
  ?client_id=7C7C4AZ9KHRS6X63AJAO
  &scope=read%20write%20dolphin
  &redirect_uri=https://client.example.net/return
  &response_type=code
  &state=123455

Now the developer wants to make an analogous request to the AS using the new protocol. To do so, the client makes an HTTP POST and places the OAuth 2 values in the appropriate places.¶

POST /tx HTTP/1.1
Host: server.example.com
Content-type: application/json
Detached-JWS: ejy0...

{
    "resources": [
        "read", "write", "dolphin"
    ],
    "client": "7C7C4AZ9KHRS6X63AJAO",
    "interact": {
        "redirect": true,
        "callback": {
            "method": "redirect",
            "uri": "https://client.example.net/return?state=123455",
            "nonce": "LKLTI25DK82FX4T4QFZC"
        }
    }
}

The client_id can be used to identify the client's keys that it uses for authentication, the scopes represent resources that the client is requesting, and the redirect_uri and state value are pre-combined into a callback URI that can be unique per request. The client additionally creates a nonce to protect the callback, separate from the state parameter that it has added to its return URL.¶

From here, the protocol continues as above.¶