Skip to content

eisenwinter/gotrxx

Repository files navigation

gotrxx

gotrxx is a OAuth2 authorization server written in go, with support for Authorization Code Grant with PKCE, Client Credentials Grant and Password Grant (to mimic gotrue behaviour). It is compatible with netlifycms.

GitHub go.mod Go Report Card Go Project Status: Active – The project has reached a stable, usable state and is being actively developed. License DeepSource Conventional Commits view - Documentation

gotrxx

Whats in the box

  • Authorization Code Grant with Proof Key of Exchange for all your SPA and public needs.
  • Client Credentials Grant for all your Backend and confidential client needs.
  • Password Grant for netlifycms compatibility
  • Discovery Endpoint although it does not support OpenID-connect it has a discovery endpoint for convenient use with oidc-client-ts
  • Flexible signing and verification choice (HS256, HS384, HS512, RS256, RS384, RS512) token signing and verification (very special thanks to jwx)
  • jwk Endpoint when using RS* signing
  • Localization of the pages
  • Administration Endpoints which can be enabled if needed and wanted
  • 2FA with TOTP - works with MS Authenticator, Google Authenticator and Authy and others1
  • Roles for optional ACL implementations
  • optional Invite Only Setup with pre-defined roles and application authorizations
  • optional Clicky Clicky Admin UI gotrxx-admin

(back to top)

Usecase

This authorization server can be used for either a restricted pool of people (like I do for my family and friends) or for public use. The main reason for this to exist is that I wanted to limit the access to applications to certain users, but still be able to make access-for-everyone applications as well.

Use this if

  • you want an easy setup authorization server with OAuth support
  • you have clients, friends, or family you wanna share certain (pre-approved) applications with them
  • you don't need OpenID-connect
  • a full-blown solution (ory, keycloak, identity server) is way too much
  • want to set up a self-hosted Netlify CMS setup with something else then gotrue
  • want an authorizations server that works with either SQLite, Postgres or MariaDB/MySQL

(back to top)

Why

Well, I went a bit overboard. It all started when a family member of mine wanted to edit the static site I made for her and I went on to set up a self-hosted version of netlify CMS. And things did not go as I wanted. Fast-forward - we are here after maniacally coding for weeks (okay it's been on and off for months at this point) because I disliked a few minor things about gotrue2.

(back to top)

Quickstart

Building from source

gotrxx is written and tested against Go 1.19+

git clone https://github.com/eisenwinter/gotrxx.git
go build main.go -o gotrxx

adapt the supplied config.yml to your needs and you are ready.

For further setup please refer to the documentation https://eisenwinter.github.io/gotrxx.

(back to top)

Help and documentation

The documentation can be found at https://eisenwinter.github.io/gotrxx or in the docs folder. If you have any questions you can open an issue and ask.

Docker Images

Yes. We have em.

docker run -v ./config.yml:/app/config.yml:ro ghcr.io/eisenwinter/gotrxx:latest

(back to top)

Documentation

If you want a deeper dive check out the documentation https://eisenwinter.github.io/gotrxx or see the docs folder.

(back to top)

MFA

NOTE: the password flow will fail if you enable MFA on a user

(back to top)

OpenIDConnect

No.

(back to top)

Thanks and shout-outs to

Thank everyone who wrote anything I used, this list in no special order.

go-chi for their awsome router

  • github.com/go-chi/chi/

lestrrat for the awsome jwx libraries (wich do a lot of the heavy lifting)

  • github.com/lestrrat-go/jwx

jaytaylor for not having me make plain text templates as well

  • github.com/jaytaylor/html2text

spf13 for cobra and viper

  • github.com/spf13/cobra
  • github.com/spf13/viper

Masterminds for squirrel

  • github.com/Masterminds/squirrel

jmoiron for sqlx

  • github.com/jmoiron/sqlx

joho for godotenv

  • github.com/joho/godotenv

jeremywohl for flatten

  • github.com/jeremywohl/flatten

mattn for the sqlite driver

  • github.com/mattn/go-sqlite3

go-mail ... for mails

  • github.com/go-mail/mail

adlio for the migrations

  • github.com/adlio/schema

11ty - for making me not regret my static template choice twice

AnandChowdhary for the language icons

  • github.com/AnandChowdhary/language-icons

(back to top)

Special thanks

Well, and of course gotrue, this main inspiration to start this.

(back to top)

Contributing

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue for further questions or recommendations.

(back to top)

License

Distributed under the BSD-2-Clause license. See LICENSE.txt for more information.

(back to top)

Footnotes

  1. Can not be used with Password Grant

  2. gotrue still is a good and well-thought-out solution tough (only love)