Announcing NGINX Plus R24

We’re happy to announce the availability of NGINX Plus Release 24 (R24). Based on NGINX Open Source, NGINX Plus is the only all-in-one software web server, load balancer, reverse proxy, content cache, and API gateway.

New features in NGINX Plus R24 include:

• Encrypted JSON Web Tokens – Building on the support for signed JSON Web Tokens (JWTs) in earlier releases, NGINX Plus now supports encrypted JWTs for confidentiality and data integrity of sensitive information when stored in web browsers and other clients.
• A major milestone in the development of the NGINX JavaScript Module – New features – in particular response filtering for both HTTP headers and bodies, and support for HTTP‑based authentication services for TCP/UDP connections and sessions – unlock a number of powerful new use cases.
• Integration with F5 Device ID+ – This real‑time, high‑precision device identifier assigns a unique identifier to each device visiting your site, enabling stronger protection against known bad actors and customized user experiences for returning visitors.

Rounding out the release are optional persistence across configuration reloads of the results of mandatory health checks and dynamic values for cookie flags.

Important Changes in Behavior

Deprecated Cookie-Flag Module

As announced at the release of NGINX Plus R23, the third‑party Cookie‑Flag module is deprecated and will be removed from the dynamic modules repo in NGINX Plus R26. The set_cookie_flag directive defined in that module is replaced by the proxy_cookie_flags directive. We recommend that you replace any set_cookie_flag directives in your configuration with proxy_cookie_flags directives as soon as possible. Also see Dynamic Cookie Flags.

Changes to Platform Support

• New operating systems supported:
  • Alpine Linux 3.13 (aarch64, amd64)
  • CentOS 7.4+ (aarch64, in addition to x86_64 and ppc64le)
  • FreeBSD 13 (amd64)
  • SLES 15 SP2
• Older operating systems removed:
  • Debian 9 is no longer supported; oldest supported version is 10
• Older operating systems deprecated and scheduled for removal in NGINX Plus R25:
  • Alpine Linux 3.10
  • Amazon Linux 1 (2018.03+)
  • FreeBSD 11
  • Ubuntu 16.04 LTS

Amazon Linux 2 Depends on OpenSSL 1.1

The NGINX Plus package for Amazon Linux 2 now depends on OpenSSL 1.1, which enables TLS 1.3 and strengthens security in numerous other ways. When upgrading Amazon Linux 2 systems to NGINX Plus R24, confirm that other software that uses OpenSSL on the system still works correctly with OpenSSL 1.1.

Changes to the NGINX Plus Installation Procedure

We have reorganized the NGINX Plus package repositories, with resulting changes to the installation procedure.

The change in repository organization reflects the expansion of our product portfolio and of the ecosystem of products that depend on NGINX Plus. For NGINX Plus in particular, the pkgs.nginx.com/plus repo replaces the old plus-pkgs.nginx.com repo.

When you install and upgrade NGINX Plus, the operating system’s package manager (apt, yum, or equivalent) is configured with the software repository for NGINX Plus. On existing systems that are configured to use the plus-pkgs.nginx.com repo, you need to update the package manager to refer to pkgs.nginx.com/plus (plus the final path element that indicates the OS).

For instructions on upgrading an existing system to NGINX Plus R24, see the F5 Knowledge Base. For updated instructions for initial installation, see Installing NGINX Plus in the NGINX Plus Admin Guide.

Consolidation of HTTP Connection‑Handling Directives

As the HTTP/3 standard nears completion and the usage of HTTP/2 increases, we have simplified how long‑lived connections are configured. In NGINX Plus R24 and later, configuration directives that previously applied only to HTTP/1.1 also work for HTTP/2. You no longer need to use different directives for the same functionality just because the protocol version is different.

More Aggressive Connection Closure

In NGINX Plus R23 and later, the lingering_close, lingering_time, and lingering_timeout directives work for HTTP/2 as well as HTTP/1.1. Configuring more efficient handling of HTTP/2 connections with these directives improves NGINX Plus’s overall HTTP/2 capabilities.

NGINX Plus R24 modifies the effect of these directives in an important way and eliminates a potential bug: if the pool of free worker connections are exhausted, NGINX Plus starts closing not only keepalive connections, but also connections in lingering‑close mode.

Changed Severity Level for Logged Health Status Changes

NGINX writes an entry to the error log when the health status of an upstream server changes – an important tool for monitoring and analyzing the overall health of your infrastructure. The severity level at which status changes are logged has changed for both HTTP and TCP/UDP (stream) upstream servers:

