<commit_before># Hydra
[![Build Status](https://travis-ci.org/ory-am/hydra.svg?branch=master)](https://travis-ci.org/ory-am/hydra)
[![Coverage Status](https://coveralls.io/repos/ory-am/hydra/badge.svg?branch=master&service=github)](https://coveralls.io/github/ory-am/hydra?branch=master)

![Hydra](hydra.png)

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](account/storage.go).

Hydra implements TLS, different OAuth2 IETF standards and supports HTTP/2. To make things as easy as possible, hydra
comes with tools to generate TLS and RS256 PEM files, leaving you with almost zero trouble to set up.

![Hydra implements HTTP/2 and TLS.](h2tls.png)

*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.*

Current status:

- Development: 90% of principal components
- HTTP API: 70% (in review)
- Real world use: 10%

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**

- [What is Hydra?](#what-is-hydra)
- [Motivation](#motivation)
- [Features](#features)
- [Caveats](#caveats)
- [HTTP/2 RESTful API](#http2-restful-api)
- [Run hydra-host](#run-hydra-host)
  - [Set up PostgreSQL locally](#set-up-postgresql-locally)
  - [Run as executable](#run-as-executable)
  - [Run from sourcecode](#run-from-sourcecode)
  - [Available Environment Variables](#available-environment-variables)
  - [CLI Usage](#cli-usage)
    - [Start server](#start-server)
    - [Create client](#create-client)
    - [Create user](#create-user)
    - [Create JWT RSA Key Pair](#create-jwt-rsa-key-pair)
    - [Create a TLS certificate](#create-a-tls-certificate)
    - [Import policies](#import-policies)
- [Good to know](#good-to-know)
  - [Everything is RESTful. No HTML. No Templates.](#everything-is-restful-no-html-no-templates)
  - [Sign up workflow](#sign-up-workflow)
  - [Sign in workflow](#sign-in-workflow)
    - [Authenticate with Google, Dropbox, ...](#authenticate-with-google-dropbox-)
    - [Authenticate with a hydra account](#authenticate-with-a-hydra-account)
  - [Visually confirm authorization](#visually-confirm-authorization)
  - [Principles](#principles)
- [Attributions](#attributions)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## 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](http://auth0.com) or [oauth.io](http://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](http://golang.org) 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](#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:

* **Account Management**: Sign up, settings, password recovery
* **Access Control / Policy Management** backed by [ladon](https://github.com/ory-am/ladon)
* Hydra comes with a rich set of **OAuth2** features:
  * Hydra implements OAuth2 as specified at [rfc6749](http://tools.ietf.org/html/rfc6749) and [draft-ietf-oauth-v2-10](http://tools.ietf.org/html/draft-ietf-oauth-v2-10).
  * Hydra uses self-contained Acccess Tokens as suggessted in [rfc6794#section-1.4](http://tools.ietf.org/html/rfc6749#section-1.4) by issuing JSON Web Tokens as specified at
   [https://tools.ietf.org/html/rfc7519](https://tools.ietf.org/html/rfc7519) with [RSASSA-PKCS1-v1_5 SHA-256](https://tools.ietf.org/html/rfc7519#section-8) hashing algorithm, Hydra reduces database roundtrips.
  * Hydra implements **OAuth2 Introspection** as specified in [rfc7662](https://tools.ietf.org/html/rfc7662)
* Easy command line tools like `hydra-jwt` for generating jwt signing key pairs.
* HTTP/2 with TLS.

## Caveats

To make hydra suitable for every use case we decided to exclude any sort of HTML templates.
Hydra speaks only JSON. This obviously prevents Hydra from delivering a dedicated login and authorization page like
"Do you want to grant App Foobar access to all of your data?" or "Please log into your account to procceed. <email field> <password field>".

You'll find more information on this in the [Good to know](#good-to-know) section.

## HTTP/2 RESTful API

The API is described at [apiary](http://docs.hydra6.apiary.io/#). The API Documentation is still work in progress.

## Run hydra-host

### 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=<PASSWORD> -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](https://www.docker.com/):

```
> docker run --name hydra-postgres -e POSTGRES_PASSWORD=<PASSWORD> -p 5432:5432 -d postgres
> export DATABASE_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 get -d -v github.com/ory-am/hydra/...
> 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](https://golang.org/doc/code.html#GOPATH)*

### Run from sourcecode

```
> go get -d -v 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
```

### Available Environment Variables

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`      |
| SIGNUP_URL           | [Sign up URL](#sign-up)   | url                                           | empty     |
| SIGNIN_URL           | [Sign in URL](#sign-in)   | url                                           | empty     |
| DROPBOX_CLIENT       | Dropbox Client ID         | string                                        | empty     |
| DROPBOX_SECRET       | Dropbox Client Secret     | string                                        | empty     |
| DROPBOX_CALLBACK     | Dropbox Redirect URL      | url                                           | empty     |
| JWT_PUBLIC_KEY_PATH  | JWT Signing Public Key    | `./cert/rs256-public.pem` (local path)        | "../../example/cert/rs256-public.pem"  |
| JWT_PRIVATE_KEY_PATH | JWT Signing Private Key   | `./cert/rs256-private.pem` (local path)       | "../../example/cert/rs256-private.pem" |
| TLS_CERT_PATH        | TLS Certificate Path      | `./cert/cert.pem`                             | "../../example/cert/tls-cert.pem"      |
| TLS_KEY_PATH         | TLS Key Path              | `./cert/key.pem`                              | "../../example/cert/tls-key.pem"       |
| DANGEROUSLY_FORCE_HTTP | Disable HTTPS           | `force`                                       | disabled  |

### CLI 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 the host service<commit_msg>readme: added port and host env var descriptions<commit_after># Hydra
[![Build Status](https://travis-ci.org/ory-am/hydra.svg?branch=master)](https://travis-ci.org/ory-am/hydra)
[![Coverage Status](https://coveralls.io/repos/ory-am/hydra/badge.svg?branch=master&service=github)](https://coveralls.io/github/ory-am/hydra?branch=master)

![Hydra](hydra.png)

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](account/storage.go).

Hydra implements TLS, different OAuth2 IETF standards and supports HTTP/2. To make things as easy as possible, hydra
comes with tools to generate TLS and RS256 PEM files, leaving you with almost zero trouble to set up.

![Hydra implements HTTP/2 and TLS.](h2tls.png)

*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.*

Current status:

- Development: 90% of principal components
- HTTP API: 70% (in review)
- Real world use: 10%

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**

- [What is Hydra?](#what-is-hydra)
- [Motivation](#motivation)
- [Features](#features)
- [Caveats](#caveats)
- [HTTP/2 RESTful API](#http2-restful-api)
- [Run hydra-host](#run-hydra-host)
  - [Set up PostgreSQL locally](#set-up-postgresql-locally)
  - [Run as executable](#run-as-executable)
  - [Run from sourcecode](#run-from-sourcecode)
  - [Available Environment Variables](#available-environment-variables)
  - [CLI Usage](#cli-usage)
    - [Start server](#start-server)
    - [Create client](#create-client)
    - [Create user](#create-user)
    - [Create JWT RSA Key Pair](#create-jwt-rsa-key-pair)
    - [Create a TLS certificate](#create-a-tls-certificate)
    - [Import policies](#import-policies)
- [Good to know](#good-to-know)
  - [Everything is RESTful. No HTML. No Templates.](#everything-is-restful-no-html-no-templates)
  - [Sign up workflow](#sign-up-workflow)
  - [Sign in workflow](#sign-in-workflow)
    - [Authenticate with Google, Dropbox, ...](#authenticate-with-google-dropbox-)
    - [Authenticate with a hydra account](#authenticate-with-a-hydra-account)
  - [Visually confirm authorization](#visually-confirm-authorization)
  - [Principles](#principles)
- [Attributions](#attributions)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## 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](http://auth0.com) or [oauth.io](http://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](http://golang.org) 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](#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:

* **Account Management**: Sign up, settings, password recovery
* **Access Control / Policy Management** backed by [ladon](https://github.com/ory-am/ladon)
* Hydra comes with a rich set of **OAuth2** features:
  * Hydra implements OAuth2 as specified at [rfc6749](http://tools.ietf.org/html/rfc6749) and [draft-ietf-oauth-v2-10](http://tools.ietf.org/html/draft-ietf-oauth-v2-10).
  * Hydra uses self-contained Acccess Tokens as suggessted in [rfc6794#section-1.4](http://tools.ietf.org/html/rfc6749#section-1.4) by issuing JSON Web Tokens as specified at
   [https://tools.ietf.org/html/rfc7519](https://tools.ietf.org/html/rfc7519) with [RSASSA-PKCS1-v1_5 SHA-256](https://tools.ietf.org/html/rfc7519#section-8) hashing algorithm, Hydra reduces database roundtrips.
  * Hydra implements **OAuth2 Introspection** as specified in [rfc7662](https://tools.ietf.org/html/rfc7662)
* Easy command line tools like `hydra-jwt` for generating jwt signing key pairs.
* HTTP/2 with TLS.

## Caveats

To make hydra suitable for every use case we decided to exclude any sort of HTML templates.
Hydra speaks only JSON. This obviously prevents Hydra from delivering a dedicated login and authorization page like
"Do you want to grant App Foobar access to all of your data?" or "Please log into your account to procceed. <email field> <password field>".

You'll find more information on this in the [Good to know](#good-to-know) section.

## HTTP/2 RESTful API

The API is described at [apiary](http://docs.hydra6.apiary.io/#). The API Documentation is still work in progress.

## Run hydra-host

### 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=<PASSWORD> -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](https://www.docker.com/):

```
> docker run --name hydra-postgres -e POSTGRES_PASSWORD=<PASSWORD> -p 5432:5432 -d postgres
> export DATABASE_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 get -d -v github.com/ory-am/hydra/...
> 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](https://golang.org/doc/code.html#GOPATH)*

### Run from sourcecode

```
> go get -d -v 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
```

### Available Environment Variables

The CLI currently requires two environment variables:

| Variable             | Description               | Format                                        | Default   |
| -------------------- | ------------------------- | --------------------------------------------- | --------- |
| PORT                 | Which port to listen on   | number                                        | 443       |
| HOST                 | Which host to listen on   | ip or hostname                                | empty (all) |
| DATABASE_URL         | PostgreSQL Database URL   | `postgres://user:password@host:port/database` | empty     |
| BCRYPT_WORKFACTOR    | BCrypt Strength           | number                                        | `10`      |
| SIGNUP_URL           | [Sign up URL](#sign-up)   | url                                           | empty     |
| SIGNIN_URL           | [Sign in URL](#sign-in)   | url                                           | empty     |
| DROPBOX_CLIENT       | Dropbox Client ID         | string                                        | empty     |
| DROPBOX_SECRET       | Dropbox Client Secret     | string                                        | empty     |
| DROPBOX_CALLBACK     | Dropbox Redirect URL      | url                                           | empty     |
| JWT_PUBLIC_KEY_PATH  | JWT Signing Public Key    | `./cert/rs256-public.pem` (local path)        | "../../example/cert/rs256-public.pem"  |
| JWT_PRIVATE_KEY_PATH | JWT Signing Private Key   | `./cert/rs256-private.pem` (local path)       | "../../example/cert/rs256-private.pem" |
| TLS_CERT_PATH        | TLS Certificate Path      | `./cert/cert.pem`                             | "../../example/cert/tls-cert.pem"      |
| TLS_KEY_PATH         | TLS Key Path              | `./cert/key.pem`                              | "../../example/cert/tls-key.pem"       |
| DANGEROUSLY_FORCE_HTTP | Disable HTTPS           | `force`                                       | disabled  |

### CLI 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 the host service
{'fraction_non_alphanumeric': 0.12305763044545008, 'fraction_numerical': 0.015429911128073714, 'mean_word_length': 2.8917886696371737, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 53, 'https://': 24, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 41, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4952099', 'n_tokens_mistral': 5796, 'n_tokens_neox': 5309, 'n_words': 1779}