From ced384562c232f89928e637d156c68654132f2eb Mon Sep 17 00:00:00 2001 From: Yaroslav Zhuravlev Date: Tue, 1 Apr 2025 11:23:22 +0100 Subject: [PATCH] Updated docs for the upcoming NGINX Plus release. --- xml/en/GNUmakefile | 1 + xml/en/docs/http/ngx_http_core_module.xml | 5 +- xml/en/docs/http/ngx_http_oidc_module.xml | 338 ++++++++++++++++++++++ xml/en/docs/index.xml | 5 + xml/en/docs/ngx_mgmt_module.xml | 71 ++++- xml/ru/docs/http/ngx_http_core_module.xml | 7 +- xml/ru/docs/index.xml | 5 + 7 files changed, 428 insertions(+), 4 deletions(-) create mode 100644 xml/en/docs/http/ngx_http_oidc_module.xml diff --git a/xml/en/GNUmakefile b/xml/en/GNUmakefile index 9357be9c..205da17a 100644 --- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -73,6 +73,7 @@ REFS = \ http/ngx_http_memcached_module \ http/ngx_http_mirror_module \ http/ngx_http_mp4_module \ + http/ngx_http_oidc_module \ http/ngx_http_perl_module \ http/ngx_http_proxy_module \ http/ngx_http_proxy_protocol_vendor_module \ diff --git a/xml/en/docs/http/ngx_http_core_module.xml b/xml/en/docs/http/ngx_http_core_module.xml index a7854486..a747b69e 100644 --- a/xml/en/docs/http/ngx_http_core_module.xml +++ b/xml/en/docs/http/ngx_http_core_module.xml @@ -2332,8 +2332,11 @@ Allows access if all (all) or at least one ngx_http_access_module, ngx_http_auth_basic_module, ngx_http_auth_request_module, -or ngx_http_auth_jwt_module +(1.13.10), +or +ngx_http_auth_oidc_module +(1.27.4) modules allow access. diff --git a/xml/en/docs/http/ngx_http_oidc_module.xml b/xml/en/docs/http/ngx_http_oidc_module.xml new file mode 100644 index 00000000..6a248f0d --- /dev/null +++ b/xml/en/docs/http/ngx_http_oidc_module.xml @@ -0,0 +1,338 @@ + + + + + + + + +
+ + +The ngx_http_oidc_module module (1.27.4) +implements authentication as a Relying Party in OpenID Connect using the + +Authorization Code Flow. + + + +The module expects the OpenID Provider's configuration to be available via + +metadata and requires dynamic +resolver. + + + +The module can be combined with other access modules +via the directive. +Note that the module may still block requests even with +satisfy any; +as an OpenID Provider might not redirect the user back to nginx. + + + + +This module is available as part of our +commercial subscription. + + + +
+ + +
+ + + +http { + resolver 10.0.0.1; + + oidc_provider my_idp { + issuer "https://provider.domain"; + client_id "unique_id"; + client_secret "unique_secret"; + } + + server { + location / { + auth_oidc my_idp; + + proxy_set_header username $oidc_claim_sub; + proxy_pass http://backend; + } + } +} + +The example assumes that the +“https://<nginx-host>/oidc_callback” +Redirection URI is configured on the OpenID Provider's side. +The path can be customized with the directive. + + +
+ + +
+ + +name + +http + + +Defines an OpenID Provider for use with the directive. + + + + + + +name | off +off +http +server +location + + +Enables end user authentication with the +specified OpenID Provider. + + + +The special value off cancels the effect +of the auth_oidc directive +inherited from the previous configuration level. + + + + + + +URL + +oidc_provider + + +Sets the Issuer Identifier URL of the OpenID Provider; +required directive. +The URL must exactly match the value of “issuer” +in the OpenID Provider metadata +and requires the “https” scheme. + + + + + + +string + +oidc_provider + + +Specifies the client ID of the Relying Party; +required directive. + + + + + + +string + +oidc_provider + + +Specifies a secret value +used to authenticate the Relying Party with the OpenID Provider. + + + + + + +URL +<issuer>/.well-known/openid-configuration +oidc_provider + + +Sets a custom URL to retrieve the OpenID Provider metadata. + + + + + + +name +NGX_OIDC_SESSION +oidc_provider + + +Sets the name of a session cookie. + + + + + + +string + +oidc_provider + + +Sets additional query arguments for the +authentication +request URL. + +extra_auth_args "display=page&prompt=login"; + + + + + + + +uri +/oidc_callback +oidc_provider + + +Defines the Redirection URI path for post-authentication redirects +expected by the module from the OpenID Provider. +The uri must match the configuration on the Provider's side. + + + + + + +scope ... +openid +oidc_provider + + +Sets requested scopes. +The openid scope is always required by OIDC. + + + + + + +name + +oidc_provider + + +Specifies a custom +key-value database +that stores session data. +By default, an 8-megabyte key-value database named +oidc_default_store_<provider name> +is created automatically. + +A separate key-value database should be configured for each Provider +to prevent session reuse across providers. + + + + + + + +time +8h +oidc_provider + + +Sets a timeout after which the session is deleted, unless it was +refreshed. + + + + + + +file + +oidc_provider + + +Specifies a file with revoked certificates (CRL) +in the PEM format used to verify +the certificates of the OpenID Provider endpoints. + + + + + + +file +system CA bundle +oidc_provider + + +Specifies a file with trusted CA certificates in the PEM format +used to verify +the certificates of the OpenID Provider endpoints. + + + + +
+ + +
+ + +The ngx_http_oidc_module module supports embedded variables: + + + + + +$oidc_id_token + +ID token + + +$oidc_access_token + +access token + + +$oidc_claim_name + +top-level ID token claim + +Nested claims can be fetched with the +auth_jwt module: + +http { + auth_jwt_claim_set $postal_code address postal_code; + + server { + location / { + auth_oidc my_idp; + auth_jwt off token=$oidc_id_token; + + proxy_set_header x-postal_code $postal_code; + proxy_pass http://backend; + } + } +} + + + + + + + + +
+ + diff --git a/xml/en/docs/index.xml b/xml/en/docs/index.xml index f7d6f431..b9ebdb75 100644 --- a/xml/en/docs/index.xml +++ b/xml/en/docs/index.xml @@ -378,6 +378,11 @@ ngx_http_mirror_module ngx_http_mp4_module + + +ngx_http_oidc_module + + ngx_http_perl_module diff --git a/xml/en/docs/ngx_mgmt_module.xml b/xml/en/docs/ngx_mgmt_module.xml index 47f6a606..a804a1fc 100644 --- a/xml/en/docs/ngx_mgmt_module.xml +++ b/xml/en/docs/ngx_mgmt_module.xml @@ -32,7 +32,8 @@ The license file is available from -Usage report is sent to F5 licensing endpoint +Usage report is sent directly or via proxy +to F5 licensing endpoint every hour using the secure connection. Optionally, in network-restricted environments @@ -130,6 +131,74 @@ By default, the license.jwt file is expected to be at + +host:port + +mgmt +1.27.4 + + +Sets the HTTP CONNECT proxy +used for sending the usage report. + + + + + + +string + +mgmt +1.27.4 + + +Sets the user name used for authentication on +the proxy. + + + + + + +string + +mgmt +1.27.4 + + +Sets the password used for authentication on +the proxy. + + + +The password is sent unencrypted by default. +If the proxy supports TLS, the connection to the proxy can be +protected with the stream +module: + +mgmt { + proxy 127.0.0.1:8080; + proxy_username <name>; + proxy_password <password>; +} + +stream { + server { + listen 127.0.0.1:8080; + + proxy_ssl on; + proxy_ssl_verify on; + proxy_ssl_trusted_certificate <proxy_ca_file>; + + proxy_pass <proxy_host>:<proxy_port>; + } +} + + + + + + address ... diff --git a/xml/ru/docs/http/ngx_http_core_module.xml b/xml/ru/docs/http/ngx_http_core_module.xml index ac12d8f1..8458d188 100644 --- a/xml/ru/docs/http/ngx_http_core_module.xml +++ b/xml/ru/docs/http/ngx_http_core_module.xml @@ -2329,9 +2329,12 @@ location /i/ { или хотя бы один (any) из модулей ngx_http_access_module, ngx_http_auth_basic_module, -ngx_http_auth_request_module -или +ngx_http_auth_request_module, ngx_http_auth_jwt_module +(1.13.10) +или +ngx_http_oidc_module +(1.27.4) разрешают доступ. diff --git a/xml/ru/docs/index.xml b/xml/ru/docs/index.xml index 8f5b0533..f1fc9ba1 100644 --- a/xml/ru/docs/index.xml +++ b/xml/ru/docs/index.xml @@ -383,6 +383,11 @@ ngx_http_mirror_module ngx_http_mp4_module + + +ngx_http_oidc_module [en] + + ngx_http_perl_module