• Change from healthy to unhealthy is logged at the warn level (was info).
• Change from unhealthy to healthy is logged at the notice level (was info).

New Features in Detail

Encrypted JSON Web Tokens

The use of JSON Web Tokens (JWTs) continues to grow. Previously, NGINX Plus supported signed tokens (the JSON Web Signature [JWS] standard defined in RFC 7515), which provide data integrity for the claims encoded in the token. However, JWS does not provide confidentiality for claims – they can be read by any component that has access to the token. TLS/SSL mitigates the exposure for tokens in transit, but tokens stored in web browsers and other clients are still exposed.

NGINX Plus R24 introduces support for encrypted tokens (the JSON Web Encryption [JWE] standard defined in RFC 7516), which provide both confidentiality and data integrity for the entire claim set. Sensitive or personally identifiable information (PII) can now be encoded inside JWTs without risk of that data being leaked by insecure clients.

NGINX Plus R24 and later supports both signed and encrypted JWTs. Signed tokens are the default, and require no explicit configuration. The new auth_jwt_type directive configures JWT encryption.

You define the encryption (or signing) algorithm and key usage in the JWT key file named by the auth_jwt_key_file directive. NGINX Plus R24 and later supports the following encryption methods.

Major Maturity Milestone for the NGINX JavaScript Module

NGINX Plus R24 marks a major milestone in the development of the NGINX JavaScript module (njs), now at 0.5.3. There are two important enhancements that enable you to extend NGINX Plus with custom solutions for a wide variety of use cases:

• Response filtering for both the headers and bodies of HTTP responses
• An embedded HTTP client that can be used to make HTTP requests during HTTP or TCP/UDP processing

If you are unfamiliar with the NGINX JavaScript module, please read this introduction on our blog<.htmla>.

[The use cases described in this section are just some of the many use cases for the NGINX JavaScript module. For a complete list, see Use Cases for the NGINX JavaScript Module.]

Response Filtering

One of the most powerful features of NGINX Plus deployed as an API gateway or reverse proxy is response filtering, which involves intercepting responses from upstream servers and replacing strings in the response body, headers, or both, based on regular expression matching. For traffic not being manipulated with the NGINX JavaScript module, response filtering is implemented in the Substitution module.

NGINX Plus R24 introduces a separate implementation of response filtering within the NGINX JavaScript module, with two directives that enable you to take advantage of the power of JavaScript to analyze and modify response bodies and headers. JavaScript extends the possibilities for inspection and manipulation far beyond simple string substitution based on regular expressions, for even more powerful response filtering than with the Substitution module.

Filtering Response Bodies with the js_body_filter Directive

With the js_body_filter directive you can use JavaScript to inspect and modify the body of the response from a proxied server. Use cases include:

• Scanning for complex patterns with regular expressions
• Transforming data format
• Inserting dynamic content into responses

In this example we scan responses for anything that looks like an AWS access key, and replace any such occurrences with a masked‑out value.

To execute this code we need simply to reference the maskAwsKeys function inside the relevant location block.

Filtering Response Headers with the js_header_filter Directive

You can use the js_header_filter directive to examine – or even intercept and modify – the contents of response headers. Consider a backend server that issues a number of Set-Cookie headers which contain sensitive information but are essential to correct operation. NGINX Plus is able to intercept the response, read the Set-Cookie headers, and save them in the key‑value store. A replacement Set-Cookie header can be created as a reference to the key‑value store, and injected in the original response.

On lines 4–5 of the NGINX Plus configuration we define the key‑value store:

Then on lines 12–13 we replace the reference cookie with the contents of the key‑value store, and intercept any new cookies with our JavaScript code.

The JavaScript code iterates over each new Set-Cookie response header and creates a new key‑value entry to store it.

Leveraging HTTP Services for TCP/UDP with a Simple HTTP Client

The primary use case for an API gateway is controlling access to specific resources. NGINX Plus supports a powerful set of authentication and access‑control features at Layer 7 for HTTP requests, but modern API implementations also leverage TCP/UDP as the underlying protocol, presenting new authentication challenges.

With the built‑in NGINX JavaScript ngx.fetch function, you can now instantiate a simple HTTP client from within the context of a TCP/UDP connection. This enables the use of HTTP‑based authentication services for access control in the stream context, for example calling a local OpenPolicy Agent daemon when proxying a database connection.

