Explain use cases of JWT token and resolver endpoint better

[chpapa]

Restructure https://docs.authgear.com/get-started/backend-api/backend-integration into explain there are different patterns for:

• Authorization headers + JWKS;
• Auth + Resolver;
• Cookies + JWKS;
• Cookies + Resolver.

Btw Cookies + JWKS depends on authgear/authgear-server#1180)

Don't mention Resolver is recommended, as JWKS should be easier to implement for most users

Instead, show a few common architecture for integrations.

Mention:

1. Developers can use auth_time to check recency of session for reauthenticate (eg before users make transaction), links to reauthentication how to
2. Developers can make certain path check resolver endpoint, to ensure the session is not revoked. Shorten accesstoken life time or resolver result cache time can shorten the time between user session is revoked and the user actually blocked from access

[Boburmirzo]

@chpapa @fungc-io Good, I will work on that!

[Boburmirzo]

@chpapa @fungc-io Backend integration page, the following JWT validation in your application server pages have been updated according to the GitHub issue:

https://docs.authgear.com/get-started/backend-api/backend-integration

https://docs.authgear.com/get-started/backend-api/jwt#check-the-validity-of-jwt

[fungc-io]

@louischan-oursky correct me if i'm wrong.

The auth_time exists in ID token but not JWT token, the backend server cannot use the auth_time to "validate" the JWT.

But rather it can be used to ensure the client has just authenticated recently, if the API call includes the ID Token in it. But this is not included in the JWT token. The developer don't need to include the ID token in every request, they can use the exp to validate the request given they have setup a short enough JWT lifetime.
If the sensitive API requires recency < the JWT lifetime, they should use the auth_time in ID Token instead.

[chpapa]

• I think normal oidc practices shouldn't include ID token which have explicit aud for client, to the API resources
• so if auth_time is expected to be the way for API backend to validate the login session is recent enough, I think the right way should be put that into access token (JWT) as well? (Similiar to the common use case of role)

Product-design wise, feel more and more like we should make it really simple to add different claims to the JWT access token. Thoughts?

[Boburmirzo]

Yeah, interesting problem. I wrote just based on knowledge Reauthentication process:

https://docs.authgear.com/how-to-guide/authenticate/reauthentication

I came across this use case from Auth0 using OIDC prompt=login param to force reauthentication.

https://auth0.com/docs/authenticate/login/max-age-reauthentication

[louischan-oursky]

Product-design wise, feel more and more like we should make it really simple to add different claims to the JWT access token. Thoughts?

Agree. Opened authgear/authgear-server#3296