Skip to content

Commit 19cb4f9

Browse files
bmcelveebmcelvee
committed
OSDOCS-2457: document procedures for Global Options to Enable HTTP Strict Transport Security (HSTS)
1 parent dce750b commit 19cb4f9

File tree

5 files changed

+243
-49
lines changed

5 files changed

+243
-49
lines changed

‎modules/nw-disabling-hsts.adoc‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
// Module included in the following assemblies:
2+
// * networking/configuring-routing.adoc
3+
4+
[id="nw-disabling-hsts_{context}"]
5+
= Disabling HTTP Strict Transport Security per-route
6+
7+
To disable HTTP strict transport security (HSTS) per-route, you can set the `max-age` value in the route annotation to `0`.
8+
9+
.Prerequisites
10+
11+
* You are logged in to the cluster with a user with `cluster-admin` privileges.
12+
* You installed the `oc` CLI.
13+
14+
.Procedure
15+
16+
* To disable HSTS, set the `max-age` value in the route annotation to `0`, by entering the following command:
17+
+
18+
[source,terminal]
19+
----
20+
$ oc annotate route <rout_name> -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=0"
21+
----
22+
+
23+
[TIP]
24+
====
25+
You can alternatively apply the following YAML to create the config map:
26+
27+
.Example of disabling HSTS per-route
28+
[source,yaml]
29+
----
30+
metadata:
31+
annotations:
32+
haproxy.router.openshift.io/hsts_header: max-age=0
33+
----
34+
====
35+
36+
* To disable HSTS for every route in a namespace, enter the followinf command:
37+
+
38+
[source,terminal]
39+
----
40+
$ oc annotate <route> --all -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=0"
41+
----
42+
43+
.Verification
44+
45+
. To query the annotation for all routes, enter the following command:
46+
+
47+
[source,terminal]
48+
----
49+
$ oc get route --all-namespaces -o go-template='{{range .items}}{{if .metadata.annotations}}{{$a := index .metadata.annotations "haproxy.router.openshift.io/hsts_header"}}{{$n := .metadata.name}}{{with $a}}Name: {{$n}} HSTS: {{$a}}{{"\n"}}{{else}}{{""}}{{end}}{{end}}{{end}}'
50+
----
51+
+
52+
.Example output
53+
[source,terminal]
54+
----
55+
Name: routename HSTS: max-age=0
56+
----

‎modules/nw-enabling-hsts-per-route.adoc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Module included in the following assemblies:
2+
// * networking/configuring-routing.adoc
3+
4+
[id="nw-enabling-hsts-per-route_{context}"]
5+
= Enabling HTTP Strict Transport Security per-route
6+
7+
HTTP strict transport security (HSTS) is implemented in the HAProxy template and applied to edge and re-encrypt routes that have the `haproxy.router.openshift.io/hsts_header` annotation.
8+
9+
.Prerequisites
10+
11+
* You are logged in to the cluster with a user with `cluster-admin` privileges.
12+
* You installed the `oc` CLI.
13+
14+
.Procedure
15+
16+
* To enable HSTS on a route, add the `haproxy.router.openshift.io/hsts_header` value to the edge-terminated or re-encrypt route:
17+
+
18+
.Example route configured with an annotation
19+
[source,yaml]
20+
----
21+
apiVersion: v1
22+
kind: Route
23+
metadata:
24+
annotations:
25+
haproxy.router.openshift.io/hsts_header: max-age=31536000;includeSubDomains;preload <1> <2> <3>
26+
...
27+
spec:
28+
host: def.abc.com
29+
tls:
30+
termination: "reencrypt"
31+
...
32+
wildcardPolicy: "Subdomain"
33+
----
34+
<1> Required. `max-age` measures the length of time, in seconds, that the HSTS policy is in effect. If set to `0`, it negates the policy.
35+
<2> Optional. When included, `includeSubDomains` tells the client
36+
that all subdomains of the host must have the same HSTS policy as the host.
37+
<3> Optional. When `max-age` is greater than 0, you can add `preload` in `haproxy.router.openshift.io/hsts_header` to allow external services to include this site in their HSTS preload lists. For example, sites such as Google can construct a list of sites that have `preload` set. Browsers can then use these lists to determine which sites they can communicate with over HTTPS, even before they have interacted with the site. Without `preload` set, browsers must have interacted with the site over HTTPS, at least once, to get the header.

