From f156bceaf7e4aa3a257bd780ad6ef93df0ca136e Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Mon, 5 Jul 2021 17:58:11 -0400 Subject: [PATCH] contrib: add first draft of ACL docs --- contributing/INTERNALS.md | 1 - contributing/acl/README.md | 35 +++++++++++++++++++ contributing/acl/acl-entity-relationship.svg | 1 - .../{acl-entity-relationship.mmd => erd.mmd} | 11 ++++-- contributing/acl/erd.svg | 1 + contributing/consul-mermaid-theme.json | 2 +- 6 files changed, 45 insertions(+), 6 deletions(-) create mode 100644 contributing/acl/README.md delete mode 100644 contributing/acl/acl-entity-relationship.svg rename contributing/acl/{acl-entity-relationship.mmd => erd.mmd} (77%) create mode 100644 contributing/acl/erd.svg diff --git a/contributing/INTERNALS.md b/contributing/INTERNALS.md index 1e37536475..1fe71ad021 100644 --- a/contributing/INTERNALS.md +++ b/contributing/INTERNALS.md @@ -36,7 +36,6 @@ There are several other top-level packages used internally by Consul as well as | Directory | Contents | | --------- | -------- | -| [acl](https://github.com/hashicorp/consul/tree/main/api) | This supports the underlying policy engine for Consul's [ACL](https://www.consul.io/docs/guides/acl.html) system. | | [api](https://github.com/hashicorp/consul/tree/main/api) | This `api` package provides an official Go API client for Consul, which is also used by Consul's [CLI](https://www.consul.io/docs/commands/index.html) commands to communicate with the local Consul agent. | | [api/watch](https://github.com/hashicorp/consul/tree/main/api/watch) | This has implementation details for Consul's [watches](https://www.consul.io/docs/agent/watches.html), used both internally to Consul and by the [watch CLI command](https://www.consul.io/docs/commands/watch.html). | | [website](https://github.com/hashicorp/consul/tree/main/website) | This has the full source code for [consul.io](https://www.consul.io/). Pull requests can update the source code and Consul's documentation all together. | diff --git a/contributing/acl/README.md b/contributing/acl/README.md new file mode 100644 index 0000000000..2be733c3b6 --- /dev/null +++ b/contributing/acl/README.md @@ -0,0 +1,35 @@ +# ACL + +This section is a work in progress. + +The ACL subsystem is responsible for authenticating and authorizing access to Consul +operations ([HTTP API], and [RPC]). + +[HTTP API]: ../http-api +[RPC]: ../rpc + +## ACL Entities + +There are many entities in the ACL subsystem. The diagram below shows the relationship +between the entities. + +![Entity Relationship Diagram](./erd.svg) + +[source](./erd.mmd) + +ACL Tokens are at the center of the ACL system. Tokens are associated with a set of +Policies, and Roles. + +AuthMethods, which consist of BindingRules, are a mechanism for creating ACL Tokens from +policies stored in external systems (ex: kubernetes, JWT, or OIDC). + +Roles are a set of policies associated with a named role, and ServiceIdentity and +NodeIdentity are policy templates that are associated with a specific service or node and +can be rendered into a full policy. + +Each Policy contains a set of rules. Each rule relates to a specific resource, and +includes an AccessLevel (read, write, list or deny). + +An ACL Token can be resolved into an Authorizer. The Authorizer is what is used by the +[HTTP API], and [RPC] endpoints to determine if an operation is allowed or forbidden (the +enforcement decision). diff --git a/contributing/acl/acl-entity-relationship.svg b/contributing/acl/acl-entity-relationship.svg deleted file mode 100644 index 8b9f57c72c..0000000000 --- a/contributing/acl/acl-entity-relationship.svg +++ /dev/null @@ -1 +0,0 @@ -TokenPolicyRoleServiceIdentityNodeIdentityAuthMethodBindingRuleRulegrantsincludesincludesincludesincludesincludesincludesincludesdefinescreatesimpliesimplies \ No newline at end of file diff --git a/contributing/acl/acl-entity-relationship.mmd b/contributing/acl/erd.mmd similarity index 77% rename from contributing/acl/acl-entity-relationship.mmd rename to contributing/acl/erd.mmd index 87031aabe0..3a9ec446c1 100644 --- a/contributing/acl/acl-entity-relationship.mmd +++ b/contributing/acl/erd.mmd @@ -7,9 +7,10 @@ erDiagram NodeIdentity AuthMethod BindingRule - Rule - // TODO: rules are made up of resources and x (enforcement decision or permission?) - // TODO: add Authorizer and Enforcement Decision + Rule { + string Resource + enum AccessLevel + } Policy ||--|{ Rule: grants Role ||--|{ Policy: includes @@ -26,3 +27,7 @@ erDiagram ServiceIdentity ||--|{ Rule: implies NodeIdentity ||--|{ Rule: implies + + Token ||--|| Authorizer: "resolves to" + Authorizer ||--|{ EnforcementDecision: produces + diff --git a/contributing/acl/erd.svg b/contributing/acl/erd.svg new file mode 100644 index 0000000000..47c4f8acaf --- /dev/null +++ b/contributing/acl/erd.svg @@ -0,0 +1 @@ +TokenPolicyRoleServiceIdentityNodeIdentityAuthMethodBindingRuleRulestringResourceenumAccessLevelAuthorizerEnforcementDecisiongrantsincludesincludesincludesincludesincludesincludesincludesdefinescreatesimpliesimpliesresolves toproduces \ No newline at end of file diff --git a/contributing/consul-mermaid-theme.json b/contributing/consul-mermaid-theme.json index c847b2cb88..c3823254b1 100644 --- a/contributing/consul-mermaid-theme.json +++ b/contributing/consul-mermaid-theme.json @@ -1,4 +1,4 @@ { "theme": "default", - "themeCSS": ".node rect { fill: rgb(220, 71, 125); stroke-width: 1; stroke: black; } .node .label { color: white; }; .cluster rect { fill: #f0f0f0; stroke-width: 1px; stroke: #333}; .edgeLabel { background-color: #f0f0f0; }" + "themeCSS": ".node rect, .er.entityBox { fill: rgb(220, 71, 125); stroke-width: 1; stroke: black; } .node .label { color: white; }; .cluster rect { fill: #f0f0f0; stroke-width: 1px; stroke: #333}; .edgeLabel { background-color: #f0f0f0; }; .er.entityBox + .er.entityLabel { fill: white }; .er.attributeBoxEven, .er.attributeBoxOdd { fill: #fff; stroke: #777 }" }