Grant Negotiation Access 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. The RC is identified by its key, and 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)

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. ]]¶

1.2. 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. 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 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.¶
• (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).¶
• (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.¶

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) +>|      |
    |        |                                  |        |  Code   |      |
    |        |--(8)--- Continue Request (A) --->|        |         |      |
    |        |                                  |        |<+ (5) +>|      |
    |        |<-(9)-- Not Yet Granted (Wait) ---|        |  AuthN  |      |
    |        |                                  |        |         |      |
    |        |                                  |        |<+ (6) +>|      |
    |        |                                  |        |  AuthZ  |      |
    |        |                                  |        |         |      |
    |        |                                  |        |<+ (7) +>|      |
    |        |                                  |        |Completed|      |
    |        |                                  |        |         |      |
    |        |--(10)-- Continue Request (B) --->|        |         +------+
    |        |                                  |        |
    |        |<-(11)----- 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 element. This element 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"
                ]
            }
        ]
    }

2.2. Requesting User Information

If the RC is requesting information about the RO from the AS, it sends a subject element 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.¶

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 by Key

When sending a non-continuation request to the AS, the RC MUST identify itself by including the key field in the request and by signing the request as described in Section 8.¶

When sent by value, the key MUST be a public key in at least one supported format and MUST contain a proof property that matches the proofing mechanism used in the request. If the key is sent in multiple formats, all the keys MUST be the same. The key presented in this field MUST be the key used to sign the request.¶

proof

The form of proof that the RC will use when presenting the key to the AS. The valid values of this field and the processing requirements for each are detailed in Section 8. This field is REQUIRED.¶

jwk

Value of the public key as a JSON Web Key. MUST contain an "alg" field which is used to validate the signature. MUST contain the "kid" field to identify the key in the signed object.¶

cert

PEM serialized value of the certificate used to sign the request, with optional internal whitespace.¶

cert#256

The certificate thumbprint calculated as per OAuth-MTLS [RFC8705] in base64 URL encoding.¶

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

