github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update intentions documentation to clarify ACL behavior (#4546) 

* Update intentions documentation to clarify ACL behavior

* Incorprate @banks suggestions into docs

* Fix my own typos!
pull/4547/head
jjshanks 2018-08-20 12:03:53 -07:00 committed by Paul Banks
parent 542cace9a2
commit 657b8d27ac
2 changed files with 33 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
website/source/api/connect/intentions.html.md
View File

@ -32,7 +32,7 @@ The table below shows this endpoint's support for
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ---------------- |
| `NO` | `none` | `service:write` |
| `NO` | `none` | `service {intentions:write}` |
### Parameters

46
website/source/docs/connect/intentions.html.md
View File

@ -122,27 +122,45 @@ Permissions for intentions are _destination-oriented_, meaning the ACLs
for managing intentions are looked up based on the destination value
of the intention, not the source.
Intention permissions are first inherited from `service` management permissions.
For example, the ACL below would allow _read_ access to intentions with a
destination starting with "web":
```hcl
service "web" {
policy = "read"
}
```
ACLs may also specify service-specific intention permissions. In the example
below, the ACL token may register a "web"-prefixed service but _may not_ read or write
intentions:
Intention permissions are by default implicitly granted at `read` level
when granting `service:read` or `service:write`. This is because a
service registered that wants to use Connect needs `intentions:read`
for its own service name in order to know whether or not to authorize
connections. The following ACL policy will implicitly grant `intentions:read`
(note _read_) for service `web`.
```hcl
service "web" {
policy = "write"
intention = "deny"
}
```
It is possible to explicitly specify intention permissions. For example,
the following policy will allow a service to be discovered without granting
access to read intentions for it.
```hcl
service "web" {
policy = "read"
intentions = "deny"
}
```
Note that `intentions:read` is required for a token that a Connect-enabled
service uses to register itself or it's proxy. If the token used does not
have `intentions:read` then the agent will be unable to resolve intentions
for the service and so will not be able to authorize any incoming connections.
~> **Security Note:** Explicitly allowing `intentions:write` on the token you
provide to a service instance at registration time opens up a significant
additional vulnerability. Although you may trust the service _team_ to define
which inbound connections they accept, using a combined token for registration
allows a compromised instance to to redefine the intentions which allows many
additional attack vectors and may be hard to detect. We strongly recommend only
delegating `intentions:write` using tokens that are used by operations teams or
orchestrators rather than spread via application config, or only manage
intentions with management tokens.
## Performance and Intention Updates
The intentions for services registered with a Consul agent are cached