0.4.0 (#203)

* warden: token introspection is urlencoded, not json - closes #199
* warden: move IntrospectToken from warden sdk to oauth2 - closes #201
* warden: rename InspectToken to IntrospectToken - closes #200 
* oauth2: introspection should return custom session values - closes #205
* oauth2: consent strategy should use at_ext for access token session data - closes #198
* docs: move docs from gitbook to github - closes #204

.gitignore

@@ -8,4 +8,6 @@ node_modules/
 .DS_Store
 vendor/
 .hydra.yml
-cover.out
+cover.out
+output/
+_book/

.travis.yml

@@ -11,6 +11,7 @@ language: go
 go:
   - 1.5
   - 1.6
+  - 1.7
 
 install:
   - go get github.com/mattn/goveralls golang.org/x/tools/cmd/cover github.com/pierrre/gotestcover github.com/Masterminds/glide

book.json

@@ -1,3 +1,5 @@
 {
-  "root": "./docs/"
+    "root": "./docs",
+    "author": "Aeneas Rekkas",
+    "gitbook": ">=3.2.0"
 }

cmd/cli/handler_warden.go

@@ -34,7 +34,7 @@ func (h *WardenHandler) IsAuthorized(cmd *cobra.Command, args []string) {
 	}
 
 	scopes, _ := cmd.Flags().GetStringSlice("scopes")
-	res, err := h.M.InspectToken(context.Background(), args[0], scopes...)
+	res, err := h.M.TokenValid(context.Background(), args[0], scopes...)
 	pkg.Must(err, "Could not validate token: %s", err)
 
 	out, err := json.MarshalIndent(res, "", "\t")

docs/README.md

@@ -0,0 +1,29 @@
+# What is [Hydra](https://github.com/ory-am/hydra)?
+
+At first, there was the monolith. The monolith worked well with the bespoke authentication module.
+Then, the web evolved into an elastic cloud that serves thousands of different user agents
+in every part of the world.
+
+Hydra is driven by the need for a **scalable in memory
+OAuth2 and OpenID Connect** layer, that integrates with every Identity Provider you can imagine.
+
+Hydra is available through [Docker](https://hub.docker.com/r/oryam/hydra/) and at [GitHub](https://github.com/ory-am/hydra).
+
+### Feature Overview
+
+1. **Availability:** Hydra uses pub/sub to have the latest data available in memory. The in-memory architecture allows for heavy duty workloads.
+2. **Scalability:** Hydra scales effortlessly on every platform you can imagine, including Heroku, Cloud Foundry, Docker,
+Google Container Engine and many more.
+3. **Integration:** Hydra wraps your existing stack like a blanket and keeps it safe. Hydra uses cryptographic tokens for authenticate users and request their consent, no APIs required.
+The deprecated php-3.0 authentication service your intern wrote? It works with that too, don't worry.
+We wrote an example with React to show you how this could look like: [React.js Identity Provider Example App](https://github.com/ory-am/hydra-idp-react).
+4. **Security:** Hydra leverages the security first OAuth2 framework **[Fosite](https://github.com/ory-am/fosite)**,
+encrypts important data at rest, and supports HTTP over TLS (https) out of the box.
+5. **Ease of use:** Developers and Operators are human. Therefore, Hydra is easy to install and manage. Hydra does not care if you use React, Angular, or Cocoa for your user interface.
+To support you even further, there are APIs available for *cryptographic key management, social log on, policy based access control, policy management, and two factor authentication (tbd)*
+Hydra is packaged using [Docker](https://hub.docker.com/r/oryam/hydra/).
+6. **Open Source:** Hydra is licensed Apache Version 2.0
+7. **Professional:** Hydra implements peer reviewed open standards published by [The Internet Engineering Task Force (IETF®)](https://www.ietf.org/) and the [OpenID Foundation](https://openid.net/)
+and under supervision of the [LMU Teaching and Research Unit Programming and Modelling Languages](http://www.en.pms.ifi.lmu.de). No funny business.
+8. **Real Time:** Operation is a lot easier with real time monitoring. Because Hydra leverages RethinkDB, you get real time monitoring for free.
+

docs/SUMMARY.md

@@ -0,0 +1,33 @@
+# Summary
+
+* [Introduction](README.md)
+* [Basics](basics.md)
+  * [Architecture](basics/architecture.md)
+  * [Security](basics/security.md)
+  * [Interoperability](basics/interoperability.md)
+* [5 Minutes Tutorial](demo.md)
+* [Installation](install.md)
+* Core Capabilities
+  * [OAuth2 & OpenID Connect](oauth2.md)
+    * [OAuth2 Basics](oauth2/basics.md)
+    * [OpenID Connect Basics](oauth2/openid.md)
+    * [Consent Flow](oauth2/consent.md)
+  * [JSON Web Keys](jwk.md)
+  * [Access Control](access-control.md)
+    * [Policy Introduction](access-control/policies.md)
+    * [The Warden](access-control/warden.md)
+    * [OAuth2 Token Introspection](access-control/introspection.md)
+  * [Manage Social Logins](sso.md)
+  * [SDK](sdk.md)
+    * [Go SDK](sdk/go.md)
+* [FAQ](faq.md)
+  * [What does *"eventually consistent"* mean?](faq/consistency.md)
+  * [Where is the HTTP API Documentation?](faq/http-api.md)
+  * [How can I disable HTTPS for testing?](faq/disable-https.md)
+  * [How can I import TLS certificates?](faq/https-tls-import.md)
+  * [Can I set the log level to warn, error, debug, ...?](faq/log-level.md)
+  * [Should I use OAuth2 tokens for authentication?](faq/oauth2-auth.md)
+  * [What will happen if an error occurs during an OAuth2 flow?](faq/oauth2-error.md)
+  * [Why isn't the redirect url working?](faq/redirect-uri.md)
+  * [How can I import a custom CA for RethinkDB?](faq/rethink-ca.md)
+  * [How do I know if OAuth2 / Hydra is the right choice for me?](faq/when-use.md)

docs/access-control.md

@@ -0,0 +1,22 @@
+# Access Control
+
+Hydra offers various access control methods. Resource providers (e.g. photo/user/asset/balance/... service) use
+
+1. **Warden Token Validation** to validate access tokens
+2. **Warden Access Control with Access Tokens** to validate access tokens and decide
+if the token's subject is allowed to perform the request
+3. **Warden Access Control without Access Tokens** to decide if any subject is allowed
+to perform a request
+
+whereas third party apps (think of a facebook app) use
+
+1. **OAuth2 Token Introspection** to validate access tokens.
+
+There are two common ways to solve access control in a distributed environment (e.g. microservices).
+
+1. Your services are behind a gateway (e.g. access control, rate limiting, and load balancer) 
+that does the access control for them. This is known as a "trusted network/subnet".
+2. Clients (e.g. Browser) talk to your services
+directly. The services are responsible for checking access privileges themselves.
+
+In both cases, you would use on of the warden endpoints.

docs/access-control/introspection.md

@@ -0,0 +1,14 @@
+# OAuth2 Token Introspection
+
+OAuth2 Token Introspection is an [IETF](https://tools.ietf.org/html/rfc7662) standard.
+It defines a method for a protected resource to query
+an OAuth 2.0 authorization server to determine the active state of an
+OAuth 2.0 token and to determine meta-information about this token.
+OAuth 2.0 deployments can use this method to convey information about
+the authorization context of the token from the authorization server
+to the protected resource.
+
+In order to make a successful Token Introspection request, the audience of the access token you are introspecting
+*must* match the subject of the access token you are using to access the introspection endpoint.
+
+The Token Introspection endpoint is documented in more detail [here](http://docs.hdyra.apiary.io/#reference/oauth2/oauth2-token-introspection).

docs/access-control/policies.md

@@ -0,0 +1,94 @@
+# Access Control Policies
+
+Hydra uses the Access Control Library [Ladon](https://github.com/ory-am/ladon).
+For a deep dive, it is a good idea to read the [Ladon Docs](https://github.com/ory-am/ladon#ladon).
+
+In Hydra, policy based access control is when you decide if:
+
+- Aaron (subject) is allowed (effect) to create (action) a new forum post (resource) when accessing the forum website from IP 192.168.178.3 (context).
+- Richard (subject) is allowed (effect) to delete (action) a status update (resource) when he is the author (context).
+
+Or, more *generalized:* **Who** is **able** to do **what** on **something** with some **context**.
+
+* **Who (Subject)**: An arbitrary unique subject name, for example "ken" or "printer-service.mydomain.com".
+* **Able (Effect)**: The effect which is always "allow" or "deny".
+* **What (Action)**: An arbitrary action name, for example "delete", "create" or "scoped:action:something".
+* **Something (Resource)**: An arbitrary unique resource name, for example "something", "resources:articles:1234" or some uniform resource name like "urn:isbn:3827370191".
+* **Context (Context)**: The current context which may environment information like the IP Address, request date, the resource owner name, the department ken is working in and anything you like.
+
+Policies are JSON documents managed via the [Policy API](http://docs.hdyra.apiary.io/#reference/policies).
+
+```
+{
+  // A required unique identifier. Used primarily for database retrieval.
+  "id": "68819e5a-738b-41ec-b03c-b58a1b19d043",
+  
+  // A optional human readable description.
+  "description": "something humanly readable",
+  
+  // A subject can be an user or a service. It is the "who" in "who is allowed to do what on something".
+  // As you can see here, you can use regular expressions inside < >.
+  "subjects": ["user", "<peter|max>"],
+    
+  
+  // Should access be allowed or denied?
+  // Note: If multiple policies match an access request, ladon.DenyAccess will always override ladon.AllowAccess
+  // and thus deny access.
+  "effect": "allow",
+  
+  // Which resources this policy affects.
+  // Again, you can put regular expressions in inside < >.
+  "resources": ["articles:<[0-9]+>"],
+  
+  // Which actions this policy affects. Supports RegExp
+  // Again, you can put regular expressions in inside < >.
+  "actions": ["create","update"],
+  
+  // Under which conditions this policy is "active".
+  "conditions": {
+    "owner": {
+     // In this example, the policy is only "active" when the requested subject is the owner of the resource as well.
+      "type": "EqualsSubjectCondition",
+      "options": {}
+    }
+   }
+}
+```
+
+## Examples
+
+### Let everyone read public JWKs
+
+```
+[
+  {
+    "description": "Allow everyone including anonymous users to read JSON Web Keys having Key ID *public*.",
+    "subject": ["<.*>"],
+    "effect": "allow",
+    "resources": [
+      "rn:hydra:keys:<[^:]+>:public"
+    ],
+    "permissions": [
+      "get"
+    ]
+  }
+]
+```
+
+### Deny anyone from reading private JWKs
+
+```
+[
+  {
+    "description": "Explicitly deny everyone reading JSON Web Keys with Key ID *private*.",
+    "subject": ["<.*>"],
+    "effect": "allow",
+    "resources": [
+      "rn:hydra:keys:<[^:]+>:private"
+    ],
+    "permissions": [
+      "get"
+    ]
+  }
+]
+```

docs/access-control/warden.md

@@ -0,0 +1,6 @@
+## Warden
+
+The Warden is usually called from your own services ("resource providers"), not from third parties. Hydra prevents
+third parties from having access to these endpoints per default, but you can change that with custom policies.
+
+The Warden endpoints are documented [here](http://docs.hdyra.apiary.io/#reference/warden:-access-control-for-resource-providers).

docs/basics/architecture.md

@@ -0,0 +1,13 @@
+## Architecture
+
+Hydra uses pub/sub to have the latest data always available in memory. RethinkDB makes it possible to recover from
+failures and synchronize the cluster when something changes. Data is kept in memory for best performance results.
+The storage layer is abstracted and can be modified to use RabbitMQ or MySQL amongst others.
+
+The message broker keeps the data between all host process in synch. This results in effortless `hydra host`
+scaling on every platform you can imagine: Heroku, Cloud Foundry, Docker, Google Container Engine and many more.
+
+![](../dist/images/hydra-arch.png)
+
+Serving a uniform API reduces security risks. This is why all clients use REST and OAuth2 HTTP APIs.
+The Command Line Interface (CLI) `hydra`, responsible for managing the cluster, uses these as well.

docs/basics/interoperability.md

@@ -0,0 +1,9 @@
+## Interoperability
+
+We did not want to provide you with LDAP, Active Directory, ADFS, SAML-P, SharePoint Apps, ...
+integrations which probably won't work well anyway. Instead we decided to rely on cryptographic tokens
+(JSON Web Tokens) for authenticating users and getting their consent. This gives you all the freedom you need with
+very little effort. JSON Web Tokens are supported by all web programming languages and Hydra's
+[JSON Web Key API](jwk.html) offers a nice way to deal with certificates and keys. Your users won't notice the difference.
+
+![OAuth2 Workflow](../dist/images/hydra-authentication.gif)

docs/basics/security.md

@@ -0,0 +1,48 @@
+## Security
+
+> Why should I use Hydra? It's not that hard to implement two OAuth2 endpoints and there are numerous SDKs out there!
+
+OAuth2 and OAuth2 related specifications are over 200 written pages. Implementing OAuth2 is easy, getting it right is hard.
+Even if you use a secure SDK (there are numerous SDKs not secure by design in the wild), messing up the implementation
+is a real threat - no matter how good you or your team is. To err is human. Now, let us take a look at security in Hydra.
+
+Hydra uses [Fosite](https://github.com/ory-am/fosite#a-word-on-security), a secure-by-design OAuth2 SDK. Fosite implements
+best practices proposed by the IETF:  
+* [No Cleartext Storage of Credentials](https://tools.ietf.org/html/rfc6819#section-5.1.4.1.3)
+* [Encryption of Credentials](https://tools.ietf.org/html/rfc6819#section-5.1.4.1.4)
+* [Use Short Expiration Time](https://tools.ietf.org/html/rfc6819#section-5.1.5.3)
+* [Limit Number of Usages or One-Time Usage](https://tools.ietf.org/html/rfc6819#section-5.1.5.4)
+* [Bind Token to Client id](https://tools.ietf.org/html/rfc6819#section-5.1.5.8)
+* [Automatic Revocation of Derived Tokens If Abuse Is Detected](https://tools.ietf.org/html/rfc6819#section-5.2.1.1)
+* [Binding of Refresh Token to "client_id"](https://tools.ietf.org/html/rfc6819#section-5.2.2.2)
+* [Refresh Token Rotation](https://tools.ietf.org/html/rfc6819#section-5.2.2.3)
+* [Revocation of Refresh Tokens](https://tools.ietf.org/html/rfc6819#section-5.2.2.4)
+* [Validate Pre-Registered "redirect_uri"](https://tools.ietf.org/html/rfc6819#section-5.2.3.5)
+* [Binding of Authorization "code" to "client_id"](https://tools.ietf.org/html/rfc6819#section-5.2.4.4)
+* [Binding of Authorization "code" to "redirect_uri"](https://tools.ietf.org/html/rfc6819#section-5.2.4.6)
+* [Opaque access tokens](https://tools.ietf.org/html/rfc6749#section-1.4)
+* [Opaque refresh tokens](https://tools.ietf.org/html/rfc6749#section-1.5)
+* [Ensure Confidentiality of Requests](https://tools.ietf.org/html/rfc6819#section-5.1.1)
+* [Use of Asymmetric Cryptography](https://tools.ietf.org/html/rfc6819#section-5.1.4.1.5)
+* **Enforcing random states:** Without a random-looking state or OpenID Connect nonce the request will fail.
+* **Advanced Token Validation:** Tokens are laid out as `<key>.<signature>` where `<signature>` is created using HMAC-SHA256
+     and a global secret. This is what a token can look like: `/tgBeUhWlAT8tM8Bhmnx+Amf8rOYOUhrDi3pGzmjP7c=.BiV/Yhma+5moTP46anxMT6cWW8gz5R5vpC9RbpwSDdM=`
+* **Enforcing scopes:** By default, you always need to include the `core` scope or Hydra will not execute the request.
+
+Hydra uses [Ladon](https://github.com/ory-am/ladon) for policy management and access control. Ladon's API is minimalistic
+and well tested.
+
+Hydra encrypts symmetric and asymmetric keys at rest using AES-GCM 256bit.
+
+Hydra does not store tokens, only their signatures. An attacker gaining database access is neither able to steal tokens nor
+to issue new ones.
+
+Hydra has automated unit and integration tests.
+
+Hydra does not use hacks. We would rather rewrite the whole thing instead of introducing a hack.
+
+APIs are uniform, well documented and secured using the warden's access control infrastructure.
+
+Hydra is open source and can be reviewed by anyone.
+
+Hydra is designed by a [security enthusiast](https://github.com/arekkas), who has written and participated in numerous auth* projects.