A twelve-factor (12factor) identity & account management library & server written in Go. Backed by PostgreSQL

go get



Build Status Coverage Status


Hydra is a twelve factor authentication, authorization and account management service, ready for you to use in your micro service architecture. Hydra is written in go and backed by PostgreSQL or any implementation of account/storage.go.

Please be aware that Hydra is not ready for production just yet and has not been tested on a production system. If time schedule holds, we will use it in production in Q1 2016 for an awesome business app that has yet to be revealed.

What is Hydra?

Authentication, authorization and user account management are always lengthy to plan and implement. If you're building a micro service app in need of these three, you are in the right place.


Many authentication, authorization and user management solutions exist. Some are outdated, some come with a crazy stack, some enforce patterns you might dislike and others like or cost good money if you're out to scale.

Hydra was written because we needed a scalable 12factor OAuth2 consumer and provider with enterprise grade authorization and interoperability without a ton of dependencies or crazy features. That is why hydra only depends on Go and PostgreSQL. If you don't like PostgreSQL you can easily implement other databases and use them instead. Hydra is completely RESTful and does not serve any template (check caveats why this might affect you).

Hydra is the open source alternative to proprietary authorization solutions in the age of microservices.

Use it, enjoy it and contribute!


Hydra is a RESTful service providing you with things like:


To make hydra suitable for every usecase we decided to exclude any sort of HTML templates. Hydra speaks only JSON. This obviously prevents Hydra from delivering a dedicated login and authorization ("Do you want to grant App Foobar access to all of your data?") page.

At this moment, the /oauth2/auth endpoint only works, if a provider is given, for example:


A provider should be an OAuth2 /authorization endpoint.

To log in a user you have to use the password grant type. At this moment, the password grant is allowed to all clients. This will be changed in the future.

We will provide an exemplary provider implementation in NodeJS which uses the password grant type to log users in and is easy to customize.

The provider workflow is not standardized by any authority, has not yet been subject to a security audit and is therefore subject to change. Unfortunately most providers do not support SSO provider endpoints so we might have to rely on the OAuth2 provider workflow for a while.


Hydra host is the server side of things.

Set up PostgreSQL locally

On Windows and Max OS X, download and install [docker-toolbox( After starting the Docker Quickstart Terminal, do the following:

> docker-machine ssh default # if you're not already ssh'ed into it
> docker run --name hydra-postgres -e POSTGRES_PASSWORD=secret -p 5432:5432 -d postgres
> exit
> docker-machine ip default
# This should give you something like:

> # On Windows
> set DATABASE_URL=postgres://postgres:secret@{ip from above}:5432/postgres?sslmode=disable

> # On Mac OSX
> export DATABASE_URL=postgres://postgres:secret@{ip from above}:5432/postgres?sslmode=disable

On Linux download and install Docker:

> docker run --name hydra-postgres -e POSTGRES_PASSWORD=secret -p 5432:5432 -d postgres
> export PG_URL=postgres://postgres:secret@localhost:5432/postgres?sslmode=disable

Warning: This uses the postgres database, which is reserved. For brevity the guide to creating a new database in Postgres has been skipped.

Run as executable

> go install
> hydra-host start

Note: For this to work, $GOPATH/bin must be in your path

Run from sourcecode

> go get -u
> # cd to project root, usually in $GOPATH/src/
> cd cli
> cd hydra-host
> go run main.go start


The CLI currently requires two environment variables:

Variable Description Format Default
DATABASE_URL PostgreSQL Database URL postgres://user:password@host:port/database empty
BCRYPT_WORKFACTOR BCrypt Strength number 10


   hydra-host - Dragons guard your resources.

   hydra-host [global options] command [command options] [arguments...]


   client       client actions
   user         user actions
   start        start hydra-host
   help, h      Shows a list of commands or help for one command

   --help, -h           show help
   --version, -v        print the version

Start server

   hydra-host start - start hydra-host

   hydra-host start [arguments...]

Create client

   D:\Local\Temp\go-build012713466\command-line-arguments\_obj\exe\main.exe client - client actions

   D:\Local\Temp\go-build012713466\command-line-arguments\_obj\exe\main.exe client [arguments...]

Create user

   hydra-host user create - create a new user

   hydra-host user create [command options] <email>

   --password           the user's password
   --as-superuser       grant superuser privileges to the user


The API is loosely described at apiary.

Core principles

  • Authorization and authentication require verbose logging.
  • Logging should never include credentials, neither passwords, secrets nor tokens.