readme: add security section

README.md

@@ -21,6 +21,8 @@ Hydra uses the security first OAuth2 and OpenID Connect SDK [Fosite](https://git
 
 - [What is Hydra?](#what-is-hydra)
   - [Feature Overview](#feature-overview)
+  - [When should I consider using Hydra?](#when-should-i-consider-using-hydra)
+  - [Security](#security)
 - [Quickstart](#quickstart)
   - [Installation](#installation)
   - [Run the example](#run-the-example)
@@ -63,6 +65,95 @@ and under supervision of the [LMU Teaching and Research Unit Programming and Mod
 8. **Real Time:** Operation is a lot easier with real time monitoring. Because Hydra leverages RethinkDB, you get real time monitoring for free:
 ![monitoring.gif](dist/monitoring.gif)
 
+### When should I consider using Hydra?
+
+OAuth2 and OpenID Connect are tricky to understand, if you are new to them. It is important to understand that OAuth2 is
+a delegation protocol. It makes sense to use Hydra in new and existing projects. A use case covering an existing project
+explains how one would use Hydra in a new one as well. So let's look at a use case!
+
+Let's assume we are running a ToDo List App (todo24.com). ToDo24 has a login endpoint (todo24.com/login).
+The login endpoint written in node and uses MongoDB to store user information (email + password + settings). Of course,
+todo24 has other services as well: list management (todo24.com/lists/manage: close, create, move), item management (todo24.com/lists/items/manage: mark solved, add), and so on.
+You are using cookies to see which user is doing the request.
+
+Now you decide to use OAuth2 on top of your current infrastructure. Reasons could be:
+* You want to open up your APIs to third-party developers. Their apps will be using OAuth2 Access Tokens to access a user's to do list.
+* You want a mobile client. Because you can not store secrets on devices (they can be reverse engineered and stolen), you use OAuth2 Access Tokens instead.
+* You have Cross Origin Requests. Making cookies work with Cross Origin Requests weakens or even disables important anti-CSRF measures.
+* You want to write an in-browser client. This is the same case as in a mobile client (you can't store secrets in a browser).
+
+These are only a couple of reasons to use OAuth2. You might decide to use OAuth2 as your single source of authorization, thus maintaining
+only one authorization protocol and being able to open up to third party devs in no-time. With OpenID Connect, you are able to delegate authentication as well as authorization!
+
+Your decision is final. You want to use OAuth2 and you want Hydra to do the job. You install Hydra in your cluster using docker.
+Next, you set up some exemplary OAuth2 clients. Clients can act on their own, but most of the times they need to access to a user's todo lists.
+To do so, the client initiates an OAuth2 request. This is where [Hydra's authentication flow](https://ory-am.gitbooks.io/hydra/content/oauth2.html#authentication-flow) comes in to play.
+Before Hydra can issue an access token, we needs to know WHICH user is giving consent. To do so, Hydra redirects the user agent (e.g. browser, mobile device)
+to the login endpoint alongside with a challenge that contains an expiry time and other information. The login endpoint (todo24.com/login) authenticates the
+user as usual, e.g. by username & password, session cookie or other means. Upon successful authentication, the login endpoint asks for the user's consent:
+*"Do you want to grant MyCoolAnalyticsApp read & write access to all your todo lists? [Yes] [No]"*. Once the user clicked *Yes* and gave consent),
+the login endpoint redirects back to hydra and appends something called a *consent token*. The consent token is a cryptographically signed
+string that contains information about the user, specifically the user's unique id. Hydra validates the signature's trustworthiness
+and issues an OAuth2 access token and optionally a refresh or open id token.
+
+Every time a request containing an access token hits a resource server (todo24.com/lists/manage), you make a request to Hydra asking who the token's
+subject (the user who authorized the client to create a token on his behalf) is and weather or not the token is valid. You may optionally
+ask if the token has permission to perform a certain action.
+
+### 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.
+
+Let's 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 layouted 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 is open source and can be reviewed by anyone.
+* Hydra is designed by a [security enthusiast](https://github.com/arekkas).
+
+Hydra has received positive reception and attention. Here's what the community is saying:
+
+> Nice! Lowering barriers to the use of technologies like these is important.
+
+[Pyxl101](https://news.ycombinator.com/item?id=11798641)
+
+> OAuth is a framework not a protocol. The security it provides can vary greatly between implementations.
+Fosite (which is what this is based on) is a very good implementation from a security perspective: https://github.com/ory-am/fosite#a-word-on-security
+
+[abritishguy](https://news.ycombinator.com/item?id=11800515)
+
+> [...] Thanks for releasing this by the way, looks really well engineered. [...]
+
+[olalonde](https://news.ycombinator.com/item?id=11798831)
+
 ## Quickstart
 
 This section is a quickstart guide to working with Hydra. In-depth docs are available as well: