NLB-7031: Update Native OIDC process in NginxaaS docs #1176

Naveen-Gopu-F5 · 2025-09-26T07:53:08Z

Proposed changes

Added Native OIDC implementation process in NginxaaS docs.

Checklist

Before sharing this pull request, I completed the following checklist:

I read the Contributing guidelines
My branch adheres to the Git conventions
My content changes adhere to the F5 NGINX Documentation style guide
If my changes involve potentially sensitive information¹, I have assessed the possible impact
I have waited to ensure my changes pass tests, and addressed any discovered issues

Set up OIDC authentication _ DEV -- docs-nginx-com.pdf

Potentially sensitive information includes personally identify information (PII), authentication credentials, and live URLs. Refer to the style guide for guidance about placeholder content. ↩

russokj

Conditionally approving assuming you address my concerns.

russokj · 2025-09-26T19:01:58Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

-3. [Configure the IdP](https://github.com/nginxinc/nginx-openid-connect/blob/main/README.md#configuring-your-idp). For example, you can [register a Microsoft Entra Web application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) as the IdP.
+These prerequisites are used for both methods of configuring NGINXaaS for Azure with IdP using Native OIDC and NJS.

+There are currently two methods available for setting up OIDC authentication.


It's a little hard to tell how the flow works here, but seems this would be best put in the overview section (and mention what the two versions are).

updated above suggested changes
Set up OIDC authentication _ DEV -- docs-nginx-com.pdf

russokj · 2025-09-26T19:04:02Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

 2. Enable [Runtime State Sharing]({{< ref "/nginxaas-azure/quickstart/runtime-state-sharing.md" >}}) on the NGINXaaS deployment.

-3. [Configure the IdP](https://github.com/nginxinc/nginx-openid-connect/blob/main/README.md#configuring-your-idp). For example, you can [register a Microsoft Entra Web application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) as the IdP.
+These prerequisites are used for both methods of configuring NGINXaaS for Azure with IdP using Native OIDC and NJS.


If you mention the two methods in the Overview section (another comment I left), then you can simplify this one by just saying it applies to both methods. Also, I would think this makes more sense to be mentioned at the top of the section (before enumerating the specific pre-reqs).

russokj · 2025-09-26T19:11:54Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

+
+## Configure NGINXaaS for Azure with IdP using NJS
+### Prerequisites
+1. [Configure the IdP](https://github.com/nginxinc/nginx-openid-connect/blob/main/README.md#configuring-your-idp). For example, you can [register a Microsoft Entra Web application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) as the IdP.


Am I seeing two "1." bulletpoints here?

"1." bullet point is under prerequisities and whereas another "1." is under the process flow

y82 · 2025-09-26T20:55:03Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

+There are currently two methods available for setting up OIDC authentication.

-## Configure NGINXaaS for Azure with IdP
+1. Using Native OIDC implementation (Introduced from NGINX Plus R35)


in R34 - https://docs.nginx.com/nginx/releases/#r34

correct feature implemetation of native oidc took place in R35, I took reference of https://docs.nginx.com/nginx/deployment-guides/single-sign-on/entra-id/. Thats the reason I added R35

No. The feature itself appeared in R34 (aka native oidc implementation). In R35, 2 more enhancements to oidcs were added: user-initiated logout and userinfo endpoint features were added. Pls see the changelog: https://docs.nginx.com/nginx/releases/
So, if you're talking about native OIDC as a new feature, it's R34, if you're talking about OIDC enhancements, (2 of them) - it's R35.

y82 · 2025-09-26T20:59:05Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

+
+
+
+    <details close>


Not sure if <details close> and <summary> tags are allowed - I've never used them, needs to be checked

Yes they are allowed. I used from existing one of https://github.com/nginx/documentation/blob/main/content/nginxaas-azure/quickstart/security-controls/oidc.md?plain=1#L80

We recently updated our hugo version, and now support the native hugo details shortcode.
We'll do a refactor pass soon, to replace all usages with this version.

@Naveen-Gopu-F5 don't worry about this now. We will fix all the <details> at once. Leave it as is.

y82 · 2025-09-26T21:02:32Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

 [Enable monitoring]({{< ref "/nginxaas-azure/monitoring/enable-monitoring.md" >}}), check [real time monitoring](https://github.com/nginxinc/nginx-openid-connect/blob/main/README.md#real-time-monitoring) to see how OIDC metrics are collected, and use "plus.http.*" metrics filtered with location_zone dimension in [NGINX requests and response statistics]({{< ref "/nginxaas-azure/monitoring/metrics-catalog.md#nginx-requests-and-response-statistics" >}}) to check the OIDC metrics.
+
+## See Also
+


We can also add a link to our admin guide:
Single Sign-On with OpenID Connect and Identity Providers (https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-oidc/)
[Single Sign-On with OpenID Connect and Identity Providers]({{< ref "nginx/admin-guide/security-controls/configuring-oidc.md" >}})

Added the above suggested reference

JTorreG · 2025-09-29T13:09:05Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

+
+1. Using Native OIDC implementation (Introduced from NGINX Plus R35)
+
+   This method applies to NGINX Plus Release 35 and later. In earlier versions, NGINX Plus relied on an njs-based solution, 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.


This paragraph starts with "this method" but is followed by prerequisites that apply to both methods.

Maybe it's better to move this paragraph to Line 33 after the Native OIDC heading.

JTorreG · 2025-09-29T13:10:49Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

+### Prerequisites
+1. Configure the IdP. For example, you can [register a Microsoft Entra Web application]({{< ref "/nginx/deployment-guides/single-sign-on/entra-id/#entra-setup" >}}) as the IdP.
+2. A domain name pointing to your NGINXaaS deployment, for example, `demo.example.com`. This will be referred to as `<nginxaas_deployment_fqdn>` throughout this guide.


Suggested change

### Prerequisites

1. Configure the IdP. For example, you can [register a Microsoft Entra Web application]({{< ref "/nginx/deployment-guides/single-sign-on/entra-id/#entra-setup" >}}) as the IdP.

2. A domain name pointing to your NGINXaaS deployment, for example, `demo.example.com`. This will be referred to as `<nginxaas_deployment_fqdn>` throughout this guide.

### Prerequisites

1. Configure the IdP. For example, you can [register a Microsoft Entra Web application]({{< ref "/nginx/deployment-guides/single-sign-on/entra-id/#entra-setup" >}}) as the IdP.

1. A domain name pointing to your NGINXaaS deployment, for example, `demo.example.com`. This will be referred to as `<nginxaas_deployment_fqdn>` throughout this guide.

This is currently not enforced but 2 markdown good practices:

Leave a blank line after headings

Numbered list can be a series of 1. 1. 1. ; Markdown will number these appropriately if the correct indenting is respected. It makes easier to add or remove steps later on.

JTorreG · 2025-09-29T13:11:17Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

+
+1. Ensure that you have the values of the **Client ID**, **Client Secret**, and **Tenant ID** obtained during IdP configuration.
+
+2. In your NGINX configuration file, add a public DNS resolver with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive in the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context:


Suggested change

2. In your NGINX configuration file, add a public DNS resolver with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive in the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context:

1. In your NGINX configuration file, add a public DNS resolver with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive in the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context:

JTorreG · 2025-09-29T13:11:26Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

+    }
+    ```
+
+3. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, define your IdP provider by specifying the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context. The `session_store` directive stores the session data and we need `keyval_zone` to sync this data in a clustered environment. Include the `state` parameter to persist session data across NGINX restarts. For example, for Microsoft Entra ID:


Suggested change

3. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, define your IdP provider by specifying the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context. The `session_store` directive stores the session data and we need `keyval_zone` to sync this data in a clustered environment. Include the `state` parameter to persist session data across NGINX restarts. For example, for Microsoft Entra ID:

1. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, define your IdP provider by specifying the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context. The `session_store` directive stores the session data and we need `keyval_zone` to sync this data in a clustered environment. Include the `state` parameter to persist session data across NGINX restarts. For example, for Microsoft Entra ID:

JTorreG · 2025-09-29T13:11:47Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

+
+    {{< call-out "note" >}} The `state=/opt/oidc_sessions.json` parameter enables persistence of OIDC session data across NGINX restarts. The state file path must be placed in a directory accessible to the NGINX worker processes, following [NGINX Filesystem Restrictions]({{< ref "/nginxaas-azure/getting-started/nginx-configuration/overview/#nginx-filesystem-restrictions" >}}).{{< /call-out >}}
+
+4. Configure your server block with OIDC protection. This example uses localhost as the upstream server:


Suggested change

4. Configure your server block with OIDC protection. This example uses localhost as the upstream server:

1. Configure your server block with OIDC protection. The following example uses localhost as the upstream server:

JTorreG · 2025-09-29T13:12:54Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

+    }
+    ```
+
+5. Add the runtime state sharing configuration to your NGINX configuration as mentioned in the [Prerequisites](#prerequisites). This enables synchronization of OIDC session data across NGINXaaS instances:


Suggested change

5. Add the runtime state sharing configuration to your NGINX configuration as mentioned in the [Prerequisites](#prerequisites). This enables synchronization of OIDC session data across NGINXaaS instances:

1. Add the runtime state sharing configuration to your NGINX configuration as mentioned in the [Prerequisites]({{< ref "/nginxaas-azure/quickstart/security-controls/oidc.md#prerequisites" >}}). This enables synchronization of OIDC session data across NGINXaaS instances:

JTorreG · 2025-09-29T13:27:50Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

+6. Upload the NGINX configurations. See [Upload an NGINX configuration]({{< ref "/nginxaas-azure/getting-started/nginx-configuration/" >}}) for more details.
+For more detailed steps on this OIDC configuration, please refer to:


Suggested change

6. Upload the NGINX configurations. See [Upload an NGINX configuration]({{< ref "/nginxaas-azure/getting-started/nginx-configuration/" >}}) for more details.

For more detailed steps on this OIDC configuration, please refer to:

1. Upload the NGINX configurations. See [Upload an NGINX configuration]({{< ref "/nginxaas-azure/getting-started/nginx-configuration/" >}}) for more details.

For more detailed steps on this OIDC configuration, please refer to:

JTorreG · 2025-09-29T13:28:00Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

+
+- [Single Sign-On with Microsoft Entra ID]({{< ref "/nginx/deployment-guides/single-sign-on/entra-id.md" >}})
+- [Terraform snippets for Native OIDC use case](https://github.com/nginxinc/nginxaas-for-azure-snippets/tree/main/terraform/configurations/native-oidc)
+### Testing


Suggested change

### Testing

### Testing

JTorreG · 2025-09-29T13:28:25Z

content/nginxaas-azure/quickstart/security-controls/oidc.md

+## Configure NGINXaaS for Azure with IdP using NJS
+### Prerequisites
+1. [Configure the IdP](https://github.com/nginxinc/nginx-openid-connect/blob/main/README.md#configuring-your-idp). For example, you can [register a Microsoft Entra Web application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) as the IdP.


Suggested change

## Configure NGINXaaS for Azure with IdP using NJS

### Prerequisites

1. [Configure the IdP](https://github.com/nginxinc/nginx-openid-connect/blob/main/README.md#configuring-your-idp). For example, you can [register a Microsoft Entra Web application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) as the IdP.

## Configure NGINXaaS for Azure with IdP using NJS

### Prerequisites

1. [Configure the IdP](https://github.com/nginxinc/nginx-openid-connect/blob/main/README.md#configuring-your-idp). For example, you can [register a Microsoft Entra Web application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) as the IdP.

JTorreG

approved with nits

Naveen-Gopu-F5 requested a review from a team as a code owner September 26, 2025 07:53

github-actions bot added documentation Improvements or additions to documentation product/nginxaas-azure Issues related to NGINX as a Service for Azure labels Sep 26, 2025

Naveen-Gopu-F5 mentioned this pull request Sep 26, 2025

NLB-6926: Update NGINXaaS docs with R35 changelog #1142

Open

5 tasks

russokj approved these changes Sep 26, 2025

View reviewed changes

y82 approved these changes Sep 26, 2025

View reviewed changes

NLB-7031: Update Native OIDC process in NginxaaS docs

d85818f

Naveen-Gopu-F5 force-pushed the NLB-7031-native-oidc-docs-for-nginxaas branch from cb6691e to d85818f Compare September 29, 2025 12:25

NLB-7031: Update Overview section in oidc and add sso references

35f83cd

JTorreG reviewed Sep 29, 2025

View reviewed changes

JTorreG approved these changes Sep 29, 2025

View reviewed changes

		[Enable monitoring]({{< ref "/nginxaas-azure/monitoring/enable-monitoring.md" >}}), check [real time monitoring](https://github.com/nginxinc/nginx-openid-connect/blob/main/README.md#real-time-monitoring) to see how OIDC metrics are collected, and use "plus.http.*" metrics filtered with location_zone dimension in [NGINX requests and response statistics]({{< ref "/nginxaas-azure/monitoring/metrics-catalog.md#nginx-requests-and-response-statistics" >}}) to check the OIDC metrics.

		## See Also


		1. Using Native OIDC implementation (Introduced from NGINX Plus R35)

		This method applies to NGINX Plus Release 35 and later. In earlier versions, NGINX Plus relied on an njs-based solution, 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.


		1. Ensure that you have the values of the Client ID, Client Secret, and Tenant ID obtained during IdP configuration.

		2. In your NGINX configuration file, add a public DNS resolver with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive in the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context:

	2. In your NGINX configuration file, add a public DNS resolver with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive in the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context:
	1. In your NGINX configuration file, add a public DNS resolver with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive in the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context:


		{{< call-out "note" >}} The `state=/opt/oidc_sessions.json` parameter enables persistence of OIDC session data across NGINX restarts. The state file path must be placed in a directory accessible to the NGINX worker processes, following [NGINX Filesystem Restrictions]({{< ref "/nginxaas-azure/getting-started/nginx-configuration/overview/#nginx-filesystem-restrictions" >}}).{{< /call-out >}}

		4. Configure your server block with OIDC protection. This example uses localhost as the upstream server:

	4. Configure your server block with OIDC protection. This example uses localhost as the upstream server:
	1. Configure your server block with OIDC protection. The following example uses localhost as the upstream server:

	5. Add the runtime state sharing configuration to your NGINX configuration as mentioned in the [Prerequisites](#prerequisites). This enables synchronization of OIDC session data across NGINXaaS instances:
	1. Add the runtime state sharing configuration to your NGINX configuration as mentioned in the [Prerequisites]({{< ref "/nginxaas-azure/quickstart/security-controls/oidc.md#prerequisites" >}}). This enables synchronization of OIDC session data across NGINXaaS instances:

		6. Upload the NGINX configurations. See [Upload an NGINX configuration]({{< ref "/nginxaas-azure/getting-started/nginx-configuration/" >}}) for more details.
		For more detailed steps on this OIDC configuration, please refer to:

NLB-7031: Update Native OIDC process in NginxaaS docs #1176

Are you sure you want to change the base?

NLB-7031: Update Native OIDC process in NginxaaS docs #1176

Uh oh!

Conversation

Naveen-Gopu-F5 commented Sep 26, 2025

Proposed changes

Checklist

Footnotes

Uh oh!

russokj left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JTorreG Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JTorreG left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JTorreG Sep 29, 2025 •

edited

Loading