diff --git a/content/nginxaas-azure/quickstart/security-controls/oidc.md b/content/nginxaas-azure/quickstart/security-controls/oidc.md index 2ac04588c..da7936beb 100644 --- a/content/nginxaas-azure/quickstart/security-controls/oidc.md +++ b/content/nginxaas-azure/quickstart/security-controls/oidc.md @@ -12,16 +12,227 @@ type: Learn how to configure F5 NGINXaaS for Azure with OpenID Connect (OIDC) authentication. +There are currently two methods available for setting up OIDC authentication. + +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 + ## 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. -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. -## Configure NGINXaaS for Azure with IdP +## 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 +375,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 +393,15 @@ 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" >}}) + +- [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)