‎modules/nw-enabling-hsts.adoc‎

Lines changed: 10 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -3,54 +3,19 @@
33
// * networking/configuring-routing.adoc
44

55
[id="nw-enabling-hsts_{context}"]
6-
= Enabling HTTP strict transport security
6+
= HTTP Strict Transport Security
77

8-
HTTP Strict Transport Security (HSTS) policy is a security enhancement, which
9-
ensures that only HTTPS traffic is allowed on the host. Any HTTP requests are
10-
dropped by default. This is useful for ensuring secure interactions with
11-
websites, or to offer a secure application for the user's benefit.
8+
HTTP Strict Transport Security (HSTS) policy is a security enhancement, which signals to the browser client that only HTTPS traffic is allowed on the route host. HSTS also optimizes web traffic by signaling HTTPS transport is required, without using HTTP redirects. HSTS is useful for speeding up interactions with websites.
129

13-
When HSTS is enabled, HSTS adds a Strict Transport Security header to HTTPS
14-
responses from the site. You can use the `insecureEdgeTerminationPolicy` value
15-
in a route to redirect to send HTTP to HTTPS. However, when HSTS is enabled, the
16-
client changes all requests from the HTTP URL to HTTPS before the request is
17-
sent, eliminating the need for a redirect. This is not required to be supported
18-
by the client, and can be disabled by setting `max-age=0`.
10+
When HSTS policy is enforced, HSTS adds a Strict Transport Security header to HTTP and HTTPS responses from the site. You can use the `insecureEdgeTerminationPolicy` value in a route to redirect HTTP to HTTPS. When HSTS is enforced, the client changes all requests from the HTTP URL to HTTPS before the request is sent, eliminating the need for a redirect.
11+
12+
Cluster administrators can configure HSTS to do the following:
13+
14+
* Enable HSTS per-route
15+
* Disable HSTS per-route
16+
* Enforce HSTS per-domain, for a set of domains, or use namespace labels in combination with domains
1917

2018
[IMPORTANT]
2119
====
22-
HSTS works only with secure routes (either edge terminated or re-encrypt). The
23-
configuration is ineffective on HTTP or passthrough routes.
20+
HSTS works only with secure routes, either edge-terminated or re-encrypt. The configuration is ineffective on HTTP or passthrough routes.
2421
====
25-
26-
.Procedure
27-
* To enable HSTS on a route, add the `haproxy.router.openshift.io/hsts_header`
28-
value to the edge terminated or re-encrypt route:
29-
+
30-
[source,yaml]
31-
----
32-
apiVersion: v1
33-
kind: Route
34-
metadata:
35-
annotations:
36-
haproxy.router.openshift.io/hsts_header: max-age=31536000;includeSubDomains;preload <1> <2> <3>
37-
----
38-
+
39-
<1> `max-age` is the only required parameter.
40-
It measures the length of time, in seconds, that the
41-
HSTS policy is in effect. The client updates `max-age` whenever a response
42-
with a HSTS header is received from the host. When `max-age` times out, the
43-
client discards the policy.
44-
+
45-
<2> `includeSubDomains` is optional. When included, it tells the client
46-
that all subdomains
47-
of the host are to be treated the same as the host.
48-
+
49-
<3> `preload` is optional. When `max-age` is greater than 0, then including
50-
`preload` in `haproxy.router.openshift.io/hsts_header` allows external
51-
services to include this site in their HSTS preload lists. For example, sites
52-
such as Google can construct a list of sites that have `preload` set. Browsers
53-
can then use these lists to determine which sites they can communicate with
54-
over HTTPS,
55-
before they have interacted with the site. Without `preload` set, browsers must
56-
have interacted with the site over HTTPS to get the header.

