diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 347f884176b..aaf98782bfc 100644 --- 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) @@ -24,6 +24,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 index d699ccfdd9b..1470ecdec83 100644 --- 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 b/docs/tutorials/5minutes.md similarity index 100% rename from docs/tutorial.md rename to docs/tutorials/5minutes.md diff --git a/docs/tutorials/consentapp.md b/docs/tutorials/consentapp.md new file mode 100644 index 00000000000..513e4d747ff --- /dev/null +++ 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 +```