github.com/KyaXTeam/consul@v1.4.5/website/source/docs/connect/intentions.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "Connect - Intentions" 4 sidebar_current: "docs-connect-intentions" 5 description: |- 6 Intentions define access control for services via Connect and are used to control which services may establish connections. Intentions can be managed via the API, CLI, or UI. 7 --- 8 9 # Intentions 10 11 Intentions define access control for services via Connect and are used 12 to control which services may establish connections. Intentions can be 13 managed via the API, CLI, or UI. 14 15 Intentions are enforced by the [proxy](/docs/connect/proxies.html) 16 or [natively integrated application](/docs/connect/native.html) on 17 inbound connections. After verifying the TLS client certificate, the 18 [authorize API endpoint](#) is called which verifies the connection 19 is allowed by testing the intentions. If authorize returns false the 20 connection must be terminated. 21 22 The default intention behavior is defined by the default 23 [ACL policy](/docs/guides/acl.html). If the default ACL policy is "allow all", 24 then all Connect connections are allowed by default. If the default ACL policy 25 is "deny all", then all Connect connections are denied by default. 26 27 ## Intention Basics 28 29 Intentions can be managed via the 30 [API](#), 31 [CLI](#), 32 or UI. Please see the respective documentation for each for full details 33 on options, flags, etc. 34 Below is an example of a basic intention to show the basic attributes 35 of an intention. The full data model of an intention can be found in the 36 [API documentation](#). 37 38 ``` 39 $ consul intention create -deny web db 40 Created: web => db (deny) 41 ``` 42 43 The intention above is a deny intention with a source of "web" and 44 destination of "db". This says that connections from web to db are not 45 allowed and the connection will be rejected. 46 47 When an intention is modified, existing connections will not be affected. 48 This means that changing a connection from "allow" to "deny" today 49 _will not_ kill the connection. Addressing this shortcoming is on 50 the near term roadmap for Consul. 51 52 ### Wildcard Intentions 53 54 An intention source or destination may also be the special wildcard 55 value `*`. This matches _any_ value and is used as a catch-all. Example: 56 57 ``` 58 $ consul intention create -deny web '*' 59 Created: web => * (deny) 60 ``` 61 62 This example says that the "web" service cannot connect to _any_ service. 63 64 ### Metadata 65 66 Arbitrary string key/value data may be associated with intentions. This 67 is unused by Consul but can be used by external systems or for visibility 68 in the UI. 69 70 ``` 71 $ consul intention create \ 72 -deny \ 73 -meta description='Hello there' \ 74 web db 75 ... 76 77 $ consul intention get web db 78 Source: web 79 Destination: db 80 Action: deny 81 ID: 31449e02-c787-f7f4-aa92-72b5d9b0d9ec 82 Meta[description]: Hello there 83 Created At: Friday, 25-May-18 02:07:51 CEST 84 ``` 85 86 ## Precedence and Match Order 87 88 Intentions are matched in an implicit order based on specificity, preferring 89 deny over allow. Specificity is determined by whether a value is an exact 90 specified value or is the wildcard value `*`. 91 The full precedence table is shown below and is evaluated 92 top to bottom, with larger numbers being evaluated first. 93 94 | Source Name | Destination Name | Precedence | 95 | ----------- | ---------------- | ---------- | 96 | Exact | Exact | 9 | 97 | `*` | Exact | 8 | 98 | Exact | `*` | 6 | 99 | `*` | `*` | 5 | 100 101 The precedence value can be read from the [API](/api/connect/intentions.html) 102 after an intention is created. 103 Precedence cannot be manually overridden today. This is a feature that will 104 be added in a later version of Consul. 105 106 In the case the two precedence values match, Consul will evaluate 107 intentions based on lexographical ordering of the destination then 108 source name. In practice, this is a moot point since authorizing a connection 109 has an exact source and destination value so its impossible for two 110 valid non-wildcard intentions to match. 111 112 The numbers in the table above are not stable. Their ordering will remain 113 fixed but the actual number values may change in the future. 114 The numbers are non-contiguous because there are 115 some unused values in the middle in preparation for a future version of 116 Consul supporting namespaces. 117 118 ## Intention Management Permissions 119 120 Intention management can be protected by [ACLs](/docs/guides/acl.html). 121 Permissions for intentions are _destination-oriented_, meaning the ACLs 122 for managing intentions are looked up based on the destination value 123 of the intention, not the source. 124 125 Intention permissions are by default implicitly granted at `read` level 126 when granting `service:read` or `service:write`. This is because a 127 service registered that wants to use Connect needs `intentions:read` 128 for its own service name in order to know whether or not to authorize 129 connections. The following ACL policy will implicitly grant `intentions:read` 130 (note _read_) for service `web`. 131 132 ```hcl 133 service "web" { 134 policy = "write" 135 } 136 ``` 137 138 It is possible to explicitly specify intention permissions. For example, 139 the following policy will allow a service to be discovered without granting 140 access to read intentions for it. 141 142 ```hcl 143 service "web" { 144 policy = "read" 145 intentions = "deny" 146 } 147 ``` 148 149 Note that `intentions:read` is required for a token that a Connect-enabled 150 service uses to register itself or it's proxy. If the token used does not 151 have `intentions:read` then the agent will be unable to resolve intentions 152 for the service and so will not be able to authorize any incoming connections. 153 154 ~> **Security Note:** Explicitly allowing `intentions:write` on the token you 155 provide to a service instance at registration time opens up a significant 156 additional vulnerability. Although you may trust the service _team_ to define 157 which inbound connections they accept, using a combined token for registration 158 allows a compromised instance to to redefine the intentions which allows many 159 additional attack vectors and may be hard to detect. We strongly recommend only 160 delegating `intentions:write` using tokens that are used by operations teams or 161 orchestrators rather than spread via application config, or only manage 162 intentions with management tokens. 163 164 ## Performance and Intention Updates 165 166 The intentions for services registered with a Consul agent are cached 167 locally on that agent. They are then updated via a background blocking query 168 against the Consul servers. 169 170 Connect connection attempts require only local agent 171 communication for authorization and generally impose only impose microseconds 172 of latency to the connection. All actions in the data path of connections 173 require only local data to ensure minimal performance overhead. 174 175 Updates to intentions are propagated nearly instantly to agents since agents 176 maintain a continuous blocking query in the background for intention updates 177 for registered services. 178 179 Because all the intention data is cached locally, the agents can fail static. 180 Even if the agents are severed completely from the Consul servers, inbound 181 connection authorization continues to work for a configured amount of time. 182 Changes to intentions will not be picked up until the partition heals, but 183 will then automatically take effect when connectivity is restored.