‎modules/nw-enforcing-hsts-per-domain.adoc‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
// Module included in the following assemblies:
2+
// * networking/configuring-routing.adoc
3+
4+
[id="nw-enforcing-hsts-per-domain_{context}"]
5+
= Enforcing HTTP Strict Transport Security per-domain
6+
7+
To enforce HTTP Strict Transport Security (HSTS) per-domain for secure routes, add a `requiredHSTSPolicies` record to the Ingress spec to capture the configuration of the HSTS policy.
8+
9+
If you configure a `requiredHSTSPolicy` to enforce HSTS, then any newly created route must be configured with a compliant HSTS policy annotation.
10+
11+
[NOTE]
12+
====
13+
To handle upgraded clusters with non-compliant HSTS routes, you can update the manifests at the source and apply the updates.
14+
====
15+
16+
[NOTE]
17+
====
18+
You cannot use `oc expose route` or `oc create route` commands to add a route in a domain that enforces HSTS, because the API for these commands does not accept annotations.
19+
====
20+
21+
[IMPORTANT]
22+
====
23+
HSTS cannot be applied to secure, or non-TLS routes, even if HSTS is requested for all routes globally.
24+
====
25+
26+
.Prerequisites
27+
28+
* You are logged in to the cluster with a user with `cluster-admin` privileges.
29+
* You installed the `oc` CLI.
30+
31+
.Procedure
32+
33+
. Edit the Ingress config file:
34+
+
35+
[source,terminal]
36+
----
37+
$ oc edit ingresses.config.openshift.io/cluster
38+
----
39+
+
40+
.Example HSTS policy
41+
[source,yaml]
42+
----
43+
apiVersion: config.openshift.io/v1
44+
kind: Ingress
45+
metadata:
46+
name: cluster
47+
spec:
48+
domain: 'hello-openshift-default.apps.username.devcluster.openshift.com'
49+
requiredHSTSPolicies: <1>
50+
- domainPatterns: <2>
51+
- '*hello-openshift-default.apps.username.devcluster.openshift.com'
52+
- '*hello-openshift-default2.apps.username.devcluster.openshift.com'
53+
namespaceSelector: <3>
54+
matchLabels:
55+
myPolicy: strict
56+
maxAge: <4>
57+
smallestMaxAge: 1
58+
largestMaxAge: 31536000
59+
preloadPolicy: RequirePreload <5>
60+
includeSubDomainsPolicy: RequireIncludeSubDomains <6>
61+
- domainPatterns: <2>
62+
- 'abc.example.com'
63+
- '*xyz.example.com'
64+
namespaceSelector:
65+
matchLabels: {}
66+
maxAge: {}
67+
preloadPolicy: NoOpinion
68+
includeSubDomainsPolicy: RequireNoIncludeSubDomains
69+
----
70+
<1> Required. `requiredHSTSPolicies` are validated in order, and the first matching `domainPatterns` applies.
71+
<2> Required. You must specify at least one `domainPatterns` hostname. Any number of domains can be listed. You can include multiple sections of enforcing options for different `domainPatterns`.
72+
<3> Optional. If you include `namespaceSelector`, it must match the labels of the project where the routes reside, to enforce the set HSTS policy on the routes. Routes that only match the `namespaceSelector` and not the `domainPatterns` are not validated.
73+
<4> Required. `max-age` measures the length of time, in seconds, that the HSTS policy is in effect. This policy setting allows for a smallest and largest `max-age` to be enforced.
74+
75+
- The `largestMaxAge` value must be between `0` and `2147483647`. It can be left unspecified, which means no upper limit is enforced.
76+
- The `smallestMaxAge` value must be between `0` and `2147483647`. Enter `0` to disable HSTS for troubleshooting, otherwise enter `1` if you never want HSTS to be disabled. It can be left unspecified, which means no lower limit is enforced.
77+
<5> Optional. Including `preload` in `haproxy.router.openshift.io/hsts_header` allows external services to include this site in their HSTS preload lists. Browsers can then use these lists to determine which sites they can communicate with over HTTPS, before they have interacted with the site. Without `preload` set, browsers need to interact at least once with the site to get the header. `preload` can be set with one of the following:
78+
79+
- `RequirePreload`: `preload` is required by the `RequiredHSTSPolicy`.
80+
- `RequireNoPreload`: `preload` is forbidden by the `RequiredHSTSPolicy`.
81+
- `NoOpinion`: `preload` does not matter to the `RequiredHSTSPolicy`.
82+
<6> Optional. `includeSubDomainsPolicy` can be set with one of the following:
83+
84+
- `RequireIncludeSubDomains`: `includeSubDomains` is required by the `RequiredHSTSPolicy`.
85+
- `RequireNoIncludeSubDomains`: `includeSubDomains` is forbidden by the `RequiredHSTSPolicy`.
86+
- `NoOpinion`: `includeSubDomains` does not matter to the `RequiredHSTSPolicy`.
87+
+
88+
. You can apply HSTS to all routes in the cluster or in a particular namespace by entering the `oc annotate command`.
89+
+
90+
* To apply HSTS to all routes in the cluster, enter the `oc annotate command`. For example:
91+
+
92+
[source,terminal]
93+
----
94+
$ oc annotate route --all --all-namespaces --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000"
95+
----
96+
+
97+
* To apply HSTS to all routes in a particular namespace, enter the `oc annotate command`. For example:
98+
+
99+
[source,terminal]
100+
----
101+
$ oc annotate route --all -n my-namespace --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000"
102+
----
103+
104+
.Verification
105+
106+
You can review the HSTS policy you configured. For example:
107+
108+
* To review the `maxAge` set for required HSTS policies, enter the following command:
109+
+
110+
[source,terminal]
111+
----
112+
$ oc get clusteroperator/ingress -n openshift-ingress-operator -o jsonpath='{range .spec.requiredHSTSPolicies[*]}{.spec.requiredHSTSPolicies.maxAgePolicy.largestMaxAge}{"\n"}{end}'
113+
----
114+
+
115+
* To review the HSTS annotations on all routes, enter the following command:
116+
+
117+
[source,terminal]
118+
----
119+
$ oc get route --all-namespaces -o go-template='{{range .items}}{{if .metadata.annotations}}{{$a := index .metadata.annotations "haproxy.router.openshift.io/hsts_header"}}{{$n := .metadata.name}}{{with $a}}Name: {{$n}} HSTS: {{$a}}{{"\n"}}{{else}}{{""}}{{end}}{{end}}{{end}}'
120+
----
121+
+
122+
.Example output
123+
[source,terminal]
124+
----
125+
Name: <_routename_> HSTS: max-age=31536000;preload;includeSubDomains
126+
----

