Update OIDC deployment guides to reflect R35 capabilities. (#952)

Authored-by: Ivan Ovchinnikov <[email protected]>
Authored-by: Ivan Ovchinnikov <[email protected]>

Author: y82

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

@@ -11,14 +11,14 @@ nd-docs: DOCS-1683
 
 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.
 
-{{< call-out "note" >}} This guide applies to [NGINX Plus Release 34]({{< ref "nginx/releases.md#r34" >}}) 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 >}}
+{{< 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 >}}
 
 
 ## Prerequisites
 
 - 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.
 
-- An NGINX Plus [subscription](https://www.f5.com/products/nginx/nginx-plus) and NGINX Plus [Release 34](({{< ref "nginx/releases.md#r34" >}})) or later. For installation instructions, see [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/).
+- 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/).
 
 - A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`.
 
@@ -57,6 +57,18 @@ This guide explains how to enable single sign-on (SSO) for applications being pr
 
    - Select **Next** to complete the steps for adding the application group.
 
+### Configure Logout URLs
+
+After creating the application group, you need to configure the logout URLs to support RP-initiated logout:
+
+1. In **AD FS Management**, navigate to **Application Groups** and select your application group.
+
+2. Right-click on the application group and select **Properties**.
+
+3. In the **Properties** dialog, add the post logout redirect URI to the application configuration:
+
+   - Add the post logout URL, for example: `https://demo.example.com/post_logout/`.
+
 ### Get the OpenID Connect Discovery URL
 
 Check the OpenID Connect endpoint URL. By default, AD FS publishes the `.well-known/openid-configuration` document at the following address:
@@ -86,6 +98,8 @@ Check the OpenID Connect endpoint URL. By default, AD FS publishes the `.well-kn
        "authorization_endpoint": "https://adfs-server-address/adfs/oauth2/authorize/",
        "token_endpoint": "https://adfs-server-address/adfs/oauth2/token/",
        "jwks_uri": "https://adfs-server-address/adfs/discovery/keys",
+       "userinfo_endpoint": "https://adfs-server-address/adfs/userinfo",
+       "end_session_endpoint": "https://adfs-server-address/adfs/oauth2/logout",
        ...
    }
    ```
@@ -101,18 +115,18 @@ Check the OpenID Connect endpoint URL. By default, AD FS publishes the `.well-kn
 
 ## Set up NGINX Plus {#nginx-plus-setup}
 
-With AF DS configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as the Rely Party (RP) application &mdash; a client service that verifies user identity.
+With AD FS configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as the Rely Party (RP) application &mdash; a client service that verifies user identity.
 
 
 1.  Ensure that you are using the latest version of NGINX Plus by running the `nginx -v` command in a terminal:
 
     ```shell
     nginx -v
     ```
-    The output should match NGINX Plus Release 34 or later:
+    The output should match NGINX Plus Release 35 or later:
 
     ```none
-    nginx version: nginx/1.27.4 (nginx-plus-r34)
+    nginx version: nginx/1.29.0 (nginx-plus-r35)
     ```
 
 2.  Ensure that you have the values of the **Client ID**, **Client Secret**, and **Issuer** obtained during [AD FS Configuration](#adfs-setup).
@@ -154,16 +168,29 @@ With AF DS configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t
 
       The `issuer` is typically your AD FS OIDC URL. By default, NGINX forms the provider metadata endpoint by appending `.well-known/openid-configuration` to the issuer. For AD FS, this often resolves to `https://adfs-server-address/adfs/.well-known/openid-configuration`. If your AD FS issuer differs from `https://adfs-server-address/adfs` (for example, a custom path), you can explicitly specify the metadata document with the [`config_url`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#config_url) directive.
 
-    - **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.
+    - The **logout_uri** is URI that a user visits to start an RP‑initiated logout flow.
+
+    - 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.
+
+    - If the **logout_token_hint** directive set to `on`, NGINX Plus sends the user's ID token as a *hint* to AD FS.
+      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.
+
+    - 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.
+
+    - **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.
 
     ```nginx
     http {
         resolver 10.0.0.1 ipv4=on valid=300s;
 
         oidc_provider adfs {
-            issuer        https://adfs.example.com/adfs;
-            client_id     <client_id>;
-            client_secret <client_secret>;
+            issuer            https://adfs.example.com/adfs;
+            client_id         <client_id>;
+            client_secret     <client_secret>;
+            logout_uri        /logout;
+            post_logout_uri   https://demo.example.com/post_logout/;
+            logout_token_hint on;
+            userinfo          on;
         }
 
         # ...
@@ -195,7 +222,7 @@ With AF DS configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t
     }
     ```
 
