Skip to content

Commit fcea746

Browse files
y82route443
y82
and
route443
authored
OIDC deployment guides update for NGINX Plus R36 (#1505)
Update OIDC deployment guides to reflect R36 capabilities. Co-authored-by: Ivan Ovchinnikov <i.ovchinnikov@f5.com>
1 parent a2e53bc commit fcea746

File tree

8 files changed

+278
-78
lines changed

8 files changed

+278
-78
lines changed

‎content/nginx/deployment-guides/single-sign-on/active-directory-federation-services.md‎

Lines changed: 44 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,13 @@ nd-docs: DOCS-1683
1010

1111
This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Microsoft Active Directory Federation Services](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services) (AD FS) as the Identity Provider (IdP) and NGINX Plus as the Relying Party (RP), or OIDC client application that verifies user identity.
1212

13-
{{< call-out "note" >}} This guide applies to [NGINX Plus Release 35]({{< ref "nginx/releases.md#r35" >}}) and later. In earlier versions, NGINX Plus relied on an [njs-based solution](#legacy-njs-guide), which required NGINX JavaScript files, key-value stores, and advanced OpenID Connect logic. In the latest NGINX Plus version, the new [OpenID Connect module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) simplifies this process to just a few directives.{{< /call-out >}}
13+
{{< call-out "note" >}} This guide applies to [NGINX Plus Release 36]({{< ref "nginx/releases.md#r36" >}}) and later. In earlier versions, NGINX Plus relied on an [njs-based solution](#legacy-njs-guide), which required NGINX JavaScript files, key-value stores, and advanced OpenID Connect logic. In the latest NGINX Plus version, the new [OpenID Connect module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) simplifies this process to just a few directives.{{< /call-out >}}
1414

1515
## Prerequisites
1616

1717
- A Microsoft AD FS instance, either on-premises or in [Azure](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/deployment/how-to-connect-fed-azure-adfs), with administrator privileges.
1818

19-
- An NGINX Plus [subscription](https://www.f5.com/products/nginx/nginx-plus) and NGINX Plus [Release 35]({{< ref "nginx/releases.md#r35" >}}) or later. For installation instructions, see [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/).
19+
- An NGINX Plus [subscription](https://www.f5.com/products/nginx/nginx-plus) and NGINX Plus [Release 36]({{< ref "nginx/releases.md#r36" >}}) or later. For installation instructions, see [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/).
2020

2121
- A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`.
2222

@@ -66,6 +66,17 @@ After creating the application group, you need to configure the logout URLs to s
6666

6767
- Add the post logout URL, for example: `https://demo.example.com/post_logout/`.
6868

69+
4. To enable OpenID Connect front-channel logout (single sign-out when the user signs out of another application):
70+
71+
- Use PowerShell to configure a **LogoutUri** for the AD FS client (there is no GUI option for this). For example, run:
72+
73+
```powershell
74+
Set-AdfsClient -TargetClientId <client-id> -LogoutUri https://demo.example.com/front_logout/
75+
```
76+
Replace `<client-id>` with the Client Identifier from [Step 5](#adfs-setup-id) above (the AD FS Application ID) and substitute the domain name of your NGINX Plus instance for `demo.example.com`.
77+
78+
This registers a front-channel logout URL (`LogoutUri`) for the client in AD FS. When a user signs out of this or any other application in AD FS, the AD FS server sends a GET request to this URL (typically via a hidden iframe) with the user's session ID (`sid`) as a query parameter, instructing NGINX Plus to clear the user's session. According to the OpenID Connect front-channel logout specification, the identity provider is supposed to send both an issuer (`iss`) and a session ID; AD FS provides only the `sid` parameter, but the NGINX Plus OIDC module supports both the fully compliant `iss+sid` and the `sid`-only variants and will clear the session in either case.
79+
6980
### Get the OpenID Connect Discovery URL
7081
7182
Check the OpenID Connect endpoint URL. By default, AD FS publishes the `.well-known/openid-configuration` document at the following address:
@@ -97,6 +108,8 @@ Check the OpenID Connect endpoint URL. By default, AD FS publishes the `.well-kn
97108
"jwks_uri": "https://adfs-server-address/adfs/discovery/keys",
98109
"userinfo_endpoint": "https://adfs-server-address/adfs/userinfo",
99110
"end_session_endpoint": "https://adfs-server-address/adfs/oauth2/logout",
111+
"frontchannel_logout_supported": true,
112+
"frontchannel_logout_session_supported": true
100113
...
101114
}
102115
```
@@ -118,10 +131,10 @@ With AD FS configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t
118131
nginx -v
119132
```
120133

121-
The output should match NGINX Plus Release 35 or later:
134+
The output should match NGINX Plus Release 36 or later:
122135

123136
```text
124-
nginx version: nginx/1.29.0 (nginx-plus-r35)
137+
nginx version: nginx/1.29.3 (nginx-plus-r36)
125138
```
126139

127140
2. Ensure that you have the values of the **Client ID**, **Client Secret**, and **Issuer** obtained during [AD FS Configuration](#adfs-setup).
@@ -165,27 +178,36 @@ With AD FS configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t
165178

166179
- The **logout_uri** is URI that a user visits to start an RP‑initiated logout flow.
167180

181+
- The **frontchannel_logout_uri** directive defines the URI that receives OpenID Connect front-channel logout requests from AD FS. This URI must be an HTTPS path and must match the LogoutUri configured for the client in AD FS. When AD FS triggers a front-channel logout (for example, when a user signs out of another application), it sends a GET request to this URI (typically via a hidden iframe) with the session ID (sid) as a query parameter. The OIDC module clears the corresponding user session on NGINX Plus.
182+
168183
- The **post_logout_uri** is absolute HTTPS URL where AD FS should redirect the user after a successful logout. This value **must also be configured** in the AD FS application properties.
169184

170185
- If the **logout_token_hint** directive set to `on`, NGINX Plus sends the user's ID token as a *hint* to AD FS.
171186
This directive is **optional**, however, if it is omitted the AD FS may display an extra confirmation page asking the user to approve the logout request.
172187
173188
- If the **userinfo** directive is set to `on`, NGINX Plus will fetch `/userinfo` from the AD FS and append the claims from userinfo to the `$oidc_claims_` variables.
174189
190+
- PKCE (Proof Key for Code Exchange) is automatically enabled when the provider's OpenID Connect discovery document advertises the S256 code challenge method in the code_challenge_methods_supported field. You can override this behavior with the pkce directive: set `pkce off;` to disable PKCE even when S256 is advertised, or `pkce on;` to force PKCE even if the IdP's metadata does not list S256.
191+
175192
- {{< call-out "important" >}} All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system's CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP's certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP's certificate. {{< /call-out >}}
176193
177194
```nginx
178195
http {
179196
resolver 10.0.0.1 ipv4=on valid=300s;
180197
181198
oidc_provider adfs {
182-
issuer https://adfs.example.com/adfs;
183-
client_id <client_id>;
184-
client_secret <client_secret>;
185-
logout_uri /logout;
186-
post_logout_uri https://demo.example.com/post_logout/;
187-
logout_token_hint on;
188-
userinfo on;
199+
issuer https://adfs.example.com/adfs;
200+
client_id <client_id>;
201+
client_secret <client_secret>;
202+
logout_uri /logout;
203+
post_logout_uri https://demo.example.com/post_logout/;
204+
frontchannel_logout_uri /front_logout;
205+
logout_token_hint on;
206+
userinfo on;
207+
208+
# Optional: PKCE configuration. By default, PKCE is automatically
209+
# enabled when the IdP advertises the S256 code challenge method.
210+
# pkce on;
189211
}
190212
191213
# ...
@@ -314,8 +336,14 @@ http {
314336
post_logout_uri https://demo.example.com/post_logout/;
315337
logout_token_hint on;
316338
339+
# Front-channel logout
340+
frontchannel_logout_uri /front_logout;
341+
317342
# Fetch userinfo claims
318343
userinfo on;
344+
345+
# Optional: PKCE configuration (enabled automatically when supported by the IdP)
346+
# pkce on;
319347
}
320348
321349
server {
@@ -373,10 +401,12 @@ If you are running NGINX Plus R33 and earlier or if you still need the njs-based
373401

374402
- [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html)
375403

376-
- [Release Notes for NGINX Plus R35]({{< ref "nginx/releases.md#r35" >}})
404+
- [Release Notes for NGINX Plus R36]({{< ref "nginx/releases.md#r36" >}})
377405

378406
## Revision History
379407

380-
- Version 2 (August 2025) – Added RP‑initiated logout (logout_uri, post_logout_uri, logout_token_hint) and userinfo support.
408+
- Version 3 (November 2025) – Updated for NGINX Plus R36; added front-channel logout support (`frontchannel_logout_uri`), PKCE configuration (`pkce` directive), and the `client_secret_post` token endpoint authentication method.
409+
410+
- Version 2 (August 2025) – Updated for NGINX Plus R35; added RP‑initiated logout (`logout_uri`, `post_logout_uri`, `logout_token_hint`) and `userinfo` support.
381411

382-
- Version 1 (March 2025) – Initial version (NGINX Plus Release 34)
412+
- Version 1 (March 2025) – Initial version (NGINX Plus Release 34).

‎content/nginx/deployment-guides/single-sign-on/auth0.md‎

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,13 @@ nd-docs: DOCS-1686
1010

1111
This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Auth0](https://auth0.com/features/single-sign-on) as the Identity Provider (IdP), and NGINX Plus as the Relying Party, or OIDC client application that verifies user identity.
1212

13-
{{< call-out "note" >}} This guide applies to [NGINX Plus Release 35]({{< ref "nginx/releases.md#r35" >}}) and later. In earlier versions, NGINX Plus relied on an [njs-based solution](#legacy-njs-guide), which required NGINX JavaScript files, key-value stores, and advanced OpenID Connect logic. In the latest NGINX Plus version, the new [OpenID Connect module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) simplifies this process to just a few directives.{{< /call-out >}}
13+
{{< call-out "note" >}} This guide applies to [NGINX Plus Release 36]({{< ref "nginx/releases.md#r36" >}}) and later. In earlier versions, NGINX Plus relied on an [njs-based solution](#legacy-njs-guide), which required NGINX JavaScript files, key-value stores, and advanced OpenID Connect logic. In the latest NGINX Plus version, the new [OpenID Connect module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) simplifies this process to just a few directives.{{< /call-out >}}
1414

1515
## Prerequisites
1616

1717
- An [Auth0](https://auth0.com/) tenant with administrator privileges.
1818

19-
- An NGINX Plus [subscription](https://www.f5.com/products/nginx/nginx-plus) and NGINX Plus [Release 35]({{< ref "nginx/releases.md#r35" >}}) or later. For installation instructions, see [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/).
19+
- An NGINX Plus [subscription](https://www.f5.com/products/nginx/nginx-plus) and NGINX Plus [Release 36]({{< ref "nginx/releases.md#r36" >}}) or later. For installation instructions, see [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/).
2020

2121
- A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`.
2222

@@ -101,10 +101,10 @@ With Auth0 configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t
101101
nginx -v
102102
```
103103

104-
The output should match NGINX Plus Release 35 or later:
104+
The output should match NGINX Plus Release 36 or later:
105105

106106
```none
107-
nginx version: nginx/1.29.0 (nginx-plus-r35)
107+
nginx version: nginx/1.29.3 (nginx-plus-r36)
108108
```
109109

110110
2. Ensure that you have the values of the **Client ID**, **Client Secret**, and **Issuer** obtained during [Auth0 Configuration](#auth0-setup).
@@ -156,6 +156,10 @@ With Auth0 configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t
156156

157157
- If the **userinfo** directive is set to `on`, NGINX Plus will fetch `/userinfo` from the Auth0 and append the claims from userinfo to the `$oidc_claims_` variables.
158158

159+
- PKCE (Proof Key for Code Exchange) is automatically enabled when Auth0's OpenID Connect discovery document advertises the `S256` code challenge method in the `code_challenge_methods_supported` field. You can override this behavior with the [`pkce`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#pkce) directive: set `pkce off;` to disable PKCE even when `S256` is advertised, or `pkce on;` to force PKCE even if the IdP metadata does not list `S256`.
160+
161+
- The module automatically selects the client authentication method for the token endpoint based on the provider metadata `token_endpoint_auth_methods_supported`. When only `client_secret_post` is advertised, NGINX Plus uses the `client_secret_post` method and sends the client credentials in the POST body. When both `client_secret_basic` and `client_secret_post` are present, the module prefers HTTP Basic (`client_secret_basic`), which remains the default for Auth0.
162+
159163
- {{< call-out "important" >}} All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system’s CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP’s certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP’s certificate. {{< /call-out >}}
160164

161165
```nginx
@@ -170,6 +174,10 @@ With Auth0 configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t
170174
post_logout_uri https://demo.example.com/post_logout/;
171175
logout_token_hint on;
172176
userinfo on;
177+
178+
# Optional: PKCE configuration. By default, PKCE is automatically
179+
# enabled when the IdP advertises the S256 code challenge method.
180+
# pkce on;
173181
}
174182
175183
# ...
@@ -292,6 +300,9 @@ http {
292300

293301
# Fetch userinfo claims
294302
userinfo on;
303+
304+
# Optional: PKCE configuration
305+
# pkce on;
295306
}
296307

297308
server {
@@ -348,10 +359,12 @@ If you are running NGINX Plus R33 and earlier or if you still need the njs-based
348359
349360
- [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html)
350361
351-
- [Release Notes for NGINX Plus R35]({{< ref "nginx/releases.md#r35" >}})
362+
- [Release Notes for NGINX Plus R36]({{< ref "nginx/releases.md#r36" >}})
352363
353364
## Revision History
354365
355-
- Version 2 (August 2025) – Added RP‑initiated logout (logout_uri, post_logout_uri, logout_token_hint) and userinfo support.
366+
- Version 3 (November 2025) – Updated for NGINX Plus R36; added PKCE configuration (`pkce` directive) and the `client_secret_post` token endpoint authentication method.
367+
368+
- Version 2 (August 2025) – Updated for NGINX Plus R35; added RP‑initiated logout (`logout_uri`, `post_logout_uri`, `logout_token_hint`) and `userinfo` support.
356369
357-
- Version 1 (March 2025) – Initial version (NGINX Plus Release 34)
370+
- Version 1 (March 2025) – Initial version (NGINX Plus Release 34).

0 commit comments

Comments
 (0)