diff --git a/book.json b/book.json index c0f5d483c61..6a87172914f 100644 --- a/book.json +++ b/book.json @@ -1,12 +1,23 @@ { - "root": "./docs", - "author": "Aeneas Rekkas", - "gitbook": ">=3.2.0", - "plugins": ["edit-link"], - "pluginsConfig": { - "edit-link": { - "base": "https://github.com/ory/hydra/tree/master/docs", - "label": "Edit this page on GitHub" - } + "root": "./docs", + "author": "Aeneas Rekkas", + "gitbook": ">=3.2.0", + "plugins": [ + "edit-link", + "summary", + "etoc" + ], + "pluginsConfig": { + "edit-link": { + "base": "https://github.com/ory/hydra/tree/master/docs", + "label": "Edit this page on GitHub" + }, + "etoc": { + "h2lb": 2, + "mindepth": 2, + "maxdepth": 5, + "notoc": false } -} \ No newline at end of file + } +} + diff --git a/docs/tutorial.md b/docs/0-Tutorial/0-README.md similarity index 92% rename from docs/tutorial.md rename to docs/0-Tutorial/0-README.md index e85575f69ba..90726e8a2bd 100644 --- a/docs/tutorial.md +++ b/docs/0-Tutorial/0-README.md @@ -3,9 +3,9 @@ To start off easy, ORY Hydra provides a docker-compose based example for setting up ORY Hydra, a PostgreSQL instance and an exemplary consent app (identity provider). You need to have the latest Docker version installed. -OAuth2 Flow +OAuth2 Flow -Running the example +Running the example Install [Docker and Docker Compose](https://github.com/ory-am/hydra#installation) and either clone the Hydra git repository, download [this zip file](https://github.com/ory-am/hydra/archive/master.zip) or use `go get github.com/ory/hydra` if you have Go (1.8+) installed on you system. diff --git a/docs/environment.md b/docs/1-Environment/0-README.md similarity index 100% rename from docs/environment.md rename to docs/1-Environment/0-README.md diff --git a/docs/2-Overview/0-README.md b/docs/2-Overview/0-README.md new file mode 100644 index 00000000000..f79cd155f0e --- /dev/null +++ b/docs/2-Overview/0-README.md @@ -0,0 +1 @@ +# Understanding ORY Hydra \ No newline at end of file diff --git a/docs/oauth2.md b/docs/2-Overview/1-OAUTH2.md similarity index 96% rename from docs/oauth2.md rename to docs/2-Overview/1-OAUTH2.md index 33abfb72740..93dd78022b5 100644 --- a/docs/oauth2.md +++ b/docs/2-Overview/1-OAUTH2.md @@ -41,7 +41,7 @@ uses the Identity Provider to authenticate peter, for example by using cookies o If you are new to OpenID Connect, please read the [Introduction to OAuth 2.0 and OpenID Connect](README.md#introduction-to-oauth-20-and-openid-connect) first. -Hydra uses the [JSON Web Key Manager](./jwk.md) to retrieve the +Hydra uses the [JSON Web Key Manager](2-JWK.md) to retrieve the key pair `hydra.openid.id-token` for signing ID tokens. You can use that endpoint to retrieve the public key for verification. Additionally, Hydra supports OpenID Connect Discovery. @@ -67,7 +67,7 @@ login service ("user management") and implement the consent flow with it. Let us look at the sequence of requests being made to successfully perform an OAuth 2.0 authorize code flow using ORY Hydra: -![Consent flow sequence diagram](./images/consent-flow.svg) +![Consent flow sequence diagram](../images/consent-flow.svg) The state machine of the consent app itself typically looks as followed. @@ -87,7 +87,7 @@ CHA-->CHR CHR-->|Redirect to redirectUrl value|H2{Hydra} --> -![Consent app state diagram](./images/consent-state.svg) +![Consent app state diagram](../images/consent-state.svg) **Legend:** @@ -109,9 +109,9 @@ consent request. Here is how Google chose to design the login and consent UI (what we call the "consent app"): -![Google OAuth 2.0 Log In Screen](./images/google.png) +![Google OAuth 2.0 Log In Screen](../images/google.png) -![Google OAuth 2.0 Authorization In Screen](./images/google2.png) +![Google OAuth 2.0 Authorization In Screen](../images/google2.png) ### Consent REST API diff --git a/docs/jwk.md b/docs/2-Overview/2-JWK.md similarity index 100% rename from docs/jwk.md rename to docs/2-Overview/2-JWK.md diff --git a/docs/access-control.md b/docs/2-Overview/3-ACCESS-CONTROL.md similarity index 100% rename from docs/access-control.md rename to docs/2-Overview/3-ACCESS-CONTROL.md diff --git a/docs/install.md b/docs/3-Install/0-README.md similarity index 99% rename from docs/install.md rename to docs/3-Install/0-README.md index d094a9a7357..af145d52245 100644 --- a/docs/install.md +++ b/docs/3-Install/0-README.md @@ -445,4 +445,4 @@ If your browser does not open automatically, navigate to: open the link, as prompted, in your browser, and follow the steps shown there. When completed, you should land at a screen that looks like this one: -![OAuth 2.0 result](images/install-result.png) +![OAuth 2.0 result](../images/install-result.png) diff --git a/docs/security.md b/docs/4-Security/0-README.md similarity index 100% rename from docs/security.md rename to docs/4-Security/0-README.md diff --git a/docs/telemetry.md b/docs/5-Telemetry/0-README.md similarity index 100% rename from docs/telemetry.md rename to docs/5-Telemetry/0-README.md diff --git a/docs/6-How To/0-README.md b/docs/6-How To/0-README.md new file mode 100644 index 00000000000..52a76ef27c2 --- /dev/null +++ b/docs/6-How To/0-README.md @@ -0,0 +1 @@ +# How To \ No newline at end of file diff --git a/docs/how-to/production.md b/docs/6-How To/1-PRODUCTION.md similarity index 100% rename from docs/how-to/production.md rename to docs/6-How To/1-PRODUCTION.md diff --git a/docs/sdk.md b/docs/7-SDK/0-README.md similarity index 83% rename from docs/sdk.md rename to docs/7-SDK/0-README.md index 2cac4163a2c..05d2da25231 100644 --- a/docs/sdk.md +++ b/docs/7-SDK/0-README.md @@ -3,4 +3,4 @@ * [Golang](./sdk/go.md) * [JavaScript](./sdk/js.md) -Missing your programming language? [Create an issue](https://github.com/ory/hydra/issues) and help us build, test and publish the SDK for your programming language! \ No newline at end of file +Missing your programming language? [Create an issue](https://github.com/ory/hydra/issues) and help us build, test and publish the SDK for your programming language! diff --git a/docs/sdk/go.md b/docs/7-SDK/1-GO.md similarity index 100% rename from docs/sdk/go.md rename to docs/7-SDK/1-GO.md diff --git a/docs/sdk/js.md b/docs/7-SDK/2-JS.md similarity index 100% rename from docs/sdk/js.md rename to docs/7-SDK/2-JS.md diff --git a/docs/sdk/php.md b/docs/7-SDK/3-PHP.md similarity index 100% rename from docs/sdk/php.md rename to docs/7-SDK/3-PHP.md diff --git a/docs/faq.md b/docs/8-FAQ/0-README.md similarity index 100% rename from docs/faq.md rename to docs/8-FAQ/0-README.md diff --git a/docs/README.md b/docs/README.md index 08fcce55fe8..41dd82e5a59 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,5 @@

- Hydra - cloud native access control + Hydra - cloud native access control

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 0d4b03de2e6..015c7a63aeb 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,82 +1,16 @@ -# Summary - -* [Introduction](README.md) - * [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) -* [Introduction Tutorial (5 minutes)](tutorial.md) -* [Dependencies](environment.md) -* Understanding Hydra - * [OAuth2 & OpenID Connect](oauth2.md) - * [Overview](oauth2.md#overview) - * [Confirming User Consent: Consent Flow](oauth2.md#consent-flow) - * [Validating Tokens: OAuth2 Token Introspection](oauth2.md#oauth2-token-introspection) - * [OAuth2 Scopes](oauth2.md#oauth2-scopes) - * [JSON Web Keys](jwk.md) - * [Access Control](access-control.md) - - [Introduction](access-control.md#introduction) - - [Warden API](access-control.md#warden-api) - - [Groups](access-control.md#groups) - - [Best Practices](access-control.md#best-practices) - - [Scalability](access-control.md#scalability) - - [URNs](access-control.md#urns) - - [Scope the Organization Name](access-control.md#scope-the-organization-name) - - [Scope Actions, Resources and Subjects](access-control.md#scope-actions-resources-and-subjects) - - [Multi-Tenant Systems](access-control.md#multi-tenant-systems) - - [Conditions & Context](access-control.md#conditions-&-context) - - [CIDR Condition](access-control.md#cidr-condition) - - [String Equal Condition](access-control.md#string-equal-condition) - - [String Match Condition](access-control.md#string-match-condition) - - [Subject Condition](access-control.md#subject-condition) - - [String Pairs Equal Condition](access-control.md#string-pairs-equal-condition) -- [Install, Configure and Run ORY Hydra (15 minutes)](install.md#install-configure-and-run-ory-hydra) - - [Create a Network](install.md#create-a-network) - - [Start a PostgreSQL container](install.md#start-a-postgresql-container) - - [Install and run ORY Hydra](install.md#install-and-run-ory-hydra) - - [Install ORY Hydra without Docker](install.md#install-ory-hydra-without-docker) - - [Download binaries](install.md#download-binaries) - - [Build from source](install.md#build-from-source) - - [Configure ORY Hydra](install.md#configure-ory-hydra) - - [Setting up the consent app](install.md#setting-up-the-consent-app) - - [Perform OAuth 2.0 Flow](install.md#perform-oauth-20-flow) -- [Security Overview](security.md#security-overview) - - [OAuth 2.0 Security Overview](security.md#oauth-20-security-overview) - - [Advanced Token Validation (Datastore Security)](security.md#advanced-token-validation-datastore-security) - - [Access Control Policies](security.md#access-control-policies) - - [Cryptography](security.md#cryptography) - - [AES-GCM](security.md#aes-gcm) - - [RS256](security.md#rs256) - - [HMAC-SHA256](security.md#hmac-sha256) - - [BCrypt](security.md#bcrypt) - - [Access Control](security.md#how-does-access-control-work-with-hydra) -* [Telemetry](telemetry.md) -* How-To - * [Running Hydra in production](how-to/production.md) -* [SDKs](sdk.md) - * [SDK for Go](sdk/go.md) - * [SDK for JavaScript](sdk/js.md) - * [Other languages](sdk.md) -* [Contribute](contribute.md) -* [FAQ](faq.md) - - [How can I control SQL connection limits?](faq.md#how-can-i-control-sql-connection-limits) - - [Why is the Resource Owner Password Credentials grant not supported?](faq.md#why-is-the-resource-owner-password-credentials-grant-not-supported) - - [Should I use OAuth2 tokens for authentication?](faq.md#should-i-use-oauth2-tokens-for-authentication) - - [How to deal with mobile apps?](faq.md#how-to-deal-with-mobile-apps) - - [How should I run migrations?](faq.md#how-should-i-run-migrations) - - [What does the installation process look like?](faq.md#what-does-the-installation-process-look-like) - - [What does a migration process look like?](faq.md#what-does-a-migration-process-look-like) - - [How can I do this in docker?](faq.md#how-can-i-do-this-in-docker) - - [Can I set the log level to warn, error, debug, ...?](faq.md#can-i-set-the-log-level-to-warn-error-debug-) - - [How can I import TLS certificates?](faq.md#how-can-i-import-tls-certificates) - - [Is there an HTTP API Documentation?](faq.md#is-there-an-http-api-documentation) - - [How can I disable HTTPS for testing?](faq.md#how-can-i-disable-https-for-testing) - - [MySQL gives `unsupported Scan, storing driver.Value type []uint8 into type *time.Time`](faq.md#mysql-gives-unsupported-scan-storing-drivervalue-type-uint8-into-type-timetime) - - [Insufficient Entropy](faq.md#insufficient-entropy) - - [The docker image exits immediately](faq.md#the-docker-image-exits-immediately) - - [I get compile errors!](faq.md#i-get-compile-errors) - - [Is JWT supported?](faq.md#is-jwt-supported) - - [Refreshing tokens](faq.md#refreshing-tokens) - - [Revoking tokens & log out](faq.md#revoking-tokens-&-log-out) - - [Operational Considerations](faq.md#operational-considerations) - - [Managing Client/Policy Definitions](faq.md#managing-clientpolicy-definitions) - - [Recovering root client access](faq.md#recovering-root-client-access) +- [5 Minute Tutorial](0-Tutorial/0-README.md) +- [Dependencies & Environment](1-Environment/0-README.md) +- [Understanding ORY Hydra](2-Overview/0-README.md) + - [OAuth 2.0 & OpenID Connect](2-Overview/1-OAUTH2.md) + - [JSON Web Keys](2-Overview/2-JWK.md) + - [Access Control](2-Overview/3-ACCESS-CONTROL.md) +- [Install, Configure and Run ORY Hydra](3-Install/0-README.md) +- [Security Overview](4-Security/0-README.md) +- [Telemetry](5-Telemetry/0-README.md) +- [How To](6-How To/0-README.md) + - [ORY Hydra in production](6-How To/1-PRODUCTION.md) +- [SDK](7-SDK/0-README.md) + - [Go SDK](7-SDK/1-GO.md) + - [JavaScript SDK](7-SDK/2-JS.md) + - [PHP SDK](7-SDK/3-PHP.md) +- [FAQ](8-FAQ/0-README.md) diff --git a/docs/access-control/policies.md b/docs/access-control/policies.md deleted file mode 100644 index 54ae0fe367c..00000000000 --- a/docs/access-control/policies.md +++ /dev/null @@ -1,97 +0,0 @@ -# Access Control Policies - -Hydra uses the Access Control Library [Ladon](https://github.com/ory/ladon). -For a deep dive, it is a good idea to read the [Ladon Docs](https://github.com/ory/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.hydra13.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", ""], - - - // 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 - -This example let's everyone, including anonymous users, read public keys. Anonymous users have no special ID and are -simply empty subject strings in Hydra. - -``` -{ - "description": "Allow everyone including anonymous users to read JSON Web Keys having Key ID *public*.", - "subjects": [ - "<.*>" - ], - "effect": "allow", - "resources": [ - "rn:hydra:keys:<[^:]+>:public" - ], - "actions": [ - "get" - ] -} -``` - -### Deny anyone from reading private JWKs - -``` -{ - "description": "Explicitly deny everyone reading JSON Web Keys with Key ID *private*.", - "subjects": [ - "<.*>" - ], - "effect": "deny", - "resources": [ - "rn:hydra:keys:<[^:]+>:private" - ], - "actions": [ - "get" - ] -} -``` diff --git a/docs/access-control/warden.md b/docs/access-control/warden.md deleted file mode 100644 index a021b64e5e3..00000000000 --- a/docs/access-control/warden.md +++ /dev/null @@ -1,6 +0,0 @@ -## 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.hydra13.apiary.io/#reference/warden:-access-control-for-resource-providers). \ No newline at end of file diff --git a/docs/contribute.md b/docs/contribute.md deleted file mode 100644 index 03f70e6d33b..00000000000 --- a/docs/contribute.md +++ /dev/null @@ -1,3 +0,0 @@ -# Contribute - -This section is work in progress. diff --git a/docs/dist/gliffy/hydra-arch.gliffy b/docs/images/gliffy/hydra-arch.gliffy similarity index 100% rename from docs/dist/gliffy/hydra-arch.gliffy rename to docs/images/gliffy/hydra-arch.gliffy diff --git a/docs/dist/gliffy/hydra.gliffy b/docs/images/gliffy/hydra.gliffy similarity index 100% rename from docs/dist/gliffy/hydra.gliffy rename to docs/images/gliffy/hydra.gliffy diff --git a/docs/overview.md b/docs/overview.md deleted file mode 100644 index bf25e726ff4..00000000000 --- a/docs/overview.md +++ /dev/null @@ -1,3 +0,0 @@ -# Overview - -This section gives you a high level overview of Hydra's core concepts and its architecture. \ No newline at end of file