diff --git a/content/nginx/admin-guide/dynamic-modules/opentracing.md b/content/nginx/admin-guide/dynamic-modules/opentracing.md index dd89c65e1..4b609050f 100644 --- a/content/nginx/admin-guide/dynamic-modules/opentracing.md +++ b/content/nginx/admin-guide/dynamic-modules/opentracing.md @@ -12,13 +12,13 @@ type: - how-to --- -{{< note >}} The module is deprecated since F5 NGINX Plus Release 32. The [OpenTelemetry]({{< ref "opentelemetry.md" >}}) module is available since NGINX Plus Release 29 that incorporates the features of the OpenTracing module.{{< /note >}} +{{< note >}} The module no longer available since F5 NGINX Plus [Release 34]({{< ref "nginx/releases.md#r34" >}}). The [OpenTelemetry]({{< ref "nginx/admin-guide/dynamic-modules/opentelemetry.md" >}}) module is available since NGINX Plus [Release 29]({{< ref "nginx/releases.md#r29" >}}) that incorporates the features of the OpenTracing module.{{< /note >}} ## Installation -1. Check the [Technical Specifications]({{< relref "../../technical-specs.md" >}}) page to verify that the module is supported by your operating system. +1. Check the [Technical Specifications]({{< ref "nginx/technical-specs.md" >}}) page to verify that the module is supported by your operating system. 2. Install the OpenTracing module package `nginx-plus-module-opentracing`. @@ -89,6 +89,6 @@ After installation you will need to enable and configure the module in NGINX Plu - [NGINX plugin for OpenTracing Reference](https://github.com/opentracing-contrib/nginx-opentracing) -- [NGINX Dynamic Modules]({{< ref "dynamic-modules.md" >}}) +- [NGINX Dynamic Modules]({{< ref "nginx/admin-guide/dynamic-modules/dynamic-modules.md" >}}) -- [NGINX Plus Technical Specifications]({{< relref "../../technical-specs.md" >}}) +- [NGINX Plus Technical Specifications]({{< ref "nginx/technical-specs.md" >}}) diff --git a/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md b/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md index 8b5d30c99..13c64f54c 100644 --- a/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md +++ b/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md @@ -78,46 +78,6 @@ This article explains how to install NGINX Plus on different operating systems, 1. {{< include "nginx-plus/install/install-nginx-agent-for-nim.md" >}} -## Install NGINX Plus on RHEL 7.4+, CentOS 7.4+, and Oracle Linux 7.4+ {#install_rhel_centos} - -{{< call-out "important" "Deprecation notice" "" >}} -CentOS 7.4, RHEL 7.4, and Oracle Linux 7.4 are deprecated as of NGINX Plus Release 32 (R32) and are not supported in Release 33 (R33) or later. For the list of supported distributions, refer to the [NGINX Plus Tech Specs]({{< ref "nginx/technical-specs.md" >}}). -{{}} - -1. {{< include "nginx-plus/install/back-up-config-and-logs.md" >}} - -1. Download the SSL certificate and private key associated with your NGINX Plus subscription from the MyF5 Customer Portal: - - - Log in to [MyF5](https://my.f5.com/manage/s/). - - Go to **My Products & Plans > Subscriptions** to see your active subscriptions. - - Find your NGINX products or services subscription, and select the **Subscription ID** for details. - - Download the **nginx-repo.crt** and **nginx-repo.key** from the subscription page. - -1. {{< include "nginx-plus/install/install-ca-certificates-dependency-yum.md" >}} - -1. {{< include "nginx-plus/install/create-dir-for-crt-key.md" >}} - -1. {{< include "nginx-plus/install/copy-crt-and-key.md" >}} - -1. Add the NGINX Plus repository by downloading the [nginx-plus-7.4.repo](https://cs.nginx.com/static/files/nginx-plus-7.4.repo) file to **/etc/yum.repos.d**: - - ```shell - sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.4.repo - ``` - -
- Learn how to pin NGINX Plus to a specific version - {{}}{{< include "nginx-plus/install/pin-to-version/pin-rhel7-R32.md" >}}{{}} -
- -1. {{< include "nginx-plus/install/install-nginx-plus-package-yum.md" >}} - -1. {{< include "nginx-plus/install/enable-nginx-service-at-boot.md" >}} - -1. {{< include "nginx-plus/install/check-nginx-binary-version.md" >}} - -1. {{< include "nginx-plus/install/install-nginx-agent-for-nim.md" >}} - ## Install NGINX Plus on RHEL 8.1+, Oracle Linux 8.1+, AlmaLinux 8, Rocky Linux 8 {#install_rhel8} 1. {{< include "nginx-plus/install/check-tech-specs.md" >}} @@ -546,10 +506,10 @@ For a community dynamic module to work with NGINX Plus, it must be compiled alo - Identify the NGINX Open Source version that corresponds to your version of NGINX Plus. See [NGINX Plus Releases]({{< ref "nginx/releases.md" >}}). - - Download the sources for the appropriate NGINX Open Source mainline version, in this case 1.27.2: + - Download the sources for the appropriate NGINX Open Source mainline version, in this case 1.27.4: ```shell - wget -qO - https://nginx.org/download/nginx-1.27.2.tar.gz | tar zxfv - + wget -qO - https://nginx.org/download/nginx-1.27.4.tar.gz | tar zxfv - ``` 1. Obtain the source for the dynamic module. @@ -565,7 +525,7 @@ For a community dynamic module to work with NGINX Plus, it must be compiled alo First establish binary compatibility by running the `configure` script with the `‑‑with‑compat` option. Then compile the module with `make modules`. ```shell - cd nginx-1.27.2/ + cd nginx-1.27.4/ ./configure --with-compat --add-dynamic-module=../ make modules ``` @@ -580,7 +540,7 @@ For a community dynamic module to work with NGINX Plus, it must be compiled alo 1. Make a copy of the module file and include the NGINX Open Source version in the filename. This makes it simpler to manage multiple versions of a dynamic module in the production environment. ```shell - cp objs/ngx_http_hello_world.so ./ngx_http_hello_world_1.27.2.so + cp objs/ngx_http_hello_world.so ./ngx_http_hello_world_1.27.4.so ``` ### Enabling Dynamic Modules {#enable_dynamic} @@ -886,7 +846,7 @@ To upgrade your NGINX Plus installation to the newest version: The output of the command: ```shell - nginx version: nginx/1.27.2 (nginx-plus-r33) + nginx version: nginx/1.27.4 (nginx-plus-r34) ``` ## Upgrade NGINX Plus Modules {#upgrade_modules} diff --git a/content/nginx/admin-guide/security-controls/configuring-oidc.md b/content/nginx/admin-guide/security-controls/configuring-oidc.md new file mode 100644 index 000000000..c9b4e2628 --- /dev/null +++ b/content/nginx/admin-guide/security-controls/configuring-oidc.md @@ -0,0 +1,356 @@ +--- +description: Enable OpenID Connect-based single sign-on (SSO) for applications proxied by NGINX Plus, using an Identity Provider (IdP). +type: +- task +title: Single Sign-On with OpenID Connect and Identity Providers +toc: true +weight: 550 +product: NGINX-PLUS +--- + +This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus using: +- OpenID Connect as the authentication mechanism. +- An external Identity Provider (IdP) such as AD FS, Auth0, Cognito, Entra ID, Keycloak, OneLogin, Okta, Ping Identity and others. +- NGINX Plus as an OIDC client application that verifies user identity (Relying Party). + +OpenID Connect is an identity protocol that utilizes the authorization and authentication mechanisms of OAuth 2.0. With it, NGINX Plus can provide a layer of authentication for protected applications that do not natively support it. + +NGINX Plus consumes authorization and claims from OpenID Connect Identity Providers by utilizing JWT-based identity tokens that are delivered via the OAuth 2.0 framework. It supports several specific flows suitable for browser-based and desktop/mobile applications. OpenID Connect allows the client (NGINX Plus) to retrieve an ID token in addition to an access token. The ID token provides information about the authenticated user. + +For the target client application, OIDC authentication can be enabled with great flexibility on different levels. It can be enabled globally, or more granular at a per-server or a per-location level. Additionally, OIDC supports auto discovery and retrieval of the OpenID provider configuration metadata while also allowing the definition of additional metadata if needed. + + +## OpenID Connect Workflow and NGINX Plus {#oidc-workflow} + +1. A user accesses a protected resource. + +2. NGINX Plus redirects the user to the IdP for user authentication and authorization. + +3. The IdP collects user credentials and authenticates the user. + +4. The IdP redirects the user back to NGINX Plus with an authorization code. + +5. NGINX Plus retrieves an `id_token` and access token using the authorization code from the IdP. + +6. NGINX Plus validates the `id_token` and retrieves profile data for the user using the `UserInfo` endpoint. The retrieved profile data is validated and the content of the `id_token` and the profile data is used for providing access control to the client application. + +7. Upon successful validation, the resource access request is sent to the client application along with the access token. + +8. The client application validates the access token and based on the token validation, the resource access request is allowed or denied. + + +{{< img src="nginx/images/oidc.png">}} + + + +## Tested Identity Providers {#deployment-guildes} + + NGINX Plus has tested support with the following Identity Providers: + +{{}} +| IdP Provider | Resource | +|-----------------|-------------------------------------------------------------------------------------------------------------| +| Amazon Cognito | [Deployment Guide for Amazon Cognito]({{< ref "nginx/deployment-guides/single-sign-on/cognito.md" >}}) | +| Auth0 | [Deployment Guide for Auth0]({{< ref "nginx/deployment-guides/single-sign-on/auth0.md" >}}) | +| Microsoft AD FS | [Deployment Guide for AD FS]({{< ref "nginx/deployment-guides/single-sign-on/active-directory-federation-services.md" >}}) | +| Microsoft Entra / Azure ID| [Deployment Guide for Entra ID]({{< ref "nginx/deployment-guides/single-sign-on/entra-id.md" >}}) | +| Keycloak | [Deployment Guide for Keycloak]({{< ref "nginx/deployment-guides/single-sign-on/keycloak.md" >}}) | +| OneLogin | [Deployment Guide for OneLogin]({{< ref "nginx/deployment-guides/single-sign-on/onelogin.md" >}}) | +| Okta | [Deployment Guide for Okta]({{< ref "nginx/deployment-guides/single-sign-on/okta.md" >}}) | +| Ping Identity | [Deployment Guide for Ping Identity]({{< ref "nginx/deployment-guides/single-sign-on/ping-identity.md" >}}) | +{{}} + + +## Prerequisites {#prerequisites} + +- An identity provider (IdP) set up on your network or in the cloud. You need admin access to the IdP. + +- An [NGINX Plus subscription](https://www.f5.com/products/nginx/nginx-plus) and NGINX Plus [Release 34]({{< ref "nginx/releases.md#r34" >}}) or later. + To install NGINX Plus, follow the steps in [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). + +- A domain name that points to your NGINX Plus instance (for example, `demo.example.com`). + + +## Set up your identity provider (IdP) {#idp-setup} + +The setup steps are similar for most identity providers, but some details may differ. + +1. Log in to your IdP's admin console. + +2. Create a new OpenID Connect (OIDC) application. + + - Give the app a name. + - Add the users or groups who need access. + +3. Find the **Client ID** and **Client Secret** for your app. + You'll need these later when you [set up NGINX Plus as the relying party](#setup-oidc-provider2). + +4. Find the **issuer** value. + + You can find the issuer value in your IdP app settings or at the standard discovery URL: + + `https://your-idp-domain/.well-known/openid-configuration` + + where: + + - the `your-idp-domain` is your IdP's server address + + - the `.well-known/openid-configuration` is the default address for IdPs for the `.well-known` document + + The IdP configuration metadata is returned in the JSON format, for example: + + ```json + { + ... + "issuer": "https://your-idp-domain/idp", + "authorization_endpoint": "https://your-idp-domain/idp/oauth2/authorize/", + "token_endpoint": "https://your-idp-domain/idp/oauth2/token/", + "jwks_uri": "https://your-idp-domain/idp/discovery/keys", + ... + } + ``` + + Copy the **issuer** value. You will need it later when [configuring NGINX Plus as the Relying Party](#setup-oidc-provider2). + + +## Configure the Relying Party (NGINX Plus) {#rp-setup} + +With your IdP configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as the Rely Party (RP) 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 34 or later: + + ```none + nginx version: nginx/1.27.4 (nginx-plus-r34) + ``` + +2. Ensure that you have the values of the **Client ID**, **Client Secret**, and **Issuer** obtained from your IdP Provider. + +3. In your preferred text editor, open the NGINX configuration file (`/etc/nginx/nginx.conf` for Linux or `/usr/local/etc/nginx/nginx.conf` for FreeBSD). + +4. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, make sure your public DNS resolver is specified with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive: By default, NGINX Plus re‑resolves DNS records at the frequency specified by time‑to‑live (TTL) in the record, but you can override the TTL value with the `valid` parameter: + + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + # ... + } + ``` + + +5. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, define the IdP provider named `my_idp` by specifying the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context: + + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider my_idp { + + # ... + + } + # ... + } + ``` + + +6. In the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context, specify: + + - Your actual **Client ID** obtained from your IdP with the [`client_id`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_id) directive + + - Your **Client Secret** obtained from your IdP with the [`client_secret`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive + + - The **Issuer** URL obtained from your IdP with the [`issuer`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive + + By default, NGINX Plus creates the metadata URL by appending the `/.well-known/openid-configuration` part to the Issuer URL. If your Issuer is different, you can explicitly specify the metadata document with the [`config_url`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#config_url) directive. + + - A valid system CA bundle with the [`ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#ssl_trusted_certificate) so that NGINX Plus could validate the IdP TLS certificates: + + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider my_idp { + issuer https://your-idp-domain/idp; + client_id ; + client_secret ; + + ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; + } + + # ... + } + ``` + +7. Make sure you have configured a [server](https://nginx.org/en/docs/http/ngx_http_core_module.html#server) that corresponds to `demo.example.com`, and there is a [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) that [points](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) to your application (see [Step 10](#oidc_app)) at `http://127.0.0.1:8080` that is going to be OIDC-protected: + + ```nginx + http { + # ... + + server { + listen 443 ssl; + server_name demo.example.com; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + # ... + + proxy_pass http://127.0.0.1:8080; + } + } + # ... + } + ``` + +8. Protect this [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) with IdP OIDC by specifying the [`auth_oidc`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#auth_oidc) directive that will point to the `my_idp` configuration specified in the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context in [Step 5](#setup-oidc-provider): + + ```nginx + # ... + location / { + auth_oidc my_idp; + + # ... + + proxy_pass http://127.0.0.1:8080; + + } + # ... + ``` + +9. Pass the OIDC claims as headers to the application ([Step 10](#oidc_app)) with the [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive. These claims are extracted from the ID token returned by the IdP: + + - [`$oidc_claim_sub`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - a unique `Subject` identifier assigned for each user by the IdP + + - [`$oidc_claim_email`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) the e-mail address of the user + + - [`$oidc_claim_name`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - the full name of the user + + - 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 / { + auth_oidc my_idp; + + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + # ... + ``` + +10. 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 + # ... + server { + listen 8080; + + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nIdP sub sub: $http_sub\n"; + default_type text/plain; + } + } + ``` +11. Save the NGINX configuration file and reload the configuration: + ```nginx + nginx -s reload + ``` + +### Complete Example {#example} + +This configuration example summarizes the steps outlined above. It includes only essential settings such as specifying the DNS resolver, defining the OIDC provider, configuring SSL, and proxying requests to an internal server. + +```nginx +http { + # Use a public DNS resolver for Issuer discovery, etc. + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider my_idp { + # The 'issuer' typically matches your IdP's base URL + issuer https:///idp; + + # Provide a CA bundle for certificate validation + ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; + + # Replace with your actual IdP's client_id and secret + client_id ; + client_secret ; + + # If the .well-known endpoint cannot be derived automatically, + # specify config_url: + # config_url https:///auth/realms/main/.well-known/openid-configuration; + } + + server { + listen 443 ssl; + server_name demo.example.com; +x + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + # Protect this location with OIDC + auth_oidc my_idp; + + # Forward OIDC claims as headers if desired + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + } + + server { + # simple test oidc-protected application + listen 8080; + + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nIdP sub: $http_sub\n"; + default_type text/plain; + } + } +} +``` + +### Testing {#testing} + +1. Open https://demo.example.com/ in a browser. You should be redirected to your IdP's login page. + +2. Enter valid IdP credentials for a user assigned to the `nginx-demo-app` client. +Upon successful sign-in, the IdP redirects you back to NGINX Plus, and you will see the proxied application content (for example, “Hello, Jane Doe!”). + + +## Glossary {#glossary} + + +{{}} +| Term | Description | +|-------------------------|----------------------------------------------------| +| Identity Provider (IdP) | A service that authenticates users and verifies their identity for client applications. | +| Protected Resource | A resource that is hosted by the resource server and requires an access token to be accessed. | +| Relying Party (RP) | A client service required to verify user identity. | +| JSON Web Token (JWT) | An open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. | +| ID Token | Specific to OIDC, the primary use of the token in JWT format is to provide information about the authentication operation's outcome. | +| Access Token | Defined in OAuth2, this (optional) short lifetime token provides access to specific user resources as defined in the scope values in the request to the authorization server (can be a JSON token as well). | +| Refresh Token | Coming from OAuth2 specs, the token is usually long-lived and may be used to obtain new access tokens. | +{{}} + + +## See Also {#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 R34]({{< ref "nginx/releases.md#r34" >}}) 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 2243b6225..ca12c8637 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,153 +1,329 @@ --- -description: Enable OpenID Connect-based single-sign for applications proxied by NGINX - Plus, using Microsoft AD FS as the identity provider (IdP). -docs: DOCS-463 -title: Single Sign-On with Microsoft Active Directory FS -toc: true -weight: 100 +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 +toc: true +weight: 300 +product: NGINX-PLUS --- -This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Microsoft Active Directory Federation Services](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services) (AD FS) as the identity provider (IdP) and NGINX Plus as the relying party. - -{{< see-also >}}{{< include "nginx-plus/nginx-openid-repo-note.txt" >}}{{< /see-also >}} +This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Microsoft Active Directory Federation Services](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services) (AD FS) as the Identity Provider (IdP) and NGINX Plus as the Relying Party (RP), or OIDC client application that verifies user identity. - -## Prerequisites +{{< note >}} This guide applies to [NGINX Plus Release 34]({{< ref "nginx/releases.md#r34" >}}) 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.{{< /note >}} -The instructions assume you have the following: -- A running deployment of AD FS, either on‑premises or in Azure. -- An NGINX Plus subscription and NGINX Plus R15 or later. For installation instructions, see the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). -- The [NGINX JavaScript module](https://www.nginx.com/blog/introduction-nginscript/) (njs), required for handling the interaction between NGINX Plus and the IdP. After installing NGINX Plus, install the module with the command for your operating system. +## Prerequisites - For Debian and Ubuntu: +- 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. - ```none - sudo apt install nginx-plus-module-njs - ``` +- An NGINX Plus [subscription](https://www.f5.com/products/nginx/nginx-plus) and NGINX Plus [Release 34](({{< ref "nginx/releases.md#r34" >}})) or later. For installation instructions, see [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). - For CentOS, RHEL, and Oracle Linux: +- A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`. - ```shell - sudo yum install nginx-plus-module-njs - ``` -- The following directive included in the top-level ("main") configuration context in **/etc/nginx/nginx.conf**, to load the NGINX JavaScript module: +## Configure the AD FS Server {#adfs-setup} - ```nginx - load_module modules/ngx_http_js_module.so; - ``` +[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. - -## Configuring AD FS +### Create an AD FS Application -Create an AD FS application for NGINX Plus: +1. In AD FS, open the Server Manager. -1. Open the AD FS Management window. In the navigation column on the left, right‑click on the **Application Groups** folder and select Add Application Group from the drop‑down menu. +2. In Server Manager, select **Tools**, and then select **AD FS Management**. - The Add Application Group Wizard window opens. The left navigation column shows the steps you will complete to add an application group. +3. In **AD FS Management**, right-click on **Application Groups** and select **Add Application Group**. -2. In the **Welcome** step, type the application group name in the **Name** field. Here we are using ADFSSSO. In the **Template** field, select **Server application** under Standalone applications. Click the  Next >  button. +4. On the Application Group Wizard **Welcome** screen: - + - Enter the Name of your application, for example, `NGINX Demo App`. - -3. In the **Server application** step: + - Under **Standalone applications**, select **Server application**. - 1. Make a note of the value in the **Client Identifier** field. You will add it to the NGINX Plus configuration in [Step 4 of _Configuring NGINX Plus_](#nginx-plus-variables).
+ +5. On the Application Group Wizard **Server application** screen: - 2. In the **Redirect URI** field, type the URI of the NGINX Plus instance including the port number, and ending in **/\_codexch**. Here we’re using https://my-nginx.example.com:443/\_codexch. Click the  Add  button. + - Copy the **Client Identifier** value generated by AD FS. The client identifier is your AD FS Application ID, you will need it later when configuring NGINX Plus. - **Notes:** + - In **Redirect URI**, enter the Redirect URI for your NGINX Plus instance, for example, `https://demo.example.com/oidc_callback`, and then click **Add**. - - For production, we strongly recommend that you use SSL/TLS (port 443). - - The port number is mandatory even when you're using the default port for HTTP (80) or HTTPS (443). + +6. On the Application Group Wizard **Configure Application Credentials** screen: -3. Click the  Next >  button. + - Select **Generate a shared secret**. - + - Copy and save the generated **Client Secret**, you will need it later when configuring NGINX Plus. You will not be able to view the secret after the application group is created. - -4. In the Configure Application Credentials step, click the Generate a shared secret checkbox. Make a note of the secret that AD FS generates (perhaps by clicking the Copy to clipboard button and pasting the clipboard content into a file). You will add the secret to the NGINX Plus configuration in [Step 4 of _Configuring NGINX Plus_](#nginx-plus-variables). Click the  Next >  button. + - Select **Next** to complete the steps for adding the application group. - +### Get the OpenID Connect Discovery URL -5. In the **Summary** step, verify that the information is correct, make any necessary corrections to previous steps, and click the  Next >  button. +Check the OpenID Connect endpoint URL. By default, AD FS publishes the `.well-known/openid-configuration` document at the following address: +`https://adfs-server-address/adfs/.well-known/openid-configuration`. - -## Configuring NGINX Plus - -Configure NGINX Plus as the OpenID Connect relying party: - -1. Create a clone of the [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) GitHub repository. +1. Run the following `curl` command in a terminal: ```shell - git clone https://github.com/nginxinc/nginx-openid-connect + curl https://adfs-server-address/adfs/.well-known/openid-configuration | jq . ``` + where: -2. Copy these files from the clone to **/etc/nginx/conf.d**: + - the `adfs-server-address` is your AD FS server address - - **frontend.conf** - - **openid\_connect.js** - - **openid\_connect.server\_conf** - - **openid\_connect\_configuration.conf** + - the `/adfs/.well-known/openid-configuration` is the default address for AD FS for document location - -3. Get the URLs for the authorization endpoint, token endpoint, and JSON Web Key (JWK) file from the AD FS configuration. Run the following `curl` command in a terminal, piping the output to the indicated `python` command to output the entire configuration in an easily readable format. We've abridged the output to show only the relevant fields. + - 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. - ```shell - $ curl https:///oidc/adfs/.well-known/openid-configuration | python -m json.tool + + The configuration metadata is returned in the JSON format: + + ```json { - ... - "authorization_endpoint": "https:///oidc/adfs/auth", ... - "jwks_uri": "https:///oidc/adfs/certs", + "issuer": "https://adfs-server-address/adfs", + "authorization_endpoint": "https://adfs-server-address/adfs/oauth2/authorize/", + "token_endpoint": "https://adfs-server-address/adfs/oauth2/token/", + "jwks_uri": "https://adfs-server-address/adfs/discovery/keys", ... - "token_endpoint": "https:///oidc/adfs/token", - ... } ``` - -4. In your preferred text editor, open **/etc/nginx/conf.d/frontend.conf**. Change the "default" parameter value of each of the following [map](https://nginx.org/en/docs/http/ngx_http_map_module.html#map) directives to the specified value: + +2. Copy the **issuer** value, you will need it later when configuring NGINX Plus. Typically, the OpenID Connect Issuer for AD FS is: + + `https://adfs-server-address/adfs`. + + +{{< note >}} You will need the values of **Client ID**, **Client Secret**, and **Issuer** in the next steps. {{< /note >}} + + +## Set up NGINX Plus {#nginx-plus-setup} + +With AF DS 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 34 or later: + + ```none + nginx version: nginx/1.27.4 (nginx-plus-r34) + ``` + +2. Ensure that you have the values of the **Client ID**, **Client Secret**, and **Issuer** obtained during [AD FS Configuration](#adfs-setup). + +3. In your preferred text editor, open the NGINX configuration file (`/etc/nginx/nginx.conf` for Linux or `/usr/local/etc/nginx/nginx.conf` for FreeBSD). + +4. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, make sure your public DNS resolver is specified with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive. By default, NGINX Plus re‑resolves DNS records at the frequency specified by time‑to‑live (TTL) in the record, but you can override the TTL value with the `valid` parameter: + + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + # ... + } + ``` + +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 + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider adfs { + + # ... + + } + # ... + } + ``` + +6. In the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context, specify: + + - Your actual AD FS **Client ID** from [Step 5](#adfs-setup-id) of AD FS Configuration with the [`client_id`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_id) directive + + - Your **Client Secret** from [Step 6](#adfs-setup-secret) of AD FS Configuration with the [`client_secret`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive + + - The **Issuer** URL from [Step 2](#adfs-setup-issuer) of AD FS Configuration with the [`issuer`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive + + The `issuer` is typically your AD FS OIDC URL. By default, NGINX forms the provider metadata endpoint by appending `.well-known/openid-configuration` to the issuer. For AD FS, this often resolves to `https://adfs-server-address/adfs/.well-known/openid-configuration`. If your AD FS issuer differs from `https://adfs-server-address/adfs` (for example, a custom path), you can explicitly specify the metadata document with the [`config_url`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#config_url) directive. + + - **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. + + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider adfs { + issuer https://adfs.example.com/adfs; + client_id ; + client_secret ; + } + + # ... + } + ``` + +7. Make sure you have configured a [server](https://nginx.org/en/docs/http/ngx_http_core_module.html#server) that corresponds to `demo.example.com`, and there is a [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) that [points](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) to your application (see [Step 10](#oidc_app)) at `http://127.0.0.1:8080` that is going to be OIDC-protected: + + ```nginx + http { + + # ... + + server { + listen 443 ssl; + server_name demo.example.com; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + + # ... + + proxy_pass http://127.0.0.1:8080; + } + } + # ... + } + ``` + +8. Protect this [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) with AD FS OIDC by specifying the [`auth_oidc`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#auth_oidc) directive that will point to the `afds` configuration specified in the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context in [Step 5](#adfs-setup-oidc-provider): + + ```nginx + # ... + location / { + + auth_oidc adfs; + + # ... + + proxy_pass http://127.0.0.1:8080; + + } + # ... + ``` + +9. Pass the OIDC claims as headers to the application ([Step 10](#oidc_app)) with the [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive. These claims are extracted from the ID token returned by AD FS: + + - [`$oidc_claim_sub`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - a unique `Subject` identifier assigned for each user by AD FS + + - [`$oidc_claim_email`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) the e-mail address of the user + + - [`$oidc_claim_name`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - the full name of the user + + - 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 / { + + auth_oidc adfs; + + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + # ... + ``` + + +10. 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 + # ... + server { + listen 8080; + + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nAD FS sub: $http_sub\n"; + default_type text/plain; + } + } + ``` +11. Save the NGINX configuration file and reload the configuration: + ```nginx + nginx -s reload + ``` + +### Complete Example + +This configuration example summarizes the steps outlined above. It includes only essential settings such as specifying the DNS resolver, defining the OIDC provider, configuring SSL, and proxying requests to an internal server. + +```nginx +http { + # Use a public DNS resolver for Issuer discovery, etc. + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider adfs { + + # The 'issuer' is typically your AD FS OIDC URL + # e.g. https://adfs.example.com/adfs + issuer https://adfs.example.com/adfs; + + # Replace with your actual AD FS Client ID and Secret + client_id ; + client_secret ; + } + + server { + listen 443 ssl; + server_name demo.example.com; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + # Protect this location with AD FS OIDC + auth_oidc adfs; + + # Forward OIDC claims as headers if desired + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + } + + server { + listen 8080; - - `map $host $oidc_authz_endpoint` – Value of `authorization_endpoint` from [Step 3](#nginx-plus-urls) (in this guide, `https:///oidc/adfs/auth`) - - `map $host $oidc_token_endpoint` – Value of `token_endpoint` from [Step 3](#nginx-plus-urls) (in this guide, `https:///oidc/adfs/token`) - - `map $host $oidc_client` – Value in the **Client ID** field from [Step 3 of _Configuring AD FS_](#ad-fs-server-application) (in this guide, `3e23f0eb-9329-46ff-9d37-6ad24afdfaeb`) - - `map $host $oidc_client_secret` – Value in the **Client secret** field from [Step 4 of _Configuring AD FS_](#ad-fs-configure-application-credentials) (in this guide, `NUeuULtSCjgXTGSkq3ZwEeCOiig4-rB2XiW_W`) - - `map $host $oidc_hmac_key` – A unique, long, and secure phrase + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nAD FS sub: $http_sub\n"; + default_type text/plain; + } + } +} +``` -5. Configure the JWK file. The procedure depends on which version of NGINX Plus you are using. +### Testing - - In NGINX Plus R17 and later, NGINX Plus can read the JWK file directly from the URL reported as `jwks_uri` in [Step 3](#nginx-plus-urls). Change **/etc/nginx/conf.d/frontend.conf** as follows: +1. Open `https://demo.example.com/` in a browser. You will be automatically redirected to the AD FS sign-in page. - 1. Comment out (or remove) the [auth_jwt_key_file](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_file) directive. - 2. Uncomment the [auth_jwt_key_request](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_request) directive. (Its parameter, `/_jwks_uri`, refers to the value of the `$oidc_jwt_keyfile` variable, which you set in the next step.) - 3. Change the second parameter of the `set $oidc_jwt_keyfile` directive to the value reported in the `jwks_uri` field in [Step 3](#nginx-plus-urls) (in this guide, `https:///oidc/adfs/certs`). +2. Enter valid AD FS credentials of a user who has access the application. Upon successful sign-in, AD FS redirects you back to NGINX Plus, and you will see the proxied application content (for example, “Hello, Jane Doe!”). - - In NGINX Plus R16 and earlier, the JWK file must be on the local disk. (You can also use this method with NGINX Plus R17 and later if you wish.) - 1. Copy the JSON contents from the JWK file named in the `jwks_uri` field in [Step 3](#nginx-plus-urls) (in this guide, `https:///oidc/adfs/certs`) to a local file (for example, `/etc/nginx/my_adfs_jwk.json`). - 2. In **/etc/nginx/conf.d/frontend.conf**, change the second parameter of the `set $oidc_jwt_keyfile` directive to the local file path. +## Legacy njs-based AD FS Solution {#legacy-njs-guide} -6. Confirm that the user named by the [user](http://nginx.org/en/docs/ngx_core_module.html#user) directive in the NGINX Plus configuration (in **/etc/nginx/nginx.conf** by convention) has read permission on the JWK file. +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. - -## Testing -In a browser, enter the address of your NGINX Plus instance and try to log in using the credentials of a user who has access to the application. +## See Also - +- [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) - -## Troubleshooting +- [Release Notes for NGINX Plus R34]({{< ref "nginx/releases.md#r34" >}}) -See the [**Troubleshooting**](https://github.com/nginxinc/nginx-openid-connect#troubleshooting) section at the nginx-openid-connect repository on GitHub. -### Revision History +## Revision History -- Version 2 (March 2020) – Updates to _Configuring NGINX Plus_ section -- Version 1 (December 2019) – Initial version (NGINX Plus Release 20) +- Version 1 (March 2025) – Initial version (NGINX Plus Release 34) diff --git a/content/nginx/deployment-guides/single-sign-on/auth0.md b/content/nginx/deployment-guides/single-sign-on/auth0.md index a06a98983..987092ce1 100644 --- a/content/nginx/deployment-guides/single-sign-on/auth0.md +++ b/content/nginx/deployment-guides/single-sign-on/auth0.md @@ -1,186 +1,314 @@ --- -description: Learn how to enable single sign-on (SSO) with [Auth0](https://auth0.com/) - for applications proxied by F5 NGINX Plus. -docs: DOCS-884 +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 toc: true weight: 100 -type: -- tutorial --- -
- -This documentation applies to F5 NGINX Plus R15 and later. -
+This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Auth0](https://auth0.com/features/single-sign-on) as the Identity Provider (IdP), and NGINX Plus as the Relying Party, or OIDC client application that verifies user identity. -You can use NGINX Plus with [Auth0](https://auth0.com/) and OpenID Connect to enable single sign-on (SSO) for your proxied applications. By following the steps in this guide, you will learn how to set up SSO using OpenID Connect as the authentication mechanism, with Auth0 as the identity provider (IdP), and NGINX Plus as the relying party. +{{< note >}} This guide applies to [NGINX Plus Release 34]({{< ref "nginx/releases.md#r34" >}}) 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.{{< /note >}} -{{< see-also >}}{{< include "nginx-plus/nginx-openid-repo-note.txt" >}}{{< /see-also >}} ## Prerequisites -To complete the steps in this guide, you need the following: +- An [Auth0](https://auth0.com/) tenant with administrator privileges. -- An Auth0 tenant with administrator privileges. -- [NGINX Plus](https://www.f5.com/products/nginx/nginx-plus) with a valid subscription. -- The [NGINX JavaScript module](https://www.nginx.com/products/nginx/modules/nginx-javascript/) (`njs`) -- the `njs` module handles the interaction between NGINX Plus and Auth0. +- An NGINX Plus [subscription](https://www.f5.com/products/nginx/nginx-plus) and NGINX Plus [Release 34](({{< ref "nginx/releases.md#r34" >}})) or later. For installation instructions, see [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). -## Install NGINX Plus and the njs Module {#install-nginx-plus-njs} +- A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`. -1. If you do not already have NGINX Plus installed, follow the steps in the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) to do so. -2. Install the NGINX JavaScript module by following the steps in the [`njs` installation guide](https://nginx.org/en/docs/njs/install.html). -3. Add the following directive to the top-level ("main") configuration context in the NGINX Plus configuration (`/etc/nginx/nginx.conf`) to load the `njs` module: - ```Nginx configuration file - load_module modules/ngx_http_js_module.so; - ``` +## Create a new Auth0 Application {#auth0-create} + +1. Log in to your Auth0 Dashboard at [manage.auth0.com](https://manage.auth0.com/). -## Configure Auth0 {#config-auth0} +2. Select **Applications > Applications** from the sidebar menu. -Take the steps in this section to create a new application for NGINX Plus. +3. On the **Applications** screen, select **Create Application**. -{{< note >}} This section contains images that reflect the state of the Auth0 web interface at the time of publication. The actual Auth0 GUI may differ from the examples shown here. Use this guide as a reference and adapt the instructions to suit the current Auth0 GUI as necessary.{{< /note >}} +4. On the **Create application** screen: -### Create a new Auth0 Application {#create-auth0-app} + - Enter the **Name** for the application, for example, **NGINX Demo App**. -1. Log in to your Auth0 Dashboard at [manage.auth0.com](https://manage.auth0.com/). -1. Select **Applications > Applications** from the sidebar menu. -1. On the **Applications** page, select the **Create Application** button. -1. In the **Create application** window, provide the information listed below and then select **Create**. + - In **Application Type**, select **Regular Web Applications**. - - **Name**: A name for the application, for example "nginx-plus-app". - - **Application Type**: **Regular Web Applications** + - Select **Create**. - {{< img src="/img/sso/auth0/sso-auth0-create-app.png" alt="image showing the Create application window in the Auth0 dashboard" >}} +5. On the **Settings** screen of your application: -### Set up the Web Application {#web-app-setup} + - Copy your **Client ID** and **Client Secret** displayed in the **Basic Information** section — you will need them later when configuring NGINX Plus. -In this section, you'll set up a web application that follows the Auth0 [Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow). +6. On the **Application URIs** section of your application: -1. On the **Application** page in the [Auth0 dashboard](https://manage.auth0.com/), select your web application. -1. Select the **Settings** tab for your application. -1. Make note of the Client ID and Client Secret displayed in the **Basic Information** section. + - Add the URI NGINX Plus callback URI in the **Allowed Callback URLs** field, for example: - {{< img src="/img/sso/auth0/sso-auth0-app.png" alt="image showing the basic information section of the web application settings in the Auth0 dashboard" >}} + `https://demo.example.com/oidc_callback`. -1. In the **Application URIs** section, provide the URI of the NGINX Plus instance in the **Allowed Callback URLs** field. +### Get the OpenID Connect Discovery URL - - The URL must include the port number and end in **/_codexch**. In our example, we used the URL `http://nginx-plus-app:8010/_codexch`. - - The port is always required, even if you use the default port for HTTP (`80`) or HTTPS (`443`). - - The use of SSL/TLS (`443`) is strongly recommended for production environments. +Check the OpenID Connect Discovery URL. By default, Auth0 publishes the `.well-known/openid-configuration` document at the following address: - {{< img src="/img/sso/auth0/sso-auth0-app-settings.png" alt="image showing the Application URIs settings in the Auth0 dashboard" >}} +`https://yourTenantId.us.auth0.com/.well-known/openid-configuration`. -1. In the **Advanced Settings** section, select the **Endpoints** tab. -1. Make note of the **OpenID Configuration** URL. +1. Run the following `curl` command in a terminal: - {{< img src="/img/sso/auth0/sso-auth0-app-advanced-settings.png" alt="image showing the Advanced Application Settings section of the Auth0 dashboard" >}} + ```shell + curl https://yourTenantId.us.auth0.com/.well-known/openid-configuration | jq + ``` + where: -1. Select **Save Changes**. + - the `yourTenantId` is your Auth0 [Tenant ID](https://auth0.com/docs/get-started/tenant-settings/find-your-tenant-name-or-tenant-id) -### Set up Authentication {#authn-setup} + - the `yourTenantId.us.auth0.com/` is your Auth0 server address -{{< note >}}For the purposes of this guide, we will add a new Auth0 user database and user account to use for testing. + - the `/.well-known/openid-configuration` is the default address for Auth0 for document location -You can set up authentication using any of the available [Auth0 identity providers](https://auth0.com/docs/authenticate/identity-providers). {{< /note >}} + - 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. -To set up a new user database and add a user account to it, take the steps below. -1. Log in to the [Auth0 dashboard](https://manage.auth0.com/) and select **Authentication > Database** from the sidebar menu. -1. Select the **Create DB Connection** button. -1. Provide a **Name** for the database connection, then select **Create**. -1. On the **Database** page, select the **Applications** tab. Then, select the toggle button next to the [application you created earlier](#create-a-new-auth0-application). + The configuration metadata is returned in the JSON format: - {{< img src="/img/sso/auth0/sso-auth0-db-app.png" alt="image showing the Applications settings for an OIDC Authentication database in the Auth0 dashboard" >}} + ```json + { + ... + "issuer": "https://{yourTenantId}.us.auth0.com/", + "authorization_endpoint": "https://{yourTenantId}.us.auth0.com/oauth/token", + "token_endpoint": "https://{yourTenantId}.us.auth0.com/oauth/token", + "jwks_uri": "https://{yourTenantId}.us.auth0.com/.well-known/jwks.json", + ... + } + ``` -1. In the sidebar menu, select **User Management > Users**. -1. On the **Users** page, select the **Create User** button. -1. In the **Create user** window, provide the following information, then select **Create**. - - **Email**: user's email - - **Password**: a password for the user account - - **Connection**: select your **database** from the list. + +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). - {{< img src="/img/sso/auth0/sso-auth0-create-user.png" alt="image showing the Create User settings window in the Auth0 dashboard" >}} +{{< note >}} You will need the values of **Client ID**, **Client Secret**, and **Issuer** in the next steps. {{< /note >}} -The user should receive an email to the email address provided. Once the user verifies their account by clicking on the link in the email, the account creation process is complete. ## Set up NGINX Plus {#nginx-plus-setup} -Take the steps in this section to set up NGINX Plus as the OpenID Connect relying party. +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. -### Configure NGINX OpenID Connect {#nginx-plus-oidc-config} +1. Ensure that you are using the latest version of NGINX Plus by running the `nginx -v` command in a terminal: -1. Clone the [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) GitHub repository, or download the repo files. + ```shell + nginx -v + ``` + The output should match NGINX Plus Release 34 or later: - ```bash - git clone https://github.com/nginxinc/nginx-openid-connect.git - ``` + ```none + nginx version: nginx/1.27.4 (nginx-plus-r34) + ``` + +2. Ensure that you have the values of the **Client ID**, **Client Secret**, and **Issuer** obtained during [Auth0 Configuration](#auth0-setup). + +3. In your preferred text editor, open the NGINX configuration file (`/etc/nginx/nginx.conf` for Linux or `/usr/local/etc/nginx/nginx.conf` for FreeBSD). -1. Run the *configure.sh* script, which will update the NGINX configuration files with the values for your Auth0 application. +4. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, make sure your public DNS resolver is specified with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive: By default, NGINX Plus re‑resolves DNS records at the frequency specified by time‑to‑live (TTL) in the record, but you can override the TTL value with the `valid` parameter: - For example: + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; - ```bash - ./nginx-openid-connect/configure.sh \ - --auth_jwt_key request \ - --client_id Nhotzxx...IERmUi \ - --client_secret 6ZHd0j_r...UtDZ5bkdu \ - https://.us.auth0.com/.well-known/openid-configuration + # ... + } ``` -1. In the `frontend.conf` file, update the **my_backend** upstream with the address of the application that you want to add OIDC authorization to. + +5. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, define the Auth0 provider named `auth0` by specifying the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context: + + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; - For example: + oidc_provider auth0 { - ```Nginx configuration file - upstream my_backend { - zone my_backend 64k; - server my-backend-app.com:80; + # ... + + } + # ... } ``` -1. In the *openid_connect.server_conf* file, add the [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive to the `/_jwks_uri` and `/_token` locations to `Accept-Encoding "gzip"`, as shown below. +6. In the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context, specify: + + - Your actual Auth0 **Client ID** obtained in [Auth0 Configuration](#auth0-create) with the [`client_id`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_id) directive - ```Nginx configuration file - ... - location = /_jwks_uri { - ... - proxy_set_header Accept-Encoding "gzip" + - Your **Client Secret** obtained in [Auth0 Configuration](#auth0-create) with the [`client_secret`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive + + - The **Issuer** URL obtained in [Auth0 Configuration](#auth0-create) with the [`issuer`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive + + The `issuer` is typically your Auth0 OIDC URL. For Auth0, a trailing slash is included, for example: `https://yourTenantId.us.auth0.com/`. + + - **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. + + + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider auth0 { + issuer https://yourTenantId.us.auth0.com/; + client_id ; + client_secret ; + } + + # ... } - ... - location = /_token { - ... - proxy_set_header Accept-Encoding "gzip" - } - ... ``` -1. Copy the following files to the */etc/nginx/conf.d* directory on the host machine where NGINX Plus is installed: +7. Make sure you have configured a [server](https://nginx.org/en/docs/http/ngx_http_core_module.html#server) that corresponds to `demo.example.com`, and there is a [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) that [points](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) to your application (see [Step 10](#oidc_app)) at `http://127.0.0.1:8080` that is going to be OIDC-protected: + + ```nginx + http { - - `frontend.conf` - - `openid_connect.js` - - `openid_connect.server_conf` - - `openid_connect_configuration.conf` + # ... -1. Reload the NGINX configuration: + server { + listen 443 ssl; + server_name demo.example.com; - ```bash - sudo nginx -s reload + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + + # ... + + proxy_pass http://127.0.0.1:8080; + } + } + # ... + } ``` -## Test the Setup +8. Protect this [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) with Auth0 OIDC by specifying the [`auth_oidc`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#auth_oidc) directive that will point to the `auth0` configuration specified in the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context in [Step 5](#auth0-setup-oidc-provider): + + ```nginx + # ... + location / { + auth_oidc auth0; + + # ... + + proxy_pass http://127.0.0.1:8080; + } + # ... + ``` + +9. Pass the OIDC claims as headers to the application ([Step 10](#oidc_app)) with the [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive. These claims are extracted from the ID token returned by Auth0: + + - [`$oidc_claim_email`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) the e-mail address of the user + + - [`$oidc_claim_name`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - the full name of the user + + - 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 / { + auth_oidc auth0; + + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + # ... + ``` + + +10. 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 + # ... + server { + listen 8080; + + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nAuth0 sub: $http_sub\n"; + default_type text/plain; + } + } + ``` +11. Save the NGINX configuration file and reload the configuration: + ```nginx + nginx -s reload + ``` + +### Complete Example + +This configuration example summarizes the steps outlined above. It includes only essential settings such as specifying the DNS resolver, defining the OIDC provider, configuring SSL, and proxying requests to an internal server. + +```nginx +http { + # Use a public DNS resolver for Issuer discovery, etc. + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider auth0 { + # Issuer from your Auth0 tenant's .well-known/openid-configuration + issuer https://yourTenantId.us.auth0.com/; + + # Replace with your actual Client ID and Secret from Auth0 + client_id ; + client_secret ; + } + + server { + listen 443 ssl; + server_name demo.example.com; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + # Enforce OIDC for root path with Auth0 + auth_oidc auth0; + + # Forward OIDC claims to the upstream as headers if desired + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + } + + server { + # Simple test upstream server + listen 8080; + + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nAuth0 sub: $http_sub\n"; + default_type text/plain; + } + } +} +``` + +### Testing + +1. Open `https://demo.example.com/` in a browser. You will be redirected to the Auth0 sign-in page. + +2. Enter valid Auth0 credentials of a user who has access the application. Upon successful sign-in, Auth0 redirects you back to NGINX Plus, and you will see the proxied application content (for example, “Hello, Jane Doe!”). + + +## Legacy njs-based Auth0 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 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. -1. In a browser, enter the address of your NGINX Plus instance. You should be directed to the Auth0 login page, as shown in the example below. - {{< img src="/img/sso/auth0/sso-auth0-login-test.png" alt="image showing an example Auth0 login screen that contains username and password fields" >}} +## See Also -1. You should be able to log in using the credentials of the user account that you created in the Auth0 database. +- [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) -## Troubleshooting +- [Release Notes for NGINX Plus R34]({{< ref "nginx/releases.md#r34" >}}) -Refer to the [Troubleshooting](https://github.com/nginxinc/nginx-openid-connect#troubleshooting) section in the `nginx-openid-connect` repository on GitHub. ## Revision History -- Version 1 (May 2022) - Initial version +- Version 1 (March 2025) – Initial version (NGINX Plus Release 34) diff --git a/content/nginx/deployment-guides/single-sign-on/cognito.md b/content/nginx/deployment-guides/single-sign-on/cognito.md index ff5f182fb..c7d70a5c2 100644 --- a/content/nginx/deployment-guides/single-sign-on/cognito.md +++ b/content/nginx/deployment-guides/single-sign-on/cognito.md @@ -1,189 +1,284 @@ --- -description: Enable OpenID Connect-based single-sign for applications proxied by NGINX - Plus, using Amazon Cognito as the identity provider (IdP). -docs: DOCS-464 -title: Single Sign-On with Amazon Cognito -toc: true -weight: 100 +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 +toc: true +weight: 200 --- -This guide explains how to enable single sign‑on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Amazon Cognito](https://aws.amazon.com/cognito/) as the identity provider (IdP), and NGINX Plus as the relying party. +This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Amazon Cognito](https://aws.amazon.com/cognito/) as the Identity Provider (IdP), and NGINX Plus as the Relying Party, or OIDC client application that verifies user identity. -{{< see-also >}}{{< include "nginx-plus/nginx-openid-repo-note.txt" >}}{{< /see-also >}} +{{< note >}} This guide applies to [NGINX Plus Release 34]({{< ref "nginx/releases.md#r34" >}}) 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.{{< /note >}} - ## Prerequisites -The instructions assume you have the following: +- An [AWS account](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/) + +- A Cognito **User Pool** + +- An NGINX Plus [subscription](https://www.f5.com/products/nginx/nginx-plus) and NGINX Plus [Release 34](({{< ref "nginx/releases.md#r34" >}})) or later. For installation instructions, see [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). + +- 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 + +2. In the Cognito dashboard, select **Create or open a User Pool**. + +3. **Create an App Client** (for example, “nginx-demo-app”) and **enable the “Generate client secret”** option. + +4. In the App client settings, select **Enable Cognito User Pool** as an **Identity Provider**: + + - Add a **Callback URL**: `https://demo.example.com/oidc_callback`. + + - Enable **Authorization code grant**. + + - In the **OAuth scopes**, check the values of **openid**, **profile**, and **email**. + +5. Copy the following values — you will need them later when configuring NGINX Plus. + + - **User Pool ID**, for example, `us-east-2_abCdEfGhI` + + - **App client id** and **App client secret** + + - **AWS region**, for example, `us-east-2` + + - **Issuer**, for example, `https://cognito-idp..amazonaws.com/` + +{{< note >}} You will need the values of **Client ID**, **Client Secret**, and **Issuer** in the next steps. {{< /note >}} + + +## 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. + +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 34 or later: + + ```none + nginx version: nginx/1.27.4 (nginx-plus-r34) + ``` + +2. Ensure that you have the values of the **Client ID**, **Client Secret**, and **Issuer** obtained during [Cognito Configuration](#cognito-setup). + +3. In your preferred text editor, open the NGINX configuration file (`/etc/nginx/nginx.conf` for Linux or `/usr/local/etc/nginx/nginx.conf` for FreeBSD). -- An [AWS account](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/). -- An NGINX Plus subscription and NGINX Plus R15 or later. For installation instructions, see the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). -- The [NGINX JavaScript module](https://www.nginx.com/blog/introduction-nginscript/) (njs), required for handling the interaction between NGINX Plus and the IdP. After installing NGINX Plus, install the module with the command for your operating system. +4. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, make sure your public DNS resolver is specified with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive: By default, NGINX Plus re‑resolves DNS records at the frequency specified by time‑to‑live (TTL) in the record, but you can override the TTL value with the `valid` parameter: - For Debian and Ubuntu: + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; - ```none - sudo apt install nginx-plus-module-njs - ``` + # ... + } + ``` - For CentOS, RHEL, and Oracle Linux: + +5. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, define the Amazon Cognito provider named `cognito` by specifying the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context: - ```shell - sudo yum install nginx-plus-module-njs - ``` + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; -- The following directive included in the top-level ("main") configuration context in **/etc/nginx/nginx.conf**, to load the NGINX JavaScript module: + oidc_provider cognito { - ```nginx - load_module modules/ngx_http_js_module.so; - ``` + # ... - -## Configuring Amazon Cognito + } + # ... + } + ``` -**Note:** The following procedure reflects the Cognito GUI at the time of publication, but the GUI is subject to change. Use this guide as a reference and adapt to the current Cognito GUI as necessary. +6. In the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context, specify: -Create a new application for NGINX Plus in the Cognito GUI: + - your actual Amazon Cognito **Client ID** obtained in [Amazon Cognito Configuration](#cognito-setup) with the [`client_id`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_id) directive -1. Log in to your AWS account, open the AWS Management Console ([console.aws.amazon.com](https://console.aws.amazon.com)), and navigate to the Cognito dashboard (you can, for example, click **Cognito** in the **Security, Identity, & Compliance** section of the **Services** drop‑down menu). + - your **Client Secret** obtained in [Amazon Cognito Configuration](#cognito-setup) with the [`client_secret`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive -2. On the Cognito dashboard, click **Manage User Pools** to open the **Your User Pools** window. Click the  Create a user pool  button or the highlighted phrase. + - the **Issuer** URL obtained in [Amazon Cognito Configuration](#cognito-setup) with the [`issuer`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive - + The `issuer` is typically your Amazon Cognito OIDC URL. As a rule, Cognito uses a unique issuer for each User Pool, for example: -3. In the **Create a user pool** window that opens, type a value in the **Pool name** field (in this guide, it's nginx-plus-pool), then click the Review defaults button. + `https://cognito-idp.us-east-2.amazonaws.com/us-east-2_abCdEfGhI` - + By default, NGINX Plus creates the metadata URL by appending the `/.well-known/openid-configuration` part to the Issuer URL. If your Issuer is different, you can explicitly specify the metadata document with the [`config_url`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#config_url) directive. - -4. On the **Review** tab which opens, click Add app client... in the **App clients** field near the bottom. + - **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. - + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; -5. On the **App clients** tab which opens, click Add an app client. + oidc_provider cognito { + issuer https://cognito-idp.us-east-2.amazonaws.com/us-east-2_abCdEfGhI; + client_id ; + client_secret ; + } -6. On the **Which app clients will have access to this user pool?** window which opens, enter a value (in this guide, nginx-plus-app) in the App client name field. Make sure the Generate client secret box is checked, then click the  Create app client  button. + # ... + } + ``` - +7. Make sure you have configured a [server](https://nginx.org/en/docs/http/ngx_http_core_module.html#server) that corresponds to `demo.example.com`, and there is a [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) that [points](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) to your application (see [Step 10](#oidc_app)) at `http://127.0.0.1:8080` that is going to be OIDC-protected: -7. On the confirmation page which opens, click Return to pool details to return to the **Review** tab. On that tab click the  Create pool  button at the bottom. (The screenshot in [Step 4](#cognito-review-tab) shows the button.) + ```nginx + http { - -8. On the details page which opens to confirm the new user pool was successfully created, make note of the value in the **Pool Id** field; you will add it to the NGINX Plus configuration in [Step 3 of _Configuring NGINX Plus_](#nginx-plus-variables). + # ... - 'General settings' tab in Amazon Cognito GUI + server { + listen 443 ssl; + server_name demo.example.com; - -9. Click Users and groups in the left navigation column. In the interface that opens, designate the users (or group of users, on the **Groups** tab) who will be able to use SSO for the app being proxied by NGINX Plus. For instructions, see the Cognito documentation about [creating users](https://docs.aws.amazon.com/cognito/latest/developerguide/how-to-create-user-accounts.html), [importing users](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-using-import-tool.html), or [adding a group](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-user-groups.html). + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; - 'Users and groups' tab in Amazon Cognito GUI + location / { -10. Click **App clients** in the left navigation bar. On the tab that opens, click the Show Details button in the box labeled with the app client name (in this guide, nginx-plus-app). + # ... - 'App clients' tab in Amazon Cognito GUI + proxy_pass http://127.0.0.1:8080; + } + } + # ... + } + ``` - -11. On the details page that opens, make note of the values in the App client id and App client secret fields. You will add them to the NGINX Plus configuration in [Step 3 of _Configuring NGINX Plus_](#nginx-plus-variables). +8. Protect this [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) with Amazon Cognito OIDC by specifying the [`auth_oidc`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#auth_oidc) directive that will point to the `cognito` configuration specified in the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context in [Step 5](#cognito-setup-oidc-provider): - + ```nginx + # ... + location / { + auth_oidc cognito; -12. Click App client settings in the left navigation column. In the tab that opens, perform the following steps: + # ... - 1. In the Enabled Identity Providers section, click the Cognito User Pool checkbox (the **Select all** box gets checked automatically). - 2. In the **Callback URL(s)** field of the Sign in and sign out URLs section, type the URI of the NGINX Plus instance including the port number, and ending in **/\_codexch**. Here we’re using https://my-nginx-plus.example.com:443/_codexch. + proxy_pass http://127.0.0.1:8080; + } + # ... + ``` - **Notes:** +9. Pass the OIDC claims as headers to the application ([Step 10](#oidc_app)) with the [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive. These claims are extracted from the ID token returned by Amazon Cognito: - - For production, we strongly recommend that you use SSL/TLS (port 443). - - The port number is mandatory even when you're using the default port for HTTP (80) or HTTPS (443). + - [`$oidc_claim_sub`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - a unique `Subject` identifier assigned for each user by Amazon Cognito - 3. In the **OAuth 2.0** section, click the Authorization code grant checkbox under Allowed OAuth Flows and the **email**, **openid**, and **profile** checkboxes under Allowed OAuth Scopes. - 4. Click the  Save changes  button. + - [`$oidc_claim_email`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) the e-mail address of the user - + - [`$oidc_claim_name`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - the full name of the user - -13. Click **Domain name** in the left navigation column. In the tab that opens, type a domain prefix in the **Domain prefix** field under Amazon Cognito domain (in this guide, my-nginx-plus). Click the  Save changes  button. + - 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 / { + auth_oidc cognito; - -## Configuring NGINX Plus + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; -Configure NGINX Plus as the OpenID Connect relying party: + proxy_pass http://127.0.0.1:8080; + } + # ... + ``` -1. Create a clone of the [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) GitHub repository. + +10. Create a simple test application referenced by the `proxy_pass` directive which returns the authenticated user's full name and email upon successful authentication: - ```shell - git clone https://github.com/nginxinc/nginx-openid-connect - ``` + ```nginx + # ... + server { + listen 8080; -2. Copy these files from the clone to **/etc/nginx/conf.d**: + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nSub: $http_sub\n"; + default_type text/plain; + } + } + ``` +11. Save the NGINX configuration file and reload the configuration: + ```nginx + nginx -s reload + ``` - - **frontend.conf** - - **openid_connect.js** - - **openid_connect.server\_conf** +### Complete Example - -3. In your preferred text editor, open **/etc/nginx/conf.d/frontend.conf**. Change the second parameter of each of the following [set](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html#set) directives to the specified value. +This configuration example summarizes the steps outlined above. It includes only essential settings such as specifying the DNS resolver, defining the OIDC provider, configuring SSL, and proxying requests to an internal server. - The `` variable is the full value in the **Domain prefix** field in [Step 13 of _Configuring Amazon Cognito_](#cognito-domain-name). In this guide it is https://my-nginx-plus.auth.us-east-2.amazoncognito.com. +```nginx +http { + # Use a public DNS resolver for Issuer discovery, etc. + resolver 10.0.0.1 ipv4=on valid=300s; - - `set $oidc_authz_endpoint` – `/oauth2/authorize` - - `set $oidc_token_endpoint` – `/oauth2/token` - - `set $oidc_client` – Value in the App client id field from [Step 11 of _Configuring Amazon Cognito_](#cognito-app-client-id-secret) - - `set $oidc_client_secret` – Value in the App client secret field from [Step 11 of _Configuring Amazon Cognito_](#cognito-app-client-id-secret) - - `set $oidc_hmac_key` – A unique, long, and secure phrase + oidc_provider cognito { + # Typically your Cognito issuer is something like: + # https://cognito-idp..amazonaws.com/ + issuer https://cognito-idp.us-east-2.amazonaws.com/us-east-2_abCdEfGhI; -4. Configure the JWK file. The file's URL is + # Your Cognito "App client id" and "App client secret" + client_id ; + client_secret ; + } - **https://cognito-idp.**_region_**.amazonaws.com/**_User-Pool-ID_**/.well-known/jwks.json** + server { + listen 443 ssl; + server_name demo.example.com; - where + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; - - _region_ is the same AWS region name as in the `` variable used in [Step 3](#nginx-plus-variables) - - _User-Pool-ID_ is the value in the **Pool Id** field in [Step 8 of _Configuring Amazon Cognito_](#cognito-pool-id) + location / { + # Protect this path with Cognito OIDC + auth_oidc cognito; - In this guide, the URL is + # Forward OIDC claims as headers if desired + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; - https://cognito-idp.us-east-2.amazonaws.com/us-east-2_mLoGHJpOs/.well-known/jwks.json. + proxy_pass http://127.0.0.1:8080; + } + } - The method for configuring the JWK file depends on which version of NGINX Plus you are using: + server { + listen 8080; - - In NGINX Plus R17 and later, NGINX Plus can read the JWK file directly. Change **/etc/nginx/conf.d/frontend.conf** as follows: + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nSub: $http_sub\n"; + default_type text/plain; + } + } +} +``` - 1. Comment out (or remove) the [auth_jwt_key_file](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_file) directive. - 2. Uncomment the [auth_jwt_key_request](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_request) directive. (Its parameter, `/_jwks_uri`, refers to the value of the `$oidc_jwt_keyfile` variable, which you set in the next step.) - 3. Change the second parameter of the `set $oidc_jwt_keyfile` directive to the URL of the JWK file (`https://cognito-idp.../.well-known/jwks.json`). +### Testing - - In NGINX Plus R16 and earlier, the JWK file must be on the local disk. (You can also use this method with NGINX Plus R17 and later if you wish.) +1. Open https://demo.example.com/ in a browser. You will be automatically redirected to Amazon Cognito login page for your realm. - 1. Copy the JSON contents from the JWK file (****) to a local file (for example, **/etc/nginx/my\_cognito\_jwk.json**). - 2. In **/etc/nginx/conf.d/frontend.conf**, change the second parameter of the `set $oidc_jwt_keyfile` directive to the local file path. +2. Enter valid Cognito user credentials (those in the assigned user pool). Upon successful sign-in, Cognito redirects you back to NGINX Plus, and you will see the proxied application content (for example, “Hello, Jane Doe!”). -5. At the time of publication, Cognito does not support the OpenID **offline_access** scope. Open **/etc/nginx/conf.d/openid\_connect.server\_conf** in a text editor and remove `+offline_access` from the list of scopes on line 10, so that it looks like this: - ```nginx - return 302 "$oidc_authz_endpoint?response_type=code&scope=openid+profile+email&client_id=$oidc_clientaws...; - ``` +## Legacy njs-based Amazon Cognito Solution {#legacy-njs-guide} -6. Confirm that the user named by the [user](http://nginx.org/en/docs/ngx_core_module.html#user) directive in the NGINX Plus configuration (in **/etc/nginx/nginx.conf** by convention) has read permission on the JWK file. +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. - -## Testing -In a browser, enter the address of your NGINX Plus instance and try to log in using the credentials of a user assigned to the application (see [Step 9 in _Configuring Amazon Cognito_](#cognito-users)). The NGINX logo that appears in the screenshot was added on Cognito's **UI customization** tab (not shown in this guide). +## See Also - +- [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) - -## Troubleshooting +- [Release Notes for NGINX Plus R34]({{< ref "nginx/releases.md#r34" >}}) -See the [**Troubleshooting**](https://github.com/nginxinc/nginx-openid-connect#troubleshooting) section at the nginx-openid-connect repository on GitHub. -### Revision History +## Revision History -- Version 1 (March 2020) – Initial version (NGINX Plus Release 20) +- Version 1 (March 2025) – Initial version (NGINX Plus Release 34) diff --git a/content/nginx/deployment-guides/single-sign-on/entra-id.md b/content/nginx/deployment-guides/single-sign-on/entra-id.md new file mode 100644 index 000000000..b9f445066 --- /dev/null +++ b/content/nginx/deployment-guides/single-sign-on/entra-id.md @@ -0,0 +1,298 @@ +--- +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 +toc: true +weight: 400 +--- + +This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) as the Identity Provider (IdP), and NGINX Plus as the Relying Party, or OIDC client application that verifies user identity. + +{{< note >}} This guide applies to [NGINX Plus Release 34]({{< ref "nginx/releases.md#r34" >}}) 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.{{< /note >}} + + +## Prerequisites + +- A Microsoft Entra tenant with admin access. + +- Azure CLI. For installation instructions, see [How to install the Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli). + +- An NGINX Plus [subscription](https://www.f5.com/products/nginx/nginx-plus) and NGINX Plus [Release 34](({{< ref "nginx/releases.md#r34" >}})) or later. For installation instructions, see [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). + +- 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. + +### Register new Azure Web Application + +1. Log in to Azure CLI: + + ```bash + 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 + az ad app create --display-name "Nginx Demo App" --web-redirect-uris "https://demo.example.com/oidc_callback" + ``` + + - From the command output, copy the `appId` value which represents your **Client ID**. You will need it later when configuring NGINX Plus. + +3. Generate a new Client Secret. + + - Create a client secret for your application by running: + + ```bash + az ad app credential reset --id + ``` + + - Replace the `` with the value obtained in the previous step. + + - From the command output, copy the the `password` value which represents your **Client Secret**. You will need it later when configuring NGINX Plus. Make sure to securely save the generated client secret, as it will not be displayed again. + + - From the same command output, copy the the `tenant` value which represents your **Tenant ID**. You will need it later when configuring NGINX Plus. + +{{< note >}} You will need the values of **Client ID**, **Client Secret**, and **Tenant ID** in the next steps. {{< /note >}} + +## Set up NGINX Plus {#nginx-plus} + +With Microsoft Entra ID 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 34 or later: + + ```none + nginx version: nginx/1.27.4 (nginx-plus-r34) + ``` + +2. Ensure that you have the values of the **Client ID**, **Client Secret**, and **Tenant ID** obtained during [Microsoft Entra ID Configuration](#entra-setup). + +3. In your preferred text editor, open the NGINX configuration file (`/etc/nginx/nginx.conf` for Linux or `/usr/local/etc/nginx/nginx.conf` for FreeBSD). + +4. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, make sure your public DNS resolver is specified with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive: By default, NGINX Plus re‑resolves DNS records at the frequency specified by time‑to‑live (TTL) in the record, but you can override the TTL value with the `valid` parameter: + + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + # ... + } + ``` + + +5. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, define the Entra ID provider named `entra` by specifying the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context: + + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider entra { + + # ... + + } + # ... + } + ``` + +6. In the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context, specify: + + - your **Client ID** obtained in [Entra ID Configuration](#entra-setup) with the [`client_id`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_id) directive + + - your **Client Secret** obtained in [Entra ID Configuration](#entra-setup) with the [`client_secret`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive + + - the **Issuer** URL obtained in [Entra ID Configuration](#entra-setup) with the [`issuer`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive + + The `issuer` is typically: + + `https://login.microsoftonline.com//v2.0`. + + By default, NGINX Plus creates the metadata URL by appending the `/.well-known/openid-configuration` part to the Issuer URL. If your metadata URL is different, you can explicitly specify it with the [`config_url`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#config_url) directive. + + - **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. + + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider entra { + issuer https://login.microsoftonline.com//v2.0; + client_id ; + client_secret ; + + ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; + } + + # ... + } + ``` + +7. Make sure you have configured a [server](https://nginx.org/en/docs/http/ngx_http_core_module.html#server) that corresponds to `demo.example.com`, and there is a [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) that [points](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) to your application (see [Step 10](#oidc_app)) at `http://127.0.0.1:8080` that is going to be OIDC-protected: + + ```nginx + http { + + # ... + + server { + listen 443 ssl; + server_name demo.example.com; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + + # ... + + proxy_pass http://127.0.0.1:8080; + } + } + # ... + } + ``` + +8. Protect this [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) with Entra ID OIDC by specifying the [`auth_oidc`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#auth_oidc) directive that will point to the `entra` configuration specified in the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context in [Step 5](#entra-setup-oidc-provider): + + ```nginx + # ... + location / { + + auth_oidc entra; + + # ... + + proxy_pass http://127.0.0.1:8080; + + } + # ... + ``` + +9. Pass the OIDC claims as headers to the application ([Step 10](#oidc_app)) with the [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive. These claims are extracted from the ID token returned by Entra ID: + + - [`$oidc_claim_sub`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - a unique `Subject` identifier assigned for each user by Entra ID + + - [`$oidc_claim_email`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - the e-mail address of the user + + - [`$oidc_claim_name`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - the full name of the user + + - 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 / { + + auth_oidc entra; + + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + # ... + ``` + + +10. 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 + # ... + server { + listen 8080; + + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nSub: $http_sub\n"; + default_type text/plain; + } + } + ``` +11. Save the NGINX configuration file and reload the configuration: + ```nginx + nginx -s reload + ``` + +### Complete Example + +This configuration example summarizes the steps outlined above. It includes only essential settings such as specifying the DNS resolver, defining the OIDC provider, configuring SSL, and proxying requests to an internal server. + +```nginx +http { + # Use a public DNS resolver for Issuer discovery, etc. + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider entra { + # The issuer is typically something like: + # https://login.microsoftonline.com//v2.0 + issuer https://login.microsoftonline.com//v2.0; + + # Replace with your actual Entra client_id and client_secret + client_id ; + client_secret ; + } + + server { + listen 443 ssl; + server_name demo.example.com; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + # Protect this location with Entra OIDC + auth_oidc entra; + + # Forward OIDC claims as headers if desired + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + } + + server { + listen 8080; + + location / { + return 200 "Hello, $http_username!\n Your email is $http_email\n Your unique id is $http_sub\n"; + default_type text/plain; + } + } +} +``` + +### Testing + +1. Open `https://demo.example.com/` in a browser. You will be automatically redirected to the Enra ID sign-in page. + +2. Enter valid Entra ID credentials of a user who has access the application. Upon successful sign-in, Entra ID redirects you back to NGINX Plus, and you will see the proxied application content (for example, “Hello, Jane Doe!”). + +{{}}If you restricted access to a group of users, be sure to select a user who has access to the application.{{}} + + +## See Also + +- [Microsoft identity platform documentation](https://learn.microsoft.com/en-us/entra/identity-platform/) + +- [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) + +- [Release Notes for NGINX Plus R34]({{< ref "nginx/releases.md#r34" >}}) + +## Revision History + +- Version 1 (March 2025) – Initial version (NGINX Plus Release 34) diff --git a/content/nginx/deployment-guides/single-sign-on/keycloak.md b/content/nginx/deployment-guides/single-sign-on/keycloak.md index d3c2a84ac..b0c17dfd1 100644 --- a/content/nginx/deployment-guides/single-sign-on/keycloak.md +++ b/content/nginx/deployment-guides/single-sign-on/keycloak.md @@ -1,168 +1,298 @@ --- -description: Enable OpenID Connect-based single-sign for applications proxied by NGINX - Plus, using Keycloak as the identity provider (IdP). -docs: DOCS-465 -title: Single Sign-On with Keycloak -toc: true -weight: 100 +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 +toc: true +weight: 500 --- -This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Keycloak](https://www.keycloak.org/) as the identity provider (IdP), and NGINX Plus as the relying party. +This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Keycloak](https://www.keycloak.org/) as the Identity Provider (IdP), and NGINX Plus as the Relying Party, or OIDC client application that verifies user identity. -{{< see-also >}}{{< include "nginx-plus/nginx-openid-repo-note.txt" >}}{{< /see-also >}} +{{< note >}} This guide applies to [NGINX Plus Release 34]({{< ref "nginx/releases.md#r34" >}}) 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.{{< /note >}} - ## Prerequisites -The instructions assume you have the following: +- A running [Keycloak](https://www.keycloak.org/) server version compatible with OIDC. -- A running Keycloak server. See the Keycloak documentation for [Getting Started](https://www.keycloak.org/guides#getting-started) and [Server](https://www.keycloak.org/guides#server) configuration instructions. -- An NGINX Plus subscription and NGINX Plus R15 or later. For installation instructions, see the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). -- The [NGINX JavaScript module](https://www.nginx.com/blog/introduction-nginscript/) (njs), required for handling the interaction between NGINX Plus and the IdP. After installing NGINX Plus, install the module with the command for your operating system. +- An NGINX Plus [subscription](https://www.f5.com/products/nginx/nginx-plus) and NGINX Plus [Release 34](({{< ref "nginx/releases.md#r34" >}})) or later. For installation instructions, see [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). - For Debian and Ubuntu: +- A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`. - ```none - sudo apt install nginx-plus-module-njs - ``` - For CentOS, RHEL, and Oracle Linux: +## Configure Keycloak {#keycloak-setup} - ```shell - sudo yum install nginx-plus-module-njs - ``` +1. Log in to your Keycloak admin console, for example, `https:///auth/admin/`. -- The following directive included in the top-level ("main") configuration context in **/etc/nginx/nginx.conf**, to load the NGINX JavaScript module: +2. In the left navigation, go to **Clients**.then - ```nginx - load_module modules/ngx_http_js_module.so; - ``` +3. Select **Create** and provide the following details: - -## Configuring Keycloak + - Enter a **Client ID**, for example, `nginx-demo-app`. You will need it later when configuring NGINX Plus. -**Note:** The following procedure reflects the Keycloak GUI at the time of publication, but the GUI is subject to change. Use this guide as a reference and adapt to the current Keycloak GUI as necessary. + - Set **Client Protocol** to **openid-connect**. -Create a Keycloak client for NGINX Plus in the Keycloak GUI: + - Select **Save**. -1. Access the Keycloak Admin Console at **http://_keycloak-server-address_:8080/auth/admin/** and log in. +4. In the **Settings** tab of your new client: -2. In the left navigation column, click **Clients**. On the **Clients** page that opens, click the **Create** button in the upper right corner. + - Set **Access Type** to `confidential`. - -3. On the **Add Client** page that opens, enter or select these values, then click the  Save  button. + - Add a **Redirect URI**, for example: + ``` + https://demo.example.com/oidc_callback + ``` + - Select **Save**. - - **Client ID** – The name of the application for which you're enabling SSO (Keycloak refers to it as the “client”). Here we're using NGINX-Plus. - - **Client Protocol** – openid-connect. +5. In the **Credentials** tab, make note of the **Client Secret**. You will need it later when configuring NGINX Plus. - +### Assign Users or Groups -4. On the **NGINX Plus** page that opens, enter or select these values on the Settings tab: +This step is optional, and is necessary if you need to restrict or organize user permissions. - - **Access Type** – confidential - - **Valid Redirect URIs** – The URI of the NGINX Plus instance, including the port number, and ending in **/\_codexch** (in this guide it is https://my-nginx.example.com:443/_codexch) +1. In the **Roles** tab, add a **Client Role**, for example, `nginx-keycloak-role`. - **Notes:** +2. Under **Users**, create a new user or select a user. - - For production, we strongly recommend that you use SSL/TLS (port 443). - - The port number is mandatory even when you're using the default port for HTTP (80) or HTTPS (443). +3. In **Role Mappings**, assign a role to the user within the `nginx-demo-app` client. - +{{< note >}} You will need the values of **Client ID**, **Client Secret**, and **Issuer** in the next steps. {{< /note >}} - -5. Click the Credentials tab and make a note of the value in the **Secret** field. You will copy it into the NGINX Plus configuration file in [Step 4 of _Configuring NGINX Plus_](#nginx-plus-variables). - +## Set up NGINX Plus {#nginx-plus-setup} -6. Click the Roles tab, then click the **Add Role** button in the upper right corner of the page that opens. +With Keycloak configured, you can enable OIDC on NGINX Plus. NGINX Plus serves as the Rely Party (RP) application — a client service that verifies user identity. -7. On the **Add Role** page that opens, type a value in the **Role Name** field (here it is nginx-keycloak-role) and click the  Save  button. +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 34 or later: -8. In the left navigation column, click **Users**. On the **Users** page that opens, either click the name of an existing user, or click the **Add user** button in the upper right corner to create a new user. For complete instructions, see the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/index.html#user-management). + ```none + nginx version: nginx/1.27.4 (nginx-plus-r34) + ``` + +2. Ensure that you have the values of the **Client ID**, **Client Secret**, and **Issuer** obtained during [Keycloak Configuration](#keycloak-setup). - -9. On the management page for the user (here, user01), click the Role Mappings tab. On the page that opens, select NGINX-Plus on the **Client Roles** drop‑down menu. Click nginx-keycloak-role in the **Available Roles** box, then click the **Add selected** button below the box. The role then appears in the **Assigned Roles** and **Effective Roles** boxes, as shown in the screenshot. +3. In your preferred text editor, open the NGINX configuration file (`/etc/nginx/nginx.conf` for Linux or `/usr/local/etc/nginx/nginx.conf` for FreeBSD). - +4. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, make sure your public DNS resolver is specified with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive: By default, NGINX Plus re‑resolves DNS records at the frequency specified by time‑to‑live (TTL) in the record, but you can override the TTL value with the `valid` parameter: + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + # ... + } + ``` + + +5. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, define the Keycloak provider named `keycloak` by specifying the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context: + + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider keycloak { + + # ... + + } + # ... + } + ``` - -## Configuring NGINX Plus +6. In the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context, specify: -Configure NGINX Plus as the OpenID Connect relying party: + - your actual Keycloak **Client ID** obtained in [Keycloak Configuration](#keycloak-setup) with the [`client_id`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_id) directive -1. Create a clone of the [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) GitHub repository. + - your **Client Secret** obtained in [Keycloak Configuration](#keycloak-setup) with the [`client_secret`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive - ```shell - git clone https://github.com/nginxinc/nginx-openid-connect - ``` + - the **Issuer** URL obtained in [Keycloak Configuration](#keycloak-setup) with the [`issuer`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive -2. Copy these files from the clone to **/etc/nginx/conf.d**: + The `issuer` is typically your Keycloak OIDC URL: - - **frontend.conf** - - **openid\_connect.js** - - **openid\_connect.server\_conf** - - **openid\_connect\_configuration.conf** + `https:///realms/`. - -3. Get the URLs for the authorization endpoint, token endpoint, and JSON Web Key (JWK) file from the Keycloak configuration. Run the following `curl` command in a terminal, piping the output to the indicated `python` command to output the entire configuration in an easily readable format. We've abridged the output to show only the relevant fields. + By default, NGINX Plus creates the metadata URL by appending the `/.well-known/openid-configuration` part to the Issuer URL. If your metadata URL is different, you can explicitly specify it with the [`config_url`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#config_url) directive. - ```shell - $ curl https:///auth/realms/master/.well-known/openid-configuration | python -m json.tool - ... - { - "authorization_endpoint": "https:///auth/realms/master/protocol/openid-connect/auth", - ... - "jwks_uri": "https:///auth/realms/master/protocol/openid-connect/certs", - ... - "token_endpoint": "https:///auth/realms/master/protocol/openid-connect/token", - ... + - **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. + + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider keycloak { + issuer https:///realms/; + client_id ; + client_secret ; + } + + # ... + } + ``` + +7. Make sure you have configured a [server](https://nginx.org/en/docs/http/ngx_http_core_module.html#server) that corresponds to `demo.example.com`, and there is a [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) that [points](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) to your application (see [Step 10](#oidc_app)) at `http://127.0.0.1:8080` that is going to be OIDC-protected: + + ```nginx + http { + # ... + + server { + listen 443 ssl; + server_name demo.example.com; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + + # ... + + proxy_pass http://127.0.0.1:8080; + } + } + # ... } ``` - -4. Using your preferred text editor, open **/etc/nginx/conf.d/openid_connect_configuration.conf**. Change the "default" parameter value of each of the following [map](https://nginx.org/en/docs/http/ngx_http_map_module.html#map) directives to the specified value: +8. Protect this [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) with Keycloak OIDC by specifying the [`auth_oidc`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#auth_oidc) directive that will point to the `keycloak` configuration specified in the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context in [Step 5](#keycloak-setup-oidc-provider): - - `map $host $oidc_authz_endpoint` – Value of `authorization_endpoint` from [Step 3](#nginx-plus-urls) (in this guide, `https:///auth/realms/master/protocol/openid-connect/auth`) - - `map $host $oidc_token_endpoint` – Value of `token_endpoint` from [Step 3](#nginx-plus-urls) (in this guide, `https:///auth/realms/master/protocol/openid-connect/token`) - - `map $host $oidc_client` – Value in the **Client ID** field from [Step 3 of _Configuring Keycloak_](#keycloak-client-id) (in this guide, `NGINX Plus`) - - `map $host $oidc_client_secret` – Value in the **Secret** field from [Step 5 of _Configuring Keycloak_](#keycloak-secret) (in this guide, ``) - - `map $host $oidc_hmac_key` – A unique, long, and secure phrase + ```nginx + # ... + location / { + auth_oidc keycloak; + + # ... + + proxy_pass http://127.0.0.1:8080; + } + # ... + ``` -5. Configure the JWK file. The procedure depends on which version of NGINX Plus you are using. +9. Pass the OIDC claims as headers to the application ([Step 10](#oidc_app)) with the [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive. These claims are extracted from the ID token returned by Keycloak: + + - [`$oidc_claim_sub`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - a unique `Subject` identifier assigned for each user by Keycloak + + - [`$oidc_claim_email`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) the e-mail address of the user + + - [`$oidc_claim_name`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - the full name of the user + + - 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 / { + auth_oidc keycloak; + + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + # ... + ``` + + +10. 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 + # ... + server { + listen 8080; + + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nSub: $http_sub\n"; + default_type text/plain; + } + } + ``` +11. Save the NGINX configuration file and reload the configuration: + ```nginx + nginx -s reload + ``` + +### Complete Example + +This configuration example summarizes the steps outlined above. It includes only essential settings such as specifying the DNS resolver, defining the OIDC provider, configuring SSL, and proxying requests to an internal server. + +```nginx +http { + # Use a public DNS resolver for Issuer discovery, etc. + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider keycloak { + # The 'issuer' typically matches your Keycloak realm's base URL: + # For example: https:///realms/ + issuer https:///realms/master; + + # Replace with your actual Keycloak client_id and secret + client_id ; + client_secret ; + + # If the .well-known endpoint can’t be derived automatically, + # specify config_url: + # config_url https:///realms/master/.well-known/openid-configuration; + } + + server { + listen 443 ssl; + server_name demo.example.com; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + # Protect this location with Keycloak OIDC + auth_oidc keycloak; + + # Forward OIDC claims as headers if desired + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + } + + server { + # Simple test backend + listen 8080; + + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nSub: $http_sub\n"; + default_type text/plain; + } + } +} +``` - - In NGINX Plus R17 and later, NGINX Plus can read the JWK file directly from the URL reported as `jwks_uri` in [Step 3](#nginx-plus-urls). Change **/etc/nginx/conf.d/frontend.conf** as follows: +### Testing - 1. Comment out (or remove) the [auth_jwt_key_file](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_file) directive. +1. Open https://demo.example.com/ in a browser. You should be redirected to Keycloak’s login page for your realm. - 2. Uncomment the [auth_jwt_key_request](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_request) directive. (Its parameter, `/_jwks_uri`, refers to the value of the `$oidc_jwt_keyfile` variable, which you set in the next step.) - 3. Change the "default" parameter of the `map $host $oidc_jwt_keyfile` directive to the value reported in the `jwks_uri` field in [Step 3](#nginx-plus-urls) (in this guide, `https:///auth/realms/master/protocol/openid-connect/certs`). +2. Enter valid Keycloak credentials for a user assigned to the `nginx-demo-app` client. +Upon successful sign-in, Keycloak redirects you back to NGINX Plus, and you will see the proxied application content (for example, “Hello, Jane Doe!”). - - In NGINX Plus R16 and earlier, the JWK file must be on the local disk. (You can also use this method with NGINX Plus R17 and later if you wish.) - 1. Copy the JSON contents from the JWK file named in the `jwks_uri` field in [Step 3](#nginx-plus-urls) (in this guide, `https:///auth/realms/master/protocol/openid-connect/certs`) to a local file (for example, `/etc/nginx/my_keycloak_jwk.json`). - 2. In **/etc/nginx/conf.d/openid_connect_configuration.conf**, change the "default" parameter of the `map $host $oidc_jwt_keyfile` directive to the local file path. +## Legacy njs-based Keycloak Solution {#legacy-njs-guide} -6. Confirm that the user named by the [user](http://nginx.org/en/docs/ngx_core_module.html#user) directive in the NGINX Plus configuration (in **/etc/nginx/nginx.conf** by convention) has read permission on the JWK file. +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. - -## Testing -In a browser, enter the address of your NGINX Plus instance and try to log in using the credentials of a user mapped to the role for NGINX Plus (see [Step 9 of _Configuring Keycloak_](#keycloak-users)). +## See Also - +- [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) - -## Troubleshooting +- [Release Notes for NGINX Plus R34]({{< ref "nginx/releases.md#r34" >}}) -See the [**Troubleshooting**](https://github.com/nginxinc/nginx-openid-connect#troubleshooting) section at the nginx-openid-connect repository on GitHub. -### Revision History +## Revision History -- Version 2 (March 2020) – Updates to _Configuring NGINX Plus_ section -- Version 1 (November 2019) – Initial version (NGINX Plus Release 19) +- Version 1 (March 2025) – Initial version (NGINX Plus Release 34) diff --git a/content/nginx/deployment-guides/single-sign-on/oidc-njs/_index.md b/content/nginx/deployment-guides/single-sign-on/oidc-njs/_index.md new file mode 100644 index 000000000..658ea11ab --- /dev/null +++ b/content/nginx/deployment-guides/single-sign-on/oidc-njs/_index.md @@ -0,0 +1,8 @@ +--- +description: Learn how to use OpenID Connect (OIDC) Provider Servers and Services + to enable single sign-on for applications proxied by F5 NGINX Plus. +title: Legacy njs-based Single Sign-On Solutions +weight: 990 +url: /nginx/deployment-guides/single-signon/oidc-njs/ +product: NGINX-PLUS +--- diff --git a/content/nginx/deployment-guides/single-sign-on/oidc-njs/active-directory-federation-services.md b/content/nginx/deployment-guides/single-sign-on/oidc-njs/active-directory-federation-services.md new file mode 100644 index 000000000..5f6ff547c --- /dev/null +++ b/content/nginx/deployment-guides/single-sign-on/oidc-njs/active-directory-federation-services.md @@ -0,0 +1,158 @@ +--- +description: Enable OpenID Connect-based single-sign for applications proxied by NGINX + Plus, using Microsoft AD FS as the identity provider (IdP). +docs: DOCS-463 +type: +- how-to +title: Single Sign-On with Microsoft AD FS and njs +toc: false +weight: 100 +product: NGINX-PLUS +--- + +{{< note >}} This guide applies to NGINX Plus [Release 15]({{< ref "nginx/releases.md#r15" >}}) and later, based on the [`nginx-openid-connect`](https://github.com/nginxinc/nginx-openid-connect) GitHub repo. Starting with NGINX Plus [Release 34]({{< ref "nginx/releases.md#r34" >}}), use the simpler solution with the [native OpenID connect module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html). + +See [Single Sign-On With Microsoft AD FS]({{< ref "nginx/deployment-guides/single-sign-on/active-directory-federation-services.md" >}}) for details.{{< /note >}} + +This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Microsoft Active Directory Federation Services](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services) (AD FS) as the identity provider (IdP) and NGINX Plus as the relying party. + +{{< see-also >}}{{< readfile file="includes/nginx-openid-repo-note.txt" markdown="true" >}}{{< /see-also >}} + + +## Prerequisites + +The instructions assume you have the following: + +- A running deployment of AD FS, either on‑premises or in Azure. +- An NGINX Plus subscription and NGINX Plus R15 or later. For installation instructions, see the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). +- The [NGINX JavaScript module](https://www.nginx.com/blog/introduction-nginscript/) (njs), required for handling the interaction between NGINX Plus and the IdP. After installing NGINX Plus, install the module with the command for your operating system. + + For Debian and Ubuntu: + + ```none + sudo apt install nginx-plus-module-njs + ``` + + For CentOS, RHEL, and Oracle Linux: + + ```shell + sudo yum install nginx-plus-module-njs + ``` + +- The following directive included in the top-level ("main") configuration context in **/etc/nginx/nginx.conf**, to load the NGINX JavaScript module: + + ```nginx + load_module modules/ngx_http_js_module.so; + ``` + + +## Configuring AD FS + +Create an AD FS application for NGINX Plus: + +1. Open the AD FS Management window. In the navigation column on the left, right‑click on the **Application Groups** folder and select Add Application Group from the drop‑down menu. + + The Add Application Group Wizard window opens. The left navigation column shows the steps you will complete to add an application group. + +2. In the **Welcome** step, type the application group name in the **Name** field. Here we are using ADFSSSO. In the **Template** field, select **Server application** under Standalone applications. Click the  Next >  button. + + + + +3. In the **Server application** step: + + 1. Make a note of the value in the **Client Identifier** field. You will add it to the NGINX Plus configuration in [Step 4 of _Configuring NGINX Plus_](#nginx-plus-variables).
+ + 2. In the **Redirect URI** field, type the URI of the NGINX Plus instance including the port number, and ending in **/\_codexch**. Here we’re using https://my-nginx.example.com:443/\_codexch. Click the  Add  button. + + **Notes:** + + - For production, we strongly recommend that you use SSL/TLS (port 443). + - The port number is mandatory even when you're using the default port for HTTP (80) or HTTPS (443). + +3. Click the  Next >  button. + + + + +4. In the Configure Application Credentials step, click the Generate a shared secret checkbox. Make a note of the secret that AD FS generates (perhaps by clicking the Copy to clipboard button and pasting the clipboard content into a file). You will add the secret to the NGINX Plus configuration in [Step 4 of _Configuring NGINX Plus_](#nginx-plus-variables). Click the  Next >  button. + + + +5. In the **Summary** step, verify that the information is correct, make any necessary corrections to previous steps, and click the  Next >  button. + + + +## Configuring NGINX Plus + +Configure NGINX Plus as the OpenID Connect relying party: + +1. Create a clone of the [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) GitHub repository. + + ```shell + git clone https://github.com/nginxinc/nginx-openid-connect + ``` + +2. Copy these files from the clone to **/etc/nginx/conf.d**: + + - **frontend.conf** + - **openid\_connect.js** + - **openid\_connect.server\_conf** + - **openid\_connect\_configuration.conf** + + +3. Get the URLs for the authorization endpoint, token endpoint, and JSON Web Key (JWK) file from the AD FS configuration. Run the following `curl` command in a terminal, piping the output to the indicated `python` command to output the entire configuration in an easily readable format. We've abridged the output to show only the relevant fields. + + ```shell + $ curl https:///oidc/adfs/.well-known/openid-configuration | python -m json.tool + { + ... + "authorization_endpoint": "https:///oidc/adfs/auth", + ... + "jwks_uri": "https:///oidc/adfs/certs", + ... + "token_endpoint": "https:///oidc/adfs/token", + ... + } + ``` + + +4. In your preferred text editor, open **/etc/nginx/conf.d/frontend.conf**. Change the "default" parameter value of each of the following [map](https://nginx.org/en/docs/http/ngx_http_map_module.html#map) directives to the specified value: + + - `map $host $oidc_authz_endpoint` – Value of `authorization_endpoint` from [Step 3](#nginx-plus-urls) (in this guide, `https:///oidc/adfs/auth`) + - `map $host $oidc_token_endpoint` – Value of `token_endpoint` from [Step 3](#nginx-plus-urls) (in this guide, `https:///oidc/adfs/token`) + - `map $host $oidc_client` – Value in the **Client ID** field from [Step 3 of _Configuring AD FS_](#ad-fs-server-application) (in this guide, `3e23f0eb-9329-46ff-9d37-6ad24afdfaeb`) + - `map $host $oidc_client_secret` – Value in the **Client secret** field from [Step 4 of _Configuring AD FS_](#ad-fs-configure-application-credentials) (in this guide, `NUeuULtSCjgXTGSkq3ZwEeCOiig4-rB2XiW_W`) + - `map $host $oidc_hmac_key` – A unique, long, and secure phrase + +5. Configure the JWK file. The procedure depends on which version of NGINX Plus you are using. + + - In NGINX Plus R17 and later, NGINX Plus can read the JWK file directly from the URL reported as `jwks_uri` in [Step 3](#nginx-plus-urls). Change **/etc/nginx/conf.d/frontend.conf** as follows: + + 1. Comment out (or remove) the [auth_jwt_key_file](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_file) directive. + 2. Uncomment the [auth_jwt_key_request](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_request) directive. (Its parameter, `/_jwks_uri`, refers to the value of the `$oidc_jwt_keyfile` variable, which you set in the next step.) + 3. Change the second parameter of the `set $oidc_jwt_keyfile` directive to the value reported in the `jwks_uri` field in [Step 3](#nginx-plus-urls) (in this guide, `https:///oidc/adfs/certs`). + + - In NGINX Plus R16 and earlier, the JWK file must be on the local disk. (You can also use this method with NGINX Plus R17 and later if you wish.) + + 1. Copy the JSON contents from the JWK file named in the `jwks_uri` field in [Step 3](#nginx-plus-urls) (in this guide, `https:///oidc/adfs/certs`) to a local file (for example, `/etc/nginx/my_adfs_jwk.json`). + 2. In **/etc/nginx/conf.d/frontend.conf**, change the second parameter of the `set $oidc_jwt_keyfile` directive to the local file path. + +6. Confirm that the user named by the [user](http://nginx.org/en/docs/ngx_core_module.html#user) directive in the NGINX Plus configuration (in **/etc/nginx/nginx.conf** by convention) has read permission on the JWK file. + + +## Testing + +In a browser, enter the address of your NGINX Plus instance and try to log in using the credentials of a user who has access to the application. + + + + +## Troubleshooting + +See the [**Troubleshooting**](https://github.com/nginxinc/nginx-openid-connect#troubleshooting) section at the nginx-openid-connect repository on GitHub. + +### Revision History + +- Version 2 (March 2020) – Updates to _Configuring NGINX Plus_ section +- Version 1 (December 2019) – Initial version (NGINX Plus Release 20) diff --git a/content/nginx/deployment-guides/single-sign-on/oidc-njs/auth0.md b/content/nginx/deployment-guides/single-sign-on/oidc-njs/auth0.md new file mode 100644 index 000000000..71d7f6f26 --- /dev/null +++ b/content/nginx/deployment-guides/single-sign-on/oidc-njs/auth0.md @@ -0,0 +1,186 @@ +--- +description: Learn how to enable single sign-on (SSO) with [Auth0](https://auth0.com/) + for applications proxied by F5 NGINX Plus. +docs: DOCS-884 +type: +- tutorial +title: Single Sign-On With Auth0 and njs +toc: false +weight: 100 +product: NGINX-PLUS +--- + +{{< note >}} This guide applies to NGINX Plus [Release 15]({{< ref "nginx/releases.md#r15" >}}) and later, based on the [`nginx-openid-connect`](https://github.com/nginxinc/nginx-openid-connect) GitHub repo. Starting with NGINX Plus [Release 34]({{< ref "nginx/releases.md#r34" >}}), use the simpler solution with the [native OpenID connect module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html). + +See [Single Sign-On With Auth0]({{< ref "nginx/deployment-guides/single-sign-on/auth0.md" >}}) for details.{{< /note >}} + +You can use F5 NGINX Plus with [Auth0](https://auth0.com/) and OpenID Connect to enable single sign-on (SSO) for your proxied applications. By following the steps in this guide, you will learn how to set up SSO using OpenID Connect as the authentication mechanism, with Auth0 as the identity provider (IdP), and NGINX Plus as the relying party. + +{{< see-also >}}{{< readfile file="includes/nginx-openid-repo-note.txt" markdown="true" >}}{{< /see-also >}} + +## Prerequisites + +To complete the steps in this guide, you need the following: + +- An Auth0 tenant with administrator privileges. +- [NGINX Plus](https://www.f5.com/products/nginx/nginx-plus) with a valid subscription. +- The [NGINX JavaScript module](https://www.nginx.com/products/nginx/modules/nginx-javascript/) (`njs`) -- the `njs` module handles the interaction between NGINX Plus and Auth0. + +## Install NGINX Plus and the njs Module {#install-nginx-plus-njs} + +1. If you do not already have NGINX Plus installed, follow the steps in the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) to do so. +2. Install the NGINX JavaScript module by following the steps in the [`njs` installation guide](https://nginx.org/en/docs/njs/install.html). +3. Add the following directive to the top-level ("main") configuration context in the NGINX Plus configuration (`/etc/nginx/nginx.conf`) to load the `njs` module: + + ```Nginx configuration file + load_module modules/ngx_http_js_module.so; + ``` + +## Configure Auth0 {#config-auth0} + +Take the steps in this section to create a new application for NGINX Plus. + +{{< note >}} This section contains images that reflect the state of the Auth0 web interface at the time of publication. The actual Auth0 GUI may differ from the examples shown here. Use this guide as a reference and adapt the instructions to suit the current Auth0 GUI as necessary.{{< /note >}} + +### Create a new Auth0 Application {#create-auth0-app} + +1. Log in to your Auth0 Dashboard at [manage.auth0.com](https://manage.auth0.com/). +1. Select **Applications > Applications** from the sidebar menu. +1. On the **Applications** page, select the **Create Application** button. +1. In the **Create application** window, provide the information listed below and then select **Create**. + + - **Name**: A name for the application, for example "nginx-plus-app". + - **Application Type**: **Regular Web Applications** + + {{< img src="/img/sso/auth0/sso-auth0-create-app.png" alt="image showing the Create application window in the Auth0 dashboard" >}} + +### Set up the Web Application {#web-app-setup} + +In this section, you'll set up a web application that follows the Auth0 [Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow). + +1. On the **Application** page in the [Auth0 dashboard](https://manage.auth0.com/), select your web application. +1. Select the **Settings** tab for your application. +1. Make note of the Client ID and Client Secret displayed in the **Basic Information** section. + + {{< img src="/img/sso/auth0/sso-auth0-app.png" alt="image showing the basic information section of the web application settings in the Auth0 dashboard" >}} + +1. In the **Application URIs** section, provide the URI of the NGINX Plus instance in the **Allowed Callback URLs** field. + + - The URL must include the port number and end in **/_codexch**. In our example, we used the URL `http://nginx-plus-app:8010/_codexch`. + - The port is always required, even if you use the default port for HTTP (`80`) or HTTPS (`443`). + - The use of SSL/TLS (`443`) is strongly recommended for production environments. + + {{< img src="/img/sso/auth0/sso-auth0-app-settings.png" alt="image showing the Application URIs settings in the Auth0 dashboard" >}} + +1. In the **Advanced Settings** section, select the **Endpoints** tab. +1. Make note of the **OpenID Configuration** URL. + + {{< img src="/img/sso/auth0/sso-auth0-app-advanced-settings.png" alt="image showing the Advanced Application Settings section of the Auth0 dashboard" >}} + +1. Select **Save Changes**. + +### Set up Authentication {#authn-setup} + +{{< note >}}For the purposes of this guide, we will add a new Auth0 user database and user account to use for testing. + +You can set up authentication using any of the available [Auth0 identity providers](https://auth0.com/docs/authenticate/identity-providers). {{< /note >}} + +To set up a new user database and add a user account to it, take the steps below. + +1. Log in to the [Auth0 dashboard](https://manage.auth0.com/) and select **Authentication > Database** from the sidebar menu. +1. Select the **Create DB Connection** button. +1. Provide a **Name** for the database connection, then select **Create**. +1. On the **Database** page, select the **Applications** tab. Then, select the toggle button next to the [application you created earlier](#create-a-new-auth0-application). + + {{< img src="/img/sso/auth0/sso-auth0-db-app.png" alt="image showing the Applications settings for an OIDC Authentication database in the Auth0 dashboard" >}} + +1. In the sidebar menu, select **User Management > Users**. +1. On the **Users** page, select the **Create User** button. +1. In the **Create user** window, provide the following information, then select **Create**. + - **Email**: user's email + - **Password**: a password for the user account + - **Connection**: select your **database** from the list. + + {{< img src="/img/sso/auth0/sso-auth0-create-user.png" alt="image showing the Create User settings window in the Auth0 dashboard" >}} + +The user should receive an email to the email address provided. Once the user verifies their account by clicking on the link in the email, the account creation process is complete. + +## Set up NGINX Plus {#nginx-plus-setup} + +Take the steps in this section to set up NGINX Plus as the OpenID Connect relying party. + +### Configure NGINX OpenID Connect {#nginx-plus-oidc-config} + +1. Clone the [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) GitHub repository, or download the repo files. + + ```bash + git clone https://github.com/nginxinc/nginx-openid-connect.git + ``` + +1. Run the *configure.sh* script, which will update the NGINX configuration files with the values for your Auth0 application. + + For example: + + ```bash + ./nginx-openid-connect/configure.sh \ + --auth_jwt_key request \ + --client_id Nhotzxx...IERmUi \ + --client_secret 6ZHd0j_r...UtDZ5bkdu \ + https://.us.auth0.com/.well-known/openid-configuration + ``` + +1. In the `frontend.conf` file, update the **my_backend** upstream with the address of the application that you want to add OIDC authorization to. + + For example: + + ```Nginx configuration file + upstream my_backend { + zone my_backend 64k; + server my-backend-app.com:80; + } + ``` + +1. In the *openid_connect.server_conf* file, add the [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive to the `/_jwks_uri` and `/_token` locations to `Accept-Encoding "gzip"`, as shown below. + + ```Nginx configuration file + ... + location = /_jwks_uri { + ... + proxy_set_header Accept-Encoding "gzip" + } + ... + location = /_token { + ... + proxy_set_header Accept-Encoding "gzip" + } + ... + ``` + +1. Copy the following files to the */etc/nginx/conf.d* directory on the host machine where NGINX Plus is installed: + + - `frontend.conf` + - `openid_connect.js` + - `openid_connect.server_conf` + - `openid_connect_configuration.conf` + +1. Reload the NGINX configuration: + + ```bash + sudo nginx -s reload + ``` + +## Test the Setup + +1. In a browser, enter the address of your NGINX Plus instance. You should be directed to the Auth0 login page, as shown in the example below. + + {{< img src="/img/sso/auth0/sso-auth0-login-test.png" alt="image showing an example Auth0 login screen that contains username and password fields" >}} + +1. You should be able to log in using the credentials of the user account that you created in the Auth0 database. + +## Troubleshooting + +Refer to the [Troubleshooting](https://github.com/nginxinc/nginx-openid-connect#troubleshooting) section in the `nginx-openid-connect` repository on GitHub. + +## Revision History + +- Version 1 (May 2022) - Initial version diff --git a/content/nginx/deployment-guides/single-sign-on/oidc-njs/cognito.md b/content/nginx/deployment-guides/single-sign-on/oidc-njs/cognito.md new file mode 100644 index 000000000..21a17b064 --- /dev/null +++ b/content/nginx/deployment-guides/single-sign-on/oidc-njs/cognito.md @@ -0,0 +1,194 @@ +--- +description: Enable OpenID Connect-based single-sign for applications proxied by NGINX + Plus, using Amazon Cognito as the identity provider (IdP). +docs: DOCS-464 +type: +- how-to +title: Single Sign-On with Amazon Cognito and njs +toc: false +weight: 100 +product: NGINX-PLUS +--- + +{{< note >}} This guide applies to NGINX Plus [Release 15]({{< ref "nginx/releases.md#r15" >}}) and later, based on the [`nginx-openid-connect`](https://github.com/nginxinc/nginx-openid-connect) GitHub repo. Starting with NGINX Plus [Release 34]({{< ref "nginx/releases.md#r34" >}}), use the simpler solution with the [native OpenID connect module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html). + +See [Single Sign-On With Amazon Cognito]({{< ref "nginx/deployment-guides/single-sign-on/cognito.md" >}}) for details.{{< /note >}} + +This guide explains how to enable single sign‑on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Amazon Cognito](https://aws.amazon.com/cognito/) as the identity provider (IdP), and NGINX Plus as the relying party. + +{{< see-also >}}{{< readfile file="includes/nginx-openid-repo-note.txt" markdown="true" >}}{{< /see-also >}} + + + +## Prerequisites + +The instructions assume you have the following: + +- An [AWS account](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/). +- An NGINX Plus subscription and NGINX Plus R15 or later. For installation instructions, see the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). +- The [NGINX JavaScript module](https://www.nginx.com/blog/introduction-nginscript/) (njs), required for handling the interaction between NGINX Plus and the IdP. After installing NGINX Plus, install the module with the command for your operating system. + + For Debian and Ubuntu: + + ```none + sudo apt install nginx-plus-module-njs + ``` + + For CentOS, RHEL, and Oracle Linux: + + ```shell + sudo yum install nginx-plus-module-njs + ``` + +- The following directive included in the top-level ("main") configuration context in **/etc/nginx/nginx.conf**, to load the NGINX JavaScript module: + + ```nginx + load_module modules/ngx_http_js_module.so; + ``` + + +## Configuring Amazon Cognito + +**Note:** The following procedure reflects the Cognito GUI at the time of publication, but the GUI is subject to change. Use this guide as a reference and adapt to the current Cognito GUI as necessary. + +Create a new application for NGINX Plus in the Cognito GUI: + +1. Log in to your AWS account, open the AWS Management Console ([console.aws.amazon.com](https://console.aws.amazon.com)), and navigate to the Cognito dashboard (you can, for example, click **Cognito** in the **Security, Identity, & Compliance** section of the **Services** drop‑down menu). + +2. On the Cognito dashboard, click **Manage User Pools** to open the **Your User Pools** window. Click the  Create a user pool  button or the highlighted phrase. + + + +3. In the **Create a user pool** window that opens, type a value in the **Pool name** field (in this guide, it's nginx-plus-pool), then click the Review defaults button. + + + + +4. On the **Review** tab which opens, click Add app client... in the **App clients** field near the bottom. + + + +5. On the **App clients** tab which opens, click Add an app client. + +6. On the **Which app clients will have access to this user pool?** window which opens, enter a value (in this guide, nginx-plus-app) in the App client name field. Make sure the Generate client secret box is checked, then click the  Create app client  button. + + + +7. On the confirmation page which opens, click Return to pool details to return to the **Review** tab. On that tab click the  Create pool  button at the bottom. (The screenshot in [Step 4](#cognito-review-tab) shows the button.) + + +8. On the details page which opens to confirm the new user pool was successfully created, make note of the value in the **Pool Id** field; you will add it to the NGINX Plus configuration in [Step 3 of _Configuring NGINX Plus_](#nginx-plus-variables). + + 'General settings' tab in Amazon Cognito GUI + + +9. Click Users and groups in the left navigation column. In the interface that opens, designate the users (or group of users, on the **Groups** tab) who will be able to use SSO for the app being proxied by NGINX Plus. For instructions, see the Cognito documentation about [creating users](https://docs.aws.amazon.com/cognito/latest/developerguide/how-to-create-user-accounts.html), [importing users](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-using-import-tool.html), or [adding a group](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-user-groups.html). + + 'Users and groups' tab in Amazon Cognito GUI + +10. Click **App clients** in the left navigation bar. On the tab that opens, click the Show Details button in the box labeled with the app client name (in this guide, nginx-plus-app). + + 'App clients' tab in Amazon Cognito GUI + + +11. On the details page that opens, make note of the values in the App client id and App client secret fields. You will add them to the NGINX Plus configuration in [Step 3 of _Configuring NGINX Plus_](#nginx-plus-variables). + + + +12. Click App client settings in the left navigation column. In the tab that opens, perform the following steps: + + 1. In the Enabled Identity Providers section, click the Cognito User Pool checkbox (the **Select all** box gets checked automatically). + 2. In the **Callback URL(s)** field of the Sign in and sign out URLs section, type the URI of the NGINX Plus instance including the port number, and ending in **/\_codexch**. Here we’re using https://my-nginx-plus.example.com:443/_codexch. + + **Notes:** + + - For production, we strongly recommend that you use SSL/TLS (port 443). + - The port number is mandatory even when you're using the default port for HTTP (80) or HTTPS (443). + + 3. In the **OAuth 2.0** section, click the Authorization code grant checkbox under Allowed OAuth Flows and the **email**, **openid**, and **profile** checkboxes under Allowed OAuth Scopes. + 4. Click the  Save changes  button. + + + + +13. Click **Domain name** in the left navigation column. In the tab that opens, type a domain prefix in the **Domain prefix** field under Amazon Cognito domain (in this guide, my-nginx-plus). Click the  Save changes  button. + + + + +## Configuring NGINX Plus + +Configure NGINX Plus as the OpenID Connect relying party: + +1. Create a clone of the [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) GitHub repository. + + ```shell + git clone https://github.com/nginxinc/nginx-openid-connect + ``` + +2. Copy these files from the clone to **/etc/nginx/conf.d**: + + - **frontend.conf** + - **openid_connect.js** + - **openid_connect.server\_conf** + + +3. In your preferred text editor, open **/etc/nginx/conf.d/frontend.conf**. Change the second parameter of each of the following [set](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html#set) directives to the specified value. + + The `` variable is the full value in the **Domain prefix** field in [Step 13 of _Configuring Amazon Cognito_](#cognito-domain-name). In this guide it is https://my-nginx-plus.auth.us-east-2.amazoncognito.com. + + - `set $oidc_authz_endpoint` – `/oauth2/authorize` + - `set $oidc_token_endpoint` – `/oauth2/token` + - `set $oidc_client` – Value in the App client id field from [Step 11 of _Configuring Amazon Cognito_](#cognito-app-client-id-secret) (in this guide, `2or4cs8bjo1lkbq6143tqp6ist`) + - `set $oidc_client_secret` – Value in the App client secret field from [Step 11 of _Configuring Amazon Cognito_](#cognito-app-client-id-secret) (in this guide, `1k63m3nrcnu...`) + - `set $oidc_hmac_key` – A unique, long, and secure phrase + +4. Configure the JWK file. The file's URL is + + **https://cognito-idp.**_region_**.amazonaws.com/**_User-Pool-ID_**/.well-known/jwks.json** + + where + + - _region_ is the same AWS region name as in the `` variable used in [Step 3](#nginx-plus-variables) + - _User-Pool-ID_ is the value in the **Pool Id** field in [Step 8 of _Configuring Amazon Cognito_](#cognito-pool-id) + + In this guide, the URL is + + https://cognito-idp.us-east-2.amazonaws.com/us-east-2_mLoGHJpOs/.well-known/jwks.json. + + The method for configuring the JWK file depends on which version of NGINX Plus you are using: + + - In NGINX Plus R17 and later, NGINX Plus can read the JWK file directly. Change **/etc/nginx/conf.d/frontend.conf** as follows: + + 1. Comment out (or remove) the [auth_jwt_key_file](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_file) directive. + 2. Uncomment the [auth_jwt_key_request](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_request) directive. (Its parameter, `/_jwks_uri`, refers to the value of the `$oidc_jwt_keyfile` variable, which you set in the next step.) + 3. Change the second parameter of the `set $oidc_jwt_keyfile` directive to the URL of the JWK file (`https://cognito-idp.../.well-known/jwks.json`). + + - In NGINX Plus R16 and earlier, the JWK file must be on the local disk. (You can also use this method with NGINX Plus R17 and later if you wish.) + + 1. Copy the JSON contents from the JWK file (****) to a local file (for example, **/etc/nginx/my\_cognito\_jwk.json**). + 2. In **/etc/nginx/conf.d/frontend.conf**, change the second parameter of the `set $oidc_jwt_keyfile` directive to the local file path. + +5. At the time of publication, Cognito does not support the OpenID **offline_access** scope. Open **/etc/nginx/conf.d/openid\_connect.server\_conf** in a text editor and remove `+offline_access` from the list of scopes on line 10, so that it looks like this: + + ```nginx + return 302 "$oidc_authz_endpoint?response_type=code&scope=openid+profile+email&client_id=$oidc_clientaws...; + ``` + +6. Confirm that the user named by the [user](http://nginx.org/en/docs/ngx_core_module.html#user) directive in the NGINX Plus configuration (in **/etc/nginx/nginx.conf** by convention) has read permission on the JWK file. + + +## Testing + +In a browser, enter the address of your NGINX Plus instance and try to log in using the credentials of a user assigned to the application (see [Step 9 in _Configuring Amazon Cognito_](#cognito-users)). The NGINX logo that appears in the screenshot was added on Cognito's **UI customization** tab (not shown in this guide). + + + + +## Troubleshooting + +See the [**Troubleshooting**](https://github.com/nginxinc/nginx-openid-connect#troubleshooting) section at the nginx-openid-connect repository on GitHub. + +### Revision History + +- Version 1 (March 2020) – Initial version (NGINX Plus Release 20) diff --git a/content/nginx/deployment-guides/single-sign-on/oidc-njs/keycloak.md b/content/nginx/deployment-guides/single-sign-on/oidc-njs/keycloak.md new file mode 100644 index 000000000..aca6e1cac --- /dev/null +++ b/content/nginx/deployment-guides/single-sign-on/oidc-njs/keycloak.md @@ -0,0 +1,173 @@ +--- +description: Enable OpenID Connect-based single-sign for applications proxied by NGINX + Plus, using Keycloak as the identity provider (IdP). +docs: DOCS-465 +type: +- how-to +title: Single Sign-On with Keycloak and njs +toc: false +weight: 100 +product: NGINX-PLUS +--- + +{{< note >}} This guide applies to NGINX Plus [Release 15]({{< ref "nginx/releases.md#r15" >}}) and later, based on the [`nginx-openid-connect`](https://github.com/nginxinc/nginx-openid-connect) GitHub repo. Starting with NGINX Plus [Release 34]({{< ref "nginx/releases.md#r34" >}}), use the simpler solution with the [native OpenID connect module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html). + +See [Single Sign-On With Keycloak]({{< ref "nginx/deployment-guides/single-sign-on/keycloak.md" >}}) for details.{{< /note >}} + +This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Keycloak](https://www.keycloak.org/) as the identity provider (IdP), and NGINX Plus as the relying party. + +{{< see-also >}}{{< readfile file="includes/nginx-openid-repo-note.txt" markdown="true" >}}{{< /see-also >}} + + + +## Prerequisites + +The instructions assume you have the following: + +- A running Keycloak server. See the Keycloak documentation for [Getting Started](https://www.keycloak.org/guides#getting-started) and [Server](https://www.keycloak.org/guides#server) configuration instructions. +- An NGINX Plus subscription and NGINX Plus R15 or later. For installation instructions, see the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). +- The [NGINX JavaScript module](https://www.nginx.com/blog/introduction-nginscript/) (njs), required for handling the interaction between NGINX Plus and the IdP. After installing NGINX Plus, install the module with the command for your operating system. + + For Debian and Ubuntu: + + ```none + sudo apt install nginx-plus-module-njs + ``` + + For CentOS, RHEL, and Oracle Linux: + + ```shell + sudo yum install nginx-plus-module-njs + ``` + +- The following directive included in the top-level ("main") configuration context in **/etc/nginx/nginx.conf**, to load the NGINX JavaScript module: + + ```nginx + load_module modules/ngx_http_js_module.so; + ``` + + +## Configuring Keycloak + +**Note:** The following procedure reflects the Keycloak GUI at the time of publication, but the GUI is subject to change. Use this guide as a reference and adapt to the current Keycloak GUI as necessary. + +Create a Keycloak client for NGINX Plus in the Keycloak GUI: + +1. Access the Keycloak Admin Console at **http://_keycloak-server-address_:8080/auth/admin/** and log in. + +2. In the left navigation column, click **Clients**. On the **Clients** page that opens, click the **Create** button in the upper right corner. + + +3. On the **Add Client** page that opens, enter or select these values, then click the  Save  button. + + - **Client ID** – The name of the application for which you're enabling SSO (Keycloak refers to it as the “client”). Here we're using NGINX-Plus. + - **Client Protocol** – openid-connect. + + + +4. On the **NGINX Plus** page that opens, enter or select these values on the Settings tab: + + - **Access Type** – confidential + - **Valid Redirect URIs** – The URI of the NGINX Plus instance, including the port number, and ending in **/\_codexch** (in this guide it is https://my-nginx.example.com:443/_codexch) + + **Notes:** + + - For production, we strongly recommend that you use SSL/TLS (port 443). + - The port number is mandatory even when you're using the default port for HTTP (80) or HTTPS (443). + + + + +5. Click the Credentials tab and make a note of the value in the **Secret** field. You will copy it into the NGINX Plus configuration file in [Step 4 of _Configuring NGINX Plus_](#nginx-plus-variables). + + + +6. Click the Roles tab, then click the **Add Role** button in the upper right corner of the page that opens. + +7. On the **Add Role** page that opens, type a value in the **Role Name** field (here it is nginx-keycloak-role) and click the  Save  button. + + + +8. In the left navigation column, click **Users**. On the **Users** page that opens, either click the name of an existing user, or click the **Add user** button in the upper right corner to create a new user. For complete instructions, see the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/index.html#user-management). + + +9. On the management page for the user (here, user01), click the Role Mappings tab. On the page that opens, select NGINX-Plus on the **Client Roles** drop‑down menu. Click nginx-keycloak-role in the **Available Roles** box, then click the **Add selected** button below the box. The role then appears in the **Assigned Roles** and **Effective Roles** boxes, as shown in the screenshot. + + + + + +## Configuring NGINX Plus + +Configure NGINX Plus as the OpenID Connect relying party: + +1. Create a clone of the [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) GitHub repository. + + ```shell + git clone https://github.com/nginxinc/nginx-openid-connect + ``` + +2. Copy these files from the clone to **/etc/nginx/conf.d**: + + - **frontend.conf** + - **openid\_connect.js** + - **openid\_connect.server\_conf** + - **openid\_connect\_configuration.conf** + + +3. Get the URLs for the authorization endpoint, token endpoint, and JSON Web Key (JWK) file from the Keycloak configuration. Run the following `curl` command in a terminal, piping the output to the indicated `python` command to output the entire configuration in an easily readable format. We've abridged the output to show only the relevant fields. + + ```shell + $ curl https:///auth/realms/master/.well-known/openid-configuration | python -m json.tool + ... + { + "authorization_endpoint": "https:///auth/realms/master/protocol/openid-connect/auth", + ... + "jwks_uri": "https:///auth/realms/master/protocol/openid-connect/certs", + ... + "token_endpoint": "https:///auth/realms/master/protocol/openid-connect/token", + ... + } + ``` + + +4. Using your preferred text editor, open **/etc/nginx/conf.d/openid_connect_configuration.conf**. Change the "default" parameter value of each of the following [map](https://nginx.org/en/docs/http/ngx_http_map_module.html#map) directives to the specified value: + + - `map $host $oidc_authz_endpoint` – Value of `authorization_endpoint` from [Step 3](#nginx-plus-urls) (in this guide, `https:///auth/realms/master/protocol/openid-connect/auth`) + - `map $host $oidc_token_endpoint` – Value of `token_endpoint` from [Step 3](#nginx-plus-urls) (in this guide, `https:///auth/realms/master/protocol/openid-connect/token`) + - `map $host $oidc_client` – Value in the **Client ID** field from [Step 3 of _Configuring Keycloak_](#keycloak-client-id) (in this guide, `NGINX Plus`) + - `map $host $oidc_client_secret` – Value in the **Secret** field from [Step 5 of _Configuring Keycloak_](#keycloak-secret) (in this guide, ``) + - `map $host $oidc_hmac_key` – A unique, long, and secure phrase + +5. Configure the JWK file. The procedure depends on which version of NGINX Plus you are using. + + - In NGINX Plus R17 and later, NGINX Plus can read the JWK file directly from the URL reported as `jwks_uri` in [Step 3](#nginx-plus-urls). Change **/etc/nginx/conf.d/frontend.conf** as follows: + + 1. Comment out (or remove) the [auth_jwt_key_file](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_file) directive. + + 2. Uncomment the [auth_jwt_key_request](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_request) directive. (Its parameter, `/_jwks_uri`, refers to the value of the `$oidc_jwt_keyfile` variable, which you set in the next step.) + 3. Change the "default" parameter of the `map $host $oidc_jwt_keyfile` directive to the value reported in the `jwks_uri` field in [Step 3](#nginx-plus-urls) (in this guide, `https:///auth/realms/master/protocol/openid-connect/certs`). + + - In NGINX Plus R16 and earlier, the JWK file must be on the local disk. (You can also use this method with NGINX Plus R17 and later if you wish.) + + 1. Copy the JSON contents from the JWK file named in the `jwks_uri` field in [Step 3](#nginx-plus-urls) (in this guide, `https:///auth/realms/master/protocol/openid-connect/certs`) to a local file (for example, `/etc/nginx/my_keycloak_jwk.json`). + 2. In **/etc/nginx/conf.d/openid_connect_configuration.conf**, change the "default" parameter of the `map $host $oidc_jwt_keyfile` directive to the local file path. + +6. Confirm that the user named by the [user](http://nginx.org/en/docs/ngx_core_module.html#user) directive in the NGINX Plus configuration (in **/etc/nginx/nginx.conf** by convention) has read permission on the JWK file. + + +## Testing + +In a browser, enter the address of your NGINX Plus instance and try to log in using the credentials of a user mapped to the role for NGINX Plus (see [Step 9 of _Configuring Keycloak_](#keycloak-users)). + + + + +## Troubleshooting + +See the [**Troubleshooting**](https://github.com/nginxinc/nginx-openid-connect#troubleshooting) section at the nginx-openid-connect repository on GitHub. + +### Revision History + +- Version 2 (March 2020) – Updates to _Configuring NGINX Plus_ section +- Version 1 (November 2019) – Initial version (NGINX Plus Release 19) diff --git a/content/nginx/deployment-guides/single-sign-on/oidc-njs/okta.md b/content/nginx/deployment-guides/single-sign-on/oidc-njs/okta.md new file mode 100644 index 000000000..4d1c81094 --- /dev/null +++ b/content/nginx/deployment-guides/single-sign-on/oidc-njs/okta.md @@ -0,0 +1,189 @@ +--- +description: Learn how to enable single sign-on (SSO) with Okta for applications proxied + by F5 NGINX Plus. +docs: DOCS-466 +type: +- how-to +title: Single Sign-On with Okta and njs +toc: false +weight: 100 +product: NGINX-PLUS +--- + +{{< note >}} This guide applies to NGINX Plus [Release 15]({{< ref "nginx/releases.md#r15" >}}) and later, based on the [`nginx-openid-connect`](https://github.com/nginxinc/nginx-openid-connect) GitHub repo. Starting with NGINX Plus [Release 34]({{< ref "nginx/releases.md#r34" >}}), use the simpler solution with the [native OpenID connect module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html). + +See [Single Sign-On With Okta]({{< ref "nginx/deployment-guides/single-sign-on/okta.md" >}}) for details.{{< /note >}} + +You can use NGINX Plus with Okta and OpenID Connect to enable single sign-on (SSO) for your proxied applications. By following the steps in this guide, you will learn how to set up SSO using OpenID Connect as the authentication mechanism, with Okta as the identity provider (IdP), and NGINX Plus as the relying party. + +{{< see-also >}}{{< readfile file="includes/nginx-openid-repo-note.txt" markdown="true" >}}{{< /see-also >}} + +## Prerequisites + +To complete the steps in this guide, you need the following: + +- An Okta administrator account. +- [NGINX Plus](https://www.f5.com/products/nginx/nginx-plus) with a valid subscription. +- The [NGINX JavaScript module](https://www.nginx.com/products/nginx/modules/nginx-javascript/) (`njs`) -- the `njs` module handles the interaction between NGINX Plus and Okta. +- Install `jq` on the host machine where you installed NGINX Plus. + +## Install NGINX Plus and the njs Module + +1. If you do not already have NGINX Plus installed, follow the steps in the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) to do so. +2. Install the NGINX JavaScript module by following the steps in the [`njs` installation guide](https://nginx.org/en/docs/njs/install.html). +3. Add the following directive to the top-level ("main") configuration context in the NGINX Plus configuration (`/etc/nginx/nginx.conf`) to load the `njs` module: + + ```Nginx configuration file + load_module modules/ngx_http_js_module.so; + ``` + +## Configure Okta {#okta} + +Take the steps in this section to create a new application for NGINX Plus. + +{{< note >}} This section contains images that reflect the state of the Okta web interface at the time of publication. The actual Okta GUI may differ from the examples shown here. Use this guide as a reference and adapt the instructions to suit the current Okta GUI as necessary.{{< /note >}} + +This section describes the Okta Workforce Identity SSO product. You will need administrator access to your organization in Okta to complete this task. Your experience may differ somewhat if you're using the Okta Customer Identity product. + +### Create a New Okta Web Application + + + +1. Log in to Okta at [okta.com](https:///www.okta.com). +1. Select the **Admin** button next to your username to access the Admin console. +1. On your Admin dashboard, select **Applications** in the left-hand navigation menu. +1. On the **Applications** page, select the **Create App Integration** button. +1. In the **Create a new app integration** window, define the following values, then select **Next**: + + - **Sign-in method**: OIDC - OpenID Connect + - **Application type**: Web Application + + {{< img src="/img/sso/okta/Okta-Create-New-Application-Integration.png" alt="image showing the Create a new app integration window in the Okta UI, with OIDC and Web Application options selected" width="65%" >}} + +### Set up the Web App Integration {#okta-integration} + +On the **New Web App Integration** page in the Okta web interface, fill in the following information, then select **Save**. + +{{< bootstrap-table "table table-striped table-bordered" >}} + +| Field | Desciption | Example Value | +|-------------|---------|----------| +| **App integration name** | The name of the OpenID Connect relying party. Okta refers to this as the "application". | **NGINX-Plus** | +| **Sign-in redirect URIs** | The URI of the NGINX Plus instance -- including the port number -- ending in **`/_codexch`**.
  • The port is always required, even if you use the default port for HTTP (`80`) or HTTPS (`443`).
  • The use of SSL/TLS (`443`) is strongly recommended for production environments.
| `https://my-nginx.example.com:443/_codexch` | +| **Sign-out redirect URIs** | The URI to redirect users to after logging out.
This is an optional field with a default value of `http://localhost:8080`. | We removed the default value in our example. | +| **Controlled access** | Controls who can access the application. | "Allow everyone in your organization to access"
**You should select the appropriate value for your use case.**| + +{{< /bootstrap-table >}} + +{{< img alt="Okta Create OpenID Connect Integration" src="/img/sso/okta/Okta-Create-OpenID-Connect-Integration.png" >}} + +### Get the Okta App Client Credentials {#okta-client-id-secret} + +After you finish creating your application, the Okta Application page should display. You can find the Client Credentials for your Okta Application here. + +{{< img src="/img/sso/okta/Okta-Client-Credentials.png" alt="Image showing the application landing page in Okta, which contains the Client Credentials for the application." width="65%" >}} + +{{< tip >}}If you need to find this information later, log in to your Okta admin account as [described above](#okta-login), select **Applications** in the left-hand menu, then select your application.{{< /tip >}} + +Make note of the **Client ID** and **Client secret** values for your application. You will need these when you [configure NGINX Plus](#nginx-plus). + +### Manage Access to your Okta Application {#okta-assign-applications} + +To change the users and groups that have access to your Okta Application: + +1. Log in to Okta as an Admin as [described above](#okta-login). +1. Select **Applications** in the left-hand menu, then select your application. +1. Select the **Assignments** tab for the Application. + +Here, you can manage which users in your organization are granted access to this application. + +## Set up NGINX Plus {#nginx-plus} + +Take the steps in this section to set up NGINX Plus as the OpenID Connect relying party. + +### Configure NGINX OpenID Connect {#nginx-plus-oidc-config} + +1. Clone the [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) GitHub repository, or download the repo files. + + ```shell + git clone https://github.com/nginxinc/nginx-openid-connect.git + ``` + +1. Copy the following files to the `/etc/nginx/conf.d` directory on the host machine where NGINX Plus is installed: + + - `frontend.conf` + - `openid_connect.js` + - `openid_connect.server_conf` + - `openid_connect_configuration.conf` + +1. Get the URLs for the authorization endpoint, token endpoint, and JSON Web Key (JWK) file from the Okta configuration. + + Run the following `curl` command in a terminal. + {{< tip>}}We recommend piping the output to `jq` to output the entire configuration in an easily readable format.{{< /tip >}} + The output in the example below is abridged to show only the relevant fields. + + ```shell + curl https://-admin.okta.com/.well-known/openid-configuration | jq + ... + { + "authorization_endpoint": "https://.okta.com/oauth2/v1/authorize", + ... + "jwks_uri": "https://.okta.com/oauth2/v1/keys", + ... + "token_endpoint": "https://.okta.com/oauth2/v1/token", + ... + } + ``` + + + +1. Add the correct values for your IdP to the OpenID Connect configuration file (`/etc/nginx/conf.d/openid_connect_configuration.conf`). + + This file contains the primary configuration for one or more IdPs in `map{}` blocks. You should modify the `map…$oidc_` blocks as appropriate to match your IdP configuration. + + - Define the `$oidc_authz_endpoint`, `$oidc_token_endpoint`, and `$oidc_jwt_keyfile` values using the information returned in the previous step. + - Change the URI defined in `map…$oidc_logout_redirect` to the URI of a resource (for example, your home page) that should be displayed after a client requests the `/logout` location. + - Set a unique, long, and secure phrase for `$oidc_hmac_key` to ensure nonce values are unpredictable. + +### Set up JSON Web Key Authorization {#nginx-plus-jwk-config} + +NGINX Plus can read the JWK file directly from the URL reported as `jwks_uri` in the output of the `curl` command you ran in the [previous section](#nginx-plus-oidc-config). + +{{< note >}} +If you are using NGINX Plus R16 or earlier, refer to [Set up JWK Authorization using a local file](#nginx-plus-jwk-auth-local). +{{< /note >}} + +Take the following steps to set up NGINX Plus to access the JWK file by using a URI. + +1. In the `/etc/nginx/conf.d/frontend.conf` file, remove (or comment out) the [auth_jwt_key_file](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_file) directive. +1. Uncomment the [auth_jwt_key_request](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_request) directive. + + The parameter `/_jwks_uri` refers to the value of the `$oidc_jwt_keyfile` variable, which you already set in the OpenID Connect configuration file (`/etc/nginx/conf.d/openid_connect_configuration.conf`). + +#### Set up JWK Authorization using a Local File {#nginx-plus-jwk-auth-local} + +In NGINX Plus R16 and earlier, NGINX Plus cannot access the JWK file via the URI. Instead, the JWK file must be on the local disk. + +Take the steps below to set up JWK authorization using a local file: + +1. Copy the JSON contents from the JWK file named in the `jwks_uri` field to a local file. For example, `/etc/nginx/my_okta_jwk.json` +1. In `/etc/nginx/conf.d/frontend.conf`, change the second parameter of the `set $oidc_jwt_keyfile` directive to the local file path of the JWK file. +1. Confirm that the user named by the [user](http://nginx.org/en/docs/ngx_core_module.html#user) directive in the NGINX Plus configuration -- usually found in `/etc/nginx/nginx.conf` -- has read permission on the JWK file. + +## Test Your Setup + +1. In a browser, enter the address of your NGINX Plus instance. You should be directed to the okta login page, as shown in the example below. + {{< img src="img/sso/okta/Okta-login-window.png" >}} +1. Try to log in using the credentials of a user who is part of your organization. + +{{}}If you restricted access to a group of users, be sure to select a user who has access to the application.{{}} + +## Troubleshooting + +Refer to the [Troubleshooting](https://github.com/nginxinc/nginx-openid-connect#troubleshooting) section in the `nginx-openid-connect` repository on GitHub. + +### Revision History + +- Version 3 (March 2022) – Full edit incorporating updates to _Configuring Okta_ and _Configuring NGINX Plus_ +- Version 2 (March 2020) – Updates to _Configuring NGINX Plus_ section +- Version 1 (April 2019) – Initial version (NGINX Plus Release 17) diff --git a/content/nginx/deployment-guides/single-sign-on/oidc-njs/onelogin.md b/content/nginx/deployment-guides/single-sign-on/oidc-njs/onelogin.md new file mode 100644 index 000000000..1048acced --- /dev/null +++ b/content/nginx/deployment-guides/single-sign-on/oidc-njs/onelogin.md @@ -0,0 +1,158 @@ +--- +description: Learn how to enable single sign-on (SSO) with [OneLogin](https://www.onelogin.com/) + for applications proxied by F5 NGINX Plus. +docs: DOCS-467 +type: +- tutorial +title: Single Sign-On with OneLogin and njs +toc: false +weight: 100 +product: NGINX-PLUS +--- + +{{< note >}} This guide applies to NGINX Plus [Release 15]({{< ref "nginx/releases.md#r15" >}}) and later, based on the [`nginx-openid-connect`](https://github.com/nginxinc/nginx-openid-connect) GitHub repo. Starting with NGINX Plus [Release 34]({{< ref "nginx/releases.md#r34" >}}), use the simpler solution with the [native OpenID connect module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html). + +See [Single Sign-On With OneLogin]({{< ref "nginx/deployment-guides/single-sign-on/onelogin.md" >}}) for details.{{< /note >}} + +You can use NGINX Plus with [OneLogin](https://www.onelogin.com/) and the OpenID Connect protocol to enable single sign-on (SSO) for your proxied applications. By following the steps in this guide, you will learn how to set up SSO using OpenID Connect as the authentication mechanism, with OneLogin as the identity provider (IdP) and NGINX Plus as the relying party. + +{{< see-also >}}{{< readfile file="includes/nginx-openid-repo-note.txt" markdown="true" >}}{{< /see-also >}} + +## Prerequisites + +To complete the steps in this guide, you need the following: + +- A OneLogin tenant with administrator privileges. +- [NGINX Plus](https://www.f5.com/products/nginx/nginx-plus) with a valid subscription. +- The [NGINX JavaScript module](https://www.nginx.com/products/nginx/modules/nginx-javascript/) (`njs`) -- the `njs` module handles the interaction between NGINX Plus and OneLogin identity provider (IdP). + +## Install NGINX Plus and the njs Module {#install-nginx-plus-njs} + +1. If you do not already have NGINX Plus installed, follow the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) steps to do so. +2. Install the NGINX JavaScript module by following the steps in the [`njs` installation guide](https://nginx.org/en/docs/njs/install.html). +3. Add the following directive to the top-level ("main") configuration context in the NGINX Plus configuration (`/etc/nginx/nginx.conf`) to load the `njs` module: + + ```Nginx configuration file + load_module modules/ngx_http_js_module.so; + ``` + +## Configure OneLogin {#config-onelogin} + +**Note:** The following procedure reflects the OneLogin GUI at the time of publication, but the GUI is subject to change. Use this guide as a reference and adapt to the current OneLogin GUI as necessary. + +Create a new application for NGINX Plus in the OneLogin GUI: + +1. Log in to your OneLogin account at **https://**_domain_**.onelogin.com**, where _domain_ is the domain you chose when you created your account. + +2. Click  Applications  in the title bar and then click the  Add App  button in the upper right corner of the window that opens. + + + +3. On the **Find Applications** page that opens, type OpenID Connect in the search box. Click on the **OpenID Connect (OIDC)** row that appears. + + + +4. On the **Add OpenId Connect (OIDC)** page that opens, change the value in the **Display Name** field to NGINX Plus and click the  Save  button. + + + +5. When the save completes, a new set of choices appears in the left navigation bar. Click **Configuration**. In the **Redirect URI's** field, type the URI of the NGINX Plus instance including the port number, and ending in **/\_codexch** (in this guide it is https://my-nginx.example.com:443/_codexch). Then click the  Save  button. + + **Notes:** + + - For production, we strongly recommend that you use SSL/TLS (port 443). + - The port number is mandatory even when you're using the default port for HTTP (80) or HTTPS (443). + + + + +6. When the save completes, click **SSO** in the left navigation bar. Click Show client secret below the **Client Secret** field. Record the values in the **Client ID** and **Client Secret** fields. You will add them to the NGINX Plus configuration in [Step 4 of _Configuring NGINX Plus_](#nginx-plus-variables). + + + + +7. Assign users to the application (in this guide, NGINX Plus) to enable them to access it for SSO. OneLogin recommends using [roles](https://onelogin.service-now.com/kb_view_customer.do?sysparm_article=KB0010606) for this purpose. You can access the **Roles** page under  Users  in the title bar. + + + + +## Set up NGINX Plus + +Take the steps in this section to set up NGINX Plus as the OpenID Connect Client. + +### Configure NGINX OpenID Connect {#nginx-plus-oidc-config} + +1. Clone the [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) GitHub repository, or download the repository files. + + ```shell + git clone https://github.com/nginxinc/nginx-openid-connect.git + ``` + +1. Run the _configure.sh_ script to update the NGINX configuration files with the values for your OneLogin application. + + For example: + + ```bash + ./nginx-openid-connect/configure.sh \ + --auth_jwt_key request \ + --client_id 168d5600-9224-... \ + --client_secret c9210a67d09e85... \ + https://.onelogin.com/oidc/2/.well-known/openid-configuration + ``` + +2. In the `frontend.conf` file, update the **my_backend** upstream with the address of the application that you want to add OIDC authorization to. + + For example: + + ```Nginx configuration file + upstream my_backend { + zone my_backend 64k; + server my-backend-app.com:80; + } + ``` + +3. In the _openid_connect.server_conf_ file, add the [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive to the `/_jwks_uri` and `/_token` locations to `Accept-Encoding "gzip"`, as shown below. + + ```Nginx configuration file + ... + location = /_jwks_uri { + ... + proxy_set_header Accept-Encoding "gzip" + } + ... + location = /_token { + ... + proxy_set_header Accept-Encoding "gzip" + } + ... + ``` + +4. Copy the following files to the _/etc/nginx/conf.d_ directory on the host machine where NGINX Plus is installed: + + - `frontend.conf` + - `openid_connect.js` + - `openid_connect.server_conf` + - `openid_connect_configuration.conf` + +5. Reload the NGINX configuration: + + ```bash + sudo nginx -s reload + ``` + +## Test Your Setup + +In a browser, enter the address of your NGINX Plus instance and try to log in using the credentials of a user assigned to the application (see [Step 7 of _Configuring OneLogin_](#onelogin-roles)). + + + + +## Troubleshooting + +Refer to the [Troubleshooting](https://github.com/nginxinc/nginx-openid-connect#troubleshooting) section in the `nginx-openid-connect` repository on GitHub. + +### Revision History + +- Version 3 (May 2022) - Updates OneLogin's OpenId Connect API endpoints from version 1 to version 2 +- Version 2 (March 2020) – Updates to _Configuring NGINX Plus_ section +- Version 1 (July 2019) – Initial version (NGINX Plus Release 18) diff --git a/content/nginx/deployment-guides/single-sign-on/oidc-njs/ping-identity.md b/content/nginx/deployment-guides/single-sign-on/oidc-njs/ping-identity.md new file mode 100644 index 000000000..3999d9a0e --- /dev/null +++ b/content/nginx/deployment-guides/single-sign-on/oidc-njs/ping-identity.md @@ -0,0 +1,198 @@ +--- +description: Enable OpenID Connect-based single-sign for applications proxied by NGINX + Plus, using Ping Identity as the identity provider (IdP). +docs: DOCS-468 +type: +- how-to +product: NGINX-PLUS +title: Single Sign-On with Ping Identity and njs +toc: false +weight: 100 +--- + +{{< note >}} This guide applies to NGINX Plus [Release 15]({{< ref "nginx/releases.md#r15" >}}) and later, based on the [`nginx-openid-connect`](https://github.com/nginxinc/nginx-openid-connect) GitHub repo. Starting with NGINX Plus [Release 34]({{< ref "nginx/releases.md#r34" >}}), use the simpler solution with the [native OpenID connect module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html). + +See [Single Sign-On With Ping Identity]({{< ref "nginx/deployment-guides/single-sign-on/ping-identity.md" >}}) for details.{{< /note >}} + +This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with Ping Identity as the identity provider (IdP) and NGINX Plus as the relying party. + +The instructions in this document apply to both Ping Identity's on‑premises and cloud products, PingFederate and PingOne for Enterprise. + +{{< see-also >}}{{< readfile file="includes/nginx-openid-repo-note.txt" markdown="true" >}}{{< /see-also >}} + + +## Prerequisites + +The instructions assume you have the following: + +- A running deployment of PingFederate or PingOne for Enterprise, and a Ping Identity account. For installation and configuration instructions, see the documentation for [PingFederate](https://docs.pingidentity.com/bundle/pingfederate-93/page/tau1564002955783.html) or [PingOne for Enterprise](https://docs.pingidentity.com/bundle/pingone/page/fjn1564020491958-1.html). +- An NGINX Plus subscription and NGINX Plus R15 or later. For installation instructions, see the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). +- The NGINX JavaScript module (njs), required for handling the interaction between NGINX Plus and the IdP. After installing NGINX Plus, install the module with the command for your operating system. + + For Debian and Ubuntu: + + ```none + sudo apt install nginx-plus-module-njs + ``` + + For CentOS, RHEL, and Oracle Linux: + + ```shell + sudo yum install nginx-plus-module-njs + ``` + +- The following directive included in the top-level ("main") configuration context in **/etc/nginx/nginx.conf**, to load the NGINX JavaScript module: + + ```nginx + load_module modules/ngx_http_js_module.so; + ``` + + +## Configuring PingFederate or PingOne for Enterprise + +**Note:** This guide uses the GUI provided with PingOne for Enterprise. It reflects the GUI at the time of initial publication, but the GUI is subject to change. The PingFederate user interface might also differ. Use this guide as a reference and adapt as necessary for the UI you are using. + +Create a new application for NGINX Plus: + +1. Log in to your Ping Identity account. The administrative dashboard opens automatically. In this guide, we show the PingOne for Enterprise dashboard, and for brevity refer simply to ”PingOne”. + +2. Click  APPLICATIONS  in the title bar, and on the **My Applications** page that opens, click **OIDC** and then the + Add Application button. + + + +3. The Add OIDC Application window pops up. Click the ADVANCED CONFIGURATION box, and then the  Next  button. + + + +4. In section 1 (PROVIDE DETAILS ABOUT YOUR APPLICATION), type a name in the **APPLICATION NAME** field and a short description in the **SHORT DESCRIPTION** field. Here, we're using nginx-plus-application and NGINX Plus. Choose a value from the **CATEGORY** drop‑down menu; here we’re using Information Technology. You can also add an icon if you wish. Click the  Next  button. + + + +5. In section 2 (AUTHORIZATION SETTINGS), perform these steps: + + 1. Under **GRANTS**, click both Authorization Code and Implicit.
+ 2. Under **CREDENTIALS**, click the + Add Secret button. PingOne creates a client secret and opens the **CLIENT SECRETS** field to display it, as shown in the screenshot. To see the actual value of the secret, click the eye icon.
+ 3. Click the  Next  button. + + + +6. In section 3 (SSO FLOW AND AUTHENTICATION SETTINGS): + + 1. In the START SSO URL field, type the URL where users access your application. Here we’re using https://example.com. + 2. In the **REDIRECT URIS** field, type the URI of the NGINX Plus instance including the port number, and ending in **/\_codexch**. Here we’re using https://my-nginx-plus.example.com:443/\_codexch (the full value is not visible in the screenshot). + + **Notes:** + + - For production, we strongly recommend that you use SSL/TLS (port 443). + - The port number is mandatory even when you're using the default port for HTTP (80) or HTTPS (443). + + + +7. In section 4 (DEFAULT USER PROFILE ATTRIBUTE CONTRACT), optionally add attributes to the required sub and idpid attributes, by clicking the + Add Attribute button. We’re not adding any in this example. When finished, click the  Next  button. + + + +8. In section 5 (CONNECT SCOPES), click the circled plus-sign on the OpenID Profile (profile) and OpenID Profile Email (email) scopes in the LIST OF SCOPES column. They are moved to the **CONNECTED SCOPES** column, as shown in the screenshot. Click the  Next  button. + + + +9. In section 6 (ATTRIBUTE MAPPING), map attributes from your identity repository to the claims available to the application. The one attribute you must map is **sub**, and here we have selected the value Email from the drop‑down menu (the screenshot is abridged for brevity). + + + + +10. In section 7 (GROUP ACCESS), select the groups that will have access to the application, by clicking the circled plus-sign on the corresponding boxes in the **AVAILABLE GROUPS** column. The boxes move to the **ADDED GROUPS** column. As shown in the screenshot we have selected the two default groups, Domain Administrators@directory and Users@directory. + + Click the  Done  button. + + + +11. You are returned to the **My Applications** window, which now includes a row for nginx-plus-application. Click the toggle switch at the right end of the row to the “on” position, as shown in the screenshot. Then click the “expand” icon at the end of the row, to display the application’s details. + + + + +12. On the page that opens, make note of the values in the following fields on the **Details** tab. You will add them to the NGINX Plus configuration in [Step 4 of _Configuring NGINX Plus_](#nginx-plus-variables). + + - **CLIENT ID** (in the screenshot, 28823604-83c5-4608-88da-c73fff9c607a) + - **CLIENT SECRETS** (in the screenshot, 7GMKILBofxb...); click on the eye icon to view the actual value + + + + +## Configuring NGINX Plus + +Configure NGINX Plus as the OpenID Connect relying party: + +1. Create a clone of the [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) GitHub repository. + + ```shell + git clone https://github.com/nginxinc/nginx-openid-connect + ``` + +2. Copy these files from the clone to **/etc/nginx/conf.d**: + + - **frontend.conf** + - **openid\_connect.js** + - **openid\_connect.server\_conf** + + +3. Get the URLs for the authorization endpoint, token endpoint, and JSON Web Key (JWK) file from the Ping Identity configuration. Run the following `curl` command in a terminal, piping the output to the indicated `python` command to output the entire configuration in an easily readable format. We've abridged the output to show only the relevant fields. + + The `` variable is the value in the **CLIENT ID** field that you noted in [Step 12 of _Configuring PingFederate or PingOne for Enterprise_](#ping-client-id-secrets). + + **Note:** This `curl` command is appropriate for Ping One for Enterprise. For PingFederate, you might need to replace `sso.connect.pingidentity.com` with the IP address of your local PingFederate server. + + ```shell + $ curl sso.connect.pingidentity.com//.well-known/openid-configuration | python -m json.tool + ... + { + "authorization_endpoint": "https://sso.connect.pingidentity.com/sso/as/authorization.oauth2", + ... + "jwks_uri": "https://sso.connect.pingidentity.com/sso/as/jwks", + ... + "token_endpoint": "https://sso.connect.pingidentity.com/sso/as/token.oauth2", + ... + } + ``` + + +4. In your preferred text editor, open **/etc/nginx/conf.d/frontend.conf**. Change the second parameter of each of the following [set](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html#set) directives to the specified value: + + - `set $oidc_authz_endpoint` – Value of `authorization_endpoint` from [Step 3](#nginx-plus-urls) (in this guide, `https://sso.connect.pingidentity.com/sso/as/authorization.oauth2`) + - `set $oidc_token_endpoint` – Value of `token_endpoint` from [Step 3](#nginx-plus-urls) (in this guide, `https://sso.connect.pingidentity.com/sso/as/token.oauth2`) + - `set $oidc_client` – Value in the **CLIENT ID** field in [Step 12 of _Configuring PingFederate or PingOne for Enterprise_](#ping-client-id-secrets) (in this guide, `28823604-83c5-4608-88da-c73fff9c607a`) + - `set $oidc_client_secret` – Value in the **CLIENT SECRETS** field in [Step 12 of _Configuring PingFederate or PingOne for Enterprise_](#ping-client-id-secrets) (in this guide, `7GMKILBofxb...`) + - `set $oidc_hmac_key` – A unique, long, and secure phrase + +5. Configure the JWK file. The procedure depends on which version of NGINX Plus you are using. + + - In NGINX Plus R17 and later, NGINX Plus can read the JWK file directly from the URL reported as `jwks_uri` in [Step 3](#nginx-plus-urls). Change **/etc/nginx/conf.d/frontend.conf** as follows: + + 1. Comment out (or remove) the [auth_jwt_key_file](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_file) directive. + 2. Uncomment the [auth_jwt_key_request](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_request) directive. (Its parameter, `/_jwks_uri`, refers to the value of the `$oidc_jwt_keyfile` variable, which you set in the next step.) + 3. Change the second parameter of the `set $oidc_jwt_keyfile` directive to the value reported in the `jwks_uri` field in [Step 3](#nginx-plus-urls) (in this guide, `https://sso.connect.pingidentity.com/sso/as/jwks`). + + - In NGINX Plus R16 and earlier, the JWK file must be on the local disk. (You can also use this method with NGINX Plus R17 and later if you wish.) + + 1. Copy the JSON contents from the JWK file named in the `jwks_uri` field in [Step 3](#nginx-plus-urls) (in this guide, `https://sso.connect.pingidentity.com/sso/as/jwks`) to a local file (for example, `/etc/nginx/my_ping_identity_jwk.json`). + 2. In **/etc/nginx/conf.d/frontend.conf**, change the second parameter of the `set $oidc_jwt_keyfile` directive to the local file path. + +6. Confirm that the user named by the [user](http://nginx.org/en/docs/ngx_core_module.html#user) directive in the NGINX Plus configuration (in **/etc/nginx/nginx.conf** by convention) has read permission on the JWK file. + + +## Testing + +In a browser, enter the address of your NGINX Plus instance and try to log in using the credentials of a user assigned to the application (see [Step 10 of _PingFederate or PingOne for Enterprise_](#ping-group-access)). + + + + +## Troubleshooting + +See the [**Troubleshooting**](https://github.com/nginxinc/nginx-openid-connect#troubleshooting) section at the nginx-openid-connect repository on GitHub. + +### Revision History + +- Version 2 (March 2020) – Updates to _Configuring NGINX Plus_ section +- Version 1 (January 2020) – Initial version (NGINX Plus Release 20) diff --git a/content/nginx/deployment-guides/single-sign-on/okta.md b/content/nginx/deployment-guides/single-sign-on/okta.md index 2b5af9cc6..9c976326a 100644 --- a/content/nginx/deployment-guides/single-sign-on/okta.md +++ b/content/nginx/deployment-guides/single-sign-on/okta.md @@ -1,189 +1,312 @@ --- -description: Learn how to enable single sign-on (SSO) with Okta for applications proxied - by F5 NGINX Plus. -docs: DOCS-466 -title: Single Sign-On with Okta -toc: true -weight: 100 +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 +toc: true +weight: 700 --- -
+This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Okta](https://www.okta.com/) as the Identity Provider (IdP), and NGINX Plus as the Relying Party, or OIDC client application that verifies user identity. -This documentation applies to F5 NGINX Plus R15 and later. -
+{{< note >}} This guide applies to [NGINX Plus Release 34]({{< ref "nginx/releases.md#r34" >}}) 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.{{< /note >}} -You can use NGINX Plus with Okta and OpenID Connect to enable single sign-on (SSO) for your proxied applications. By following the steps in this guide, you will learn how to set up SSO using OpenID Connect as the authentication mechanism, with Okta as the identity provider (IdP), and NGINX Plus as the relying party. +## Prerequisites -{{< see-also >}}{{< include "nginx-plus/nginx-openid-repo-note.txt" >}}{{< /see-also >}} +- An [Okta](https://www.okta.com/) administrator account with privileges to create and manage applications. -## Prerequisites +- An NGINX Plus [subscription](https://www.f5.com/products/nginx/nginx-plus) and NGINX Plus [Release 34](({{< ref "nginx/releases.md#r34" >}})) or later. For installation instructions, see [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). + +- A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`. -To complete the steps in this guide, you need the following: -- An Okta administrator account. -- [NGINX Plus](https://www.f5.com/products/nginx/nginx-plus) with a valid subscription. -- The [NGINX JavaScript module](https://www.nginx.com/products/nginx/modules/nginx-javascript/) (`njs`) -- the `njs` module handles the interaction between NGINX Plus and Okta. -- Install `jq` on the host machine where you installed NGINX Plus. +## Configure Okta {#okta-setup} -## Install NGINX Plus and the njs Module +In Okta, register a new application for NGINX Plus as the OIDC client to obtain the Client ID, Client Secret, and required OIDC endpoints. -1. If you do not already have NGINX Plus installed, follow the steps in the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) to do so. -2. Install the NGINX JavaScript module by following the steps in the [`njs` installation guide](https://nginx.org/en/docs/njs/install.html). -3. Add the following directive to the top-level ("main") configuration context in the NGINX Plus configuration (`/etc/nginx/nginx.conf`) to load the `njs` module: +1. Log in to your Okta admin console. - ```Nginx configuration file - load_module modules/ngx_http_js_module.so; - ``` +2. In the Admin Console, go to **Applications** > **Applications**. -## Configure Okta {#okta} +3. Select **Create App Integration**. -Take the steps in this section to create a new application for NGINX Plus. +4. In **Create a new app integration**, select: -{{< note >}} This section contains images that reflect the state of the Okta web interface at the time of publication. The actual Okta GUI may differ from the examples shown here. Use this guide as a reference and adapt the instructions to suit the current Okta GUI as necessary.{{< /note >}} + - **Sign-in method**: `OIDC - OpenID Connect`. -This section describes the Okta Workforce Identity SSO product. You will need administrator access to your organization in Okta to complete this task. Your experience may differ somewhat if you're using the Okta Customer Identity product. + - **Application type**: `Web Application`. -### Create a New Okta Web Application + - Select **Next**. - +5. In **New Web App Integration**: -1. Log in to Okta at [okta.com](https:///www.okta.com). -1. Select the **Admin** button next to your username to access the Admin console. -1. On your Admin dashboard, select **Applications** in the left-hand navigation menu. -1. On the **Applications** page, select the **Create App Integration** button. -1. In the **Create a new app integration** window, define the following values, then select **Next**: + - Enter the **Name** for your new application, for example, **Nginx Demo App**. - - **Sign-in method**: OIDC - OpenID Connect - - **Application type**: Web Application + - Add a URI for the OIDC callback in **Sign-in redirect URIs**, for example, `https://demo.example.com/oidc_callback`. - {{< img src="/img/sso/okta/Okta-Create-New-Application-Integration.png" alt="image showing the Create a new app integration window in the Okta UI, with OIDC and Web Application options selected" width="65%" >}} + - Select **Save**. -### Set up the Web App Integration {#okta-integration} +6. In **Applications**, select **Nginx Demo App**. -On the **New Web App Integration** page in the Okta web interface, fill in the following information, then select **Save**. +7. In the **General** tab: -{{< bootstrap-table "table table-striped table-bordered" >}} + - Copy the **Client ID**. You will need it later when configuring NGINX Plus. -| Field | Desciption | Example Value | -|-------------|---------|----------| -| **App integration name** | The name of the OpenID Connect relying party. Okta refers to this as the "application". | **NGINX-Plus** | -| **Sign-in redirect URIs** | The URI of the NGINX Plus instance -- including the port number -- ending in **`/_codexch`**.
  • The port is always required, even if you use the default port for HTTP (`80`) or HTTPS (`443`).
  • The use of SSL/TLS (`443`) is strongly recommended for production environments.
| `https://my-nginx.example.com:443/_codexch` | -| **Sign-out redirect URIs** | The URI to redirect users to after logging out.
This is an optional field with a default value of `http://localhost:8080`. | We removed the default value in our example. | -| **Controlled access** | Controls who can access the application. | "Allow everyone in your organization to access"
**You should select the appropriate value for your use case.**| + - Copy the **Client secret**. You will need it later when configuring NGINX Plus. -{{< /bootstrap-table >}} +8. In the **Sign On** tab: -{{< img alt="Okta Create OpenID Connect Integration" src="/img/sso/okta/Okta-Create-OpenID-Connect-Integration.png" >}} + - Copy the **Okta Issuer (Authorization Server)**, for example: -### Get the Okta App Client Credentials {#okta-client-id-secret} + `https://dev-123456.oktapreview.com/oauth2/default` -After you finish creating your application, the Okta Application page should display. You can find the Client Credentials for your Okta Application here. + You will need it later when configuring NGINX Plus. -{{< img src="/img/sso/okta/Okta-Client-Credentials.png" alt="Image showing the application landing page in Okta, which contains the Client Credentials for the application." width="65%" >}} +{{< note >}} You will need the values of **Client ID**, **Client Secret**, and **Issuer** in the next steps. {{< /note >}} -{{< tip >}}If you need to find this information later, log in to your Okta admin account as [described above](#okta-login), select **Applications** in the left-hand menu, then select your application.{{< /tip >}} +### Assign Users or Groups -Make note of the **Client ID** and **Client secret** values for your application. You will need these when you [configure NGINX Plus](#nginx-plus). +By default, Okta might limit application access to certain users or groups. To add or remove users in Okta: -### Manage Access to your Okta Application {#okta-assign-applications} +1. Log in to your Okta admin console. -To change the users and groups that have access to your Okta Application: +2. In **Applications**, choose **Nginx Demo App**. -1. Log in to Okta as an Admin as [described above](#okta-login). -1. Select **Applications** in the left-hand menu, then select your application. -1. Select the **Assignments** tab for the Application. +3. Go to **Assignments**. -Here, you can manage which users in your organization are granted access to this application. +4. Add or remove users and groups that can access this application. -## Set up NGINX Plus {#nginx-plus} -Take the steps in this section to set up NGINX Plus as the OpenID Connect relying party. +## Set up NGINX Plus {#nginx-plus-setup} -### Configure NGINX OpenID Connect {#nginx-plus-oidc-config} +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. -1. Clone the [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) GitHub repository, or download the repo files. +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 34 or later: - ```shell - git clone https://github.com/nginxinc/nginx-openid-connect.git - ``` + ```none + nginx version: nginx/1.27.4 (nginx-plus-r34) + ``` -1. Copy the following files to the `/etc/nginx/conf.d` directory on the host machine where NGINX Plus is installed: +2. Ensure that you have the values of the **Client ID**, **Client Secret**, and **Issuer** obtained during [Okta Configuration](#okta-setup). - - `frontend.conf` - - `openid_connect.js` - - `openid_connect.server_conf` - - `openid_connect_configuration.conf` +3. In your preferred text editor, open the NGINX configuration file (`/etc/nginx/nginx.conf` for Linux or `/usr/local/etc/nginx/nginx.conf` for FreeBSD). -1. Get the URLs for the authorization endpoint, token endpoint, and JSON Web Key (JWK) file from the Okta configuration. +4. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, make sure your public DNS resolver is specified with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive: By default, NGINX Plus re‑resolves DNS records at the frequency specified by time‑to‑live (TTL) in the record, but you can override the TTL value with the `valid` parameter: - Run the following `curl` command in a terminal. - {{< tip>}}We recommend piping the output to `jq` to output the entire configuration in an easily readable format.{{< /tip >}} - The output in the example below is abridged to show only the relevant fields. + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; - ```shell - curl https://-admin.okta.com/.well-known/openid-configuration | jq - ... - { - "authorization_endpoint": "https://.okta.com/oauth2/v1/authorize", - ... - "jwks_uri": "https://.okta.com/oauth2/v1/keys", - ... - "token_endpoint": "https://.okta.com/oauth2/v1/token", - ... + # ... } ``` - + +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 + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider okta { -1. Add the correct values for your IdP to the OpenID Connect configuration file (`/etc/nginx/conf.d/openid_connect_configuration.conf`). + # ... - This file contains the primary configuration for one or more IdPs in `map{}` blocks. You should modify the `map…$oidc_` blocks as appropriate to match your IdP configuration. + } + # ... + } + ``` - - Define the `$oidc_authz_endpoint`, `$oidc_token_endpoint`, and `$oidc_jwt_keyfile` values using the information returned in the previous step. - - Change the URI defined in `map…$oidc_logout_redirect` to the URI of a resource (for example, your home page) that should be displayed after a client requests the `/logout` location. - - Set a unique, long, and secure phrase for `$oidc_hmac_key` to ensure nonce values are unpredictable. +6. In the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context, specify: -### Set up JSON Web Key Authorization {#nginx-plus-jwk-config} + - your actual Okta **Client ID** obtained in [Okta Configuration](#okta-setup) with the [`client_id`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_id) directive -NGINX Plus can read the JWK file directly from the URL reported as `jwks_uri` in the output of the `curl` command you ran in the [previous section](#nginx-plus-oidc-config). + - your **Client Secret** obtained in [Okta Configuration](#okta-setup) with the [`client_secret`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive -{{< note >}} -If you are using NGINX Plus R16 or earlier, refer to [Set up JWK Authorization using a local file](#nginx-plus-jwk-auth-local). -{{< /note >}} + - the **Issuer** URL obtained in [Okta Configuration](#okta-setup) with the [`issuer`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive -Take the following steps to set up NGINX Plus to access the JWK file by using a URI. + The `issuer` is typically your Okta OIDC URL: -1. In the `/etc/nginx/conf.d/frontend.conf` file, remove (or comment out) the [auth_jwt_key_file](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_file) directive. -1. Uncomment the [auth_jwt_key_request](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_request) directive. + `https://dev-123456.okta.com/oauth2/default`. - The parameter `/_jwks_uri` refers to the value of the `$oidc_jwt_keyfile` variable, which you already set in the OpenID Connect configuration file (`/etc/nginx/conf.d/openid_connect_configuration.conf`). + - **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. -#### Set up JWK Authorization using a Local File {#nginx-plus-jwk-auth-local} + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider okta { + issuer https://dev-123456.okta.com/oauth2/default; + client_id ; + client_secret ; + } + + # ... + } + ``` -In NGINX Plus R16 and earlier, NGINX Plus cannot access the JWK file via the URI. Instead, the JWK file must be on the local disk. +7. Make sure you have configured a [server](https://nginx.org/en/docs/http/ngx_http_core_module.html#server) that corresponds to `demo.example.com`, and there is a [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) that [points](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) to your application (see [Step 10](#oidc_app)) at `http://127.0.0.1:8080` that is going to be OIDC-protected: -Take the steps below to set up JWK authorization using a local file: + ```nginx + http { + # ... -1. Copy the JSON contents from the JWK file named in the `jwks_uri` field to a local file. For example, `/etc/nginx/my_okta_jwk.json` -1. In `/etc/nginx/conf.d/frontend.conf`, change the second parameter of the `set $oidc_jwt_keyfile` directive to the local file path of the JWK file. -1. Confirm that the user named by the [user](http://nginx.org/en/docs/ngx_core_module.html#user) directive in the NGINX Plus configuration -- usually found in `/etc/nginx/nginx.conf` -- has read permission on the JWK file. + server { + listen 443 ssl; + server_name demo.example.com; -## Test Your Setup + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; -1. In a browser, enter the address of your NGINX Plus instance. You should be directed to the okta login page, as shown in the example below. - {{< img src="img/sso/okta/Okta-login-window.png" >}} -1. Try to log in using the credentials of a user who is part of your organization. + location / { + # ... + + proxy_pass http://127.0.0.1:8080; + } + } + # ... + } + ``` + +8. Protect this [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) with Okta OIDC by specifying the [`auth_oidc`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#auth_oidc) directive that will point to the `okta` configuration specified in the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context in [Step 5](#okta-setup-oidc-provider): + + ```nginx + # ... + location / { + auth_oidc okta; + + # ... + + proxy_pass http://127.0.0.1:8080; + } + # ... + ``` + +9. Pass the OIDC claims as headers to the application ([Step 10](#oidc_app)) with the [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive. These claims are extracted from the ID token returned by Okta: + + - [`$oidc_claim_sub`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - a unique `Subject` identifier assigned for each user by Okta + + - [`$oidc_claim_email`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) the e-mail address of the user + + - [`$oidc_claim_name`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - the full name of the user + + - 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 / { + auth_oidc okta; + + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + # ... + ``` + + +10. 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 + # ... + server { + listen 8080; + + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nSub: $http_sub\n"; + default_type text/plain; + } + } + ``` +11. Save the NGINX configuration file and reload the configuration: + ```nginx + nginx -s reload + ``` + +### Complete Example + +This configuration example summarizes the steps outlined above. It includes only essential settings such as specifying the DNS resolver, defining the OIDC provider, configuring SSL, and proxying requests to an internal server. + +```nginx +http { + # Use a public DNS resolver for Issuer discovery, etc. + resolver 10.0.0.1 ipv4=on valid=300s; + + # Define the OIDC provider block for Okta + oidc_provider okta { + # The 'issuer' is your Okta issuer URL + # For okta dev it looks like: https://dev-123456.okta.com/oauth2/default + issuer https://dev-123456.okta.com/oauth2/default; + + # Your Okta “Client ID” from the application settings + client_id ; + + # Your Okta “Client Secret” from the application settings + client_secret ; + } + + server { + listen 443 ssl; + server_name demo.example.com; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + # Enforce OIDC authentication with Okta + auth_oidc okta; + + # Pass OIDC claims as HTTP headers to the backend + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + } + + server { + # Simple backend listening on 8080 + listen 8080; + + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nSub: $http_sub\n"; + default_type text/plain; + } + } +} +``` + +### Testing + +1. Open `https://demo.example.com/` in a browser. You will be automatically redirected to the Okta sign-in page. + +2. Enter valid Okta credentials of a user who has access the application. Upon successful sign-in, Okta redirects you back to NGINX Plus, and you will see the proxied application content (for example, “Hello, Jane Doe!”). {{}}If you restricted access to a group of users, be sure to select a user who has access to the application.{{}} -## Troubleshooting -Refer to the [Troubleshooting](https://github.com/nginxinc/nginx-openid-connect#troubleshooting) section in the `nginx-openid-connect` repository on GitHub. +## 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 R34]({{< ref "nginx/releases.md#r34" >}}) + + +## Revision History -### Revision History +- Version 1 (March 2025) – Initial version (NGINX Plus Release 34) -- Version 3 (March 2022) – Full edit incorporating updates to _Configuring Okta_ and _Configuring NGINX Plus_ -- Version 2 (March 2020) – Updates to _Configuring NGINX Plus_ section -- Version 1 (April 2019) – Initial version (NGINX Plus Release 17) diff --git a/content/nginx/deployment-guides/single-sign-on/onelogin.md b/content/nginx/deployment-guides/single-sign-on/onelogin.md index e4c5c4fa1..99f323b49 100644 --- a/content/nginx/deployment-guides/single-sign-on/onelogin.md +++ b/content/nginx/deployment-guides/single-sign-on/onelogin.md @@ -1,158 +1,294 @@ --- -description: Learn how to enable single sign-on (SSO) with [OneLogin](https://www.onelogin.com/) - for applications proxied by F5 NGINX Plus. -docs: DOCS-467 +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 toc: true -weight: 100 -type: -- tutorial +weight: 600 --- -
- -This documentation applies to F5 NGINX Plus R15 and later. -
+This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [OneLogin](https://www.onelogin.com/) as the Identity Provider (IdP) and NGINX Plus as the Relying Party (RP), or OIDC client application that verifies user identity. -You can use NGINX Plus with [OneLogin](https://www.onelogin.com/) and the OpenID Connect protocol to enable single sign-on (SSO) for your proxied applications. By following the steps in this guide, you will learn how to set up SSO using OpenID Connect as the authentication mechanism, with OneLogin as the identity provider (IdP) and NGINX Plus as the relying party. +{{< note >}} This guide applies to [NGINX Plus Release 34]({{< ref "nginx/releases.md#r34" >}}) 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.{{< /note >}} -{{< see-also >}}{{< include "nginx-plus/nginx-openid-repo-note.txt" >}}{{< /see-also >}} ## Prerequisites -To complete the steps in this guide, you need the following: +- An [OneLogin](https://www.onelogin.com/) account with administrator privileges. -- A OneLogin tenant with administrator privileges. -- [NGINX Plus](https://www.f5.com/products/nginx/nginx-plus) with a valid subscription. -- The [NGINX JavaScript module](https://www.nginx.com/products/nginx/modules/nginx-javascript/) (`njs`) -- the `njs` module handles the interaction between NGINX Plus and OneLogin identity provider (IdP). +- An NGINX Plus [subscription](https://www.f5.com/products/nginx/nginx-plus) and NGINX Plus [Release 34](({{< ref "nginx/releases.md#r34" >}})) or later. For installation instructions, see [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). -## Install NGINX Plus and the njs Module {#install-nginx-plus-njs} +- A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`. -1. If you do not already have NGINX Plus installed, follow the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) steps to do so. -2. Install the NGINX JavaScript module by following the steps in the [`njs` installation guide](https://nginx.org/en/docs/njs/install.html). -3. Add the following directive to the top-level ("main") configuration context in the NGINX Plus configuration (`/etc/nginx/nginx.conf`) to load the `njs` module: - ```Nginx configuration file - load_module modules/ngx_http_js_module.so; - ``` +## Configure OneLogin {#onelogin-setup} -## Configure OneLogin {#config-onelogin} +### Create a OneLogin OIDC Application -**Note:** The following procedure reflects the OneLogin GUI at the time of publication, but the GUI is subject to change. Use this guide as a reference and adapt to the current OneLogin GUI as necessary. +1. Log in to your OneLogin admin console, for example, `https://.onelogin.com`. -Create a new application for NGINX Plus in the OneLogin GUI: +2. In the navigation bar, select **Applications**. -1. Log in to your OneLogin account at **https://**_domain_**.onelogin.com**, where _domain_ is the domain you chose when you created your account. +3. Click the **Add App** button. -2. Click  Applications  in the title bar and then click the  Add App  button in the upper right corner of the window that opens. + - On the **Find Applications** page, search for **OpenID Connect (OIDC)** and then select it. - + - Enter a **Display Name**, for example, `NGINX Demo App`. -3. On the **Find Applications** page that opens, type OpenID Connect in the search box. Click on the **OpenID Connect (OIDC)** row that appears. + - Select **Save**. - +4. In the app navigation, select **Configuration**. -4. On the **Add OpenId Connect (OIDC)** page that opens, change the value in the **Display Name** field to NGINX Plus and click the  Save  button. + - In **Redirect URIs**, add the callback URI for your NGINX Plus instance, for example, `https://demo.example.com/oidc_callback`. - + - Select **Save**. -5. When the save completes, a new set of choices appears in the left navigation bar. Click **Configuration**. In the **Redirect URI's** field, type the URI of the NGINX Plus instance including the port number, and ending in **/\_codexch** (in this guide it is https://my-nginx.example.com:443/_codexch). Then click the  Save  button. +5. In the app navigation, select **SSO**. - **Notes:** + - Copy the **Client ID**. You will need it later when configuring NGINX Plus. - - For production, we strongly recommend that you use SSL/TLS (port 443). - - The port number is mandatory even when you're using the default port for HTTP (80) or HTTPS (443). + - Select **Show client secret** and copy the **Client Secret**. You will need it later when configuring NGINX Plus. - + - Copy the **Issuer** URL, or OpenID Connect Discovery URL. You will need it later when configuring NGINX Plus. For OneLogin, the Issuer ID generally structured as: - -6. When the save completes, click **SSO** in the left navigation bar. Click Show client secret below the **Client Secret** field. Record the values in the **Client ID** and **Client Secret** fields. You will add them to the NGINX Plus configuration in [Step 4 of _Configuring NGINX Plus_](#nginx-plus-variables). + `https://.onelogin.com/oidc/2` - + See [Provider Configuration](https://developers.onelogin.com/openid-connect/api/provider-config) for details. - -7. Assign users to the application (in this guide, NGINX Plus) to enable them to access it for SSO. OneLogin recommends using [roles](https://onelogin.service-now.com/kb_view_customer.do?sysparm_article=KB0010606) for this purpose. You can access the **Roles** page under  Users  in the title bar. +{{< note >}} You will need the values of **Client ID**, **Client Secret**, and **Issuer** in the next steps. {{< /note >}} - +### Assign Users and Groups - -## Set up NGINX Plus +1. In the app navigation, select **Users** > **Roles**. -Take the steps in this section to set up NGINX Plus as the OpenID Connect Client. +2. Add users and groups who should have access to this application. -### Configure NGINX OpenID Connect {#nginx-plus-oidc-config} -1. Clone the [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) GitHub repository, or download the repository files. +## Set up NGINX Plus {#nginx-plus-setup} - ```shell - git clone https://github.com/nginxinc/nginx-openid-connect.git - ``` +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. -1. Run the _configure.sh_ script to update the NGINX configuration files with the values for your OneLogin application. +1. Ensure that you are using the latest version of NGINX Plus by running the `nginx -v` command in a terminal: - For example: + ```shell + nginx -v + ``` + The output should match NGINX Plus Release 34 or later: - ```bash - ./nginx-openid-connect/configure.sh \ - --auth_jwt_key request \ - --client_id 168d5600-9224-... \ - --client_secret c9210a67d09e85... \ - https://.onelogin.com/oidc/2/.well-known/openid-configuration + ```none + nginx version: nginx/1.27.4 (nginx-plus-r34) ``` -2. In the `frontend.conf` file, update the **my_backend** upstream with the address of the application that you want to add OIDC authorization to. +2. Ensure that you have the values of the **Client ID**, **Client Secret**, and **Issuer** obtained during [Onelogin Configuration](#onelogin-setup). + +3. In your preferred text editor, open the NGINX configuration file (`/etc/nginx/nginx.conf` for Linux or `/usr/local/etc/nginx/nginx.conf` for FreeBSD). - For example: +4. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, make sure your public DNS resolver is specified with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive: By default, NGINX Plus re‑resolves DNS records at the frequency specified by time‑to‑live (TTL) in the record, but you can override the TTL value with the `valid` parameter: - ```Nginx configuration file - upstream my_backend { - zone my_backend 64k; - server my-backend-app.com:80; + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + # ... } ``` -3. In the _openid_connect.server_conf_ file, add the [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive to the `/_jwks_uri` and `/_token` locations to `Accept-Encoding "gzip"`, as shown below. + +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 + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider onelogin { + + # ... + + } + # ... + } + ``` + +6. In the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context, specify: + + - your actual OneLogin **Client ID** obtained in [OneLogin Configuration](#onelogin-create) with the [`client_id`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_id) directive + + - your **Client Secret** obtained in [OneLogin Configuration](#onelogin-create) with the [`client_secret`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive + + - the **Issuer** URL obtained in [OneLogin Configuration](#onelogin-create) with the [`issuer`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive + + The `issuer` is typically your OneLogin OIDC URL: - ```Nginx configuration file - ... - location = /_jwks_uri { - ... - proxy_set_header Accept-Encoding "gzip" + `https://.onelogin.com/oidc/2`. + + - **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. + + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider onelogin { + issuer https://.onelogin.com/oidc/2; + client_id ; + client_secret ; + } + + # ... } - ... - location = /_token { - ... - proxy_set_header Accept-Encoding "gzip" + ``` + +7. Make sure you have configured a [server](https://nginx.org/en/docs/http/ngx_http_core_module.html#server) that corresponds to `demo.example.com`, and there is a [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) that [points](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) to your application (see [Step 10](#oidc_app)) at `http://127.0.0.1:8080` that is going to be OIDC-protected: + + ```nginx + http { + # ... + + server { + listen 443 ssl; + server_name demo.example.com; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + # ... + + proxy_pass http://127.0.0.1:8080; + } + } + # ... } - ... ``` -4. Copy the following files to the _/etc/nginx/conf.d_ directory on the host machine where NGINX Plus is installed: +8. Protect this [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) with OneLogin OIDC by specifying the [`auth_oidc`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#auth_oidc) directive that will point to the `onelogin` configuration specified in the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context in [Step 5](#onelogin-setup-oidc-provider): - - `frontend.conf` - - `openid_connect.js` - - `openid_connect.server_conf` - - `openid_connect_configuration.conf` + ```nginx + # ... + location / { + auth_oidc onelogin; -5. Reload the NGINX configuration: + # ... - ```bash - sudo nginx -s reload + proxy_pass http://127.0.0.1:8080; + } + # ... ``` -## Test Your Setup +9. Pass the OIDC claims as headers to the application ([Step 10](#oidc_app)) with the [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive. These claims are extracted from the ID token returned by OneLogin: + + - [`$oidc_claim_sub`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - a unique `Subject` identifier assigned for each user by OneLogin + + - [`$oidc_claim_email`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) the e-mail address of the user + + - [`$oidc_claim_name`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - the full name of the user + + - 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 / { + auth_oidc onelogin; + + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + # ... + ``` + + +10. 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 + # ... + server { + listen 8080; + + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nSub: $http_sub\n"; + default_type text/plain; + } + } + ``` +11. Save the NGINX configuration file and reload the configuration: + ```nginx + nginx -s reload + ``` + +### Complete Example + +This configuration example summarizes the steps outlined above. It includes only essential settings such as specifying the DNS resolver, defining the OIDC provider, configuring SSL, and proxying requests to an internal server. + +```nginx +http { + # Use a public DNS resolver for Issuer discovery, etc. + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider onelogin { + # The 'issuer' is typically your OneLogin OIDC base URL + # e.g. https://.onelogin.com/oidc/2 + issuer https://.onelogin.com/oidc/2; + + # Replace with your actual OneLogin Client ID and Secret + client_id ; + client_secret ; + } + + server { + listen 443 ssl; + server_name demo.example.com; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + # Protect this path with OneLogin OIDC + auth_oidc onelogin; + + # Forward OIDC claims to the upstream as headers if desired + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + proxy_pass http://127.0.0.1:8080; + } + } + + server { + listen 8080; + + location / { + return 200 "Hello, $http_name!\nYour email is $http_email\nSub: $http_sub\n"; + default_type text/plain; + } + } +} +``` + +### Testing + +1. Open `https://demo.example.com/` in a browser. You will be automatically redirected to the OneLogin sign-in page. + +2. Enter valid OneLogin credentials of a user who has access the application. Upon successful sign-in, OneLogin redirects you back to NGINX Plus, and you will see the proxied application content (for example, “Hello, Jane Doe!”). + +{{}}If you restricted access to a group of users, be sure to select a user who has access to the application.{{}} + + +## 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. + -In a browser, enter the address of your NGINX Plus instance and try to log in using the credentials of a user assigned to the application (see [Step 7 of _Configuring OneLogin_](#onelogin-roles)). +## See Also - +- [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) - -## Troubleshooting +- [Release Notes for NGINX Plus R34]({{< ref "nginx/releases.md#r34" >}}) -Refer to the [Troubleshooting](https://github.com/nginxinc/nginx-openid-connect#troubleshooting) section in the `nginx-openid-connect` repository on GitHub. -### Revision History +## Revision History -- Version 3 (May 2022) - Updates OneLogin's OpenId Connect API endpoints from version 1 to version 2 -- Version 2 (March 2020) – Updates to _Configuring NGINX Plus_ section -- Version 1 (July 2019) – Initial version (NGINX Plus Release 18) +- Version 1 (March 2025) – Initial version (NGINX Plus Release 34) 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 dfe13ef38..92ed75600 100644 --- a/content/nginx/deployment-guides/single-sign-on/ping-identity.md +++ b/content/nginx/deployment-guides/single-sign-on/ping-identity.md @@ -1,193 +1,300 @@ --- -description: Enable OpenID Connect-based single-sign for applications proxied by NGINX - Plus, using Ping Identity as the identity provider (IdP). -docs: DOCS-468 -title: Single Sign-On with Ping Identity -toc: true -weight: 100 +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 +toc: true +weight: 800 --- -This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with Ping Identity as the identity provider (IdP) and NGINX Plus as the relying party. +This guide explains how to enable single sign-on (SSO) for applications being proxied by F5 NGINX Plus. The solution uses OpenID Connect as the authentication mechanism, with [Ping Identity](https://www.pingidentity.com/en.html) (PingFederate or PingOne) as the Identity Provider (IdP), and NGINX Plus as the Relying Party. -The instructions in this document apply to both Ping Identity's on‑premises and cloud products, PingFederate and PingOne for Enterprise. +{{< note >}} This guide applies to [NGINX Plus Release 34]({{< ref "nginx/releases.md#r34" >}}) 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.{{< /note >}} -{{< see-also >}}{{< include "nginx-plus/nginx-openid-repo-note.txt" >}}{{< /see-also >}} - ## Prerequisites -The instructions assume you have the following: +- [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. -- A running deployment of PingFederate or PingOne for Enterprise, and a Ping Identity account. For installation and configuration instructions, see the documentation for [PingFederate](https://docs.pingidentity.com/bundle/pingfederate-93/page/tau1564002955783.html) or [PingOne for Enterprise](https://docs.pingidentity.com/bundle/pingone/page/fjn1564020491958-1.html). -- An NGINX Plus subscription and NGINX Plus R15 or later. For installation instructions, see the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). -- The NGINX JavaScript module (njs), required for handling the interaction between NGINX Plus and the IdP. After installing NGINX Plus, install the module with the command for your operating system. +- An NGINX Plus [subscription](https://www.f5.com/products/nginx/nginx-plus) and NGINX Plus [Release 34](({{< ref "nginx/releases.md#r34" >}})) or later. For installation instructions, see [Installing NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). - For Debian and Ubuntu: +- A domain name pointing to your NGINX Plus instance, for example, `demo.example.com`. - ```none - sudo apt install nginx-plus-module-njs - ``` - For CentOS, RHEL, and Oracle Linux: +## Configure PingFederate or PingOne for Enterprise {#ping-create} - ```shell - sudo yum install nginx-plus-module-njs - ``` +{{< 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. {{< /note >}} -- The following directive included in the top-level ("main") configuration context in **/etc/nginx/nginx.conf**, to load the NGINX JavaScript module: +Create a new application for NGINX Plus: - ```nginx - load_module modules/ngx_http_js_module.so; - ``` +1. Log in to your Ping Identity admin console. + +2. Go to **Applications** > **Applications**. - -## Configuring PingFederate or PingOne for Enterprise +3. Click the **+** (plus) symbol to create a new OIDC Application. -**Note:** This guide uses the GUI provided with PingOne for Enterprise. It reflects the GUI at the time of initial publication, but the GUI is subject to change. The PingFederate user interace might also differ. Use this guide as a reference and adapt as necessary for the UI you are using. +4. On the New Application screen: -Create a new application for NGINX Plus: + - Enter the Name of your application, for example, `nginx-demo-app`. -1. Log in to your Ping Identity account. The administrative dashboard opens automatically. In this guide, we show the PingOne for Enterprise dashboard, and for brevity refer simply to ”PingOne”. + - Select the Application Type **OIDC Web App**. -2. Click  APPLICATIONS  in the title bar, and on the **My Applications** page that opens, click **OIDC** and then the + Add Application button. + - Select **Save**. - +5. In your OIDC application, Select the **Overview** tab: -3. The Add OIDC Application window pops up. Click the ADVANCED CONFIGURATION box, and then the  Next  button. + - in the **General** section, copy your **Client ID** and **Client Secret** values. You will need then later when configuring NGINX Plus. - + - In the **Connection Details** section, copy your **Issuer ID**. You will need it later when configuring NGINX Plus. -4. In section 1 (PROVIDE DETAILS ABOUT YOUR APPLICATION), type a name in the **APPLICATION NAME** field and a short description in the **SHORT DESCRIPTION** field. Here, we're using nginx-plus-application and NGINX Plus. Choose a value from the **CATEGORY** drop‑down menu; here we’re using Information Technology. You can also add an icon if you wish. Click the  Next  button. + For PingOne Cloud, the Issuer ID generally structured as `https://auth.pingone.com//as`. - + For PingFederate, the Issuer ID generally structured as `https://pingfederate.example.com:9031` appended with the realm path of your environment. -5. In section 2 (AUTHORIZATION SETTINGS), perform these steps: +6. On the **Configuration** tab of your OIDC application: - 1. Under **GRANTS**, click both Authorization Code and Implicit.
- 2. Under **CREDENTIALS**, click the + Add Secret button. PingOne creates a client secret and opens the **CLIENT SECRETS** field to display it, as shown in the screenshot. To see the actual value of the secret, click the eye icon.
- 3. Click the  Next  button. + - In the **Redirect URIs** field, add the NGINX Plus callback URI, for example: - + `https://demo.example.com/oidc_callback`. -6. In section 3 (SSO FLOW AND AUTHENTICATION SETTINGS): + - Select **Save**. - 1. In the START SSO URL field, type the URL where users access your application. Here we’re using https://example.com. - 2. In the **REDIRECT URIS** field, type the URI of the NGINX Plus instance including the port number, and ending in **/\_codexch**. Here we’re using https://my-nginx-plus.example.com:443/\_codexch (the full value is not visible in the screenshot). +7. Assign the application to the appropriate **Groups** or **Users** who will be allowed to log in. - **Notes:** +{{< note >}} You will need the values of **Client ID**, **Client Secret**, and **Issuer** in the next steps. {{< /note >}} - - For production, we strongly recommend that you use SSL/TLS (port 443). - - The port number is mandatory even when you're using the default port for HTTP (80) or HTTPS (443). - +## Set up NGINX Plus {#nginx-plus-setup} -7. In section 4 (DEFAULT USER PROFILE ATTRIBUTE CONTRACT), optionally add attributes to the required sub and idpid attributes, by clicking the + Add Attribute button. We’re not adding any in this example. When finished, click the  Next  button. +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. - +1. Ensure that you are using the latest version of NGINX Plus by running the `nginx -v` command in a terminal: -8. In section 5 (CONNECT SCOPES), click the circled plus-sign on the OpenID Profile (profile) and OpenID Profile Email (email) scopes in the LIST OF SCOPES column. They are moved to the **CONNECTED SCOPES** column, as shown in the screenshot. Click the  Next  button. + ```shell + nginx -v + ``` + The output should match NGINX Plus Release 34 or later: - + ```none + nginx version: nginx/1.27.4 (nginx-plus-r34) + ``` -9. In section 6 (ATTRIBUTE MAPPING), map attributes from your identity repository to the claims available to the application. The one attribute you must map is **sub**, and here we have selected the value Email from the drop‑down menu (the screenshot is abridged for brevity). +2. Ensure that you have the values of the **Client ID**, **Client Secret**, and **Issuer** obtained during [PingOne or PingFederate Configuration](#ping-setup). - +3. In your preferred text editor, open the NGINX configuration file (`/etc/nginx/nginx.conf` for Linux or `/usr/local/etc/nginx/nginx.conf` for FreeBSD). - -10. In section 7 (GROUP ACCESS), select the groups that will have access to the application, by clicking the circled plus-sign on the corresponding boxes in the **AVAILABLE GROUPS** column. The boxes move to the **ADDED GROUPS** column. As shown in the screenshot we have selected the two default groups, Domain Administrators@directory and Users@directory. +4. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, make sure your public DNS resolver is specified with the [`resolver`](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive: By default, NGINX Plus re‑resolves DNS records at the frequency specified by time‑to‑live (TTL) in the record, but you can override the TTL value with the `valid` parameter: - Click the  Done  button. + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; - + # ... + } + ``` -11. You are returned to the **My Applications** window, which now includes a row for nginx-plus-application. Click the toggle switch at the right end of the row to the “on” position, as shown in the screenshot. Then click the “expand” icon at the end of the row, to display the application’s details. + +5. In the [`http {}`](https://nginx.org/en/docs/http/ngx_http_core_module.html#http) context, define the PingOne or PingFederate provider named `ping` by specifying the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context: - + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; - -12. On the page that opens, make note of the values in the following fields on the **Details** tab. You will add them to the NGINX Plus configuration in [Step 4 of _Configuring NGINX Plus_](#nginx-plus-variables). + oidc_provider ping { - - **CLIENT ID** (in the screenshot, 28823604-83c5-4608-88da-c73fff9c607a) - - **CLIENT SECRETS** (in the screenshot, 7GMKILBofxb...); click on the eye icon to view the actual value + # ... + } + # ... + } + ``` + +6. In the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context, specify: + + - your actual Ping **Client ID** obtained in [Ping Configuration](#ping-create) with the [`client_id`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_id) directive - + - your **Client Secret** obtained in [Ping Configuration](#ping-create) with the [`client_secret`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive - -## Configuring NGINX Plus + - the **Issuer** URL obtained in [Ping Configuration](#ping-create) with the [`issuer`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#client_secret) directive -Configure NGINX Plus as the OpenID Connect relying party: + The `issuer` is typically your Ping Identity OIDC URL. -1. Create a clone of the [nginx-openid-connect](https://github.com/nginxinc/nginx-openid-connect) GitHub repository. + For PingOne Cloud, the URL is `https://auth.pingone.com//as`. - ```shell - git clone https://github.com/nginxinc/nginx-openid-connect - ``` + For PingFederate, the URL is `https://pingfederate.example.com:9031` followed by your environment’s realm path. -2. Copy these files from the clone to **/etc/nginx/conf.d**: + By default, NGINX Plus creates the OpenID metadata URL by appending the `/.well-known/openid-configuration` part to the Issuer URL. If your metadata URL is different, you can explicitly specify the metadata document with the [`config_url`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#config_url) directive. - - **frontend.conf** - - **openid\_connect.js** - - **openid\_connect.server\_conf** + - **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. - -3. Get the URLs for the authorization endpoint, token endpoint, and JSON Web Key (JWK) file from the Ping Identity configuration. Run the following `curl` command in a terminal, piping the output to the indicated `python` command to output the entire configuration in an easily readable format. We've abridged the output to show only the relevant fields. - The `` variable is the value in the **CLIENT ID** field that you noted in [Step 12 of _Configuring PingFederate or PingOne for Enterprise_](#ping-client-id-secrets). + ```nginx + http { + resolver 10.0.0.1 ipv4=on valid=300s; - **Note:** This `curl` command is appropriate for Ping One for Enterprise. For PingFederate, you might need to replace `sso.connect.pingidentity.com` with the IP address of your local PingFederate server. + oidc_provider ping { + issuer https://auth.pingone.com//as; + client_id ; + client_secret ; + } - ```shell - $ curl sso.connect.pingidentity.com//.well-known/openid-configuration | python -m json.tool - ... - { - "authorization_endpoint": "https://sso.connect.pingidentity.com/sso/as/authorization.oauth2", - ... - "jwks_uri": "https://sso.connect.pingidentity.com/sso/as/jwks", - ... - "token_endpoint": "https://sso.connect.pingidentity.com/sso/as/token.oauth2", - ... + # ... } ``` - -4. In your preferred text editor, open **/etc/nginx/conf.d/frontend.conf**. Change the second parameter of each of the following [set](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html#set) directives to the specified value: +7. Make sure you have configured a [server](https://nginx.org/en/docs/http/ngx_http_core_module.html#server) that corresponds to `demo.example.com`, and there is a [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) that [points](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) to your application (see [Step 10](#oidc_app)) at `http://127.0.0.1:8080` that is going to be OIDC-protected: + + ```nginx + http { + + # ... + + server { + listen 443 ssl; + server_name demo.example.com; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + # ... + + proxy_pass http://127.0.0.1:8080; + } + } + # ... + } + ``` + +8. Protect this [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) with Ping Identity OIDC by specifying the [`auth_oidc`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#auth_oidc) directive that will point to the `ping` configuration specified in the [`oidc_provider {}`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#oidc_provider) context in [Step 5](#ping-setup-oidc-provider): + + ```nginx + # ... + location / { + auth_oidc ping; + + # ... + + proxy_pass http://127.0.0.1:8080; + } + # ... + ``` + +9. Pass the OIDC claims as headers to the application ([Step 10](#oidc_app)) with the [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive. These claims are extracted from the ID token returned by Ping: + + - [`$oidc_claim_sub`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - a unique `Subject` identifier assigned for each user by Ping Identity + + - [`$oidc_claim_email`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - the e-mail address of the user - - `set $oidc_authz_endpoint` – Value of `authorization_endpoint` from [Step 3](#nginx-plus-urls) (in this guide, `https://sso.connect.pingidentity.com/sso/as/authorization.oauth2`) - - `set $oidc_token_endpoint` – Value of `token_endpoint` from [Step 3](#nginx-plus-urls) (in this guide, `https://sso.connect.pingidentity.com/sso/as/token.oauth2`) - - `set $oidc_client` – Value in the **CLIENT ID** field in [Step 12 of _Configuring PingFederate or PingOne for Enterprise_](#ping-client-id-secrets) (in this guide, `28823604-83c5-4608-88da-c73fff9c607a`) - - `set $oidc_client_secret` – Value in the **CLIENT SECRETS** field in [Step 12 of _Configuring PingFederate or PingOne for Enterprise_](#ping-client-id-secrets) (in this guide, `7GMKILBofxb...`) - - `set $oidc_hmac_key` – A unique, long, and secure phrase + - [`$oidc_claim_name`](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) - the full name of the user + + - any other OIDC claim using the [`$oidc_claim_ `](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#var_oidc_claim_) variable + + {{< note >}} Ensure the `openid`, `profile`, `email` Scopes are enabled in Ping Identity.{{< /note >}} + + ```nginx + # ... + location / { + auth_oidc ping; + + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + # ... + ``` + + +10. 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 + # ... + server { + listen 8080; + + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nSub: $http_sub\n"; + default_type text/plain; + } + } + ``` +11. Save the NGINX configuration file and reload the configuration: + ```nginx + nginx -s reload + ``` + +### Complete Example + +This configuration example summarizes the steps outlined above. It includes only essential settings such as specifying the DNS resolver, defining the OIDC provider, configuring SSL, and proxying requests to an internal server. + +```nginx +http { + # Use a public DNS resolver for Issuer discovery, etc. + resolver 10.0.0.1 ipv4=on valid=300s; + + oidc_provider ping { + # The issuer is typically something like: + # https://auth.pingone.com//as + issuer https://auth.pingone.com//as; + + # Your Ping Identity Client ID and Secret + client_id ; + client_secret ; + } + + server { + listen 443 ssl; + server_name demo.example.com; + + ssl_certificate /etc/ssl/certs/fullchain.pem; + ssl_certificate_key /etc/ssl/private/key.pem; + + location / { + # Enforce OIDC with Ping Identity + auth_oidc ping; + + # Forward OIDC claims as headers if desired + proxy_set_header sub $oidc_claim_sub; + proxy_set_header email $oidc_claim_email; + proxy_set_header name $oidc_claim_name; + + proxy_pass http://127.0.0.1:8080; + } + } + + server { + # Simple backend application for demonstration + listen 8080; + + location / { + return 200 "Hello, $http_name!\nEmail: $http_email\nSub: $http_sub\n"; + default_type text/plain; + } + } +} +``` -5. Configure the JWK file. The procedure depends on which version of NGINX Plus you are using. +### Testing - - In NGINX Plus R17 and later, NGINX Plus can read the JWK file directly from the URL reported as `jwks_uri` in [Step 3](#nginx-plus-urls). Change **/etc/nginx/conf.d/frontend.conf** as follows: +1. Open `https://demo.example.com/` in a browser. You will be automatically redirected to the PingOne sign-in page. - 1. Comment out (or remove) the [auth_jwt_key_file](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_file) directive. - 2. Uncomment the [auth_jwt_key_request](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_request) directive. (Its parameter, `/_jwks_uri`, refers to the value of the `$oidc_jwt_keyfile` variable, which you set in the next step.) - 3. Change the second parameter of the `set $oidc_jwt_keyfile` directive to the value reported in the `jwks_uri` field in [Step 3](#nginx-plus-urls) (in this guide, `https://sso.connect.pingidentity.com/sso/as/jwks`). +2. Enter valid Ping Identity credentials of a user who has access the application. Upon successful sign-in, PingOne redirects you back to NGINX Plus, and you will see the proxied application content (for example, “Hello, Jane Doe!”). - - In NGINX Plus R16 and earlier, the JWK file must be on the local disk. (You can also use this method with NGINX Plus R17 and later if you wish.) - 1. Copy the JSON contents from the JWK file named in the `jwks_uri` field in [Step 3](#nginx-plus-urls) (in this guide, `https://sso.connect.pingidentity.com/sso/as/jwks`) to a local file (for example, `/etc/nginx/my_ping_identity_jwk.json`). - 2. In **/etc/nginx/conf.d/frontend.conf**, change the second parameter of the `set $oidc_jwt_keyfile` directive to the local file path. +## Legacy njs-based Ping Identity Solution {#legacy-njs-guide} -6. Confirm that the user named by the [user](http://nginx.org/en/docs/ngx_core_module.html#user) directive in the NGINX Plus configuration (in **/etc/nginx/nginx.conf** by convention) has read permission on the JWK file. +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. - -## Testing -In a browser, enter the address of your NGINX Plus instance and try to log in using the credentials of a user assigned to the application (see [Step 10 of _PingFederate or PingOne for Enterprise_](#ping-group-access)). +## See Also - +- [NGINX Plus Native OIDC Module Reference documentation](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) - -## Troubleshooting +- [Release Notes for NGINX Plus R34]({{< ref "nginx/releases.md#r34" >}}) -See the [**Troubleshooting**](https://github.com/nginxinc/nginx-openid-connect#troubleshooting) section at the nginx-openid-connect repository on GitHub. -### Revision History +## Revision History -- Version 2 (March 2020) – Updates to _Configuring NGINX Plus_ section -- Version 1 (January 2020) – Initial version (NGINX Plus Release 20) +- Version 1 (March 2025) – Initial version for NGINX Plus Release 34 diff --git a/content/nginx/open-source-components.md b/content/nginx/open-source-components.md index 838f1eaa8..6ecd01ee2 100644 --- a/content/nginx/open-source-components.md +++ b/content/nginx/open-source-components.md @@ -12,13 +12,13 @@ type: Open source components included in the F5 NGINX Plus (package name is `nginx-plus`) are: -- nginx/OSS 1.27.2, distributed under 2-clause BSD license. +- nginx/OSS 1.27.4, distributed under 2-clause BSD license. Homepage: Copyright © 2002-2021 Igor Sysoev - Copyright © 2011-2024 NGINX, Inc. + Copyright © 2011-2025 NGINX, Inc. All rights reserved. @@ -51,7 +51,7 @@ modification, are permitted. - MurmurHash algorithm (version 2), distributed under MIT license. - Homepage: + Homepage: Copyright © Austin Appleby @@ -226,7 +226,7 @@ like `import/require()` and will resolve them (6.8.1). Copyright © 2013-present, Facebook, Inc. - - `regenerator-runtime`, standalone runtime for Regenerator-compiled generator and async functions (0.13.9). + - `regenerator-runtime`, standalone runtime for Regenerator-compiled generator and async functions (0.14.1). Homepage: diff --git a/content/nginx/releases.md b/content/nginx/releases.md index 25b8d2802..58dc8cdcf 100644 --- a/content/nginx/releases.md +++ b/content/nginx/releases.md @@ -18,6 +18,54 @@ We do not issue updates for releases that have reached EoSD. For this reason, we The initial release dates for NGINX Plus are noted in this document. New releases are announced on the [NGINX Product Support Announcements](https://interact.f5.com/Customer-Preference-Center.html) mailing list. + +## NGINX Plus Release 34 (R34) +_01 April 2025_
+_Based on NGINX Open Source 1.27.4_ + +NGINX Plus R34 is a feature release: + +- [OIDC authentication support]({{< ref "nginx/admin-guide/security-controls/configuring-oidc.md" >}}) via native [ngx_http_oidc_module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) module. + +- NGINX usage reporting: [proxy](https://nginx.org/en/docs/ngx_mgmt_module.html#proxy) support. + +- [Caching](https://blog.nginx.org/blog/optimizing-resource-usage-for-complex-ssl-configurations) of SSL certificates and secret keys with variables for [http](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate_cache) and [stream](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_certificate_cache). + +- The [`keepalive_min_timeout`](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_min_timeout) directive. + +- TLSv1.2 and TLSv1.3 are the default [SSL protocols](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols) (if supported by the OpenSSL library). If OpenSSL 1.0.0 or older is used, the default SSL protocols are TLSv1 and TLSv1.1. + +- Bugfixes in QUIC and HTTP/3, mail proxy, the MP4 module, the `proxy_store` and `proxy_bind` directives. + +- Security: insufficient check in virtual servers handling with TLSv1.3 SNI allowed to reuse SSL sessions in a different virtual server, to bypass client SSL certificates verification ([CVE-2025-23419](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2025-23419)). + + +NGINX Plus R34 is supported on: + +- AlmaLinux 8, 9 +- Alpine Linux 3.18, 3.19, 3.20, 3.21 +- Amazon Linux 2 LTS, 2023 +- Debian 11, 12 +- FreeBSD 13, 14 +- Oracle Linux 8.1+, 9 +- RHEL 8.1+, 9.0+ +- Rocky Linux 8, 9 +- SUSE Linux Enterprise Server 15 SP5+ +- Ubuntu 20.04 LTS, 22.04 LTS, 24.04 LTS + +**Notes:** + +- Alpine Linux 3.17 is removed +- Alpine Linux 3.18 is deprecated +- Alpine Linux 3.21 is new in this release +- Amazon Linux 2 LTS is deprecated +- SUSE Linux Enterprise Server 12 is removed +- Ubuntu 20.04 is deprecated +- the [OpenTracing]({{< ref "nginx/admin-guide/dynamic-modules/opentracing.md" >}}) dynamic module is no longer available. It is recommended to use the [OpenTelemetry Distributed Tracing]({{< ref "nginx/admin-guide/dynamic-modules/opentelemetry.md" >}}) module, which incorporates all the features of the OpenTracing module. + +More information: [Announcing NGINX Plus R34](https://community.f5.com/kb/technicalarticles/f5-nginx-plus-r34-release-now-available/340300) + + ## NGINX Plus Release 33 (R33) _19 November 2024_
diff --git a/content/nginx/technical-specs.md b/content/nginx/technical-specs.md index 7ee616da0..76f3f339a 100644 --- a/content/nginx/technical-specs.md +++ b/content/nginx/technical-specs.md @@ -15,20 +15,19 @@ NGINX Plus is available only as a binary; it is not distributed as source code. ## Supported Distributions {#supported-distributions} {{}} -| Distribution | Supported on R33 | Supported on R32 | -|-------------------------------------|-----------------------------------------------|-----------------------------------------------| -| AlmaLinux | 8 (x86_64, aarch64)
9 (x86_64, aarch64) | 8 (x86_64, aarch64)
9 (x86_64, aarch64) | -| Alpine Linux | 3.17 (x86_64, aarch64) **(deprecated)**
3.18 (x86_64, aarch64)
3.19 (x86_64, aarch64)
3.20 (x86_64, aarch64) **(new)** | 3.16 (x86_64, aarch64) **(deprecated)**
3.17 (x86_64, aarch64)
3.18 (x86_64, aarch64)
3.19 (x86_64, aarch64) | -| Amazon Linux | 2023 (x86_64, aarch64) | 2023 (x86_64, aarch64) | -| Amazon Linux 2 | LTS (x86_64, aarch64) | LTS (x86_64, aarch64) | -| CentOS | **Not supported** | 7.4+ (x86_64) **(deprecated)** | -| Debian | 11 (x86_64, aarch64)
12 (x86_64, aarch64) | 11 (x86_64, aarch64)
12 (x86_64, aarch64) | -| FreeBSD | 13 (amd64)
14 (amd64) | 13 (amd64)
14 (amd64) | -| Oracle Linux | 8.1+ (x86_64, aarch64)
9 (x86_64) | 7.4+ (x86_64) **(deprecated)**
8.1+ (x86_64, aarch64)
9 (x86_64) | -| Red Hat Enterprise Linux (RHEL) | 8.1+ (x86_64, aarch64)
9.0+ (x86_64, aarch64) | 7.4+ (x86_64) **(deprecated)**
8.1+ (x86_64, aarch64)
9.0+ (x86_64, aarch64) | -| Rocky Linux | 8 (x86_64, aarch64)
9 (x86_64, aarch64) | 8 (x86_64, aarch64)
9 (x86_64, aarch64) | -| SUSE Linux Enterprise Server (SLES) | 12 SP5 (x86_64) **(deprecated)**
15 SP2+ (x86_64) | 12 SP5 (x86_64)
15 SP2+ (x86_64) | -| Ubuntu | 20.04 LTS (x86_64, aarch64)
22.04 LTS (x86_64, aarch64)
24.04 LTS (x86_64, aarch64) | 20.04 LTS (x86_64, aarch64)
22.04 LTS (x86_64, aarch64)
24.04 LTS (x86_64, aarch64 **(new)** | +| Distribution | Supported on R34 | Supported on R33 | +|-------------------------------------|----------------------------------------------------|--------------------------------------------------------| +| AlmaLinux | 8 (x86_64, aarch64)
9 (x86_64, aarch64) | 8 (x86_64, aarch64)
9 (x86_64, aarch64) | +| Alpine Linux | 3.18 (x86_64, aarch64) **(deprecated)**
3.19 (x86_64, aarch64)
3.20 (x86_64, aarch64)
3.21 (x86_64, aarch64) **(new)** | 3.17 (x86_64, aarch64) **(deprecated)**
3.18 (x86_64, aarch64)
3.19 (x86_64, aarch64)
3.20 (x86_64, aarch64) **(new)** | +| Amazon Linux | 2023 (x86_64, aarch64) | 2023 (x86_64, aarch64) | +| Amazon Linux 2 | LTS (x86_64, aarch64) **(deprecated)** | LTS (x86_64, aarch64) | +| Debian | 11 (x86_64, aarch64)
12 (x86_64, aarch64) | 11 (x86_64, aarch64)
12 (x86_64, aarch64) | +| FreeBSD | 13 (amd64)
14 (amd64) | 13 (amd64)
14 (amd64) | +| Oracle Linux | 8.1+ (x86_64, aarch64)
9 (x86_64) | 8.1+ (x86_64, aarch64)
9 (x86_64) | +| Red Hat Enterprise Linux (RHEL) | 8.1+ (x86_64, aarch64)
9.0+ (x86_64, aarch64) | 8.1+ (x86_64, aarch64)
9.0+ (x86_64, aarch64) | +| Rocky Linux | 8 (x86_64, aarch64)
9 (x86_64, aarch64) | 8 (x86_64, aarch64)
9 (x86_64, aarch64) | +| SUSE Linux Enterprise Server (SLES) | 15 SP2+ (x86_64) | 12 SP5 (x86_64) **(deprecated)**
15 SP2+ (x86_64) | +| Ubuntu | 20.04 LTS (x86_64, aarch64) **(deprecated)**
22.04 LTS (x86_64, aarch64)
24.04 LTS (x86_64, aarch64) | 20.04 LTS (x86_64, aarch64)
22.04 LTS (x86_64, aarch64)
24.04 LTS (x86_64, aarch64) | {{}} --- @@ -41,13 +40,11 @@ Dynamic modules are supported on the [same distributions as NGINX Plus](#support | Module | Distribution and details | |-------------------|-----------------------------------------------------------------------------------------------------------| | AppProtect | AlmaLinux/Rocky Linux: **Not supported**
Alpine Linux: **Not supported**
Amazon Linux 2: **x86_64 only**
Amazon Linux 2023: **Not supported**
Debian 11: **x86_64 only**
FreeBSD: **Not supported**
Oracle Linux 8: **x86_64 only**
RHEL 8: **x86_64 only**
SLES: **Not supported**
Ubuntu 20.04: **x86_64 only** | -| Brotli | SLES 12: **Not supported** | -| GeoIP | RHEL/Oracle Linux/AlmaLinux/Rocky Linux 8.0+, 9: **Not supported**
FreeBSD: **Not supported** | -| GeoIP2 | SLES 12: **Not supported**
Amazon Linux 2: **Not supported** | +| GeoIP | Amazon Linux 2023 **Not supported**
RHEL/Oracle Linux/AlmaLinux/Rocky Linux 8.0+, 9: **Not supported**
FreeBSD: **Not supported** | +| GeoIP2 | Amazon Linux 2: **Not supported** | | HA-Keepalived | FreeBSD: **Not supported**
Alpine Linux: **Not supported**
Amazon Linux 2: **Not supported**
Amazon Linux 2023: **Not supported** | | NGINX sync | FreeBSD: **Not supported**
Alpine Linux: **Not supported** | -| OpenTelemetry | Amazon Linux 2: **Not supported**
SLES: **Not supported** | -| OpenTracing | SLES 12: **Not supported** | +| OpenTelemetry | Amazon Linux 2: **Not supported**
SLES: **Not supported** | | {{}} --- @@ -66,7 +63,9 @@ You can configure which protocols to enable or disable with the [ssl_protocols]( TLSv1.2 and earlier are supported on all operating systems listed in [Supported Distributions](#supported-distributions). -TLSv1.3 is supported starting in NGINX Plus R17 and is enabled by default in NGINX Plus R29 and later. It requires OpenSSL 1.1.1 or higher. Note that not all operating systems supported by NGINX Plus include OpenSSL 1.1.1. Check your operating system's documentation to confirm TLSv1.3 compatibility. +TLSv1.3 is supported starting from NGINX Plus R17 and is enabled by default in NGINX Plus R29 and later. It requires OpenSSL 1.1.1 or higher. Note that not all operating systems supported by NGINX Plus include OpenSSL 1.1.1. Check your operating system's documentation to confirm TLSv1.3 compatibility. + +TLSv1.2 and TLSv1.3 are the default SSL protocols starting from NGINX Plus R34 (if supported by the OpenSSL library). If OpenSSL 1.0.0 or older is used, the default SSL protocols are TLSv1 and TLSv1.1. --- @@ -119,6 +118,7 @@ See [Sizing Guide for Deploying NGINX Plus on Bare Metal Servers](https://www.ng - [Auth Basic](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) – Implement HTTP Basic Authentication scheme - [Auth JWT](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html) – Validate JSON Web Tokens - [Auth Request](https://nginx.org/en/docs/http/ngx_http_auth_request_module.html) – Determine client authorization using subrequests to external authentication server +- [OIDC](https://nginx.org/en/docs/http/ngx_http_oidc_module.html) – Implement authentication as a Relying Party in OpenID Connect solution - [Referer](https://nginx.org/en/docs/http/ngx_http_referer_module.html) – Control access based on `Referer` field in HTTP request header - [Secure Link](https://nginx.org/en/docs/http/ngx_http_secure_link_module.html) – Process encrypted, time-limited links to content @@ -182,7 +182,7 @@ See [Sizing Guide for Deploying NGINX Plus on Bare Metal Servers](https://www.ng - [NGINX Plus API](https://nginx.org/en/docs/http/ngx_http_api_module.html) – Provide REST API for accessing metrics, configuring upstream server groups dynamically, and managing key-value pairs, without the need to reload NGINX configuration - [Key-Value Store](https://nginx.org/en/docs/http/ngx_http_keyval_module.html) – Create variables with values taken from key-value pairs managed by the [NGINX Plus API](https://nginx.org/en/docs/http/ngx_http_api_module.html#http_keyvals_) -- [Management](https://nginx.org/en/docs/ngx_mgmt_module.html) – Configure licensing and usage reporting of NGINX Plus installation to F5 licensing endpoint or [NGINX Instance Manager]({{< ref "nim/index.md" >}}) +- [Management](https://nginx.org/en/docs/ngx_mgmt_module.html) – [Configure licensing and usage reporting]({{< ref "solutions/about-subscription-licenses.md" >}}) of NGINX Plus installation to F5 licensing endpoint or [NGINX Instance Manager]({{< ref "nim/index.md" >}}) ### TCP and UDP Proxying and Load Balancing diff --git a/content/solutions/about-subscription-licenses.md b/content/solutions/about-subscription-licenses.md index 1a964d7c7..2157ead8e 100644 --- a/content/solutions/about-subscription-licenses.md +++ b/content/solutions/about-subscription-licenses.md @@ -65,11 +65,22 @@ To ensure NGINX Plus R33 or later can send usage reports, follow these steps bas ### For internet-connected environments -Allow outbound HTTPS traffic on TCP port `443` to communicate with F5's licensing endpoint (`product.connect.nginx.com`). Ensure that the following IP addresses are allowed: +1. Allow outbound HTTPS traffic on TCP port `443` to communicate with F5's licensing endpoint (`product.connect.nginx.com`). Ensure that the following IP addresses are allowed: -- `3.135.72.139` -- `3.133.232.50` -- `52.14.85.249` + - `3.135.72.139` + - `3.133.232.50` + - `52.14.85.249` + +2. (Optional, R34 and later) If your company enforces a strict outbound traffic policy, you can use an outbound proxy for establishing an end-to-end tunnel to the F5 licensing endpoint. On each NGINX Plus instance, update the [`proxy`](https://nginx.org/en/docs/ngx_mgmt_module.html#proxy) directive in the [`mgmt`](https://nginx.org/en/docs/ngx_mgmt_module.html) block of the NGINX configuration (`/etc/nginx/nginx.conf`) to point to the company's outbound proxy server: + + + ```nginx + mgmt { + proxy PROXY_ADDR:PORT; #can be http or https + proxy_username USER; #optional + proxy_password PASS; #optional + } + ``` ### For network-restricted environments diff --git a/static/nginx/images/oidc.png b/static/nginx/images/oidc.png new file mode 100644 index 000000000..2e7e86270 Binary files /dev/null and b/static/nginx/images/oidc.png differ