github.com/thanzen/hydra/account/handler

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


Install
go get github.com/thanzen/hydra/account/handler

Documentation

Hydra

Build Status Coverage Status

Hydra

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.

Motivation

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 auth0.com or oauth.io 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!

Features

Hydra is a RESTful service providing you with things like:

Caveats

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:

/oauth2/auth?provider=google&client_id=123&response_type=code&redirect_uri=/callback&state=randomstate

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

Hydra host is the server side of things.

Set up PostgreSQL locally

On Windows and Max OS X, download and install [docker-toolbox(https://www.docker.com/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: 192.168.99.100

> # 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 github.com/ory-am/hydra/cli/hydra-host
> hydra-host start

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

Run from sourcecode

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

Environment

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

Usage

NAME:
   hydra-host - Dragons guard your resources.

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

VERSION:
   0.0.0

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

GLOBAL OPTIONS:
   --help, -h           show help
   --version, -v        print the version

Start server

NAME:
   hydra-host start - start hydra-host

USAGE:
   hydra-host start [arguments...]

Create client

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

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

Create user

NAME:
   hydra-host user create - create a new user

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

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

API

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.

Attributions