Skip to content

Commit d85818f

Browse files
Naveen-Gopu-F5Naveen-Gopu-F5
committed
NLB-7031: Update Native OIDC process in NginxaaS docs
1 parent 1b8cc6f commit d85818f

File tree

1 file changed

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

1 file changed

+233
-2
lines changed

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

Lines changed: 233 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,220 @@ Learn how to configure F5 NGINXaaS for Azure with OpenID Connect (OIDC) authenti
1818

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

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.
21+
These prerequisites are used for both methods of configuring NGINXaaS for Azure with IdP using Native OIDC and NJS.
2222

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

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