Rule evaluation determines whether a web request should be allowed or denied by using the rules that you set in your policy. It considers the following attributes to make its decisions:
- Priority of a rule: Lower integers indicate higher priorities.
- SessionMatcher: Matches against the following session level attributes:
- IP address of the source machine
- Service account of the source machine
- Secure Tag of the source machine
- Hostname of the target machine
- ApplicationMatcher: Matches against the following HTTP request attributes:
- Request headers
For a list of all the
ApplicationMatcher attributes, see
Available attributes in
How rule evaluation works
The rules are evaluated in the following order:
- High-priority rules are evaluated first.
- The highest priority rule that matches the
ApplicationMatcherattributes determines the action to be taken on the traffic.
- If the request does not match the
ApplicationMatcherattributes of that rule, the next rule with the highest priority is evaluated.
- This process continues until a rule is found that matches the request, or all the rules have been evaluated. If no match is found, the request is denied.
Before you configure TLS inspection
You must understand the following rule-evaluation scenarios before you configure TLS inspection:
A client can send an HTTP request to the proxy server. The request is then evaluated by using all the available data, including the hostname, source identity, HTTP headers, and path.
If the request is allowed, the HTTP traffic is sent to the destination. However, if the request is denied, the HTTP traffic is not allowed to pass.
A client can send the proxy an HTTP CONNECT request to establish a TCP tunnel to the destination. This is done when the client wants to send arbitrary TCP traffic or establish an end-to-end TLS connection with the destination through the proxy, as with HTTPS.
If a rule has a matching
SessionMatcherattribute and does not contain an
ApplicationMatcherattribute, and the rule evaluation results in allowing the traffic, then a tunnel to the destination is established and the traffic is TCP-proxied. This applies to HTTPS and TCP traffic.
If higher priority rules are unable to determine the action to be taken on a request, then the rule evaluation continues. If the evaluation proceeds to a rule with an
ApplicationMatcherattribute, then the tunneled traffic is interpreted as HTTP or HTTPS.
If the underlying data is not HTTP or HTTPS, then the connection fails.
If the underlying data is HTTP, then the requests are evaluated, including the hostname, source identity, HTTP headers, and path. Based on the evaluation result, the traffic is either allowed or denied.
For HTTPS traffic, a rule is evaluated only if it has the TLS inspection flag enabled; otherwise, that rule is skipped.
For HTTPS traffic, a rule is inspected only if the following conditions are true:
- The TLS inspection flag is enabled.
- Traffic matches the
Recommendations for configuring TLS inspection rules
- If you want to allow TCP traffic, then the rule that allows TCP traffic must have a higher priority than the rules that allow HTTP traffic.
- Rules with the
ApplicationMatcherattribute should be tightly scoped by using the
SessionMatcherattribute to minimize the interpretation of unrelated flows as HTTP.
- Rules that allow TLS (including HTTPS) traffic but do not perform TLS inspection can be interpreted as TCP proxy rules.
- To avoid unnecessary TLS inspection of traffic, TLS inspection rules
should be lower in priority than non-TLS inspection rules. Alternatively,
to fail fast for non-matching traffic, TLS inspection rules should be
tightly scoped by using the
Examples of TLS inspection rule configurations
Consider the two rules in the following examples.
In this example, we assume the presence of other lower priority rules. Consider the following two rules:
description: do not allow POST requests priority: 10 basicProfile: DENY sessionMatcher: true tlsInspectionEnabled: true applicationMatcher: request.method == 'POST'
description: allow TCP proxying from tag 12345 to example.com priority: 20 basicProfile: ALLOW sessionMatcher: source.matchTag('tagValues/12345') && host() == 'example.com'
In this example, Secure Web Proxy interprets the two rules as follows:
- Allowing TCP traffic but disallowing a specific type of HTTP request is mutually exclusive because the TCP traffic can contain a POST request.
- Traffic in rule 2 is never allowed. It is denied because the traffic from tag 12345 to example.com is intercepted and interpreted as HTTP to evaluate the HTTP method.
For rule 2 to take effect, you can use either of the following solutions:
- Recommended: Increase the priority of rule 2 to a higher level (priority: 5).
Scope rule 1 to avoid overlapping the allowed traffic with its
sessionMatcher: !(source.matchTag('tagValues/12345') && host() == 'example.com')
We do not recommend this solution because it becomes difficult to maintain many overlapping rules.
Consider the following two rules:
description: allow to specific GitHub repository (TLS inspect to match specific path) priority: 10 basicProfile: ALLOW sessionMatcher: true tlsInspectionEnabled: true applicationMatcher: request.url().startsWith('github.com/grpc/grpc')
description: allow TCP proxying from tag 12345 to example.com priority: 20 basicProfile: ALLOW sessionMatcher: host() == 'bankofamerica.com'
In this example, Secure Web Proxy interprets the two rules as follows:
- All traffic, including that destined for
bankofamerica.com, is inspected for TLS to match the
request.url()of the high priority rule 1.
To avoid TLS inspection in rule 2, you can use either of the following solutions:
- Increase the priority of rule 2 to a higher level (priority: 5).
As a result, rule 2 is applied before evaluating rule 1, and
bankofamerica.comis allowed without being TLS inspected.
Recommended: Narrow the scope of rule 1 to allow TLS inspection specifically for the
github.comdomain. To narrow the scope, add a targeted
sessionMatcher: host() == 'github.com'
- Increase the priority of rule 2 to a higher level (priority: 5). As a result, rule 2 is applied before evaluating rule 1, and traffic from
You must consider these limitations before configuring TLS inspection:
Servers are only verified by using public root certificates. The root certificate authority (CA) set is based on the Mozilla Root Program. The behavior of certificate verification is subject to change and corresponds to how web browsers verify certificates.
Because backend verification is not possible at this time, traffic to servers with private or self-signed certificates cannot be intercepted.
Secure Web Proxy does not run certificate revocation list (CRL) checks.
For TLS inspection to work, clients must currently send Server Name Indication (SNI). SNI is a TLS specification extension that is optional, but most clients enable it by default.
TLS inspection does not work if the client requires Encrypted Client Hello (ECH) (formerly known as Encrypted SNI).
ECH is a draft IETF standard that allows clients to encrypt the beginning of the TLS handshake by using a pre-established server key. Because TLS inspection is acting as an intercepting proxy, it does not have access to that pre-established server key. As a result, ECH does not function.
Clients must be configured to trust your private root certificate.
If you remove CAs from your private CA pool, you are served cached certificates signed by that CA for up to 28 hours. To prevent using the cached certificates, you can update your TLS inspection policy to point to a new CA pool. As a result, Secure Web Proxy is forced to generate new certificates.