From c2c9c84c48584eab2f8f5166654ae700ebda96f7 Mon Sep 17 00:00:00 2001 From: Aeneas Date: Thu, 7 Dec 2017 17:12:59 +0100 Subject: [PATCH] docs: Adds ACP best practices (#681) --- docs/SUMMARY.md | 6 +++-- docs/access-control.md | 52 ++++++++++++++++++++++++++++++++++++++---- 2 files changed, 51 insertions(+), 7 deletions(-) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 0a3983f46fb..49b869515aa 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -12,8 +12,10 @@ * [Validating Tokens: OAuth2 Token Introspection](oauth2.md#oauth2-token-introspection) * [OAuth2 Scopes](oauth2.md#oauth2-scopes) * [JSON Web Keys](jwk.md) - * [Access Control Policies](access-control.md) - * [Introduction](access-control.md#introduction-to-access-control-policies) + * [Access Control](access-control.md) + * [Access Control Policies](access-control.md#access-control-policies) + * [Introduction](access-control.md#introduction) + * [Best Practices](access-control.md#best-practices) * [The Warden](access-control.md#warden) - [Install, Configure and Run ORY Hydra (15 minutes)](install.md#install-configure-and-run-ory-hydra) - [Start a PostgreSQL container](install.md#start-a-postgresql-container) diff --git a/docs/access-control.md b/docs/access-control.md index 27d48aa7279..b98098e8a93 100644 --- a/docs/access-control.md +++ b/docs/access-control.md @@ -1,10 +1,23 @@ -# Access Control Policies +# Access Control -Besides OAuth2 Token Introspection, Hydra offers Access Control Policies using -the [Ladon](https://github.com/ory/ladon) framework. Access Control Policies are used by Hydra internally and exposed -via various HTTP APIs. +OAuth 2.0 is a protocol that allows applications to act on a user's behalf, +without knowing their credentials. While it offers a secure flow for applications +(web apps, mobile apps, touchpoints, IoT) to gain access to your APIs, +it does not specify what access rights users actually have. +The frequent question "is the user actually allowed to access that resource?" +is not answered by OAuth 2.0, nor by OpenID Connect. -## Introduction to Access Control Policies +For that reason, ORY Hydra offers something we call Access Control Policies. +If you ever worked with Google Cloud IAM or AWS IAM, you probably know +what these policies look like. Access Control Policies are a powerful tool +capable of modeling simple and complex access control environments, such as +simple read/write APIs or complex multi-tenant environments. + +The next sections give you an overview and best practices of these principles. + +## Access Control Policies + +### Introduction Hydra's Access Control is able to answer the question: @@ -64,6 +77,35 @@ In this case, the access request will be allowed: 4. `"remoteIP": "192.168.0.5"` matches the [`CIDRCondition`](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) condition that was configured for the field `remoteIP`. +### Best Practices + +This sections gives an overview of best practices for access control policies +we developed over the years at ORY. + +#### URNs + +> “There are only two hard things in Computer Science: cache invalidation and naming things.” +-- Phil Karlton + +URN naming is as hard as naming API endpoints. Thankfully, by doing the latter, the former is usually solved as well. +We will explore further best practices in the following sections. + +##### Scope the organization name + +A rule of thumb is to prefix resource names with a domain that represents the organization creating the software. + +* **Do not:** `` +* **Do:** `:` + +##### Scope actions, resources and subjects + +It is wise to scope actions, resources, and subjects in order to prevent name collisions: + +* **Do not:** `myorg.com:`, `myorg.com:`, `myorg.com:` +* **Do:** `myorg.com:subjects:`, `myorg.com:resources:`, `myorg.com:actions:` +* **Do:** `subjects:myorg.com:`, `resources:myorg.com:`, `actions:myorg.com:` + + ## Access Control Decisions: The Warden The warden is a HTTP API allowing you to perform these access requests.