[[ Editor's note: we will eventually want to have fetchable keys, I would guess. Things like DID for key identification are going to be important. ]]¶

This non-normative example shows a single key presented in multiple formats using a single proofing mechanism.¶

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

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 are of methods are described in Section 8.¶

Continuation requests (Section 5) MUST use the same key and proof method as the initial request.¶

[[ Editor's note: additional client attestation frameworks will eventually need to be addressed here beyond the presentation of the key. 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 the key identifier. ]]¶

  "key": "7C7C4AZ9KHRS6X63AJAO"

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 capabilities in its request.¶

"user": "XUT2MFM1XBIKJKSDU8QM"

2.5. Interacting with the User

If the RC is capable of driving interaction with the RQ, and the client presumes the RQ can act as the RO, the RC SHOULD declare the means that it can interact using the "interact" field. This field is a JSON object with keys that declare different interaction capabilities. A RC MUST NOT declare an interaction capability it does not support.¶

The RC MAY send multiple capabilities 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 capabilities (Section 3.3) in a request, depending on its capabilities and what is allowed to fulfill the request. This specification defines the following interaction capabilities:¶

<spanx style="verb">redirect</spanx>

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

<spanx style="verb">app</spanx>

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

<spanx style="verb">callback</spanx>

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

<spanx style="verb">user_code</spanx>

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¶

<spanx style="verb">ui_locales</spanx>

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 capabilities. Additional interaction capabilities are defined in a registry TBD (Section 12).¶

[[ Editor's note: there need to be more examples (Appendix C) that knit together the interaction capabilities 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": {
    "callback": {
       "method": "redirect",
       "uri": "https://client.example.net/return/123455",
       "nonce": "LKLTI25DK82FX4T4QFZC"
    }
}

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

"interact": {
    "user_code": true
}

"interact": {
    "ui_locales": ["en_US", "fr_CA"]
}

2.6. Providing Displayable RC Information

If the RC has additional information to display to the RO during any interactions at the AS, it MAY send that information in the "display" field. This field is a JSON object that declares information to present to the RO during any interactive sequences.¶

name

Display name of the RC software¶

uri

User-facing web page of the RC software¶

logo_uri

Display image to represent the RC software¶

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

[[ Editor's note: would we want to support pushing a display logo by value? On the upside it allows for more dynamic detached clients and doesn't require the AS to fetch information. On the downside, this is harder for the AS to enforce a policy about and could lead to potential exploits caused by sending binary image files. ]]¶

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

The AS SHOULD use these values during interaction with the RO. The values are for informational purposes only and MUST NOT be taken as authentic proof of the RC's identity or source. The AS MAY restrict display values to specific RC instances, as identified by their keys in Section 2.3.¶

[[ Editor's note: this might make sense to combine with the "key" field, but some classes of more dynamic client vary those fields separately from the key material. We should also consider things like signed statements for client attestation, but that might fit better into a different top-level field instead of this "display" field. ]]¶

2.7. 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.8. 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 reference handle 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? ]]¶

2.9. 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 an 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: I'm not a fan of GNAP defining how OIDC would work 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. ]]¶

2.10. 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 Handle

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.¶

handle

REQUIRED. A unique reference for continuing the request.¶

uri

REQUIRED. The URI at which the RC can make continuation requests. This URI MAY vary per RC or ongoing request, or MAY be stable at the AS. 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.¶

expires_in

OPTIONAL. The number of seconds in which the handle will expire. The RC MUST NOT use the handle past this time. The AS MUST respond to an expired handle with an error. Note that the handle MAY be revoked at any point prior to its expiration.¶

{
    "continue": {
        "handle": "80UPRY5NM33OMUKMKSKU",
        "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.¶

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 combination of a "handle" and "uri" really feels like the access token pattern. Perhaps the exact constructs for tokens could be re-used here instead of something special for the request continuation? Especially if we're using some kind of directed access token mechanism. ]]¶

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",
        "proof": "bearer",
        "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"
        ]
    }

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

3.3. Interaction Capabilities

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 capabilities in the response, and it is up to the RC to determine which ones to use.¶

The AS MUST NOT respond with any interaction capability that the RC did not indicate in its request.¶

    "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..."
   }
}

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's keys (Section 2.3.2) 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. 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 used to be objects to allow for expansion to future elements, 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).¶

key_handle

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

user_handle

A 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",
    "key_handle": "7C7C4AZ9KHRS6X63AJAO",
    "access_token": {
        "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
        "proof": "bearer"
    }
}

[[ 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? 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. ]]¶

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_handle

The request referenced an unknown handle.¶

[[ 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) capability, 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) capability, 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" capability (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) capability 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 capability 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.¶

[[ 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. ]]¶

The AS MUST calculate a hash value as described in Section 4.4.3. The RC will use this value to validate the return call from the AS.¶

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 AS then MUST send the hash and interaction reference based on the interaction finalization capability 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 Finalized Interaction

If the RC has received an interaction reference from a "callback" (Section 4.4.1) message, the RC MUST include the "interaction_ref" in its continuation request. The RC MUST validate the hash before making the continuation request, but note that the RC does not send the hash back to the AS in the request.¶

{
  "handle": "tghji76ytghj9876tghjko987yh",
  "interact_ref": "4IFWWIKYBC2PQ6U56NL1"
}

5.2. Continuing after Tokens are Issued

A request MAY be continued even after access tokens have been issued, so long as the handle is valid. The AS MAY respond to such a continuation request with new access tokens as described in Section 3.2 based on the RC's original request. The AS SHOULD revoke existing access tokens. If the AS determines that the RC can make a further continuation request in the future, the AS MUST include a new "continue" response element (Section 3.1). The returned handle value MUST NOT be the same as that used to make the continuation request, and the continuation URI MAY remain the same. If the AS does not return a new "continue" response element, the RC MUST NOT make an additional continuation request. If the RC does so, the AS MUST return an error.¶

[[ Editor's note: There is significant overlap here with the functionality that allows the rotation of an individual access token in the next main section. It seems like this would still be needed to modify the entire request, but for the common case where you've got a single access token in the response, you've got two ways to do almost the same thing, which is confusing for client developers. We need to discuss how best to manage these patterns in concert with each other. ]]¶

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....

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. 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.¶

{
    "access_token": {
        "value": "FP6A8H6HY37MH13CK76LBZ6Y1UADG6VEUPEER5H2",
        "proof": "bearer",
        "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, signing the request with its key.¶

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

If the token was issued to the RC identified by the key, the AS MUST invalidate the access token, if possible, and return an HTTP 204 response code.¶

204 No Content

If the access token has expired, 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.¶

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.¶

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.¶

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¶

[[ 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. ]]¶

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? ]]¶

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

{
    "display": {
        "name": "My Client Display Name",
        "uri": "https://example.net/client"
    },
    "resources": [
        "dolphin-metadata"
    ],
    "interact": {
        "redirect": true,
        "callback": {
            "method": "redirect",
            "uri": "https://client.foo",
            "nonce": "VJLO6A4CAYLBXHTR0KRO"
        }
    },
    "key": {
        "proof": "jwsd",
        "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"
        }
    }
}

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 the method or URL of the request in the signature, but it's simple to calculate and useful for body-driven requests, like the client to the AS. We might want to remove this in favor of general-purpose HTTP signing. ]]¶

8.2. Attached 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.¶

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¶

[[ 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. ]]¶

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

[[ 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 requires things to be sent in the body. 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. Furthermore, it doesn't protect the method or URL of the request in the signature. We might want to remove this in favor of general-purpose HTTP signing. ]]¶

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

{
    "display": {
        "name": "My Client Display Name",
        "uri": "https://example.net/client"
    },
    "resources": [
        "dolphin-metadata"
    ],
    "interact": {
        "redirect": true,
        "callback": {
            "method": "redirect",
            "uri": "https://client.foo",
            "nonce": "VJLO6A4CAYLBXHTR0KRO"
        }
    },
    "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: ]]¶

8.4. 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

{
    "display": {
        "name": "My Client Display Name",
        "uri": "https://example.net/client"
    },
    "resources": [
        "dolphin-metadata"
    ],
    "interact": {
        "redirect": true,
        "callback": {
            "method": "redirect",
            "uri": "https://client.foo",
            "nonce": "VJLO6A4CAYLBXHTR0KRO"
        }
    },
    "key": {
        "proof": "dpop",
        "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=

{
    "display": {
        "name": "My Client Display Name",
        "uri": "https://example.net/client"
    },
    "resources": [
        "dolphin-metadata"
    ],
    "interact": {
        "redirect": true,
        "callback": {
            "method": "push",
            "uri": "https://client.foo",
            "nonce": "VJLO6A4CAYLBXHTR0KRO"
        }
    },
    "key": {
        "proof": "httpsig",
        "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 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¶
• 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

{
    "display": {
        "name": "My Client Display Name",
        "uri": "https://example.net/client"
    },
    "resources": [
        "dolphin-metadata"
    ],
    "interact": {
        "redirect": true,
        "callback": {
            "method": "redirect",
            "uri": "https://client.foo",
            "nonce": "VJLO6A4CAYLBXHTR0KRO"
        }
    },
    "key": {
        "proof": "oauthpop",
        "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"
    ],
    "proof": "httpsig",
    "key": {
        "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.8 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"
    ],
    "key": "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"
    ],
    "key": "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"
            ]
        }
    ],
    "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 key handle to identify itself in future calls.¶

Content-type: application/json

{
    "interact": {
       "redirect": "https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ",
       "callback": "MBDOFXG4Y5CVJCX821LH"
    }
    "continue": {
        "handle": "80UPRY5NM33OMUKMKSKU",
        "uri": "https://server.example.com/continue"
    },
    "key_handle": "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
Detached-JWS: ejy0...


{
    "handle": "80UPRY5NM33OMUKMKSKU",
    "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",
        "proof": "bearer",
        "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": {
        "handle": "80UPRY5NM33OMUKMKSKU",
        "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"
    ],
    "key": "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": {
        "handle": "80UPRY5NM33OMUKMKSKU",
        "uri": "https://server.example.com/continue",
        "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.¶

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


{
    "handle": "80UPRY5NM33OMUKMKSKU"
}

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": {
        "handle": "BI9QNW6V9W3XFJK4R02D",
        "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
Content-type: application/json
Detached-JWS: ejy0...


{
    "handle": "BI9QNW6V9W3XFJK4R02D"
}

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",
        "proof": "bearer",
        "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"
    ],
    "key": "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": {
        "handle": "80UPRY5NM33OMUKMKSKU",
        "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
Content-type: application/json
Detached-JWS: ejy0...


{
    "handle": "80UPRY5NM33OMUKMKSKU"
}

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": {
        "handle": "BI9QNW6V9W3XFJK4R02D",
        "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
Content-type: application/json
Detached-JWS: ejy0...


{
    "handle": "BI9QNW6V9W3XFJK4R02D"
}

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",
        "proof": "bearer",
        "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"
    ],
    "key": "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.¶