From 5d0cad7655b3aef50c7284821a2b5849427cc525 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 22 Oct 2025 17:16:05 +0100 Subject: [PATCH] feat: Convert important psuedo-callouts This commit converts the majority of important psuedo-callouts in documentation to proper Hugo call-out shortcodes. The instances that have been left are parts of files that will be deprecated in the future. As part of this commit, metadata and Markdown linting issues were also fixed, and some peripheral process documentation was updated for clarity. --- .markdownlint.yaml | 2 +- .../config-templates/submit-templates.md | 54 +++++++++++++------ .../set-up-security-alerts.md | 9 +++- .../active-directory-federation-services.md | 28 ++++------ .../deployment-guides/single-sign-on/auth0.md | 25 ++++----- .../single-sign-on/cognito.md | 22 ++++---- .../single-sign-on/entra-id.md | 25 +++++---- .../single-sign-on/keycloak.md | 33 ++++++------ .../deployment-guides/single-sign-on/okta.md | 24 ++++----- .../single-sign-on/onelogin.md | 25 ++++----- .../single-sign-on/ping-identity.md | 23 ++++---- content/nic/configuration/policy-resource.md | 38 ++++++++++++- .../authentication/oidc/getting-started.md | 10 ++-- .../add-license-disconnected-deployment.md | 26 ++------- documentation/README.md | 3 +- documentation/hugo-content.md | 34 +++--------- documentation/include-files.md | 20 ++----- 17 files changed, 191 insertions(+), 210 deletions(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 85d36b083..26a707400 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -36,5 +36,5 @@ MD039: true # All images should have alt text MD045: true -# Tables shou ld be surrounded by blank lines +# Tables should be surrounded by blank lines MD058: true \ No newline at end of file diff --git a/content/nginx-one/nginx-configs/config-templates/submit-templates.md b/content/nginx-one/nginx-configs/config-templates/submit-templates.md index 26b590073..17647b409 100644 --- a/content/nginx-one/nginx-configs/config-templates/submit-templates.md +++ b/content/nginx-one/nginx-configs/config-templates/submit-templates.md @@ -1,10 +1,9 @@ --- -nd-docs: DOCS-000 title: Submit templates toc: true weight: 200 -type: -- how-to +nd-content-type: how-to +nd-product: ONE --- # Template submission and preview guide @@ -12,6 +11,7 @@ type: This guide explains how to submit templates for rendering NGINX configurations and preview the results using the Templates API. Before submitting templates for preview, you need to import templates into NGINX One Console. + - See the [Import Templates Guide]({{< ref "import-templates.md" >}}) for instructions on creating templates. - For guidance on writing templates, see the [Template Authoring Guide]({{< ref "author-templates.md" >}}). @@ -20,11 +20,11 @@ Before submitting templates for preview, you need to import templates into NGINX Template submission allows you to compose templates that generate complete NGINX configuration. The process involves: 1. **Discovering templates** - Find base and augment templates that match your infrastructure needs -2. **Understanding capabilities** - Review what contexts and features the base template supports -3. **Selecting augments** - Choose augments for additional features (CORS, rate limiting, SSL, etc.) -4. **Providing values** - Supply values for all template variables -5. **Preview and validate** - Generate and review the complete NGINX configuration -6. **Save as staged config** - Use NGINX One Console to save the preview as a staged configuration for deployment +1. **Understanding capabilities** - Review what contexts and features the base template supports +1. **Selecting augments** - Choose augments for additional features (CORS, rate limiting, SSL, etc.) +1. **Providing values** - Supply values for all template variables +1. **Preview and validate** - Generate and review the complete NGINX configuration +1. **Save as staged config** - Use NGINX One Console to save the preview as a staged configuration for deployment ## Current limitations @@ -41,7 +41,8 @@ Before creating a submission, find base and augment templates that match your in Use the [List Templates]({{< ref "/nginx-one/api/api-reference-guide/#operation/listTemplates" >}}) API operation to find templates organized by use case. -**Example Response:** +**Example response:** + ```json { "count": 3, @@ -89,11 +90,13 @@ Use the [List Templates]({{< ref "/nginx-one/api/api-reference-guide/#operation/ ``` **Use Case Identification:** + - **Base templates** represent primary NGINX use cases (reverse proxy, load balancer, static site, API gateway) - **Template descriptions** help identify which base template matches your infrastructure need - **augment_includes** shows what additional features each base template supports **Information Available In API Response:** + - **object_id** - A unique identifier of a template to use in submission requests - **type** - Identifies base templates (use exactly one) vs augment templates (use zero or more) - **allowed_in_contexts** - Shows where augment templates can be applied within a base template @@ -106,12 +109,14 @@ The API response contains all information needed for creating a submission to re Use the [Retrieve a Template]({{< ref "/nginx-one/api/api-reference-guide/#operation/getTemplate" >}}) API operation only when you need to examine template content or detailed variable requirements. **When to use template details:** + - Review the actual template code and structure - Examine detailed schema definitions for variable validation - Understand specific variable names and constraints - Debug template behavior or compatibility issues -**Example Response:** +**Example response:** + ```json { "allowed_in_contexts": [], @@ -149,6 +154,7 @@ Use the [Retrieve a Template]({{< ref "/nginx-one/api/api-reference-guide/#opera ``` **Details:** + - **Template content** - Shows `augment_includes` placeholders and variable usage (e.g., `{{ .backend_url }}`) - **Schema definition** - Shows required variables (`backend_url`) and their validation rules - **Variable constraints** - Data types, descriptions, and any pattern requirements @@ -164,31 +170,41 @@ The following sections describe what you need for the request: ### Required parameters **Query Parameter:** + - `preview_only=true` - Currently the only supported mode. Renders configuration for preview without creating a submission object. ### Configuration path (`conf_path`) -**Required.** The absolute path where the main NGINX configuration file should be placed. +{{< call-out "important" >}} -**Examples:** -- `/etc/nginx/nginx.conf` (standard installation) -- `/opt/nginx/nginx.conf` (custom installation) +This path determines where augment configurations are rendered: -**Important:** This path determines where augment configurations are rendered: - Base template → renders to the exact `conf_path` - Augment templates → render to `{base_dir}/conf.d/augments/{filename}.{hash}.conf` Where `base_dir` is derived from `conf_path`: + - `conf_path: /etc/nginx/nginx.conf` → augments in `/etc/nginx/conf.d/augments/` - `conf_path: /opt/nginx/nginx.conf` → augments in `/opt/nginx/conf.d/augments/` +{{< /call-out >}} + +**Required.** The absolute path where the main NGINX configuration file should be placed. + +**Examples:** + +- `/etc/nginx/nginx.conf` (standard installation) +- `/opt/nginx/nginx.conf` (custom installation) + ### Template properties **Base Template:** + - `object_id` - Template unique identifier (use a template where `type` is `base`) - `values` - Key-value pairs for template variables **Augment Templates:** + - `object_id` - Template unique identifier (use a template where `type` is `augment`) - `target_context` - NGINX context where the augment should be applied - `values` - Key-value pairs for template variables (optional if template has no variables) @@ -199,6 +215,7 @@ Where `base_dir` is derived from `conf_path`: Augment templates must specify a `target_context` that determines where the augment will be placed in the base template. **Validation:** + - The augment's `target_context` must be listed in the augment template's `allowed_in_contexts` (specified during import) **Available Contexts:** @@ -206,6 +223,7 @@ Augment templates must specify a `target_context` that determines where the augm See the [Template Authoring Guide]({{< ref "author-templates.md#config-templates-contexts" >}}) for detailed information about context paths and how they map to NGINX configuration structure. **Rendering Behavior:** + - If the base template has an `augment_includes` placeholder for the target context, the augment content is injected there - If the base template doesn't have a matching placeholder, the augment is ignored (no error) - If the base template has placeholders but no matching augments are provided, those placeholders render as empty strings @@ -352,15 +370,18 @@ Parse errors indicate the rendered configuration has NGINX syntax issues, often When templates are successfully rendered, the system creates multiple files: ### Base template output + - **File:** Exact path specified in `conf_path` - **Content:** Rendered base template with augment content injected at `augment_includes` points ### Augment template outputs + - **Location:** `{base_dir}/conf.d/augments/` - **Filename:** `{template-name}.{content-hash}.conf` - **Content:** Individual augment template rendered output **Example structure:** + ``` /etc/nginx/ ├── nginx.conf # Base template output @@ -417,6 +438,7 @@ Template rendering follows predictable ordering rules at two levels: Directives render in the exact order they appear in the template file. This includes the placement of `{{ augment_includes "context_path" . }}` extension points. **Example:** + ```nginx http { # This renders first @@ -435,6 +457,7 @@ http { When multiple augments target the same context, they render in the order specified in the submission request's augments array. **Example submission:** + ```json { "conf_path": "/etc/nginx/nginx.conf", @@ -458,6 +481,7 @@ When multiple augments target the same context, they render in the order specifi ``` **Rendered output:** + ```text http { # First augment renders first diff --git a/content/nginx-one/secure-your-fleet/set-up-security-alerts.md b/content/nginx-one/secure-your-fleet/set-up-security-alerts.md index ee3d3c6c2..2f02b4180 100644 --- a/content/nginx-one/secure-your-fleet/set-up-security-alerts.md +++ b/content/nginx-one/secure-your-fleet/set-up-security-alerts.md @@ -3,7 +3,7 @@ title: "Set up security alerts" weight: 500 toc: true nd-content-type: how-to -nd-product: NGINX One +nd-product: ONE --- With this page, you'll learn how to set up alerts in F5 Distributed Cloud. Once configured, you'll see the CVEs and insecure configurations associated with your NGINX fleet. These instructions are intended for those responsible for keeping their NGINX infrastructure and application traffic secure. It assumes you know how to: @@ -139,14 +139,19 @@ When you set up an email alert for a problem, you'll see the alert in: You may also get a follow-up email with the subject **Alert Resolved**. -> **Important:** Sometimes an **Alert Resolved** email is sent even though the issue is still active. +{{< call-out "important" >}} + +Sometimes an **Alert Resolved** email is sent even though the issue is still active. To check the current status, go to the NGINX One Console. For CVEs, the trusted source is: + - **NGINX One Console > Manage > Instances > `Instance hostname`** Open the instance dashboard to see the latest list of CVEs. Use the Console, not email, to confirm whether an issue is resolved. +{{< /call-out >}} + ## Summary In this tutorial, you learned how to: diff --git a/content/nginx/deployment-guides/single-sign-on/active-directory-federation-services.md b/content/nginx/deployment-guides/single-sign-on/active-directory-federation-services.md index c4dead22d..a77487fcd 100644 --- a/content/nginx/deployment-guides/single-sign-on/active-directory-federation-services.md +++ b/content/nginx/deployment-guides/single-sign-on/active-directory-federation-services.md @@ -1,11 +1,10 @@ --- -description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using Microsoft AD FS as the identity provider (IdP). -type: -- how-to title: Single Sign-On with Microsoft Active Directory FS +description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using Microsoft AD FS as the identity provider (IdP). toc: true weight: 300 -product: NGINX-PLUS +nd-content-type: how-to +nd-product: NPL nd-docs: DOCS-1683 --- @@ -13,7 +12,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr {{< call-out "note" >}} This guide applies to [NGINX Plus Release 35]({{< ref "nginx/releases.md#r35" >}}) and later. In earlier versions, NGINX Plus relied on an [njs-based solution](#legacy-njs-guide), 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.{{< /call-out >}} - ## Prerequisites - A Microsoft AD FS instance, either on-premises or in [Azure](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/deployment/how-to-connect-fed-azure-adfs), with administrator privileges. @@ -22,7 +20,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr - A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`. - ## Configure the AD FS Server {#adfs-setup} [Microsoft Active Directory Federation Services](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services) (AD FS) serves as the Identity Provider. @@ -80,7 +77,8 @@ Check the OpenID Connect endpoint URL. By default, AD FS publishes the `.well-kn ```shell curl https://adfs-server-address/adfs/.well-known/openid-configuration | jq . ``` - where: + + Where: - the `adfs-server-address` is your AD FS server address @@ -88,7 +86,6 @@ Check the OpenID Connect endpoint URL. By default, AD FS publishes the `.well-kn - the `jq` command (optional) is used to format the JSON output for easier reading and requires the [jq](https://jqlang.github.io/jq/) JSON processor to be installed. - The configuration metadata is returned in the JSON format: ```json @@ -109,23 +106,21 @@ Check the OpenID Connect endpoint URL. By default, AD FS publishes the `.well-kn `https://adfs-server-address/adfs`. - {{< call-out "note" >}} You will need the values of **Client ID**, **Client Secret**, and **Issuer** in the next steps. {{< /call-out >}} - ## Set up NGINX Plus {#nginx-plus-setup} With AD FS configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as the Rely Party (RP) application — a client service that verifies user identity. - 1. Ensure that you are using the latest version of NGINX Plus by running the `nginx -v` command in a terminal: ```shell nginx -v ``` + The output should match NGINX Plus Release 35 or later: - ```none + ```text nginx version: nginx/1.29.0 (nginx-plus-r35) ``` @@ -142,7 +137,7 @@ With AD FS configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t # ... } ``` - + 5. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, define the AD FS OIDC provider named `adfs` by specifying the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context: ```nginx @@ -177,7 +172,7 @@ With AD FS configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t - If the **userinfo** directive is set to `on`, NGINX Plus will fetch `/userinfo` from the AD FS and append the claims from userinfo to the `$oidc_claims_` variables. - - **Important:** All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system's CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP's certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP's certificate. + - {{< call-out "important" >}} All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system's CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP's certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP's certificate. {{< /call-out >}} ```nginx http { @@ -288,7 +283,9 @@ With AD FS configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t } } ``` + 12. Save the NGINX configuration file and reload the configuration: + ```nginx nginx -s reload ``` @@ -368,19 +365,16 @@ http { 4. Refresh `https://demo.example.com/` again. You should be redirected to AD FS for a fresh sign‑in, proving the session has been terminated. - ## Legacy njs-based AD FS Solution {#legacy-njs-guide} If you are running NGINX Plus R33 and earlier or if you still need the njs-based solution, refer to the [Legacy njs-based Microsoft AD FS Guide]({{< ref "nginx/deployment-guides/single-sign-on/oidc-njs/active-directory-federation-services.md" >}}) for details. The solution uses the [`nginx-openid-connect`](https://github.com/nginxinc/nginx-openid-connect) GitHub repository and NGINX JavaScript files. - ## See Also - [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) - [Release Notes for NGINX Plus R35]({{< ref "nginx/releases.md#r35" >}}) - ## Revision History - Version 2 (August 2025) – Added RP‑initiated logout (logout_uri, post_logout_uri, logout_token_hint) and userinfo support. diff --git a/content/nginx/deployment-guides/single-sign-on/auth0.md b/content/nginx/deployment-guides/single-sign-on/auth0.md index 90d0dffd4..ce67f4d3b 100644 --- a/content/nginx/deployment-guides/single-sign-on/auth0.md +++ b/content/nginx/deployment-guides/single-sign-on/auth0.md @@ -1,11 +1,10 @@ --- -description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using Auth0 as the identity provider (IdP). -type: -- how-to -product: NGINX-PLUS title: Single Sign-On With Auth0 +description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using Auth0 as the identity provider (IdP). toc: true weight: 100 +nd-content-type: how-to +nd-product: NPL nd-docs: DOCS-1686 --- @@ -13,7 +12,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr {{< call-out "note" >}} This guide applies to [NGINX Plus Release 35]({{< ref "nginx/releases.md#r35" >}}) and later. In earlier versions, NGINX Plus relied on an [njs-based solution](#legacy-njs-guide), 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.{{< /call-out >}} - ## Prerequisites - An [Auth0](https://auth0.com/) tenant with administrator privileges. @@ -22,7 +20,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr - A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`. - ## Create a new Auth0 Application {#auth0-create} 1. Log in to your Auth0 Dashboard at [manage.auth0.com](https://manage.auth0.com/). @@ -64,7 +61,8 @@ Check the OpenID Connect Discovery URL. By default, Auth0 publishes the `.well-k ```shell curl https://yourTenantId.us.auth0.com/.well-known/openid-configuration | jq ``` - where: + + Where: - the `yourTenantId` is your Auth0 [Tenant ID](https://auth0.com/docs/get-started/tenant-settings/find-your-tenant-name-or-tenant-id) @@ -74,7 +72,6 @@ Check the OpenID Connect Discovery URL. By default, Auth0 publishes the `.well-k - the `jq` command (optional) is used to format the JSON output for easier reading and requires the [jq](https://jqlang.github.io/jq/) JSON processor to be installed. - The configuration metadata is returned in the JSON format: ```json @@ -90,12 +87,10 @@ Check the OpenID Connect Discovery URL. By default, Auth0 publishes the `.well-k } ``` - 2. Copy the **issuer** value, you will need it later when configuring NGINX Plus. Typically, the OpenID Connect Issuer for Auth0 is `https://yourTenantId.us.auth0.com/` (including the trailing slash). To verify the accuracy of the endpoints, refer to the [Auth0 official documentation](https://auth0.com/docs/get-started/applications/configure-applications-with-oidc-discovery). {{< call-out "note" >}} You will need the values of **Client ID**, **Client Secret**, and **Issuer** in the next steps. {{< /call-out >}} - ## Set up NGINX Plus {#nginx-plus-setup} With Auth0 configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as the Rely Party (RP) application — a client service that verifies user identity. @@ -105,6 +100,7 @@ With Auth0 configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t ```shell nginx -v ``` + The output should match NGINX Plus Release 35 or later: ```none @@ -160,8 +156,7 @@ With Auth0 configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t - If the **userinfo** directive is set to `on`, NGINX Plus will fetch `/userinfo` from the Auth0 and append the claims from userinfo to the `$oidc_claims_` variables. - - **Important:** All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system’s CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP’s certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP’s certificate. - + - {{< call-out "important" >}} All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system’s CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP’s certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP’s certificate. {{< /call-out >}} ```nginx http { @@ -242,7 +237,6 @@ With Auth0 configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t # ... ``` - 10. Provide endpoint for completing logout: ```nginx @@ -253,6 +247,7 @@ With Auth0 configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t } # ... ``` + 11. Create a simple test application referenced by the `proxy_pass` directive which returns the authenticated user's full name and email upon successful authentication: ```nginx @@ -266,7 +261,9 @@ With Auth0 configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as t } } ``` + 12. Save the NGINX configuration file and reload the configuration: + ```nginx nginx -s reload ``` @@ -347,14 +344,12 @@ http { If you are running NGINX Plus R33 and earlier or if you still need the njs-based solution, refer to the [Legacy njs-based Auth0 Guide]({{< ref "nginx/deployment-guides/single-sign-on/oidc-njs/auth0.md" >}}) for details. The solution uses the [`nginx-openid-connect`](https://github.com/nginxinc/nginx-openid-connect) GitHub repository and NGINX JavaScript files. - ## See Also - [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) - [Release Notes for NGINX Plus R35]({{< ref "nginx/releases.md#r35" >}}) - ## Revision History - Version 2 (August 2025) – Added RP‑initiated logout (logout_uri, post_logout_uri, logout_token_hint) and userinfo support. diff --git a/content/nginx/deployment-guides/single-sign-on/cognito.md b/content/nginx/deployment-guides/single-sign-on/cognito.md index cdc38ada5..6e46b2101 100644 --- a/content/nginx/deployment-guides/single-sign-on/cognito.md +++ b/content/nginx/deployment-guides/single-sign-on/cognito.md @@ -1,11 +1,10 @@ --- -description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using Amazon Cognito as the identity provider (IdP). -type: -- how-to -product: NGINX-PLUS title: Single Sign-On with Amazon Cognito +description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using Amazon Cognito as the identity provider (IdP). toc: true weight: 200 +nd-content-type: how-to +nd-product: NPL nd-docs: DOCS-1685 --- @@ -13,7 +12,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr {{< call-out "note" >}} This guide applies to [NGINX Plus Release 35]({{< ref "nginx/releases.md#r35" >}}) and later. In earlier versions, NGINX Plus relied on an [njs-based solution](#legacy-njs-guide), 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.{{< /call-out >}} - ## Prerequisites - An [AWS account](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/) @@ -24,7 +22,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr - A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`. - ## Configure Amazon Cognito {#cognito-setup} 1. Open the Amazon Cognito console in the AWS Management Console @@ -66,7 +63,8 @@ Check the OpenID Connect Discovery URL. By default, Amazon Cognito publishes the ```shell curl https://cognito-idp.us-east-2.amazonaws.com/us-east-2_abCdEfGhI/.well-known/openid-configuration | jq ``` - where: + + Where: - the `cognito-idp.us-east-2.amazonaws.com` is your Amazon Cognito server address @@ -76,7 +74,6 @@ Check the OpenID Connect Discovery URL. By default, Amazon Cognito publishes the - the `jq` command (optional) is used to format the JSON output for easier reading and requires the [jq](https://jqlang.github.io/jq/) JSON processor to be installed. - The configuration metadata is returned in the JSON format: ```json @@ -96,7 +93,6 @@ Check the OpenID Connect Discovery URL. By default, Amazon Cognito publishes the {{< call-out "note" >}} You will need the values of **Client ID**, **Client Secret**, and **Issuer** in the next steps. {{< /call-out >}} - ## Set up NGINX Plus {#nginx-plus-setup} With Cognito configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as the Rely Party (RP) application — a client service that verifies user identity. @@ -106,6 +102,7 @@ With Cognito configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as ```shell nginx -v ``` + The output should match NGINX Plus Release 35 or later: ```none @@ -162,7 +159,7 @@ With Cognito configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as - If the **userinfo** directive is set to `on`, NGINX Plus will fetch `/oauth2/userInfo` from the Amazon Cognito and append the claims from userinfo to the `$oidc_claims_` variables. - - **Important:** All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system's CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP's certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP's certificate. + - {{< call-out "important" >}} All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system’s CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP’s certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP’s certificate. {{< /call-out >}} ```nginx http { @@ -269,7 +266,9 @@ With Cognito configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as } } ``` + 12. Save the NGINX configuration file and reload the configuration: + ```nginx nginx -s reload ``` @@ -347,19 +346,16 @@ http { 4. Refresh `https://demo.example.com/` again. You should be redirected to Amazon Cognito for a fresh sign‑in, proving the session has been terminated. - ## Legacy njs-based Amazon Cognito Solution {#legacy-njs-guide} If you are running NGINX Plus R33 and earlier or if you still need the njs-based solution, refer to the [Legacy njs-based Cognito Guide]({{< ref "nginx/deployment-guides/single-sign-on/oidc-njs/cognito.md" >}}) for details. The solution uses the [`nginx-openid-connect`](https://github.com/nginxinc/nginx-openid-connect) GitHub repository and NGINX JavaScript files. - ## See Also - [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) - [Release Notes for NGINX Plus R35]({{< ref "nginx/releases.md#r35" >}}) - ## Revision History - Version 2 (August 2025) – Added RP‑initiated logout (logout_uri, post_logout_uri, logout_token_hint) and userinfo support. diff --git a/content/nginx/deployment-guides/single-sign-on/entra-id.md b/content/nginx/deployment-guides/single-sign-on/entra-id.md index 3ab1b51ee..5191751a7 100644 --- a/content/nginx/deployment-guides/single-sign-on/entra-id.md +++ b/content/nginx/deployment-guides/single-sign-on/entra-id.md @@ -1,11 +1,10 @@ --- -description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using Microsoft Entra ID (formerly Azure Active Directory) as the identity provider (IdP). -type: -- how-to -product: NGINX-PLUS title: Single Sign-On with Microsoft Entra ID +description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using Microsoft Entra ID (formerly Azure Active Directory) as the identity provider (IdP). toc: true weight: 400 +nd-content-type: how-to +nd-product: NPL nd-docs: DOCS-1688 --- @@ -13,7 +12,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr {{< call-out "note" >}} This guide applies to [NGINX Plus Release 35]({{< ref "nginx/releases.md#r35" >}}) and later. In earlier versions, NGINX Plus relied on an [njs-based solution](#legacy-njs-guide), 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.{{< /call-out >}} - ## Prerequisites - A Microsoft Entra tenant with admin access. @@ -24,7 +22,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr - A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`. - ## Configure Entra ID {#entra-setup} Register a new application in Microsoft Entra ID that will represent NGINX Plus as an OIDC client. This is necessary to obtain unique identifiers and secrets for OIDC, as well as to specify where Azure should return tokens. Ensure you have access to the Azure Portal with Entra ID app administrator privileges. @@ -33,16 +30,17 @@ Register a new application in Microsoft Entra ID that will represent NGINX Plus 1. Log in to Azure CLI: - ```bash + ```shell az login ``` + This command will open your default browser for authentication. 2. Register a New Application. - Create a new application, for example, "Nginx Demo App", with NGINX callback URI `/oidc_callback`: - ```bash + ```shell az ad app create --display-name "Nginx Demo App" --web-redirect-uris "https://demo.example.com/oidc_callback" ``` @@ -83,7 +81,8 @@ Check the OpenID Connect Discovery URL. By default, Microsoft Entra ID publishes ```shell curl https://login.microsoftonline.com//v2.0/.well-known/openid-configuration | jq ``` - where: + + Where: - the `` is your Microsoft Entra Tenant ID @@ -93,7 +92,6 @@ Check the OpenID Connect Discovery URL. By default, Microsoft Entra ID publishes - the `jq` command (optional) is used to format the JSON output for easier reading and requires the [jq](https://jqlang.github.io/jq/) JSON processor to be installed. - The configuration metadata is returned in the JSON format: ```json @@ -122,6 +120,7 @@ With Microsoft Entra ID configured, you can enable OIDC on NGINX Plus. NGINX Plu ```shell nginx -v ``` + The output should match NGINX Plus Release 35 or later: ```none @@ -182,7 +181,7 @@ With Microsoft Entra ID configured, you can enable OIDC on NGINX Plus. NGINX Plu - If the **userinfo** directive is set to `on`, NGINX Plus will fetch userinfo from Microsoft Graph API and append the claims from userinfo to the `$oidc_claims_` variables. - - **Important:** All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system's CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP's certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP's certificate. + - {{< call-out "important" >}} All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system’s CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP’s certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP’s certificate. {{< /call-out >}} ```nginx http { @@ -255,7 +254,6 @@ With Microsoft Entra ID configured, you can enable OIDC on NGINX Plus. NGINX Plu - any other OIDC claim using the [`$oidc_claim_ `](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) variable - ```nginx # ... location / { @@ -296,7 +294,9 @@ With Microsoft Entra ID configured, you can enable OIDC on NGINX Plus. NGINX Plu } } ``` + 12. Save the NGINX configuration file and reload the configuration: + ```nginx nginx -s reload ``` @@ -377,7 +377,6 @@ http { {{< call-out "note" >}}If you restricted access to a group of users, be sure to select a user who has access to the application.{{< /call-out >}} - ## See Also - [Microsoft identity platform documentation](https://learn.microsoft.com/en-us/entra/identity-platform/) diff --git a/content/nginx/deployment-guides/single-sign-on/keycloak.md b/content/nginx/deployment-guides/single-sign-on/keycloak.md index 718ae4a7d..722fc9d66 100644 --- a/content/nginx/deployment-guides/single-sign-on/keycloak.md +++ b/content/nginx/deployment-guides/single-sign-on/keycloak.md @@ -1,11 +1,10 @@ --- -description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using Keycloak as the identity provider (IdP). -type: -- how-to -product: NGINX-PLUS title: Single Sign-On with Keycloak +description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using Keycloak as the identity provider (IdP). toc: true weight: 500 +nd-content-type: how-to +nd-product: NPL nd-docs: DOCS-1682 --- @@ -13,7 +12,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr {{< call-out "note" >}} This guide applies to [NGINX Plus Release 35]({{< ref "nginx/releases.md#r35" >}}) and later. In earlier versions, NGINX Plus relied on an [njs-based solution](#legacy-njs-guide), 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.{{< /call-out >}} - ## Prerequisites - A running [Keycloak](https://www.keycloak.org/) server version compatible with OIDC. @@ -22,7 +20,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr - A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`. - ## Configure Keycloak {#keycloak-setup} 1. Log in to your Keycloak admin console, for example, `https:///admin/master/console/`. @@ -45,13 +42,15 @@ This guide explains how to enable single sign-on (SSO) for applications being pr 5. In the **Login Settings** section: - - Add a **Redirect URI**, for example: - ``` + Add a **Redirect URI**, for example: + + ```text https://demo.example.com/oidc_callback ``` - - Add a **Post Logout Redirect URI** to support RP-initiated logout, for example: - ``` + Add a **Post Logout Redirect URI** to support RP-initiated logout, for example: + + ```text https://demo.example.com/post_logout/ ``` @@ -80,7 +79,8 @@ Check the OpenID Connect Discovery URL. By default, Keycloak publishes the `.wel ```shell curl https:///realms//.well-known/openid-configuration | jq ``` - where: + + Where: - the `` is your Keycloak server address @@ -90,7 +90,6 @@ Check the OpenID Connect Discovery URL. By default, Keycloak publishes the `.wel - the `jq` command (optional) is used to format the JSON output for easier reading and requires the [jq](https://jqlang.github.io/jq/) JSON processor to be installed. - The configuration metadata is returned in the JSON format: ```json @@ -110,7 +109,6 @@ Check the OpenID Connect Discovery URL. By default, Keycloak publishes the `.wel {{< call-out "note" >}} You will need the values of **Client ID**, **Client Secret**, and **Issuer** in the next steps. {{< /call-out >}} - ## Set up NGINX Plus {#nginx-plus-setup} With Keycloak configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as the Relying Party (RP) application — a client service that verifies user identity. @@ -120,6 +118,7 @@ With Keycloak configured, you can enable OIDC on NGINX Plus. NGINX Plus serves a ```shell nginx -v ``` + The output should match NGINX Plus Release 35 or later: ```none @@ -181,7 +180,7 @@ With Keycloak configured, you can enable OIDC on NGINX Plus. NGINX Plus serves a - If the **userinfo** directive is set to `on`, NGINX Plus will fetch `/protocol/openid-connect/userinfo` from the Keycloak and append the claims from userinfo to the `$oidc_claims_` variables. - - **Important:** All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system's CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP's certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP's certificate. + - {{< call-out "important" >}} All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system’s CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP’s certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP’s certificate. {{< /call-out >}} ```nginx http { @@ -249,7 +248,6 @@ With Keycloak configured, you can enable OIDC on NGINX Plus. NGINX Plus serves a - any other OIDC claim using the [`$oidc_claim_ `](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) variable - ```nginx # ... location / { @@ -289,7 +287,9 @@ With Keycloak configured, you can enable OIDC on NGINX Plus. NGINX Plus serves a } } ``` + 12. Save the NGINX configuration file and reload the configuration: + ```nginx nginx -s reload ``` @@ -373,19 +373,16 @@ Upon successful sign-in, Keycloak redirects you back to NGINX Plus, and you will 4. Refresh `https://demo.example.com/` again. You should be redirected to Keycloak for a fresh sign‑in, proving the session has been terminated. - ## Legacy njs-based Keycloak Solution {#legacy-njs-guide} If you are running NGINX Plus R33 and earlier or if you still need the njs-based solution, refer to the [Legacy njs-based Keycloak Guide]({{< ref "nginx/deployment-guides/single-sign-on/oidc-njs/keycloak.md" >}}) for details. The solution uses the [`nginx-openid-connect`](https://github.com/nginxinc/nginx-openid-connect) GitHub repository and NGINX JavaScript files. - ## See Also - [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) - [Release Notes for NGINX Plus R35]({{< ref "nginx/releases.md#r35" >}}) - ## Revision History - Version 2 (August 2025) – Added RP‑initiated logout (logout_uri, post_logout_uri, logout_token_hint) and userinfo support. diff --git a/content/nginx/deployment-guides/single-sign-on/okta.md b/content/nginx/deployment-guides/single-sign-on/okta.md index c8e019f41..ae022321f 100644 --- a/content/nginx/deployment-guides/single-sign-on/okta.md +++ b/content/nginx/deployment-guides/single-sign-on/okta.md @@ -1,11 +1,10 @@ --- -description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using Okta as the identity provider (IdP). -type: -- how-to -product: NGINX-PLUS title: Single Sign-On with Okta +description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using Okta as the identity provider (IdP). toc: true weight: 700 +nd-content-type: how-to +nd-product: NPL nd-docs: DOCS-1689 --- @@ -13,7 +12,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr {{< call-out "note" >}} This guide applies to [NGINX Plus Release 35]({{< ref "nginx/releases.md#r35" >}}) and later. In earlier versions, NGINX Plus relied on an [njs-based solution](#legacy-njs-guide), 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.{{< /call-out >}} - ## Prerequisites - An [Okta](https://www.okta.com/) administrator account with privileges to create and manage applications. @@ -22,7 +20,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr - A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`. - ## Configure Okta {#okta-setup} In Okta, register a new application for NGINX Plus as the OIDC client to obtain the Client ID, Client Secret, and required OIDC endpoints. @@ -78,7 +75,8 @@ Check the OpenID Connect Discovery URL. By default, Okta publishes the `.well-kn ```shell curl https://dev-123456.okta.com/oauth2/default/.well-known/openid-configuration | jq ``` - where: + + Where: - the `dev-123456.okta.com` is your Okta domain @@ -88,7 +86,6 @@ Check the OpenID Connect Discovery URL. By default, Okta publishes the `.well-kn - the `jq` command (optional) is used to format the JSON output for easier reading and requires the [jq](https://jqlang.github.io/jq/) JSON processor to be installed. - The configuration metadata is returned in the JSON format: ```json @@ -120,7 +117,6 @@ By default, Okta might limit application access to certain users or groups. To a 4. Add or remove users and groups that can access this application. - ## Set up NGINX Plus {#nginx-plus-setup} With Okta configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as the Rely Party (RP) application — a client service that verifies user identity. @@ -130,6 +126,7 @@ With Okta configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as th ```shell nginx -v ``` + The output should match NGINX Plus Release 35 or later: ```none @@ -150,7 +147,6 @@ With Okta configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as th } ``` - 5. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, define the Okta provider named `okta` by specifying the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context: ```nginx @@ -187,7 +183,7 @@ With Okta configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as th - If the **userinfo** directive is set to `on`, NGINX Plus will fetch `/oauth2/default/v1/userinfo` from the Okta and append the claims from userinfo to the `$oidc_claims_` variables. - - **Important:** All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system's CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP's certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP's certificate. + - {{< call-out "important" >}} All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system’s CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP’s certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP’s certificate. {{< /call-out >}} ```nginx http { @@ -268,7 +264,6 @@ With Okta configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as th # ... ``` - 10. Provide endpoint for completing logout: ```nginx @@ -293,7 +288,9 @@ With Okta configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as th } } ``` + 12. Save the NGINX configuration file and reload the configuration: + ```nginx nginx -s reload ``` @@ -377,19 +374,16 @@ http { {{< call-out "note" >}}If you restricted access to a group of users, be sure to select a user who has access to the application.{{< /call-out >}} - ## Legacy njs-based Okta Solution {#legacy-njs-guide} If you are running NGINX Plus R33 and earlier or if you still need the njs-based solution, refer to the [Legacy njs-based Okta Guide]({{< ref "nginx/deployment-guides/single-sign-on/oidc-njs/okta.md" >}}) for details. The solution uses the [`nginx-openid-connect`](https://github.com/nginxinc/nginx-openid-connect) GitHub repository and NGINX JavaScript files. - ## See Also - [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) - [Release Notes for NGINX Plus R35]({{< ref "nginx/releases.md#r35" >}}) - ## Revision History - Version 2 (August 2025) – Added RP‑initiated logout (logout_uri, post_logout_uri, logout_token_hint) and userinfo support. diff --git a/content/nginx/deployment-guides/single-sign-on/onelogin.md b/content/nginx/deployment-guides/single-sign-on/onelogin.md index 98b1278be..3b0e2c225 100644 --- a/content/nginx/deployment-guides/single-sign-on/onelogin.md +++ b/content/nginx/deployment-guides/single-sign-on/onelogin.md @@ -1,11 +1,10 @@ --- -description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using OneLogin as the identity provider (IdP). -type: -- how-to -product: NGINX-PLUS title: Single Sign-On with OneLogin +description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using OneLogin as the identity provider (IdP). toc: true weight: 600 +nd-content-type: how-to +nd-product: NPL nd-docs: DOCS-1687 --- @@ -13,7 +12,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr {{< call-out "note" >}} This guide applies to [NGINX Plus Release 35]({{< ref "nginx/releases.md#r35" >}}) and later. In earlier versions, NGINX Plus relied on an [njs-based solution](#legacy-njs-guide), 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.{{< /call-out >}} - ## Prerequisites - An [OneLogin](https://www.onelogin.com/) account with administrator privileges. @@ -22,7 +20,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr - A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`. - ## Configure OneLogin {#onelogin-setup} ### Create a OneLogin OIDC Application @@ -70,7 +67,8 @@ Check the OpenID Connect Discovery URL. By default, OneLogin publishes the `.wel ```shell curl https://.onelogin.com/oidc/2/.well-known/openid-configuration | jq ``` - where: + + Where: - the `.onelogin.com` is your OneLogin subdomain @@ -80,7 +78,6 @@ Check the OpenID Connect Discovery URL. By default, OneLogin publishes the `.wel - the `jq` command (optional) is used to format the JSON output for easier reading and requires the [jq](https://jqlang.github.io/jq/) JSON processor to be installed. - The configuration metadata is returned in the JSON format: ```json @@ -106,7 +103,6 @@ Check the OpenID Connect Discovery URL. By default, OneLogin publishes the `.wel 2. Add users and groups who should have access to this application. - ## Set up NGINX Plus {#nginx-plus-setup} With Onelogin configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as the Rely Party (RP) application — a client service that verifies user identity. @@ -116,6 +112,7 @@ With Onelogin configured, you can enable OIDC on NGINX Plus. NGINX Plus serves a ```shell nginx -v ``` + The output should match NGINX Plus Release 35 or later: ```none @@ -136,7 +133,6 @@ With Onelogin configured, you can enable OIDC on NGINX Plus. NGINX Plus serves a } ``` - 5. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, define the OneLogin provider named `onelogin` by specifying the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context: ```nginx @@ -173,7 +169,7 @@ With Onelogin configured, you can enable OIDC on NGINX Plus. NGINX Plus serves a - If the **userinfo** directive is set to `on`, NGINX Plus will fetch `/oidc/2/me` from the OneLogin and append the claims from userinfo to the `$oidc_claims_` variables. - - **Important:** All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system's CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP's certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP's certificate. + - {{< call-out "important" >}} All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system’s CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP’s certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP’s certificate. {{< /call-out >}} ```nginx http { @@ -240,7 +236,6 @@ With Onelogin configured, you can enable OIDC on NGINX Plus. NGINX Plus serves a - any other OIDC claim using the [`$oidc_claim_ `](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) variable - ```nginx # ... location / { @@ -255,7 +250,6 @@ With Onelogin configured, you can enable OIDC on NGINX Plus. NGINX Plus serves a # ... ``` - 10. Provide endpoint for completing logout: ```nginx @@ -280,7 +274,9 @@ With Onelogin configured, you can enable OIDC on NGINX Plus. NGINX Plus serves a } } ``` + 12. Save the NGINX configuration file and reload the configuration: + ```nginx nginx -s reload ``` @@ -360,19 +356,16 @@ http { {{< call-out "note" >}}If you restricted access to a group of users, be sure to select a user who has access to the application.{{< /call-out >}} - ## Legacy njs-based OneLogin Solution {#legacy-njs-guide} If you are running NGINX Plus R33 and earlier or if you still need the njs-based solution, refer to the [Legacy njs-based OneLogin Guide]({{< ref "nginx/deployment-guides/single-sign-on/oidc-njs/onelogin.md" >}}) for details. The solution uses the [`nginx-openid-connect`](https://github.com/nginxinc/nginx-openid-connect) GitHub repository and NGINX JavaScript files. - ## See Also - [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) - [Release Notes for NGINX Plus R35]({{< ref "nginx/releases.md#r35" >}}) - ## Revision History - Version 2 (August 2025) – Added RP‑initiated logout (logout_uri, post_logout_uri, logout_token_hint) and userinfo support. diff --git a/content/nginx/deployment-guides/single-sign-on/ping-identity.md b/content/nginx/deployment-guides/single-sign-on/ping-identity.md index d321dd854..71f8fc242 100644 --- a/content/nginx/deployment-guides/single-sign-on/ping-identity.md +++ b/content/nginx/deployment-guides/single-sign-on/ping-identity.md @@ -1,11 +1,10 @@ --- -description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using Ping Identity as the identity provider (IdP). -type: -- how-to -product: NGINX-PLUS title: Single Sign-On with Ping Identity +description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using Ping Identity as the identity provider (IdP). toc: true weight: 800 +nd-content-type: how-to +nd-product: NPL nd-docs: DOCS-1684 --- @@ -13,7 +12,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr {{< call-out "note" >}} This guide applies to [NGINX Plus Release 35]({{< ref "nginx/releases.md#r35" >}}) and later. In earlier versions, NGINX Plus relied on an [njs-based solution](#legacy-njs-guide), 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.{{< /call-out >}} - ## Prerequisites - [PingFederate](https://docs.pingidentity.com/pingfederate/latest/pf_pf_landing_page.html) Enterprise Federation Server or [PingOne](https://docs.pingidentity.com/pingone/p1_cloud__platform_main_landing_page.html) Cloud deployment with a Ping Identity account. @@ -22,7 +20,6 @@ This guide explains how to enable single sign-on (SSO) for applications being pr - A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`. - ## Configure PingFederate or PingOne for Enterprise {#ping-create} {{< call-out "note" >}} These steps outline an example with the cloud offering of **PingOne**. If you are using the on‑premises PingFederate, the user interface might slightly differ. {{< /call-out >}} @@ -80,7 +77,8 @@ For PingFederate: `https://pingfederate.example.com:9031//.well-know ```shell curl https://auth.pingone.com//as/.well-known/openid-configuration | jq ``` - where: + + Where: - the `auth.pingone.com` is your PingOne server address (or your PingFederate server for on-premises) @@ -92,7 +90,6 @@ For PingFederate: `https://pingfederate.example.com:9031//.well-know - the `jq` command (optional) is used to format the JSON output for easier reading and requires the [jq](https://jqlang.github.io/jq/) JSON processor to be installed. - The configuration metadata is returned in the JSON format: ```json @@ -112,7 +109,6 @@ For PingFederate: `https://pingfederate.example.com:9031//.well-know {{< call-out "note" >}} You will need the values of **Client ID**, **Client Secret**, and **Issuer** in the next steps. {{< /call-out >}} - ## Set up NGINX Plus {#nginx-plus-setup} With PingOne or PingFederate configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as the Rely Party (RP) application — a client service that verifies user identity. @@ -122,6 +118,7 @@ With PingOne or PingFederate configured, you can enable OIDC on NGINX Plus. NGIN ```shell nginx -v ``` + The output should match NGINX Plus Release 35 or later: ```none @@ -182,8 +179,7 @@ With PingOne or PingFederate configured, you can enable OIDC on NGINX Plus. NGIN - If the **userinfo** directive is set to `on`, NGINX Plus will fetch userinfo from Ping Identity and append the claims from userinfo to the `$oidc_claims_` variables. - - **Important:** All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system's CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP's certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP's certificate. - + - {{< call-out "important" >}} All interaction with the IdP is secured exclusively over SSL/TLS, so NGINX must trust the certificate presented by the IdP. By default, this trust is validated against your system’s CA bundle (the default CA store for your Linux or FreeBSD distribution). If the IdP’s certificate is not included in the system CA bundle, you can explicitly specify a trusted certificate or chain with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) directive so that NGINX can validate and trust the IdP’s certificate. {{< /call-out >}} ```nginx http { @@ -292,7 +288,9 @@ With PingOne or PingFederate configured, you can enable OIDC on NGINX Plus. NGIN } } ``` + 12. Save the NGINX configuration file and reload the configuration: + ```nginx nginx -s reload ``` @@ -371,19 +369,16 @@ http { 4. Refresh `https://demo.example.com/` again. You should be redirected to Ping Identity for a fresh sign‑in, proving the session has been terminated. - ## Legacy njs-based Ping Identity Solution {#legacy-njs-guide} If you are running NGINX Plus R33 and earlier or if you still need the njs-based solution, refer to the [Legacy njs-based Ping Identity Guide]({{< ref "nginx/deployment-guides/single-sign-on/oidc-njs/ping-identity.md" >}}) for details. The solution uses the [`nginx-openid-connect`](https://github.com/nginxinc/nginx-openid-connect) GitHub repository and NGINX JavaScript files. - ## See Also - [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) - [Release Notes for NGINX Plus R35]({{< ref "nginx/releases.md#r35" >}}) - ## Revision History - Version 2 (August 2025) – Added RP‑initiated logout (logout_uri, post_logout_uri, logout_token_hint) and userinfo support. diff --git a/content/nic/configuration/policy-resource.md b/content/nic/configuration/policy-resource.md index 4aa16457a..c073f7871 100644 --- a/content/nic/configuration/policy-resource.md +++ b/content/nic/configuration/policy-resource.md @@ -33,6 +33,7 @@ spec: ``` {{% table %}} + |Field | Description | Type | Required | | ---| ---| ---| --- | |``accessControl`` | The access control policy based on the client IP address. | [accessControl](#accesscontrol) | No | @@ -69,6 +70,7 @@ accessControl: deny: - 10.0.0.0/8 ``` + {{< call-out "note" >}} The feature is implemented using the NGINX [ngx_http_access_module](http://nginx.org/en/docs/http/ngx_http_access_module.html). NGINX Ingress Controller access control policy supports either allow or deny rules, but not both (as the module does). @@ -76,10 +78,12 @@ The feature is implemented using the NGINX [ngx_http_access_module](http://nginx {{< /call-out >}} {{% table %}} + |Field | Description | Type | Required | | ---| ---| ---| --- | |``allow`` | Allows access for the specified networks or addresses. For example, ``192.168.1.1`` or ``10.1.1.0/16``. | ``[]string`` | No | |``deny`` | Denies access for the specified networks or addresses. For example, ``192.168.1.1`` or ``10.1.1.0/16``. | ``[]string`` | No | \* an accessControl must include either `allow` or `deny`. | + {{% /table %}} #### AccessControl Merging Behavior @@ -115,6 +119,7 @@ rateLimit: zoneSize: 10M key: ${binary_remote_addr} ``` + {{< call-out "note" >}} The feature is implemented using the NGINX [ngx_http_limit_req_module](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html). @@ -128,6 +133,7 @@ When the [Zone Sync feature]({{< ref "/nic/configuration/global-configuration/co {{< /call-out >}} {{% table %}} + |Field | Description | Type | Required | | ---| ---| ---| --- | |``rate`` | The rate of requests permitted. The rate is specified in requests per second (r/s) or requests per minute (r/m). | ``string`` | Yes | @@ -141,6 +147,7 @@ When the [Zone Sync feature]({{< ref "/nic/configuration/global-configuration/co |``rejectCode`` | Sets the status code to return in response to rejected requests. Must fall into the range ``400..599``. Default is ``503``. | ``int`` | No | |``scale`` | Enables a constant rate-limit by dividing the configured rate by the number of nginx-ingress pods currently serving traffic. This adjustment ensures that the rate-limit remains consistent, even as the number of nginx-pods fluctuates due to autoscaling. **This will not work properly if requests from a client are not evenly distributed across all ingress pods** (Such as with sticky sessions, long lived TCP Connections with many requests, and so forth). In such cases using [zone-sync]({{< ref "/nic/configuration/global-configuration/configmap-resource.md#zone-sync" >}}) instead would give better results. Enabling `zone-sync` will suppress this setting. | ``bool`` | No | |``condition`` | Add a condition to a rate-limit policy. | [ratelimit.condition](#ratelimitcondition) | No | + {{% /table %}} {{< call-out "note" >}} @@ -174,11 +181,13 @@ condition: ``` {{% table %}} + |Field | Description | Type | Required | | ---| ---| ---| --- | |``jwt`` | defines a JWT condition to rate limit against. | [ratelimit.condition.jwt](#ratelimitconditionjwt) | No | |``variables`` | defines a Variable condition to rate limit against. | [ratelimit.condition.variables](#ratelimitconditionvariables) | No | |``default`` | sets the rate limit in this policy to be the default if no conditions are met. In a group of policies with the same condition, only one policy can be the default. | ``bool`` | No | + {{% /table %}} {{< call-out "note" >}} @@ -189,6 +198,7 @@ If conditions are used, a request doesn't match any, and a `default` has been de The rate limit policy with condition is designed to be used in combination with one or more rate limit policies. For example, multiple rate limit policies with [RateLimit.Condition.JWT](#ratelimitconditionjwt) can be used to apply different tiers of rate limit based on the value of a JWT claim. For a practical example of tiered rate limiting by the value of a JWT claim, see the example in our [GitHub repository](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources/rate-limit-tiered-jwt-claim/README.md). ### RateLimit.Condition.JWT + {{< call-out "note" >}} This feature is only available with NGINX Plus. @@ -215,10 +225,12 @@ The rate limit policy will only apply to requests that contain a JWT with the sp ``` {{% table %}} + |Field | Description | Type | Required | | ---| ---| ---| --- | |``claim`` | Claim is the JWT claim to be rate limit by. Nested claims should be separated by ".". | ``string`` | Yes | |``match`` | the value of the claim to match against. | ``string`` | Yes | + {{% /table %}} ### RateLimit.Condition.Variables @@ -236,10 +248,12 @@ Only one variable at a time is supported at present. {{< /call-out >}} {{% table %}} + |Field | Description | Type | Required | | ---| ---| ---| --- | |``name`` | the name of the NGINX variable to be rate limit by. | ``string`` | Yes | |``match`` | the value of the NGINX variable to match against. Values prefixed with the `~` character denote the following is a [regular expression](https://nginx.org/en/docs/http/ngx_http_map_module.html#map). | ``string`` | Yes | + {{% /table %}} ### APIKey @@ -281,12 +295,14 @@ data: ``` {{% table %}} + |Field | Description | Type | Required | | ---| ---| ---| --- | |``suppliedIn`` | `header` or `query`. | | Yes | |``suppliedIn.header`` | An array of headers that the API Key may appear in. | ``string[]`` | No | |``suppliedIn.query`` | An array of query params that the API Key may appear in. | ``string[]`` | No | |``clientSecret`` | The name of the Kubernetes secret that stores the API Key(s). It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/apikey``, and the API Key(s) must be stored in a key: val format where each key is a unique clientID and each value is a unique base64 encoded API Key | ``string`` | Yes | + {{% /table %}} {{< call-out "important" >}}An APIKey Policy must include a minimum of one of the `suppliedIn.header` or `suppliedIn.query` parameters. Both can also be supplied.{{< /call-out >}} @@ -335,15 +351,18 @@ basicAuth: secret: htpasswd-secret realm: "My API" ``` + {{< call-out "note" >}} The feature is implemented using the NGINX [ngx_http_auth_basic_module](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html). {{< /call-out >}} {{% table %}} + |Field | Description | Type | Required | | ---| ---| ---| --- | |``secret`` | The name of the Kubernetes secret that stores the Htpasswd configuration. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/htpasswd``, and the config must be stored in the secret under the key ``htpasswd``, otherwise the secret will be rejected as invalid. | ``string`` | Yes | |``realm`` | The realm for the basic authentication. | ``string`` | No | + {{% /table %}} #### BasicAuth Merging Behavior @@ -402,11 +421,13 @@ This feature is implemented using the NGINX Plus [ngx_http_auth_jwt_module](http {{< /call-out >}} {{% table %}} + |Field | Description | Type | Required | | ---| ---| ---| --- | |``secret`` | The name of the Kubernetes secret that stores the JWK. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/jwk``, and the JWK must be stored in the secret under the key ``jwk``, otherwise the secret will be rejected as invalid. | ``string`` | Yes | |``realm`` | The realm of the JWT. | ``string`` | Yes | |``token`` | The token specifies a variable that contains the JSON Web Token. By default the JWT is passed in the ``Authorization`` header as a Bearer Token. JWT may be also passed as a cookie or a part of a query string, for example: ``$cookie_auth_token``. Accepted variables are ``$http_``, ``$arg_``, ``$cookie_``. | ``string`` | No | + {{% /table %}} #### JWT Merging Behavior @@ -448,6 +469,7 @@ This feature is implemented using the NGINX Plus directive [auth_jwt_key_request {{< /call-out >}} {{% table %}} + |Field | Description | Type | Required | Default | | ---| ---| ---| --- | --- | |``jwksURI`` | The remote URI where the request will be sent to retrieve JSON Web Key set| ``string`` | Yes | -- | @@ -456,6 +478,7 @@ This feature is implemented using the NGINX Plus directive [auth_jwt_key_request |``token`` | The token specifies a variable that contains the JSON Web Token. By default the JWT is passed in the ``Authorization`` header as a Bearer Token. JWT may be also passed as a cookie or a part of a query string, for example: ``$cookie_auth_token``. Accepted variables are ``$http_``, ``$arg_``, ``$cookie_``. | ``string`` | No | -- | |``sniEnabled`` | Enables SNI (Server Name Indication) for the JWT policy. This is useful when the remote server requires SNI to serve the correct certificate. | ``bool`` | No | `false` | |``sniName`` | The SNI name to use when connecting to the remote server. If not set, the hostname from the ``jwksURI`` will be used. | ``string`` | No | -- | + {{% /table %}} {{< call-out "note" >}} @@ -582,7 +605,7 @@ ingressMTLS: verifyDepth: 1 ``` -**IMPORTANT NOTE** +{{< call-out "important" >}} When configuring a CRL with the `ingressMTLS.crlFileName` field, there is additional context to keep in mind: 1. NGINX Ingress Controller will expect the CRL, in this case `webapp.crl`, will be in `/etc/nginx/secrets`. A volume mount will need to be added to NGINX Ingress Controller deployment add your CRL to `/etc/nginx/secrets` @@ -590,13 +613,17 @@ When configuring a CRL with the `ingressMTLS.crlFileName` field, there is additi Please refer to the Kubernetes documentation on [volumes](https://kubernetes.io/docs/concepts/storage/volumes/) to find the best implementation for your environment. +{{< /call-out >}} + {{% table %}} + |Field | Description | Type | Required | | ---| ---| ---| --- | |``clientCertSecret`` | The name of the Kubernetes secret that stores the CA certificate. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/ca``, and the certificate must be stored in the secret under the key ``ca.crt``, otherwise the secret will be rejected as invalid. | ``string`` | Yes | |``verifyClient`` | Verification for the client. Possible values are ``"on"``, ``"off"``, ``"optional"``, ``"optional_no_ca"``. The default is ``"on"``. | ``string`` | No | |``verifyDepth`` | Sets the verification depth in the client certificates chain. The default is ``1``. | ``int`` | No | |``crlFileName`` | The file name of the Certificate Revocation List. NGINX Ingress Controller will look for this file in `/etc/nginx/secrets` | ``string`` | No | + {{% /table %}} #### IngressMTLS Merging Behavior @@ -632,6 +659,7 @@ The feature is implemented using the NGINX [ngx_http_proxy_module](https://nginx {{< /call-out >}} {{% table %}} + |Field | Description | Type | Required | | ---| ---| ---| --- | |``tlsSecret`` | The name of the Kubernetes secret that stores the TLS certificate and key. It must be in the same namespace as the Policy resource. The secret must be of the type ``kubernetes.io/tls``, the certificate must be stored in the secret under the key ``tls.crt``, and the key must be stored under the key ``tls.key``, otherwise the secret will be rejected as invalid. | ``string`` | No | @@ -643,6 +671,7 @@ The feature is implemented using the NGINX [ngx_http_proxy_module](https://nginx |``sslName`` | Allows overriding the server name used to verify the certificate of the upstream HTTPS server. | ``string`` | No | |``ciphers`` | Specifies the enabled ciphers for requests to an upstream HTTPS server. The default is ``DEFAULT``. | ``string`` | No | |``protocols`` | Specifies the protocols for requests to an upstream HTTPS server. The default is ``TLSv1 TLSv1.1 TLSv1.2``. | ``string`` | No | > Note: the value of ``ciphers`` and ``protocols`` is not validated by NGINX Ingress Controller. As a result, NGINX can fail to reload the configuration. To ensure that the configuration for a VirtualServer/VirtualServerRoute that references the policy was successfully applied, check its [status]({{< ref "/nic/configuration/global-configuration/reporting-resources-status.md#virtualserver-and-virtualserverroute-resources" >}}). The validation will be added in the future releases. | + {{% /table %}} #### EgressMTLS Merging Behavior @@ -707,6 +736,7 @@ The configuration in the example doesn't enable TLS and the synchronization betw The OIDC policy defines a few internal locations that can't be customized: `/_jwks_uri`, `/_token`, `/_refresh`, `/_id_token_validation`, `/logout`. In addition, as explained below, `/_codexch` is the default value for redirect URI, and `/_logout` is the default value for post logout redirect URI, both of which can be customized. Specifying one of these locations as a route in the VirtualServer or VirtualServerRoute will result in a collision and NGINX Plus will fail to reload. {{% table %}} + |Field | Description | Type | Required | | ---| ---| ---| --- | |``clientID`` | The client ID provided by your OpenID Connect provider. | ``string`` | Yes | @@ -722,6 +752,7 @@ The OIDC policy defines a few internal locations that can't be customized: `/_jw |``zoneSyncLeeway`` | Specifies the maximum timeout in milliseconds for synchronizing ID/access tokens and shared values between Ingress Controller pods. The default is ``200``. | ``int`` | No | |``accessTokenEnable`` | Option of whether Bearer token is used to authorize NGINX to access protected backend. | ``boolean`` | No | |``pkceEnable`` | Switches Proof Key for Code Exchange on. The OpenID client needs to be in public mode. `clientSecret` is not used in this mode. | ``boolean`` | No | + {{% /table %}} {{< call-out "note" >}} @@ -777,6 +808,7 @@ The feature is implemented using the NGINX [ngx_http_proxy_module](https://nginx {{< /call-out >}} {{% table %}} + |Field | Description | Type | Required | | --- | ---| ---| --- | | ``cacheZoneName`` | CacheZoneName defines the name of the cache zone. Must start with a lowercase letter,followed by alphanumeric characters or underscores, and end with an alphanumeric character. Single lowercase letters are also allowed. Examples: "cache", "my_cache", "cache1". | ``string`` | Yes | @@ -787,6 +819,7 @@ The feature is implemented using the NGINX [ngx_http_proxy_module](https://nginx |``levels`` | Levels defines the cache directory hierarchy levels for storing cached files. Must be in format "X:Y" or "X:Y:Z" where X, Y, Z are either 1 or 2. This controls the number of subdirectory levels and their name lengths. Examples: "1:2", "2:2", "1:2:2". Invalid: "3:1", "1:3", "1:2:3". | ``string`` | No | |``overrideUpstreamCache`` | OverrideUpstreamCache controls whether to override upstream cache headers (using proxy_ignore_headers directive). When true, NGINX will ignore cache-related headers from upstream servers like Cache-Control, Expires etc, Default: false. | ``bool`` | No | |``cachePurgeAllow`` | CachePurgeAllow defines IP addresses or CIDR blocks allowed to purge cache. This feature is only available in NGINX Plus. Examples: ["192.168.1.100", "10.0.0.0/8", "::1"]. | ``[]string`` | No | + {{% /table %}} #### Cache Merging Behavior @@ -817,6 +850,7 @@ waf: {{< call-out "note" >}} The field `waf.securityLog` is deprecated and will be removed in future releases. It will be ignored if `waf.securityLogs` is populated. {{< /call-out >}} {{% table %}} + |Field | Description | Type | Required | | ---| ---| ---| --- | |``enable`` | Enables F5 WAF for NGINX. | ``bool`` | Yes | @@ -827,11 +861,13 @@ waf: |``securityLog.apLogBundle`` | **Deprecated:** The [F5 WAF for NGINX log bundle]({{< ref "/nic/installation/integrations/app-protect-waf/configuration.md#waf-bundles" >}}) resource. Only works with ``apBundle``. | ``string`` | No | |``securityLog.logDest`` | **Deprecated:** The log destination for the security log. Only accepted variables are ``syslog:server=; localhost; :``, ``stderr``, ````. | ``string`` | No | |``securityLogs`` | Config for security log destinations. | [waf.securityLogs](#wafsecurityLogs) | No | + {{% /table %}} #### WAF.SecurityLogs {{% table %}} + |Field | Description | Type | Required | | ---| ---| ---| --- | |``enable`` | Enables security log. | ``bool`` | No | diff --git a/content/nim/admin-guide/authentication/oidc/getting-started.md b/content/nim/admin-guide/authentication/oidc/getting-started.md index 15796d1d2..a51cc25e0 100644 --- a/content/nim/admin-guide/authentication/oidc/getting-started.md +++ b/content/nim/admin-guide/authentication/oidc/getting-started.md @@ -1,11 +1,10 @@ --- -description: '' -nd-docs: DOCS-1267 title: Get started with OIDC toc: true weight: 1 -type: -- tutorial +nd-content-type: how-to +nd-product: NIM +nd-docs: DOCS-1267 --- ## Overview @@ -25,7 +24,7 @@ When using OIDC for authentication, administrators don't need to create and mana To grant users access using OIDC, follow these steps: 1. Create a role in NGINX Instance Manager. -2. Create a user group and assign a role to it. **Important**: The group name must exactly match a group name in your IdP. +2. Create a user group and assign a role to it. **The group name must exactly match a group name in your IdP**. 3. Set up OIDC. ### Create a role {#create-role} @@ -96,7 +95,6 @@ The sections below provide detailed descriptions of the OIDC configuration value For custom settings, adjust parameters such as `$oidc_authz_path_params_enable`, `$oidc_logout_query_params`, and others to match your IdP’s needs. - ## Set up specific IdPs for OIDC {#oidc-specific-idps} For specific IdP setup instructions, refer to the following: diff --git a/content/nim/disconnected/add-license-disconnected-deployment.md b/content/nim/disconnected/add-license-disconnected-deployment.md index 66c2d60ed..8434babf7 100644 --- a/content/nim/disconnected/add-license-disconnected-deployment.md +++ b/content/nim/disconnected/add-license-disconnected-deployment.md @@ -1,17 +1,10 @@ --- title: Add a license (disconnected) -draft: false -description: '' weight: 200 toc: true +nd-content-type: how-to +nd-product: NIM nd-docs: DOCS-1657 -personas: -- devops -- netops -- secops -- support -type: -- how-to --- ## Overview @@ -20,7 +13,6 @@ This guide shows you how to add a license to NGINX Instance Manager in a disconn {{< call-out "tip" "Using the REST API" "" >}}{{< include "nim/how-to-access-nim-api.md" >}}{{}} - ## Before you begin ### Set the operation mode to disconnected @@ -33,12 +25,8 @@ To configure NGINX Instance Manager for a disconnected environment, you need to {{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}} - -
- ## Add license and submit initial usage report {#add-license-submit-initial-usage-report} - {{< tabs name="submit-usage-report" >}} {{%tab name="Bash script (recommended)"%}} @@ -47,9 +35,7 @@ To configure NGINX Instance Manager for a disconnected environment, you need to To add a license and submit the initial usage report in a disconnected environment, use the provided `license_usage_offline.sh` script. Run this script on a system that can access NGINX Instance Manager and connect to `https://product.apis.f5.com/` on port `443`. Replace each placeholder with your specific values. -**Important**: The script to add a license won't work if a license has already been added. - -
+{{< call-out "important" >}} The script to add a license won't work if a license has already been added. {{< /call-out >}} 1. {{}}[Download license_usage_offline.sh](/scripts/license_usage_offline.sh). 1. Run the following command to allow the script to run: @@ -81,7 +67,7 @@ To add a license and submit the initial usage report in a disconnected environme To license NGINX Instance Manager, complete each of the following steps in order. -**Important**: The `curl` command to add a license won't work if a license has already been added. +{{< call-out "important" >}} The `curl` command to add a license won't work if a license has already been added. {{< /call-out >}} Run these `curl` commands on a system that can access NGINX Instance Manager and connect to `https://product.apis.f5.com/` on port `443`. Replace each placeholder with your specific values. @@ -218,7 +204,6 @@ Download the initial usage report to send to F5: - On the **License > Overview** page, select **Download License Report**. - #### Submit usage report to F5 You need to submit the usage report to F5 and download the acknowledgment over REST. To do so, follow steps 5–7 in the [**REST**](#add-license-submit-initial-usage-report) tab in this section. @@ -233,5 +218,4 @@ To upload the usage acknowledgement: {{%/tab%}} - -{{}} +{{}} \ No newline at end of file diff --git a/documentation/README.md b/documentation/README.md index d7414d222..6f8ea81ad 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -13,6 +13,7 @@ If you're interested in contributing to the [NGINX documentation website](https: ## Content workflows - [Set up pre-commit](/documentation/pre-commit.md) +- [Linting tools](/documentation/linting-tools.md) - [Git conventions](/documentation/git-conventions.md) - [Managing content with Hugo](/documentation/hugo-content.md) - [Using include files](/documentation/include-files.md) @@ -25,6 +26,6 @@ If you're interested in contributing to the [NGINX documentation website](https: # Ways of working -- [Maintainers etiquette](/documentation/maintainers-etiquette.md) - [Preparing a good issue](/documentation/prepare-issue.md) +- [Maintainers etiquette](/documentation/maintainers-etiquette.md) - [Proposals](/documentation/proposals/README.md) diff --git a/documentation/hugo-content.md b/documentation/hugo-content.md index 36b37f6b5..c00b69352 100644 --- a/documentation/hugo-content.md +++ b/documentation/hugo-content.md @@ -97,7 +97,7 @@ This is an example of a call-out shortcode: Here are some other shortcodes: -- `include`: Include the content of a file in another file: read the [Re-use content with includes](#re-use-content-with-includes) instructions +- `include`: Include the content of a file in another file: read the [Using include files](/documentation/include-files.md) topic - `tabs`: Create mutually exclusive tabbed window panes, useful for parallel instructions - `table`: Add scrollbars to wide tables for browsers with smaller viewports - `icon`: Add a [Lucide icon](https://lucide.dev/icons/) by using its name as a parameter @@ -120,6 +120,7 @@ If you do, and things break, don't say we didn't warn you. The first parameter determines the type of call-out, which defines the colour given to it. Supported types: + - `note` - `tip` - `important` @@ -150,35 +151,14 @@ You can also use the `ghcode` shortcode to embed a single file directly from Git An example of this can be seen in [/content/ngf/get-started.md](https://github.com/nginx/documentation/blob/af8a62b15f86a7b7be7944b7a79f44fd5e526c15/content/ngf/get-started.md?plain=1#L233C1-L233C128), which embeds a YAML file. -#### Re-use content with includes - -The includes are a custom shortcode that allows you to embed content stored in the [`/content/includes` directory](https://github.com/nginx/documentation/tree/main/content/includes). - -It allows for content to be defined once and display in multiple places without duplication, creating consistency and simplifying the maintenance of items such as reference tables. - -For example, the [`licensing-and-reporting/apply-jwt.md`](https://github.com/nginx/documentation/blob/main/content/includes/licensing-and-reporting/apply-jwt.md) file contains instructions for where to add a JWT license file to an NGINX instance. - -To add it to a documentation page, use the path as a parameter for the `include` shortcode: - -```md -{{< include "licensing-and-reporting/apply-jwt.md" >}} -``` - -This particular include file is used in the following pages: - -- [About subscription licenses](https://github.com/nginx/documentation/blob/77939c1f9f41ae1984ddfc43c65c3b743836057a/content/solutions/about-subscription-licenses.md?plain=1#L54) -- [R33 pre-release guidance for automatic upgrades](https://github.com/nginx/documentation/blob/77939c1f9f41ae1984ddfc43c65c3b743836057a/content/solutions/r33-pre-release-guidance-for-automatic-upgrades.md?plain=1#L62) -- [Installing F5 WAF for NGINX](https://github.com/nginx/documentation/blob/77939c1f9f41ae1984ddfc43c65c3b743836057a/content/nap-waf/v5/admin-guide/install.md?plain=1#L132) - -View the [Guidelines for includes](/templates/style-guide.md#guidelines-for-includes) for instructions on how to write effective include files. - #### Add images to documentation pages +> [!IMPORTANT] +> We have strict guidelines for using images. Review them in our [style guide](/documentation/style-guide.md#guidelines-for-screenshots). + Use the `img` shortcode to add images to documentation pages. It has the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure). 1. Add the image to the `/static/img` directory. -2. Add the `img` shortcode: - - `{{< img src="" alt="">}}` - - Do not include a forward slash at the beginning of the file path or it will [break the image](https://gohugo.io/functions/relurl/#input-begins-with-a-slash). +2. Add the `img` shortcode: `{{< img src="" alt="">}}` -> **Important**: We have strict guidelines for using images. Review them in our [style guide](/documentation/style-guide.md#guidelines-for-screenshots). +Do not include a forward slash at the beginning of the file path or it will [break the image](https://gohugo.io/functions/relurl/#input-begins-with-a-slash). diff --git a/documentation/include-files.md b/documentation/include-files.md index 8a69d7be6..4fd95286e 100644 --- a/documentation/include-files.md +++ b/documentation/include-files.md @@ -1,4 +1,4 @@ -# Using Include files +# Using include files _Include files_, often referred to as _includes_, are Markdown files with self-contained text fragments used by Hugo for content re-use. @@ -8,7 +8,7 @@ We use them to [avoid repeating ourselves](https://en.wikipedia.org/wiki/Don%27t Include files are designed to be context-agnostic and should not rely on or assume any prior content. -The files are located in the [content/includes](https://github.com/nginxinc/docs/tree/main/content/includes) folder, and are implemented using the Hugo `include` shortcode: +The files are located in the [content/includes](https://github.com/nginx/documentation/tree/main/content/includes) folder, and are implemented using the Hugo `include` shortcode: ```text {{< include "use-cases/docker-registry-instructions.md" >}} @@ -29,18 +29,8 @@ To make sure includes are effective and easy to maintain, follow these guideline - **Don't start documents with includes**: The opening of most documents is the introduction which explains its purpose. Includes are reused text, so starting multiple documents with identical content could look odd, especially in search results. - **Do not add the F5 prefix to product names in includes**: The brand name is required only on [the first mention in a document](/documentation/style-guide.md#f5-brand-trademarks-and-product-names). -## Include file index +## Understanding include file usage -To aid in discoverability of include files, see the [include section](https://docs.nginx.com/stats#include) of our [shortcode report page](https://docs.nginx.com/stats). -This page is updated as part of every documentation build. +To view how include files are being used, see the [include section](https://docs.nginx.com/stats#include) of the shortcode report page. -When viewing an include file, you may also see the `files`: parameter in the frontmatter, which shows where the file is currently in use. - -Examples of commonly used includes: - -| **_File name_** | **_Description_** | -| ----------------| ------------------ | -| [_licensing-and-reporting/download-jwt-from-myf5.md_](/content/includes/licensing-and-reporting/download-jwt-from-myf5.md) | Instructions for downloading a JSON Web Token from MyF5 | -| [_licensing-and-reporting/download-certificates-from-myf5.md_](/content/includes/licensing-and-reporting/download-certificates-from-myf5.md) | Instructions for downloading certificate files from MyF5 | -| [_use-cases/credential-download-instructions.md_](/content/includes/use-cases/credential-download-instructions.md) | Parallel tabbed instructions for downloading credential files from MyF5 | -| [_use-cases/docker-registry-instructions.md_](/content/includes/use-cases/docker-registry-instructions.md) | Parallel tabbed instructions for listing Docker images from the F5 Registry | +This page is updated as part of every documentation build. It shows how often certain shortcodes are used and where, including specific include files. \ No newline at end of file