Add to pgrst docs

[steve-chavez]

Just a reminder that it would be great to have this on the postgrest docs!

I think you could add this as a how-to(like in http://postgrest.org/en/v7.0.0/how-tos/providing-images-for-img.html) since it's hard to follow the sequence of the current tutorials on the docs.

Ideally I would also cleanup http://postgrest.org/en/v7.0.0/auth.html and make it only about roles and then have JWT and Sessions be two different topics. But you might refer to authentication sequence to keep the content shorter.

[monacoremo]

@steve-chavez That would be great! The key will be to keep the text short and staying close to recommendation in https://documentation.divio.com/how-to-guides/ . Maybe also refer to https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html

It might also be worth to remove the section on SQL JWT signing. Securely implementing that scheme would require some kind of token revocation mechanism (e.g. with a blacklist), which I think would always be as complicated (but probably more, and more risky) than using sessions. If that's the case, there might be no valid use case for signing JWTs in the db. What do you think?

A bit unrelated: I was wondering why the docs are in a separate repository - is there a specific reason, or is it historical? It seems it would make things a bit easier if the repositories were merged (e.g. to ensure that each PR has documentation, keeping versions in sync, common CI etc.)

[steve-chavez]

It might also be worth to remove the section on SQL JWT signing.

The revocation aspect of JWT is a major shortcoming, I agree!

Blacklist paired with Custom Validation is what we recommend. But it always leaves doubts on users.

However I believe it does offers some benefits: stateless, integration with third-party auth(Auth0, Keycloak, etc). It also has some history to it(this one is the oldest issue I remember about: PostgREST/postgrest#260) and many users.

Personally, I would prefer your sessions approach be the default recommendation for auth, it's simpler to understand and familiar. But JWT should remain as an option.

The best outcome I can think of is making http://postgrest.org/en/v7.0.0/auth.html only about roles and then have two subpages on JWT and sessions.

[steve-chavez]

A bit unrelated: I was wondering why the docs are in a separate repository - is there a specific reason, or is it historical? It seems it would make things a bit easier if the repositories were merged

I don't have the exact issue number but it used to be that the docs and code were on the same repo. IIRC they were split because a change on the docs meant a CI trigger. It also made the repo extra loaded with commits and harder to follow.

From my experience on maintaining the docs, I think it's good to have two separate repos.
I'm certain I wouldn't have had the focus to think how to structure them(consequently finding the divio docs), if they were next to the codebase. A dedicated repo also allows me to track pure doc issues better. Lastly, I also see docs projects like https://github.com/godotengine/godot-docs do well. That makes me think it's good to have the doc repo.

Though I may be making doc maintenance extra hard with the CHANGELOG duplication. I haven't thought about that well. I do that mostly to inform users of new additions to the docs.

Main advantage of having it all one repo is that it makes it harder to forget to update some change/addition. But maybe we can somehow work around this, perhaps a github PR template.

[monacoremo]

However I believe it does offers some benefits: stateless, integration with third-party auth(Auth0, Keycloak, etc). It also has some history to it(this one is the oldest issue I remember about: PostgREST/postgrest#260) and many users.

@steve-chavez Totally agree, JWTs are fine in general, especially for integrating with other services! Just signing them from the database does not make much sense if you think though, as it leads to unnecessary complexity and can never be stateless securely, I think.

Sessions are not super simple to implement either, unfortunately. Maybe it would make sense to include an even simpler alternative with Nginx basic auth. Then we would have something like:

• For small projects: How to password-protect your PostgREST API with Nginx basic authentication (we could brainstorm here)
• For integrating with other applications: How to authenticate PostgREST users with JWTs from other applications
• For creating applications: How to implement session-based authentication for PostgREST applications

I'm certain I wouldn't have had the focus to think how to structure them(consequently finding the divio docs), if they were next to the codebase.

This is the key point I think, and probably one of the drivers why PostgREST has so excellent documentation. Makes sense to me :-)

[steve-chavez]

One doubt that I have is if those should be how-tos or explanations. JWT and sessions would be integral to postgrest auth. Maybe they'd be a mix, with the explanation linking to the how-to. The nginx basic auth would definitely be a how-to.

You certainly have good ideas on how to evolve the docs :)

I'm wondering if we could iterate better on these if I had some sort of way of making a PR publish to readthedocs directly(on a dedicated url for the branch). Not sure how larger docs projects handle this or if it's possible.

[monacoremo]

@steve-chavez Hm, that's a good question... maybe the basic auth approach could even be a tutorial, as it would guide through basics like nginx reverse proxy, separating the api schema etc. Let's think a bit more about it.

Building PRs on readthedocs should be possible, I found this: https://docs.readthedocs.io/en/stable/guides/autobuild-docs-for-pull-requests.html

[steve-chavez]

Hey @monacoremo. Just some update. I opened PostgREST/postgrest-docs#328 for reminding myself of the autobuild PRs.

Also regarding doc maintenance, I'm thinking that instead of duplicating the contents of the CHANGELOG.md on the docs, maybe we should make the docs upcoming page the source of truth.

Then the github release would point to the docs page instead of showing the CHANGELOG contents.

I've seen that godot does it like this https://github.com/godotengine/godot/releases.

Though they separate docs changelog from code changelog. But that would be one page for us.

Might make doc maintenance easier..