Suggestion: Define the response message for expired JWT as part of the spec

[abkarcher]

Hello!

The spec currently indicates that in the case of an expired JWT, the server will send the client a 401 status code. However, as this code could be the result of an expired JWT, an invalid JWT, or (hypothetically) a bug/feature on server (or proxy) infrastructure, it would be good for the server to respond with a spec-defined message that indicates that a JWT is expired.

That way, clients can reliably take the needed refresh action automatically instead of requiring user intervention (and automation is the goal!)

In our case, we are automatically refreshing when we get a JWT expired message, but there is no way for our client to be able to handle changes in the phrasing of that message (or formatting of the JSON, as we just discovered this week). We are simply looking for the substring "JWT expired" in an error item. While this logic is not ideal, it is still better than requiring user intervention, so having ACV servers send a consistent JWT expired message would make automating this process more reliable.

Thanks,
Andrew

[Kritner]

Could probably benefit from #863.

Currently we put the expiration datetime in UTC in the returned message, and this is what you'd like to avoid?

#883 (comment) being an example expiration message.

Thoughts @celic @shaneshaffer @smuellerDD @bfussell ? I'm fine with making that change something along the lines of "JWT expired".

[abkarcher]

Thanks for the links! If people wanted to keep expiration datetime, I think it could be beneficial to have it be its own JSON Object - Ideally, In my opinion, it would be ideal to have at least one JSON object to look for that will be consistently identical in the case of an expired JWT.

I do like the suggestion that was made of having error codes in the JSON itself as well - this makes it much easier for clients to handle specific scenarios from the server in a future-proof way, assuming the error codes were indicated in the spec. HTTP status codes are nice but subject to the whims of proxies or other infrastructure specifics.

[AlexThurston]

👍 to this. HTTP codes give loosely defined reasons, but internally define errors code give users of the API much more detail and flexibility in how to behave/respond.

[smuellerDD]

Am Montag, 22. Juni 2020, 18:31:00 CEST schrieb Alex Thurston: Hi Alex,

👍 to this. HTTP codes give loosely defined reasons, but internally :define errors code give users of the API much more detail and flexibility :in how to behave/respond.

I second that: I would like to see documented error codes. The HTTP errors are too coarse for the purpose of a RESTAPI. See the 403 HTTP error that we discuss here - ACVP may have several more error codes that can indicate the issue. E.g. error codes for authentication failed, JWT expired, JWT missing, etc. Note HTTP error codes are good for the purpose of the simple HTTP. But RESTAPI is another layer *on top* of HTTP and constitutes a full API. Hence, we should treat it like an API and apply this logic. RESTAPI relates to HTTP like a network-transparent protocol to, say, RPC. RPC has error codes, but applying them to the protocol on top is not going to be helpful. What I recommend is the following: for each RESTAPI endpoint, the SPEC should have a subsection error code. That subsection may remain empty for now, but should be enhanced over the time. When we agree on a numeric error code, I would like to recommend to use different "namespaces" per endpoint. E.g. /login gets the error "namespace" of 100 through 199. /testSessions gets 200 through 299. And so on. In this thread, the issue was raised that somebody wants to see some human- readable text. As the ACVP server already offers such text, I think this return JSON object should just be enhanced with an error code and keep the existing human-readable text. Yet, the human-readable description may be optional, but the numeric error code should be mandatory. This approach allows also adding new human-readable error responses while the ACVP server is further developed. With that, I would assume all use cases should be covered. Ciao Stephan

[dmchodnicki]

This item has been incorporated into a new Error Code Enhancement ticket and is therefore being Closed. Please refer to #1070 for future updates.