Grant Management API Query Response expiration and issued at

[Jacob Ideskog]

The API Query response is missing a few key fields that I think would be helpful for the client to be aware of.

I propose the following fields to be added to the top level response object in section 6.4 “Query Status of Grant”

---

iat : (required) A valid JSON number representing the UTC epoch date/time in seconds when the grant was issued

exp: (required) A valid JSON number representing the UTC epoch date/time in seconds when the grant expires

last_updated : (required) A valid JSON number representing the UTC epoch date/time in seconds when the the grant was last updated.

---

I’m on the fence if the last_updated field should be required, but I think it should at least be required if the grant has been updated after its creation.

[Torsten Lodderstedt]

sounds reasonable. However, I would not make any of those claims mandatory, especially exp. The OP does not necessarily establish an expiration date for a grant or the exp is extended with every token issuance.

[Stuart Low]

I concur with Torsten on not being mandatory. I’m also a bit dubious about last_updated as the definition of a grant “update” could be a bit ambiguous. Finally on exp I wonder how to purvey the expiration for grants involving multi-dimensional durations (ie. Permission A for 1 week, Permission B for 2 months, is the grant exp 2 months?)

[Dima Postnikov]

Thanks @Jacob Ideskog for raising this one.

Given that we are exposing existing grant records, it makes sense to expose these metadata fields as optional.

last_updated

We can leave the exact definition of last_updated up to AS, still can be useful. Although, it would help if last_updated indicates when the grant was updated by a user or by the AS.

exp

We should be clear that exp is a property of a grant, and not the individual permissions included in the grant.

When we previously discussed expiry we said that we don’t want to enforce grant expiry as it is not applicable to all implementations: https://bitbucket.org/openid/fapi/issues/355/grant-management-should-grants-expire. So “optional“ would make sense.

iat

It might make sense to be clear for the replace action that this field should be reset.

Thoughts?

@Takahiko Kawasaki @Jacob Ideskog @Brian Campbell @Filip Skokan We would be keen to get you views..

‌

[Tom Jones]

The very idea that a grant comes from an OP makes my skin crawl. Grants should be at the consent of the RO. And they certainly should be required to have a exp.

[Dima Postnikov]

@Takahiko Kawasaki @Lukasz Jaromin @Jacob Ideskog @Brian Campbell @Filip Skokan We would be keen to get you views on this issue

[Brian Campbell]

Expiration definitely shouldn’t be required. Issued at doesn’t really seem like the right term. Maybe created at? Maybe don’t use/overload JWT claim names at all - expires, created, updated or something like that. The created / iat value shouldn’t change.

‌

[Jacob Ideskog]

Yes, created at feels a bit more appropriate as you say @Brian Campbell . It makes sense to keep these fields optional, the one we’ve ran into the most with regards to consent is the expiration, since it’s required by PSD2 to re-require consent after 90 days (if I remember correctly).

Does last_updated need to convey if it was the AS or the Client? Not sure, what case is a good example where the AS updates the grant without the user’s involvement? I can only think of revocation, which then would be signaled by the fact that the grant is revoked.

I agree with @Dima Postnikov that the expiration should be of the entire grant. Different implementations may expire different parts of a grant such as scopes or claims differently, which is not something this spec handles.

[Dima Postnikov]

Thanks @Brian Campbell ,

Happy to change to created_at.

In regards to changes to all metadata field names not overloading JWT names and changing to expires, created and last_updated, what does everyone think? @Torsten Lodderstedt @Jacob Ideskog ?

Thanks @Jacob Ideskog , yes revocation is the one we were thinking of. Potentially we could have updated_by or something like that?

[Jacob Ideskog]

I have no strong opinion about the updated_by idea. It makes sense as an optional field, perhaps then as an enum of authorization_server or client. The problem is that we probably don’t want to expose the client id here, since the grant may be updated by other mechanisms than grant management such as a god-client that kills all grants etc. So the entity that updated the grant may be something the spec don’t take into account. That makes he enum less useful.

I suggest that expiresand created are named expires_at and created_at to match response values of the token endpoint (expires_in). It’s good to know if it’s a timestamp or a duration just by looking at the name.

‌

[Takahiko Kawasaki]

If asked, I would say that it would be difficult to define time-related properties now. One of reasons is that the specification has room for different "lifecycle" interpretations and implementations. Probably, it would be wise to postpone introducing time-related properties until we accumulate experience through actual deployments of Grant Management.

[Jacob Ideskog]

I agree with the problem of the lifecycle definition but I disagree that it should wait. I think that omitting these now will cause implementations to use custom time properties since it is often relevant for implementations to know. That will make it harder to standardize later. Perhaps the lifecycle doesn’t have to be well defined by the spec, but there’s some common ground. A first time a grant is created, a time when it is updated and sometimes it can expire, but probably not always.

[Dima Postnikov]

Thanks @Takahiko Kawasaki , @Brian Campbell and @Jacob Ideskog .

I think, this is the summary of where we are now:

‌

last_updated

optional timestamp field that indicates when the grant was last updated.

expires_at

optional timestamp field that indicates when the grant expires.

created_at

optional timestamp field that indicates when the grant was originally created. This value must be reset if `replace` grant management action was used.

updated_by

optional string value that indicates who updated the grant. Allowed values are 'client' and “authorization_server“.

[Dima Postnikov]

@Takahiko Kawasaki @Brian Campbell @Jacob Ideskog @Torsten Lodderstedt could you please review?

[Jacob Ideskog]

It looks good, but I wonder if we create ambiguity when resetting created_at on replace. Isn’t it enough to use last_updated for that.

Problem:

new grant: last_updated == created_at

updated grant: last_updated > created_at

replaced grant: last_updated == created_at

So we can’t distinguish between a replace and a create, perhaps that’s the idea. But since a replaced grant uses the same grant_id for a new purpose (new scopes) it feels like there should be some traceability that this happened. Replace is an odd bird operation in this sense so perhaps there isn’t a clean solution without adding even more fields (which I don’t think we should). Personally I’d rather leave created_at still and only touch last_updated after creation. But I might be missing a use-case here.

‌

[Brian Campbell]

Agree w/ Jacob that created_at shouldn’t change.

‌

[Nat Sakimura]

Dima to prepare a PR

[Dima Postnikov]

PR created https://bitbucket.org/openid/fapi/pull-requests/389

[Dima Postnikov]

PR merged

[Dima Postnikov]

change completed