Skip to content

Commit 18200d3

Browse files
Naveen-Gopu-F5Naveen-Gopu-F5
authored
NLB-7031: Update Native OIDC process in NginxaaS docs (#1176)
* NLB-7031: Update Native OIDC process in NginxaaS docs
1 parent 6a6cd89 commit 18200d3

File tree

1 file changed

+241
-2
lines changed
  • content/nginxaas-azure/quickstart/security-controls

1 file changed

+241
-2
lines changed

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

Lines changed: 241 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,232 @@ type:
1212

1313
Learn how to configure F5 NGINXaaS for Azure with OpenID Connect (OIDC) authentication.
1414

15+
There are currently two methods available for setting up OIDC authentication.
16+
17+
1. Using Native OIDC implementation (Introduced from NGINX Plus R34)
18+
19+
2. Using NJS based implementation
20+
1521
## Prerequisites
1622

23+
These prerequisites are used for both methods of configuring NGINXaaS for Azure with IdP using Native OIDC and NJS.
24+
1725
1. Configure an NGINXaaS deployment with [SSL/TLS certificates]({{< ref "/nginxaas-azure/getting-started/ssl-tls-certificates/" >}}).
1826

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

21-
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.
29+
30+
## Configure NGINXaaS for Azure with IdP using Native OIDC
31+
32+
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.
33+
34+
### Prerequisites
35+
36+
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.
37+
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.
38+
39+
With your IdP configured, you can enable OIDC on NGINXaaS for Azure.
40+
41+
1. Ensure that you have the values of the **Client ID**, **Client Secret**, and **Tenant ID** obtained during IdP configuration.
42+
43+
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:
44+
45+
```nginx
46+
http {
47+
resolver 127.0.0.1:49153 ipv4=on valid=300s;
48+
49+
# ...
50+
}
51+
```
52+
53+
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:
54+
55+
```nginx
56+
http {
57+
resolver 127.0.0.1:49153 ipv4=on valid=300s;
58+
keyval_zone zone=my_store:8M state=/opt/oidc_sessions.json timeout=1h sync;
59+
60+
oidc_provider entra {
61+
issuer https://login.microsoftonline.com/<tenant_id>/v2.0;
62+
client_id <client_id>;
63+
client_secret <client_secret>;
64+
session_store my_store;
65+
logout_uri /logout;
66+
post_logout_uri https://<nginxaas_deployment_fqdn>/post_logout/;
67+
logout_token_hint on;
68+
userinfo on;
69+
}
70+
# ...
71+
}
72+
```
73+
74+
Where:
75+
- `<tenant_id>` is your Microsoft Entra Tenant ID
76+
- `<client_id>` is your Application (client) ID from Entra ID
77+
- `<client_secret>` is your client secret from Entra ID
78+
- `<nginxaas_deployment_fqdn>` is your NGINXaaS deployment FQDN
79+
80+
{{< 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 >}}
81+
82+
1. Configure your server block with OIDC protection. The following example uses localhost as the upstream server:
83+
84+
```nginx
85+
server {
86+
listen 443 ssl;
87+
server_name <nginxaas_deployment_fqdn>;
88+
89+
ssl_certificate /etc/ssl/certs/fullchain.pem;
90+
ssl_certificate_key /etc/ssl/private/key.pem;
91+
92+
location / {
93+
# Protect this location with OIDC
94+
auth_oidc entra;
95+
96+
# Forward OIDC claims as headers
97+
proxy_set_header sub $oidc_claim_sub;
98+
proxy_set_header email $oidc_claim_email;
99+
proxy_set_header name $oidc_claim_name;
100+
101+
proxy_pass http://127.0.0.1:8080;
102+
}
103+
104+
location /post_logout/ {
105+
return 200 "You have been logged out.\n";
106+
default_type text/plain;
107+
}
108+
}
109+
110+
server {
111+
# Simple test upstream server
112+
listen 8080;
113+
location / {
114+
return 200 "Hello, $http_name!\nEmail: $http_email\nEntra ID sub: $http_sub\n";
115+
default_type text/plain;
116+
}
117+
}
118+
```
119+
120+
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:
121+
122+
```nginx
123+
stream {
124+
resolver 127.0.0.1:49153 valid=20s;
125+
126+
server {
127+
listen 9000;
128+
zone_sync;
129+
zone_sync_server internal.nginxaas.nginx.com:9000 resolve;
130+
}
131+
}
132+
```
133+
134+
135+
136+
<details close>
137+
<summary>Complete configuration example of nginx.conf using the localhost as a upstream server</summary>
138+
139+
```nginx
140+
http {
141+
# Use a public DNS resolver for OIDC discovery
142+
resolver 127.0.0.1:49153 ipv4=on valid=300s;
143+
keyval_zone zone=my_store:8M state=/opt/oidc_sessions.json timeout=1h sync;
144+
145+
# Define OIDC provider (Microsoft Entra ID example)
146+
oidc_provider entra {
147+
# The issuer is typically something like:
148+
# https://login.microsoftonline.com/<tenant_id>/v2.0
149+
issuer https://login.microsoftonline.com/<tenant_id>/v2.0;
150+
151+
# Replace with your actual Entra client_id and client_secret
152+
client_id <client_id>;
153+
client_secret <client_secret>;
154+
session_store my_store;
155+
156+
# RP‑initiated logout
157+
logout_uri /logout;
158+
post_logout_uri https://<nginxaas_deployment_fqdn>/post_logout/;
159+
logout_token_hint on;
160+
161+
# Fetch userinfo claims
162+
userinfo on;
163+
}
164+
165+
server {
166+
listen 443 ssl;
167+
server_name <nginxaas_deployment_fqdn>;
168+
169+
ssl_certificate /etc/ssl/certs/fullchain.pem;
170+
ssl_certificate_key /etc/ssl/private/key.pem;
171+
172+
location / {
173+
# Protect this location with Entra OIDC
174+
auth_oidc entra;
175+
176+
# Forward OIDC claims as headers if desired
177+
proxy_set_header sub $oidc_claim_sub;
178+
proxy_set_header email $oidc_claim_email;
179+
proxy_set_header name $oidc_claim_name;
180+
181+
proxy_pass http://127.0.0.1:8080;
182+
}
183+
184+
location /post_logout/ {
185+
return 200 "You have been logged out.\n";
186+
default_type text/plain;
187+
}
188+
}
189+
190+
server {
191+
# Simple test upstream server
192+
listen 8080;
193+
194+
location / {
195+
return 200 "Hello, $http_name!\nEmail: $http_email\nEntra ID sub: $http_sub\n";
196+
default_type text/plain;
197+
}
198+
}
199+
}
200+
201+
stream {
202+
resolver 127.0.0.1:49153 valid=20s;
203+
204+
server {
205+
listen 9000;
206+
zone_sync;
207+
zone_sync_server internal.nginxaas.nginx.com:9000 resolve;
208+
}
209+
}
210+
```
211+
</details>
212+
213+
1. Upload the NGINX configurations. See [Upload an NGINX configuration]({{< ref "/nginxaas-azure/getting-started/nginx-configuration/" >}}) for more details.
214+
215+
For more detailed steps on this OIDC configuration, please refer to:
216+
217+
- [Single Sign-On with Microsoft Entra ID]({{< ref "/nginx/deployment-guides/single-sign-on/entra-id.md" >}})
218+
- [Terraform snippets for Native OIDC use case](https://github.com/nginxinc/nginxaas-for-azure-snippets/tree/main/terraform/configurations/native-oidc)
219+
220+
### Testing
221+
222+
1. Open `https://<nginxaas_deployment_fqdn>/` in a browser. You will be automatically redirected to your IdP sign-in page.
223+
224+
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:
225+
226+
```text
227+
Hello, [Name]!
228+
Email: [email]
229+
Entra ID sub: [subject_id]
230+
```
231+
232+
1. To test logout, navigate to `https://<nginxaas_deployment_fqdn>/logout`. NGINXaaS initiates an RP-initiated logout, and your IdP ends the session and redirects back to the post-logout page.
22233
23234
24-
## Configure NGINXaaS for Azure with IdP
235+
236+
## Configure NGINXaaS for Azure with IdP using NJS
237+
238+
### Prerequisites
239+
240+
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.
25241
26242
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.
27243
@@ -164,10 +380,33 @@ Configuring NGINXaaS for Azure with OIDC is similar as [Configuring NGINX Plus](
164380
This is a site protected by OIDC!
165381
```
166382
383+
## Limitations of Native OIDC vs NJS
384+
385+
The Native OIDC implementation has the following limitations compared to the NJS-based implementation:
386+
387+
- Proof Key for Code Exchange (PKCE) Support
388+
- Front-Channel Logout
389+
- Back-Channel Logout
390+
391+
These features will be added in future releases.
392+
393+
167394
## Troubleshooting
168395
169396
[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.
170397
171398
## Monitoring
172399
173400
[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.
401+
402+
## See Also
403+
404+
- [Microsoft identity platform documentation](https://learn.microsoft.com/en-us/entra/identity-platform/)
405+
406+
- [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html)
407+
408+
- [Single Sign-On with Microsoft Entra ID]({{< ref "/nginx/deployment-guides/single-sign-on/entra-id.md" >}})
409+
410+
- [Single Sign-On with OpenID Connect and Identity Providers]({{< ref "nginx/admin-guide/security-controls/configuring-oidc.md" >}})
411+
412+
- [Terraform snippets for sample Native OIDC](https://github.com/nginxinc/nginxaas-for-azure-snippets/tree/main/terraform/configurations/native-oidc)

0 commit comments

Comments
 (0)