‎networking/routes/route-configuration.adoc‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,25 @@ toc::[]
99

1010
//Creating route timeouts
1111
include::modules/nw-configuring-route-timeouts.adoc[leveloffset=+1]
12-
//
13-
//Enabling HTTP Strict Transport Security
12+
13+
//HTTP Strict Transport Security
1414
include::modules/nw-enabling-hsts.adoc[leveloffset=+1]
15-
//
15+
16+
//Enabling HTTP strict transport security per-route
17+
include::modules/nw-enabling-hsts-per-route.adoc[leveloffset=+2]
18+
19+
//Disabling HTTP strict transport security per-route
20+
include::modules/nw-disabling-hsts.adoc[leveloffset=+2]
21+
22+
//Enforcing HTTP strict transport security per-domain
23+
include::modules/nw-enforcing-hsts-per-domain.adoc[leveloffset=+2]
24+
1625
//Troubleshooting Throughput Issues
1726
include::modules/nw-throughput-troubleshoot.adoc[leveloffset=+1]
18-
//
27+
1928
//Using cookies to keep route statefulness
2029
include::modules/nw-using-cookies-keep-route-statefulness.adoc[leveloffset=+1]
30+
2131
include::modules/nw-annotating-a-route-with-a-cookie-name.adoc[leveloffset=+2]
2232

2333
include::modules/nw-path-based-routes.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)