This example demonstrates the use of a local HTTP authentication service on port 8085 to authenticate each new connection. The js_access directive and ngx.fetch function together implement functionality in the newly instantiated HTTP context that is similar to client authorization based on the result of a subrequest (as implemented by the auth_request directive for regular HTTP requests). Based on the HTTP status code available in the Response object, the connection to the backend database is allowed (s.allow) or rejected (s.deny).

Note: The ngx.fetch function works with the NGINX JavaScript HTTP module as well as the NGINX JavaScript Stream module, but has significant limitations compared to the r.subrequest object in the HTTP module. For most HTTP use cases, r.subrequest is preferred as it provides support for TLS connections, caching, and all of the capabilities in the Proxy module.

Other njs Enhancements

When an NGINX variable is defined with the set [HTTP][Stream] or js_set [HTTP][Stream] directive, the value can get overridden when request processing encounters a redirect. The new js_var [HTTP][Stream] directive enables a variable to be evaluated by a JavaScript function, and its value to persist across redirects.

The new njs.on object enables a JavaScript function to be executed when the njs virtual machine exits. This can be used to execute a function at the end of a TCP connection, for example.

The new s.status property of the Stream session object provides access to the overall session status (see $status for possible values).

Integration with F5 Device ID+

F5 Device ID+ is a real‑time, high‑precision device identifier that utilizes advanced signal collection and proven machine‑learning algorithms to assign a unique identifier to each device visiting your site. Deployment is simple, with immediate benefits for your security, networking, fraud, and digital teams. Never has understanding the unique devices visiting your applications been so easy.

For instructions on activating F5 Device ID+ on your NGINX Plus instances, see Mitigate Fraud and Risk with F5 Device ID+.

Benefits of Using F5 Device ID+

• Strengthen application security – Strengthen your attack detection and mitigation analysis through accurate device identification. Recognize returning devices that your security systems have already flagged as suspicious.
• Optimize traffic management – Incorporate a unique device identifier into routing logic to better manage and optimize network traffic. Identify devices even when malicious actors manipulate Layer 7 data.
• Mitigate fraud and risk – Monitor customer behavior across operations like new account creation, user authentication, e‑commerce checkout, and financial transactions, detecting anomalous patterns that might indicate identity theft among other threats.
• Personalize and accelerate online experiences – Make login, checkout, and authentication seamless for known returning users and devices. A/B testing by F5 demonstrates that reducing security friction increases revenue, and device identification is an important element in any strategy for friction reduction.

How F5 Device ID+ Works

When each user visits your website, F5 Device ID+ leverages JavaScript to collect information about the browser, device’s OS, hardware, and network configuration. These attributes feed into the F5 Device ID+ service built on F5 Shape’s industry‑recognized AI and machine learning capabilities. The data is processed in real time, and a unique identifier is assigned to the device, unless it is already a known device. For returning devices, behavior, actions, and other properties can be recorded, learned, and studied to facilitate the reduction of fraud and a smooth experience for known good users.

Other Enhancements in NGINX Plus R24

Status from Mandatory Health Checks Can Persist Across Configuration Reloads

Mandatory health checks are used to enable the slow‑start of upstream servers that are added using the NGINX Plus API or through DNS resolution. They ensure that new nodes are first health‑checked, and then slow‑started once they are ready to receive traffic.

Previously, after a configuration reload upstream servers were considered unhealthy regardless of their status before the reload. As a result, the servers didn’t accept client requests until the first mandatory check had passed.

With NGINX Plus R24, you can mark mandatory HTTP health checks as persistent, so that their previous state is remembered when the configuration is reloaded. Add the persistent parameter to the health_check directive along with the mandatory parameter.

Dynamic Cookie Flags

In the previous release of NGINX Plus we introduced the proxy_cookie_flags directive as a native method for setting cookie flags. NGINX Plus R24 extends this capability by enabling dynamic values for cookie flags. This enables specific cookie flags to be controlled by NGINX variables.

Note: The proxy_cookie_flags directive deprecates the Cookie‑Flag module, which will be removed in NGINX Plus R26. See Deprecated Cookie‑Flag Module.

This example uses a map to enable the Secure cookie flag when the scheme is https rather than http.

Upgrade or Try NGINX Plus

If you’re running NGINX Plus, we strongly encourage you to upgrade to NGINX Plus R24 as soon as possible. You’ll also pick up several additional fixes and improvements, and it will help NGINX to help you when you need to raise a support ticket.

If you haven’t tried NGINX Plus, we encourage you to try it out – for security, load balancing, and API gateway, or as a fully supported web server with enhanced monitoring and management APIs. You can get started today with a free 30-day trial.