From 69bfaebbaa5c2141e08adfde6b601e6ce855c185 Mon Sep 17 00:00:00 2001 From: Naveen GOPU Date: Fri, 26 Sep 2025 13:16:51 +0530 Subject: [PATCH 1/3] NLB-7031: Update Native OIDC process in NginxaaS docs --- .../quickstart/security-controls/oidc.md | 235 +++++++++++++++++- 1 file changed, 233 insertions(+), 2 deletions(-) diff --git a/content/nginxaas-azure/quickstart/security-controls/oidc.md b/content/nginxaas-azure/quickstart/security-controls/oidc.md index 2ac04588c..eec08ea16 100644 --- a/content/nginxaas-azure/quickstart/security-controls/oidc.md +++ b/content/nginxaas-azure/quickstart/security-controls/oidc.md @@ -18,10 +18,220 @@ Learn how to configure F5 NGINXaaS for Azure with OpenID Connect (OIDC) authenti 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. +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) + + 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. + +2. Using NJS based implementation + +## Configure NGINXaaS for Azure with IdP using Native OIDC + +### 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 `` throughout this guide. + +With your IdP configured, you can enable OIDC on NGINXaaS for Azure. + +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: + + ```nginx + http { + resolver 127.0.0.1:49153 ipv4=on valid=300s; + + # ... + } + ``` + +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: + + ```nginx + http { + resolver 127.0.0.1:49153 ipv4=on valid=300s; + keyval_zone zone=my_store:8M state=/opt/oidc_sessions.json timeout=1h sync; + + oidc_provider entra { + issuer https://login.microsoftonline.com//v2.0; + client_id ; + client_secret ; + session_store my_store; + logout_uri /logout; + post_logout_uri https:///post_logout/; + logout_token_hint on; + userinfo on; + } + # ... + } + ``` + + Where: + - `` is your Microsoft Entra Tenant ID + - `` is your Application (client) ID from Entra ID + - `` is your client secret from Entra ID + - `` is your NGINXaaS deployment FQDN + + {{< 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: + + ```nginx + server { + listen 443 ssl; + server_name ; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + # Protect this location with OIDC + auth_oidc entra; + + # Forward OIDC claims as headers + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + 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 / { + return 200 "Hello, $http_name!\nEmail: $http_email\nEntra ID sub: $http_sub\n"; + default_type text/plain; + } + } + ``` + +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: + + ```nginx + stream { + resolver 127.0.0.1:49153 valid=20s; + + server { + listen 9000; + zone_sync; + zone_sync_server internal.nginxaas.nginx.com:9000 resolve; + } + } + ``` + + + +
+ Complete configuration example of nginx.conf using the localhost as a upstream server + + ```nginx + http { + # Use a public DNS resolver for OIDC discovery + resolver 127.0.0.1:49153 ipv4=on valid=300s; + keyval_zone zone=my_store:8M state=/opt/oidc_sessions.json timeout=1h sync; + + # Define OIDC provider (Microsoft Entra ID example) + oidc_provider entra { + # The issuer is typically something like: + # https://login.microsoftonline.com//v2.0 + issuer https://login.microsoftonline.com//v2.0; + + # Replace with your actual Entra client_id and client_secret + client_id ; + client_secret ; + session_store my_store; + + # RP‑initiated logout + logout_uri /logout; + post_logout_uri https:///post_logout/; + logout_token_hint on; + + # Fetch userinfo claims + userinfo on; + } + + server { + listen 443 ssl; + server_name ; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + # Protect this location with Entra OIDC + auth_oidc entra; + + # Forward OIDC claims as headers if desired + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + 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 / { + return 200 "Hello, $http_name!\nEmail: $http_email\nEntra ID sub: $http_sub\n"; + default_type text/plain; + } + } + } + + stream { + resolver 127.0.0.1:49153 valid=20s; + + server { + listen 9000; + zone_sync; + zone_sync_server internal.nginxaas.nginx.com:9000 resolve; + } + } + ``` +
+ +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: + +- [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 + +1. Open `https:///` in a browser. You will be automatically redirected to your IdP sign-in page. + +2. Enter valid IdP credentials. Upon successful sign-in, you will be redirected back to NGINXaaS and see your protected application. Using the example configuration, you will see a message displaying the authenticated user's information in the browser: + + ```text + Hello, [Name]! + Email: [email] + Entra ID sub: [subject_id] + ``` + +3. To test logout, navigate to `https:///logout`. NGINXaaS initiates an RP-initiated logout, and your IdP ends the session and redirects back to the post-logout page. + + + +## 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. Configuring NGINXaaS for Azure with OIDC is similar as [Configuring NGINX Plus](https://github.com/nginxinc/nginx-openid-connect/blob/main/README.md#configuring-nginx-plus) in [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) but it also has its own specific configurations that must be completed to work normally. @@ -164,6 +374,17 @@ Configuring NGINXaaS for Azure with OIDC is similar as [Configuring NGINX Plus]( This is a site protected by OIDC! ``` +## Limitations of Native OIDC vs NJS + +The Native OIDC implementation has the following limitations compared to the NJS-based implementation: + +- Proof Key for Code Exchange (PKCE) Support +- Front-Channel Logout +- Back-Channel Logout + +These features will be added in future releases. + + ## Troubleshooting [Enable NGINX logs]({{< ref "/nginxaas-azure/monitoring/enable-logging/" >}}) and [Troubleshooting](https://github.com/nginxinc/nginx-openid-connect/tree/main?tab=readme-ov-file#troubleshooting) the OIDC issues. @@ -171,3 +392,13 @@ Configuring NGINXaaS for Azure with OIDC is similar as [Configuring NGINX Plus]( ## Monitoring [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 + +- [Microsoft identity platform documentation](https://learn.microsoft.com/en-us/entra/identity-platform/) + +- [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) + +- [Single Sign-On with Microsoft Entra ID]({{< ref "/nginx/deployment-guides/single-sign-on/entra-id.md" >}}) + +- [Terraform snippets for sample Native OIDC](https://github.com/nginxinc/nginxaas-for-azure-snippets/tree/main/terraform/configurations/native-oidc) From 253d5be8ef3099927f3d0a4d1650584205ed83f5 Mon Sep 17 00:00:00 2001 From: Naveen GOPU Date: Mon, 29 Sep 2025 17:56:49 +0530 Subject: [PATCH 2/3] NLB-7031: Update Overview section in oidc and add sso references --- .../quickstart/security-controls/oidc.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/content/nginxaas-azure/quickstart/security-controls/oidc.md b/content/nginxaas-azure/quickstart/security-controls/oidc.md index eec08ea16..da7936beb 100644 --- a/content/nginxaas-azure/quickstart/security-controls/oidc.md +++ b/content/nginxaas-azure/quickstart/security-controls/oidc.md @@ -12,14 +12,6 @@ type: Learn how to configure F5 NGINXaaS for Azure with OpenID Connect (OIDC) authentication. -## Prerequisites - -1. Configure an NGINXaaS deployment with [SSL/TLS certificates]({{< ref "/nginxaas-azure/getting-started/ssl-tls-certificates/" >}}). - -2. Enable [Runtime State Sharing]({{< ref "/nginxaas-azure/quickstart/runtime-state-sharing.md" >}}) on the NGINXaaS deployment. - -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. 1. Using Native OIDC implementation (Introduced from NGINX Plus R35) @@ -28,6 +20,15 @@ There are currently two methods available for setting up OIDC authentication. 2. Using NJS based implementation +## Prerequisites + +These prerequisites are used for both methods of configuring NGINXaaS for Azure with IdP using Native OIDC and NJS. +1. Configure an NGINXaaS deployment with [SSL/TLS certificates]({{< ref "/nginxaas-azure/getting-started/ssl-tls-certificates/" >}}). + +2. Enable [Runtime State Sharing]({{< ref "/nginxaas-azure/quickstart/runtime-state-sharing.md" >}}) on the NGINXaaS deployment. + + + ## Configure NGINXaaS for Azure with IdP using Native OIDC ### Prerequisites @@ -401,4 +402,6 @@ These features will be added in future releases. - [Single Sign-On with Microsoft Entra ID]({{< ref "/nginx/deployment-guides/single-sign-on/entra-id.md" >}}) +- [Single Sign-On with OpenID Connect and Identity Providers]({{< ref "nginx/admin-guide/security-controls/configuring-oidc.md" >}}) + - [Terraform snippets for sample Native OIDC](https://github.com/nginxinc/nginxaas-for-azure-snippets/tree/main/terraform/configurations/native-oidc) From b2d76ce63275f6128f687d455a0c47445d2bcea2 Mon Sep 17 00:00:00 2001 From: Naveen GOPU Date: Fri, 3 Oct 2025 11:17:36 +0530 Subject: [PATCH 3/3] NLB-7031: Addressed the spacing and some content change in oidc section --- .../quickstart/security-controls/oidc.md | 29 +++++++++++-------- 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/content/nginxaas-azure/quickstart/security-controls/oidc.md b/content/nginxaas-azure/quickstart/security-controls/oidc.md index da7936beb..f67343281 100644 --- a/content/nginxaas-azure/quickstart/security-controls/oidc.md +++ b/content/nginxaas-azure/quickstart/security-controls/oidc.md @@ -14,32 +14,33 @@ Learn how to configure F5 NGINXaaS for Azure with OpenID Connect (OIDC) authenti There are currently two methods available for setting up OIDC authentication. -1. Using Native OIDC implementation (Introduced from NGINX Plus R35) +1. Using Native OIDC implementation (Introduced from NGINX Plus R34) - 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. - 2. Using NJS based implementation ## Prerequisites These prerequisites are used for both methods of configuring NGINXaaS for Azure with IdP using Native OIDC and NJS. + 1. Configure an NGINXaaS deployment with [SSL/TLS certificates]({{< ref "/nginxaas-azure/getting-started/ssl-tls-certificates/" >}}). 2. Enable [Runtime State Sharing]({{< ref "/nginxaas-azure/quickstart/runtime-state-sharing.md" >}}) on the NGINXaaS deployment. - ## Configure NGINXaaS for Azure with IdP using Native OIDC +This method applies to NGINX Plus Release 34 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. + ### 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 `` throughout this guide. +1. A domain name pointing to your NGINXaaS deployment, for example, `demo.example.com`. This will be referred to as `` throughout this guide. With your IdP configured, you can enable OIDC on NGINXaaS for Azure. 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: +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: ```nginx http { @@ -49,7 +50,7 @@ With your IdP configured, you can enable OIDC on NGINXaaS for Azure. } ``` -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: ```nginx http { @@ -78,7 +79,7 @@ With your IdP configured, you can enable OIDC on NGINXaaS for Azure. {{< 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: +1. Configure your server block with OIDC protection. The following example uses localhost as the upstream server: ```nginx server { @@ -116,7 +117,7 @@ With your IdP configured, you can enable OIDC on NGINXaaS for Azure. } ``` -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: ```nginx stream { @@ -209,16 +210,18 @@ With your IdP configured, you can enable OIDC on NGINXaaS for Azure. ``` -6. Upload the NGINX configurations. See [Upload an NGINX configuration]({{< ref "/nginxaas-azure/getting-started/nginx-configuration/" >}}) for more details. +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: - [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 1. Open `https:///` in a browser. You will be automatically redirected to your IdP sign-in page. -2. Enter valid IdP credentials. Upon successful sign-in, you will be redirected back to NGINXaaS and see your protected application. Using the example configuration, you will see a message displaying the authenticated user's information in the browser: +1. Enter valid IdP credentials. Upon successful sign-in, you will be redirected back to NGINXaaS and see your protected application. Using the example configuration, you will see a message displaying the authenticated user's information in the browser: ```text Hello, [Name]! @@ -226,12 +229,14 @@ For more detailed steps on this OIDC configuration, please refer to: Entra ID sub: [subject_id] ``` -3. To test logout, navigate to `https:///logout`. NGINXaaS initiates an RP-initiated logout, and your IdP ends the session and redirects back to the post-logout page. +1. To test logout, navigate to `https:///logout`. NGINXaaS initiates an RP-initiated logout, and your IdP ends the session and redirects back to the post-logout page. ## 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. Configuring NGINXaaS for Azure with OIDC is similar as [Configuring NGINX Plus](https://github.com/nginxinc/nginx-openid-connect/blob/main/README.md#configuring-nginx-plus) in [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) but it also has its own specific configurations that must be completed to work normally.