Pushed Request Object - The payload of the response

[Takahiko Kawasaki]

In some REST API practices, when a server returns 201 Created, the response contains the registered/created resource in its HTTP message body. If this practice is followed, a response from the request object endpoint should contain the payload part of the registered request object or the request object itself. (Note that I myself don't insist that the request object endpoint should follow this practice.)

From a viewpoint of the practice, the HTTP message body in the response from the request object endpoint in the current draft is confusing. It's because iss and aud are not for the registered request object while exp is for the registered request object. That is, claims of different entities are mixed in the HTTP message body.

Probably, request_uri and expires_in are enough. If we wanted to include iss, aud, exp and other well-known claims in the response from the request object endpoint, the HTTP message body of the response should be the payload part of the registered request object or the request object itself.

[Torsten Lodderstedt]

I personally think returning the request URI is sufficient. This is an open issue in the spec.

What would be the best way to return it? in the body or the header?

[Takahiko Kawasaki]

If we follow CIBA, Device Flow and RFC 6749, JSON in the response body.

CIBA: response from the backchannel authentication endpoint which issues an auth_req_id. The expires_in property represents the lifetime of the auth_req_id.

{
  "auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac1",
  "expires_in": 3600,
  "interval": 2
}

‌

Device Flow: response from the device authorization endpoint which issues a device_code and a user_code. The expires_in property represents the lifetime of the device_code and the user_code.

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://example.com/device",
  "verification_uri_complete":
  "https://example.com/device?user_code=WDJB-MJHT",
  "expires_in": 1800,
  "interval": 5
}

‌

RFC 6749 Flows: response from the token endpoint which issues an access_token. The expires_in property represents the lifetime of the access_token.

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter":"example_value"
}

‌

If we omitted a property that represents the lifetime of the registered request object (i.e. expires_in), we would be asked to explain why expires_in is included in responses from the backchannel authentication endpoint, the device authorization endpoint and the token endpoint, but it is not included in responses from the request object endpoint. Personally, however, I don't have strong reasoning to include or omit expires_in .

[Torsten Lodderstedt]

thanks for the explanation

I personally consider “expires_in” to be rather useless as any of those elements can be revoked anytime. Have you (or someone else) every written code that uses this data?

[Joseph Heenan]

I’ve certainly found knowing whether the ‘expires_in’ value is 10 seconds or 10 days to be useful when experimenting with APIs or determining the reason for failed API requests. That probably doesn’t quite count as writing code that uses expires_in. I’ve almost certainly written code that assumes an access token doesn’t expire within a few minutes of obtaining it. (I’m not necessarily sure I should admit to having done so. It was a quick hack, honest, not production code...)

[Brian Campbell]

Maybe a bit of confirmation bias but I think this issue is further evidence around the question/discussion in the document itself.

‌

Question: What is the value of returning iss and aud? Does the exp really add anything given the text encourages one-time use of the request object?

(BC QUESTION/RESPONSE: I suspect Nat will say there's value in explicitly identifying the participants in any exchange. But I'm not so sure myself (they are already identified by HTTPS and client authentication/identification) and worry a little that iss and aud will only confuse in this context (case in point the definition of iss above is rather confusing referring to JWT/RFC7519 for the definition of an authorization server issuer rather than RFC8414 but also mentioning 'the redirection URI' as the issuer for the AS). I also don't see what value exp adds here - is it anything more than a hint to the client about how long the request_uri will be valid? I don't see the use in that. And using something like expires_in similar to RFC6749 with a relative value of how long the URI is valid would be more appropriate for that anyway, if it were needed.)

[Torsten Lodderstedt]

moved over to draft-oauth-par