An illustrated guide to OAuth

I am implementing oauth right now, along with oidc. I must say that for such a simple concept, getting to the facts that help me to actually implement it is insanely hard. I have no idea why but everywhere i look it just seems like it only scratches the surface and you get no tangible information that you can use to actually implement it in code. I ended up mostly browsing the specs and grok was insanely helpful to explain meaning of various things where information was lacking or buried deep in documentation/specifications. I would say this was the first time where i actually appreciated these new "AIs", which i don't use at all.

When I implemented Oauth2 (Authorization Code Grant, both sides), I found this guide to be quite helpful: https://alexbilbie.github.io/guide-to-oauth-2-grants/

One thing I found after a while: even though the refresh tokens should theoretically not expire, many sites do expire them. You have to refresh every once in a while to maintain a usable refresh token.

Many people will tell you to "just use a library", but I found that the contact surface of oauth with your app is quite large, such that a library might not actually help much. This (among other reasons) is why I wrote my own implementation (Clojure).

> the refresh tokens should theoretically not expire

That is subjective. In essence, they should last long enough so the client can use them to get new access token without the user(resource owner) having to authorise a new grant. Each client is different with different needs and the scopes might be too sensitive to provide a long lasting access. So as usual, it depends.

In my server implementation, access tokens are valid for one hour and refresh tokens for 30 days. I also return refresh tokens with each access token request, so as long as the client makes at least one request per month, they do not have to bother the user for a new grant.

I just wish the spec would have a dedicated "refresh_expires_in" field in addition to "expires_in" for refresh tokens, so the client would be better informed about this. As refresh tokens are part of the spec, though optional, their life span information is lacking here.