Subject: [GNAP] Proposed Access Token Request/Response Syntax Updates

From: Justin Richer <[email-masked]>
Date: Tue, 26 Jan 2021 16:48:58 -0500

As discussed on the last call, the editors have put together a proposed syntax change for requesting and receiving access tokens, both single and multiple. The proposed changes are found here:

https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/162 <https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/162>

You can see both the diffs and the rendered preview there, as always. There’s a lot going on in this one, but it’s all around access tokens:

- The old “resources” array that signaled requesting an access token, which used to exist at the top level of the request, has now been moved into an “access_token” object within the request and renamed “access”. 
- This top level object now has additional fields including “flags”, to encompass the old “token flag” functionality that had been previously rolled into the “resources” array
- The token request and response now have a “label” field for directing the client instance on what to do with each token it gets back (required in the multiple token state).
- Bound tokens are now the default for the protocol. To request a bearer token, you now have to include the flag “bearer” explicitly
- The token response object now has both a “bound” and “key” field, to encompass functionality that was previously in the “key” field alone.
- The token response object now has a “durable” field that allows the AS to signal token rotation behavior. The client no longer has a means to request changes in this behavior (but a flag could be defined if this signaling is desired). 
- The old “multiple_access_token” response field is replaced by the “access_token” field being able to return an array with mandatory internal “label” fields on each token object.

Examples should all be updated. 

The editors think this is moving in the right direction and there are many advantages to this new approach:

- Parallelism for single and multiple tokens
- Parallelism for request and response
- Clear place to put extensions (flags and new object members in request and response)
- Flexibility for directing the client instance where to use a token (labels today, possibly other fields in the future)
- Arguably clearer use of polymorphic structures, e.g. either a an object or an array of those same objects

Even so, there are a few of noted downsides to these changes that people should be aware of:

- The internal “label’ field now needs to be checked for both presence and uniqueness in the multiple access token case. (Previously, this was enforced by syntax.)
- The combination of “bound” and “key” now need to be checked, including an explicitly disallowed combination of “bound: false” with an explicit key. (Previously, this was enforced by syntax.)
- Flags now need to be parsed as strings instead of object member names. 
- The syntax for requesting a single “scope” equivalent for a single access token is now much more complex. 

For that last one, previously a request would look like this:

{
    “resources": [ “scope” ]
}

But now, it needs to look like this:

{
    “access_token”: {
        “access": [ “scope” ]
    }
}

While more explicit and more flexible overall, you can see that it’s also verbose for the simple use case that OAuth 2 systems will particularly be bringing to the table. There are some things we can probably optimize to make this simpler for this case, using polymorphism in limited and unambiguous ways, but those all need to be explored in more depth. As such, the editors recommend addressing any optimizations of this verbosity problem after the base syntax can be agreed on.

Thank you,

 — Justin

---

From: Justin Richer <[email-masked]>
Date: Fri, 29 Jan 2021 13:15:50 -0500

To provide some “running code” to the proposal, I’ve put together a preliminary set of changes that implement the new Access Token syntax in the XYZ Java implementation. You can see the draft set here:

https://github.com/bspk/oauth.xyz-java/pull/11 <https://github.com/bspk/oauth.xyz-java/pull/11>

It works for a handful of basic tests, but I have some more cleanups and a few more changes to do before it’s ready for merge there. Still, it does run if you want to check it out yourself!

Overall it seems to have made the whole JSON parsing simpler to manage (though to be fair, I did also discover a somewhat hidden Jackson feature this week that lets me hook into the parser at a different layer than before and still get reliable behavior). This PR also makes the change to the “key” field and incorporates checking for the bearer flag on token generation, defaulting to bound tokens when the flag isn’t present.

In any event, you can try out the code on the branch if you want to see what this looks like under an actual implementation on both client and server side. The client code in particular prints the relevant HTTP messages to the console.

 — Justin

> On Jan 26, 2021, at 4:48 PM, Justin Richer <[email-masked]> wrote:
> 
> -- 
> TXAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/txauth

---

From: Fabien Imbault <[email-masked]>
Date: Fri, 29 Jan 2021 19:19:43 +0100

Thanks Justin. Will try!

Le ven. 29 janv. 2021 à 19:16, Justin Richer <[email-masked]> a écrit :

> To provide some “running code” to the proposal, I’ve put together a
> preliminary set of changes that implement the new Access Token syntax in
> the XYZ Java implementation. You can see the draft set here:
>
> https://github.com/bspk/oauth.xyz-java/pull/11
>
> It works for a handful of basic tests, but I have some more cleanups and a
> few more changes to do before it’s ready for merge there. Still, it does
> run if you want to check it out yourself!
>
> Overall it seems to have made the whole JSON parsing simpler to manage
> (though to be fair, I did also discover a somewhat hidden Jackson feature
> this week that lets me hook into the parser at a different layer than
> before and still get reliable behavior). This PR also makes the change to
> the “key” field and incorporates checking for the bearer flag on token
> generation, defaulting to bound tokens when the flag isn’t present.
>
> In any event, you can try out the code on the branch if you want to see
> what this looks like under an actual implementation on both client and
> server side. The client code in particular prints the relevant HTTP
> messages to the console.
>
>  — Justin
>
>
> As discussed on the last call, the editors have put together a proposed
> syntax change for requesting and receiving access tokens, both single and
> multiple. The proposed changes are found here:
>
> https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/162
>
> You can see both the diffs and the rendered preview there, as always.
> There’s a lot going on in this one, but it’s all around access tokens:
>
> - The old “resources” array that signaled requesting an access token,
> which used to exist at the top level of the request, has now been moved
> into an “access_token” object within the request and renamed “access”.
> - This top level object now has additional fields including “flags”, to
> encompass the old “token flag” functionality that had been previously
> rolled into the “resources” array
> - The token request and response now have a “label” field for directing
> the client instance on what to do with each token it gets back (required in
> the multiple token state).
> - Bound tokens are now the default for the protocol. To request a bearer
> token, you now have to include the flag “bearer” explicitly
> - The token response object now has both a “bound” and “key” field, to
> encompass functionality that was previously in the “key” field alone.
> - The token response object now has a “durable” field that allows the AS
> to signal token rotation behavior. The client no longer has a means to
> request changes in this behavior (but a flag could be defined if this
> signaling is desired).
> - The old “multiple_access_token” response field is replaced by the
> “access_token” field being able to return an array with mandatory internal
> “label” fields on each token object.
>
> - Flexibility for directing the client instance where to use a token
> (labels today, possibly other fields in the future)
> - The internal “label’ field now needs to be checked for both presence and
> uniqueness in the multiple access token case. (Previously, this was
> enforced by syntax.)
> - The combination of “bound” and “key” now need to be checked, including
> an explicitly disallowed combination of “bound: false” with an explicit
> key. (Previously, this was enforced by syntax.)
> While more explicit and more flexible overall, you can see that it’s also
> verbose for the simple use case that OAuth 2 systems will particularly be
> bringing to the table. There are some things we can probably optimize to
> make this simpler for this case, using polymorphism in limited and
> unambiguous ways, but those all need to be explored in more depth. As such,
> the editors recommend addressing any optimizations of this verbosity
> problem after the base syntax can be agreed on.
>
> Thank you,
>
>  — Justin
> --
> TXAuth mailing list
> [email-masked]