diff --git a/content/nic/configuration/policy-resource.md b/content/nic/configuration/policy-resource.md index e6c2bd31c..b975821ac 100644 --- a/content/nic/configuration/policy-resource.md +++ b/content/nic/configuration/policy-resource.md @@ -33,6 +33,7 @@ Supported policy types are: - `cors` - `waf` - `externalAuth` +- `hsts` {{% table %}} @@ -50,6 +51,7 @@ Supported policy types are: | [`jwt`](#jwt-using-local-kubernetes-secret) | The JWT policy configures NGINX Plus to authenticate client requests using JSON Web Tokens. | Yes | No | | [`oidc`](#oidc) | The OIDC policy configures NGINX Plus as a relying party for OpenID Connect authentication. | Yes | No | | [`cache`](#cache) | The cache policy configures proxy caching for serving cached content. | Yes | No | +| [`hsts`](#hsts) | The HSTS policy configures [HTTP Strict Transport Security](https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/) for ensuring secure connections to the server. | Yes | No | {{% /table %}} @@ -1327,6 +1329,61 @@ policies: In this example NGINX Ingress Controller will use the configuration from the first policy reference `waf-policy-one`, and ignores `waf-policy-two`. +### HSTS + +The HSTS policy configures [HTTP Strict Transport Security](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security), instructing browsers to enforce HTTPS connections to the host for a specified duration. + +For example, the following policy configures a 30-day HSTS duration and extends the policy to all subdomains of the host: + +```yaml +hsts: + maxAge: 2592000 + includeSubDomains: true +``` + +When deployed behind a proxy or load balancer that terminates TLS upstream of the Ingress Controller, enable `behindProxy`. In this mode, NGINX uses the `X-Forwarded-Proto` request header to determine whether the connection is HTTPS, rather than checking the `$https` variable directly: + +```yaml +hsts: + maxAge: 2592000 + behindProxy: true +``` + +A VirtualServer that references an HSTS policy must: + +- Enable [TLS termination]({{< ref "/nic/configuration/virtualserver-and-virtualserverroute-resources.md#virtualservertls" >}}), or `behindProxy` if TLS is terminated upstream. +- Reference the policy in the VirtualServer [spec]({{< ref "/nic/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-specification" >}}). It is not allowed to reference an HSTS policy in a [route]({{< ref "/nic/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserverroute" >}}) or in a VirtualServerRoute [subroute]({{< ref "/nic/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserverroutesubroute" >}}). + +If the conditions above are not met, NGINX will send the `500` status code to clients. + +{{< call-out class="note" >}} + +The feature is implemented using the NGINX `add_header` directive and the [ngx_http_ssl_module](https://nginx.org/en/docs/http/ngx_http_ssl_module.html) `$https` variable. + +{{< /call-out >}} + +{{% table %}} + +|Field | Description | Type | Required | Default | +| ---| ---| ---| --- | --- | +|``maxAge`` | Sets the duration in seconds that the browser should cache and enforce the HSTS policy. | ``int`` | Yes | -- | +|``includeSubDomains`` | Extends the HSTS policy to all subdomains of the host. | ``bool`` | No | `false` | +|``behindProxy`` | Configures NGINX to set the HSTS header based on the `X-Forwarded-Proto` request header rather than the `$https` variable. Enable this when the Ingress Controller is deployed behind a proxy or load balancer that terminates TLS upstream. | ``bool`` | No | `false` | + +{{% /table %}} + +#### HSTS Merging Behavior + +A VirtualServer can reference only a single HSTS policy. Every subsequent reference will be ignored. For example, here we reference two policies: + +```yaml +policies: +- name: hsts-policy-one +- name: hsts-policy-two +``` + +In this example NGINX Ingress Controller will use the configuration from the first policy reference `hsts-policy-one`, and ignores `hsts-policy-two`. + ## Using Policy You can use the usual `kubectl` commands to work with Policy resources, just as with built-in Kubernetes resources.