🦇  Gothic

Gothic is a user registration and authentication microservice written in Go. It's based on OAuth2 and JWT and will handle user signup, authentication and custom user data.

WHY?

Gothic is a free production-ready authentication server.

It is a complete rewrite of Netlify's GoTrue and is ~85-90% complete.

GoTrue only supports REST + mysql, and is outdated. Auth0 is prohibitively expensive for small startups, garage projects, & consumer applications.

Gothic is designed to get you up and running quickly without having to spend months coding the exact same thing for the umpteenth time —  without sacrificing functionality, or a professional look & feel.

UPDATE

• Docker containers now build and compose correctly on Apple Silicon (arm64).

• REST API is now complete w.r.t. GoTrue's functionality (except for SAML — which was intentionally left out).

• gRPC API is now (95%) complete w.r.t. GoTrue's functionality.

WIP

This project is currently in progress. Things will change. Sometimes big things. Don't @ me.

Getting Started

Installing

To start using Gothic, install Go (version 1.15+) and run go get:

$ go get -u github.com/jrapoport/gothic

Building

Gothic supports GO Modules. To build Gothic simply type make or make build after cloning this repo to build a DEBUG version of Gothic for development. This will build gothic & its command line tool, gadmin, under the build directory.

$ make
# or 
$ make build

To build a RELEASE (a.k.a. production) version of Gothic use make release

$ make release

Running

Gothic supports configuration through environment vars, .env files, .json files or .yaml and only requires a handful of configuration options to get started.

For a full list of configuration options please see the Configuration section below.

Using Gadmin

Gadmin is the Gothic control plane.

Building Gadmin

$ make
# or 
$ make build

To build a RELEASE (a.k.a. production) version of Gadmin use make release

GAdmin requires the address of your Gothic rpc admin server & your root password. The address and password can be supplied in a configuration file by setting a path to the file with -c (or --config) command line switch. Alternatively you can set the server address with the -s (--server) switch and the root password using the --root switch.

Generating a signup code with Gadmin

First make sure that Gothic is up and running and that its admin server is accessible.

$ ./build/release/gadmin -s [ADMIN_SERVER_ADDRESS] --root [ROOT_PASSWORD] code
> created 1 codes
> 123456

Using gRPC-Web

First start your instance of gothic, or use the container:

$ make db
$ make gothic

Next, you will need to start the envoy server

$ make envoy

Once gothic, the db, & envoy are running you can make gRPC-Web calls using the javascript bindings.

to regenerate the protobuf typescript bindings:

$ make rpcw
# or
$ make grpc

Startup

By default, Gothic will search a config file named gothic.env, gothic.json, or gothic.yaml in the following directory locations:

$ .
$ ~/.gothic
$ /etc/gothic

Alternatively, you can use the --config or -c command line flag to specify a path to a config file to use.

Required Settings

GOTHIC_SITE_URL=http://example.com
GOTHIC_ROOT_PASSWORD=my-super-admin-password
GOTHIC_JWT_SECRET=i-am-a-secret
GOTHIC_DB_DRIVER=mysql
GOTHIC_DB_DSN=root@tcp(localhost:3306)/my_gothic_db

GOTHIC_SITE_URL - string required

This is base URL for your site. The base url is used to construct things like referral URLs in email.

GOTHIC_ROOT_PASSWORD - string required

The password for the built-in super admin account. Certain operations are currently restricted to the super admin user.

Interactive logins are not supported for super admins and super admin functionality must be accessed via gadmin. This may change in the future with additional API support for the root password a/o a specialized bearer token.

GOTHIC_JWT_SECRET - string required

The shared secret for JWT tokens. Webhooks can optionally override this with a custom value for callbacks.

GOTHIC_DB_DRIVER=mysql
GOTHIC_DB_DSN=root@tcp(0.0.0.0:3306)/my_gothic_db

GOTHIC_DB_DRIVER - string required

The dialect of the database you to use. Currently, mysql, postgres, sqlserver, and sqlite (or sqlite3) are all supported. Other values will be treated as a generic sql connection and passed to the mysql driver.
Defaults to mysql.

In the future, direct support for other databases via gorm.io drivers may be added.

GOTHIC_DB_DSN - string required

Connection string for the database.

Supported Technologies

gRPC & gRPC-Web APIs

Gothic supports a full range of gRPC & gRPC-Web APIs. gRPC-Web APIs are external and designed to be publicly available. By contrast, gRPC APIs are reserved for admin operations a/o microservice communication. The gRPC host address should not be publicly accessible.

API are currently a WIP. For now, they should not be considered stable and subject to change at any time.

REST APIs

Gothic supports a full range of REST APIs for users & administrative access.

API are currently a WIP. For now, they should not be considered stable and subject to change at any time.

Databases

Gothic uses gorm for database support.

OAuth External Providers

Gothic uses goth for external oauth providers now. Now we support everything that goth supports.

Email Formatting

Gothic uses hermes for email templates.

SMTP

Gothic uses go-simple-mail for smtp server support.

JWT Tokens

Gothic uses lestrrat-go for jwt tokens.

Config Files

Gothic uses viper for configuration file support.

CLI

Gothic uses cobra for command line tool support.

Configuration

Gothic supports config files in .env, .yaml and .json formats in addition to env vars.

Please see the example.env or test configurations for complete examples.

Service

GOTHIC_SERVICE="gothic"
GOTHIC_SITE_URL=http://example.com

GOTHIC_SERVICE - string

The name of the authentication service. This is used in a variety of places and settings. A normalized version of this value is also used as the name of the internal (email) signup provider (enabled by default). Defaults to gothic.

GOTHIC_SITE_URL - string required

This is base URL for your site. The base url is used to construct things like referral URLs in email.

Networking

GOTHIC_HOST=localhost
GOTHIC_HEALTH_ADDRESS=localhost:7720
GOTHIC_RPC_ADDRESS=localhost:7721
GOTHIC_ADMIN_ADDRESS=localhost:7722
GOTHIC_REST_ADDRESS=localhost:7727
GOTHIC_RPCWEB_ADDRESS=localhost:7729
GOTHIC_REQUEST_ID=gothic-req

GOTHIC_HOST - string

Hostname to listen on. Defaults to localhost.

GOTHIC_HEALTH_ADDRESS - string

The health check host address to listen on. The health check host currently uses HTTP and responds to any GET request with a json response. Defaults to [GOTHIC_HOST]:7720.

GOTHIC_RPC_ADDRESS - string

The gRPC host address to listen on. gRPC APIs are for admin operations a/o microservice communication. Defaults to [GOTHIC_HOST]:7721.

The gRPC API should be considered internal and not publicly available. This address should not be internet accessible.

GOTHIC_ADMIN_ADDRESS - string

The gRPC admin host address to listen on. Operations on this address are secured by a valid JWT token with admin permissions. Defaults to [GOTHIC_HOST]:7722.

GOTHIC_REST_ADDRESS - string

The REST host address to listen on. REST APIs are for users & administrative access. Defaults to [GOTHIC_HOST]:7727.

The REST API should be considered external and publicly available. This address should be internet accessible.

GOTHIC_RPCWEB_ADDRESS - string

The gRPC-Web host address to listen on. gRPC-Web APIs are for users & (potentially some) administrative access. Defaults to [GOTHIC_HOST]:7729.

The gRPC-Web API should be considered external and publicly available. This address could be internet accessible for direct gGPC HTTP/2 communication. However, typically this address would not be internet accessible. Instead, it would be accessible to an Envoy proxy server, which would itself expose an internet accessible address. Please see [envoy.yaml](https://github.com/jrapoport/gothic/blob/master