docs: add example about securing the consent app (#450)

Signed-off-by: Matteo Suppo <[email protected]>
ory · May 4, 2017 · 7c39f8b · 7c39f8b
1 parent 7c24fc2
commit 7c39f8b
Show file tree

Hide file tree

Showing 4 changed files with 72 additions and 4 deletions.
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -4,7 +4,7 @@
   * [Introduction to OAuth 2.0 and OpenID Connect](README.md#introduction-to-oauth-20-and-openid-connect)
   * [Introduction to Hydra](README.md#introduction-to-hydra)
   * [OAuth2 Case Study](README.md#oauth-20-case-study)
-* [5 Minute Tutorial](tutorial.md)
+* [5 Minute Tutorial](tutorials/5minutes.md)
 * [Using Hydra](install.md)
   * [Installing Hydra](install.md#installing-hydra)
   * [Configuring Hydra](install.md#configuring-hydra)
@@ -33,6 +33,9 @@
 * [Contribute](contribute.md)
   * [Architecture and Design](contribute.md)
   * [Running Tests](contribute.md)
+* Tutorials
+  * [5 Minute Tutorial](tutorials/5minutes.md)
+  * [Secure the consent app](tutorials/consentapp.md)
 * [FAQ](faq.md)
   * [How to deal with mobile apps?](faq/mobile.md)
   * [Why is the Resource Owner Password Credentials grant not supported?](faq/ropc.md)

diff --git a/docs/install.md b/docs/install.md
@@ -1,6 +1,6 @@
 # Installing, Configuring and Running Hydra
 
-Before starting with this section, please check out the [tutorial](./demo.md). It will teach you the most important flows
+Before starting with this section, please check out the [tutorial](./tutorials/5minutes.md). It will teach you the most important flows
 and settings for Hydra.
 
 ## Installing Hydra
@@ -44,7 +44,7 @@ Hydra is a twelve factor OAuth2 and OpenID Connect provider
 
 The client and server **binaries are downloadable at the [releases tab](https://github.com/ory-am/hydra/releases)**.
 There is currently no installer available. You have to add the hydra binary to the PATH environment variable yourself or put
-the binary in a location that is already in your path (`/usr/bin`, ...). 
+the binary in a location that is already in your path (`/usr/bin`, ...).
 If you do not understand what that all of this means, ask in our [chat channel](https://gitter.im/ory-am/hydra). We are happy to help.
 
 Once installed, you should be able to run:
@@ -86,7 +86,7 @@ Available Commands:
 ## Configuring Hydra
 
 Running the default Hydra environment is as easy as:
- 
+
 ```
 $ hydra host
 time="2016-10-13T10:04:01+02:00" level=info msg="DATABASE_URL not set, connecting to ephermal in-memory database."

diff --git a/docs/tutorial.md → docs/tutorials/5minutes.md b/docs/tutorial.md → docs/tutorials/5minutes.md
diff --git a/docs/tutorials/consentapp.md b/docs/tutorials/consentapp.md
@@ -0,0 +1,65 @@
+### Secure the consent app
+
+This tutorial requires to have read and understood [OAuth 2.0 & OpenID Connect](../oauth2.md).
+
+A consent app should never use the root hydra credentials, and fortunately you can create in two simple steps:
+
+#### 1. Create the client in Hydra
+
+A consent app needs to communicate with hydra, so it needs a client:
+
+```json
+{
+    "id": "YOURCONSENTID",
+    "client_secret": "YOURCONSENTSECRET",
+    "client_name": "consent",
+    "redirect_uris": [],
+    "grant_types": [
+        "client_credentials"
+    ],
+    "response_types": [
+        "token"
+    ],
+    "scope": "hydra.keys.get"
+}
+```
+
+`hydra.keys.get` is the only scope that's strictly required for the consent flow, but you may need to
+use other scopes.
+
+To create the client you can save the json configuration on a file ```consent.json``` and then issue the command
+
+```
+$ hydra clients import consent.json
+```
+
+#### 2. Grant permissions to the client
+
+Giving the `hydra.keys.get` scope is not enough. Hydra's warden needs an explicit policy to access hydra's keys.
+
+```json
+{
+    "actions": [
+        "get"
+    ] ,
+    "conditions": {},
+    "description": "Allow consent app to access hydra's keys" ,
+    "effect": "allow" ,
+    "id": "consent_keys" ,
+    "resources": [
+        "rn:hydra:hydra.consent.challenge:public"
+        "rn:hydra:hydra.consent.response:private"
+    ] ,
+    "subjects": [
+        "YOURCONSENTID"
+    ]
+}
+```
+
+We are granting access explicitedly only to the two strictly necessary keys for the consent flow
+
+To create the policy you can save the json configuration on a file ```policy.json``` and then issue the command
+
+```
+$ hydra policies create -f policy.json
+```