fix: Update NIC OIDC template configmap customisation

content/nic/changelog/_index.md

@@ -24,12 +24,12 @@ For older releases, check the changelogs for previous years: [2024]({{< ref "/ni
 
 {{< /details >}}
 
-
 ## 5.3.0
 
 09 Dec 2025
 
 ### {{% icon rocket %}} Features
+
 - [8292](https://github.com/nginx/kubernetes-ingress/pull/8292) Add sslverify for jwksuri
 - [8447](https://github.com/nginx/kubernetes-ingress/pull/8447) Add support for ssl ciphers related annotations
 - [8340](https://github.com/nginx/kubernetes-ingress/pull/8340) Implement oidc front channel logout nginx directives
@@ -42,25 +42,28 @@ For older releases, check the changelogs for previous years: [2024]({{< ref "/ni
 - [8533](https://github.com/nginx/kubernetes-ingress/pull/8533) Extend cache policy for more configurable parameters
 
 ### {{% icon bug %}} Fixes
+
 - [8299](https://github.com/nginx/kubernetes-ingress/pull/8299) Remove type field for objects with schema ref
 - [8455](https://github.com/nginx/kubernetes-ingress/pull/8455) Cleanup stale socket files on startup
 
 ### {{% icon arrow-up %}} Dependencies
+
 - [8553](https://github.com/nginx/kubernetes-ingress/pull/8553) Bump Go dependencies
 - [8244](https://github.com/nginx/kubernetes-ingress/pull/8244), [8279](https://github.com/nginx/kubernetes-ingress/pull/8279), [8284](https://github.com/nginx/kubernetes-ingress/pull/8284), [8595](https://github.com/nginx/kubernetes-ingress/pull/8595), [8584](https://github.com/nginx/kubernetes-ingress/pull/8584), [8315](https://github.com/nginx/kubernetes-ingress/pull/8315), [8324](https://github.com/nginx/kubernetes-ingress/pull/8324), [8334](https://github.com/nginx/kubernetes-ingress/pull/8334), [8466](https://github.com/nginx/kubernetes-ingress/pull/8466), [8384](https://github.com/nginx/kubernetes-ingress/pull/8384), [8502](https://github.com/nginx/kubernetes-ingress/pull/8502), [8406](https://github.com/nginx/kubernetes-ingress/pull/8406), [8588](https://github.com/nginx/kubernetes-ingress/pull/8588), [8589](https://github.com/nginx/kubernetes-ingress/pull/8589), [8598](https://github.com/nginx/kubernetes-ingress/pull/8598), [8575](https://github.com/nginx/kubernetes-ingress/pull/8575), [8542](https://github.com/nginx/kubernetes-ingress/pull/8542), [8543](https://github.com/nginx/kubernetes-ingress/pull/8543), [8599](https://github.com/nginx/kubernetes-ingress/pull/8599), [8551](https://github.com/nginx/kubernetes-ingress/pull/8551), [8484](https://github.com/nginx/kubernetes-ingress/pull/8484), [8475](https://github.com/nginx/kubernetes-ingress/pull/8475), [8497](https://github.com/nginx/kubernetes-ingress/pull/8497), [8498](https://github.com/nginx/kubernetes-ingress/pull/8498), [8499](https://github.com/nginx/kubernetes-ingress/pull/8499), [8596](https://github.com/nginx/kubernetes-ingress/pull/8596), [8511](https://github.com/nginx/kubernetes-ingress/pull/8511) & [8581](https://github.com/nginx/kubernetes-ingress/pull/8581) Bump Docker dependencies
 - [8616](https://github.com/nginx/kubernetes-ingress/pull/8616) Update dependency go to v1.25.5 (main)
 - [8611](https://github.com/nginx/kubernetes-ingress/pull/8611) Bump waf version to 5.10.0
 - [8494](https://github.com/nginx/kubernetes-ingress/pull/8494) Update nginx to 1.29.3, nginx agent to 3.5
 - [8600](https://github.com/nginx/kubernetes-ingress/pull/8600) Update nginx plus waf pkg and alpine base version
 
-
-
 ### {{% icon download %}} Upgrade
+
 - For NGINX, use the 5.3.0 images from our [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/tags?page=1&ordering=last_updated&name=5.3.0), [GitHub Container](https://github.com/nginx/kubernetes-ingress/pkgs/container/kubernetes-ingress), [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress) or [Quay.io](https://quay.io/repository/nginx/nginx-ingress).
 - For NGINX Plus, use the 5.3.0 images from the F5 Container registry or build your own image using the 5.3.0 source code.
 - For Helm, use version 2.4.0 of the chart.
+- For users making use of a custom `oidc.conf` by following this [guide]({{< ref "/nic/tutorials/oidc-custom-configuration.md" >}}), in this release this behaviour has changed from a static file (`oidc.conf`) to a dynamic template (`oidc.tmpl`).  The [guide]({{< ref "/nic/tutorials/oidc-custom-configuration.md" >}}) has been updated to reflect the recent changes.  If you still require a custom OIDC configuration, you should copy all the modifications you have made prior to 5.3.0 to the `oidc.tmpl` in the `ConfigMap`.
 
 ### {{% icon life-buoy %}} Supported Platforms
+
 We will provide technical support for NGINX Ingress Controller on any Kubernetes platform that is currently supported by its provider and that passes the Kubernetes conformance tests. This release was fully tested on the following Kubernetes versions: 1.27-1.34.
 
 ## 5.2.1

content/nic/tutorials/oidc-custom-configuration.md

@@ -13,24 +13,24 @@ This guide will walk through how to customize and configure this default impleme
 
 ## Prerequisites
 
-{{< call-out "note" >}}This guide only works with F5 NGINX Ingress Controller version 5.2.1 or below. Please make sure you are using a compatible version before proceeding.{{< /call-out >}}
+{{< call-out "note" >}}This guide only works with F5 NGINX Ingress Controller version 5.3.0 or above. Please make sure you are using a compatible version before proceeding.{{< /call-out >}}
 
 This guide assumes that you have an F5 NGINX Ingress Controller deployed. If not, please follow the installation steps using either the [Manifest]({{< ref "/nic/install/manifests.md" >}}) or [Helm]({{< ref "/nic/install/helm.md" >}}) approach.
 
 To customize the NGINX OpenID Connect Reference implementation, you will need to:
 
-1. Create a ConfigMap containing the contents of the default `oidc.conf` file
+1. Create a ConfigMap containing the contents of the default `oidc.tmpl` file
 2. Attach a `Volume` and `VolumeMount` to your deployment of the F5 NGINX Ingress Controller
 
-This setup will allow the custom configuration in your ConfigMap to override the contents of the default `oidc.conf` file.
+This setup will allow the custom configuration in your ConfigMap to override the contents of the default `oidc.tmpl` file.
 
 ## Step 1 - Creating the ConfigMap
 
-Run the below command to generate a ConfigMap with the contents of the `oidc.conf` file.
+Run the below command to generate a ConfigMap with the contents of the `oidc.tmpl` file.
 **NOTE** The ConfigMap must be deployed in the same `namespace` as the F5 NGINX Ingress Controller.
 
 ```console
-kubectl create configmap oidc-config-map --from-literal=oidc.conf="$(curl -k https://raw.githubusercontent.com/nginx/kubernetes-ingress/v{{< nic-version >}}/internal/configs/oidc/oidc.conf)"
+kubectl create configmap oidc-config-map --from-literal=oidc.tmpl="$(curl -k https://raw.githubusercontent.com/nginx/kubernetes-ingress/v{{< nic-version >}}/internal/configs/version2/oidc.tmpl)"
 ```
 
 Use the `kubectl describe` command to confirm the contents of the ConfigMap are correct.
@@ -47,11 +47,12 @@ Annotations:  <none>
 
 Data
 ====
-oidc.conf:
+oidc.tmpl:
 ----
     # Advanced configuration START
     set $internal_error_message "NGINX / OpenID Connect login failure\n";
     set $pkce_id "";
+    set $idp_sid "";
     # resolver 8.8.8.8; # For DNS lookup of IdP endpoints;
     subrequest_output_buffer_size 32k; # To fit a complete tokenset response
     gunzip on; # Decompress IdP responses if necessary
@@ -63,8 +64,8 @@ oidc.conf:
 
 ## Step 2 - Customizing the default configuration
 
-Once the contents of the `oidc.conf` file has been added to the ConfigMap, you are free to customize the contents of this ConfigMap.
-This example demonstrates adding a comment to the top of the file. The comment will be shown at the top of the `oidc.conf` file.
+Once the contents of the `oidc.tmpl` file has been added to the ConfigMap, you are free to customize the contents of this ConfigMap.
+This example demonstrates adding a comment to the top of the file. The comment will be shown at the top of the `oidc.tmpl` file.
 This comment will be `# >> Custom Comment for my OIDC file <<`
 
 ```shell
@@ -80,11 +81,12 @@ Add the custom content:
 #
 apiVersion: v1
 data:
-  oidc.conf: |2-
+  oidc.tmpl: |2-
         # >> Custom Comment for my OIDC file <<
         # Advanced configuration START
         set $internal_error_message "NGINX / OpenID Connect login failure\n";
         set $pkce_id "";
+        set $idp_sid "";
         # resolver 8.8.8.8; # For DNS lookup of IdP endpoints;
         subrequest_output_buffer_size 32k; # To fit a complete tokenset response
         gunzip on; # Decompress IdP responses if necessary
@@ -107,7 +109,7 @@ Applying any updates to the data in this ConfigMap will require NGINX Ingress Co
 ## Step 3 - Add Volume and VolumeMount to the Ingress Controller deployment
 
 In this step we will add a `Volume` and `VolumeMount` to the NGINX Ingress Controller deployment.
-This will allow you to mount the ConfigMap created in Step 1 and overwrite the contents of the `oidc.conf` file.
+This will allow you to mount the ConfigMap created in Step 1 and overwrite the contents of the `oidc.tmpl` file.
 
 This document will demonstrate how to add the `Volume` and `VolumeMount` using both Manifest and HELM
 
@@ -143,17 +145,17 @@ spec:
         ...
         volumeMounts:
         - name: oidc-volume
-          mountPath: /etc/nginx/oidc/oidc.conf
-          subPath: oidc.conf # Must match the name in the data filed
+          mountPath: /oidc.tmpl
+          subPath: oidc.tmpl # Must match the name in the data filed
           readOnly: true
 ```
 
 Once the `Volume` and `VolumeMount` has been added the manifest file, apply the changes to the Ingress Controller deployment.
 
-Confirm the `oidc.conf` file has been updated:
+Confirm the `oidc.tmpl` file has been updated:
 
 ```shell
-kubectl exec -it -n <ic-namespace> <ingess-controller-pod> -- cat /etc/nginx/oidc/oidc.conf
+kubectl exec -it -n <ic-namespace> <ingess-controller-pod> -- cat /oidc.tmpl
 ```
 
 ### Helm
@@ -207,15 +209,15 @@ spec:
         ...
         volumeMounts:
         - name: oidc-volume
-          mountPath: /etc/nginx/oidc/oidc.conf
-          subPath: oidc.conf # Must match the name in the data filed
+          mountPath: /oidc.tmpl
+          subPath: oidc.tmpl # Must match the name in the data filed
           readOnly: true
 ```
 
 Once the Deployment/DaemonSet/StatefulSet has been edited, save the file and exit.
 
-Confirm the `oidc.conf` file has been updated:
+Confirm the `oidc.tmpl` file has been updated:
 
 ```shell
-kubectl exec -it -n <ic-namespace> <ingess-controller-pod> -- cat /etc/nginx/oidc/oidc.conf
+kubectl exec -it -n <ic-namespace> <ingess-controller-pod> -- cat /oidc.tmpl
 ```