-8.  Protect this [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) with AD FS OIDC by specifying the [`auth_oidc`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#auth_oidc) directive that will point to the `afds` configuration specified in the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context in [Step 5](#adfs-setup-oidc-provider):
+8.  Protect this [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) with AD FS OIDC by specifying the [`auth_oidc`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#auth_oidc) directive that will point to the `adfs` configuration specified in the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context in [Step 5](#adfs-setup-oidc-provider):
 
     ```nginx
     # ...
@@ -237,7 +264,18 @@ With AF DS configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t
     ```
 
     <span id="oidc_app"></span>
-10. Create a simple test application referenced by the `proxy_pass` directive which returns the authenticated user's full name and email upon successful authentication:
+10. Provide endpoint for completing logout:
+
+    ```nginx
+    # ...
+    location /post_logout/ {
+         return 200 "You have been logged out.\n";
+         default_type text/plain;
+    }
+    # ...
+    ```
+
+11. Create a simple test application referenced by the `proxy_pass` directive which returns the authenticated user's full name and email upon successful authentication:
 
     ```nginx
     # ...
@@ -250,7 +288,7 @@ With AF DS configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t
         }
     }
     ```
-11. Save the NGINX configuration file and reload the configuration:
+12. Save the NGINX configuration file and reload the configuration:
     ```nginx
     nginx -s reload
     ```
@@ -273,6 +311,14 @@ http {
         # Replace with your actual AD FS Client ID and Secret
         client_id     <client_id>;
         client_secret <client_secret>;
+
+        # RP‑initiated logout
+        logout_uri /logout;
+        post_logout_uri https://demo.example.com/post_logout/;
+        logout_token_hint on;
+
+        # Fetch userinfo claims
+        userinfo on;
     }
 
     server {
@@ -293,9 +339,15 @@ http {
 
             proxy_pass http://127.0.0.1:8080;
         }
+
+        location /post_logout/ {
+            return 200 "You have been logged out.\n";
+            default_type text/plain;
+        }
     }
 
     server {
+        # Simple test upstream server
         listen 8080;
 
         location / {
@@ -310,7 +362,11 @@ http {
 
 1. Open `https://demo.example.com/` in a browser. You will be automatically redirected to the AD FS sign-in page.
 
-2. Enter valid AD FS credentials of a user who has access the application. Upon successful sign-in, AD FS redirects you back to NGINX Plus, and you will see the proxied application content (for example, “Hello, Jane Doe!”).
+2. Enter valid AD FS credentials of a user who has access the application. Upon successful sign-in, AD FS redirects you back to NGINX Plus, and you will see the proxied application content (for example, "Hello, Jane Doe!").
+
+3. Navigate to `https://demo.example.com/logout`. NGINX Plus initiates an RP‑initiated logout; AD FS ends the session and redirects back to `https://demo.example.com/post_logout/`.
+
+4. Refresh `https://demo.example.com/` again. You should be redirected to AD FS for a fresh sign‑in, proving the session has been terminated.
 
 
 ## Legacy njs-based AD FS Solution {#legacy-njs-guide}
@@ -322,9 +378,11 @@ If you are running NGINX Plus R33 and earlier or if you still need the njs-based
 
 - [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html)
 
-- [Release Notes for NGINX Plus R34]({{< ref "nginx/releases.md#r34" >}})
+- [Release Notes for NGINX Plus R35]({{< ref "nginx/releases.md#r35" >}})
 
 
 ## Revision History
 
-- Version 1 (March 2025) – Initial version (NGINX Plus Release 34)
+- Version 2 (August 2025) – Added RP‑initiated logout (logout_uri, post_logout_uri, logout_token_hint) and userinfo support.
+
+- Version 1 (March 2025) – Initial version (NGINX Plus Release 34)