Single Sign-On With Auth0

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 as the Identity Provider (IdP), and NGINX Plus as the Relying Party, or OIDC client application that verifies user identity.

This guide applies to NGINX Plus Release 34 and later. In earlier versions, NGINX Plus relied on an njs-based solution, which required NGINX JavaScript files, key-value stores, and advanced OpenID Connect logic. In the latest NGINX Plus version, the new OpenID Connect module simplifies this process to just a few directives.

Prerequisites

An Auth0 tenant with administrator privileges.
An NGINX Plus subscription and NGINX Plus Release 34 or later. For installation instructions, see Installing NGINX Plus.
A domain name pointing to your NGINX Plus instance, for example, demo.example.com.

Create a new Auth0 Application

Log in to your Auth0 Dashboard at manage.auth0.com.
Select Applications > Applications from the sidebar menu.
On the Applications screen, select Create Application.
On the Create application screen:
- Enter the Name for the application, for example, NGINX Demo App.
- In Application Type, select Regular Web Applications.
- Select Create.
On the Settings screen of your application:
- Copy your Client ID and Client Secret displayed in the Basic Information section — you will need them later when configuring NGINX Plus.
On the Application URIs section of your application:
- Add the URI NGINX Plus callback URI in the Allowed Callback URLs field, for example:
  
  https://demo.example.com/oidc_callback.

Get the OpenID Connect Discovery URL

Check the OpenID Connect Discovery URL. By default, Auth0 publishes the .well-known/openid-configuration document at the following address:

https://yourTenantId.us.auth0.com/.well-known/openid-configuration.

Run the following curl command in a terminal:

curl https://yourTenantId.us.auth0.com/.well-known/openid-configuration | jq

where:

the yourTenantId is your Auth0 Tenant ID
the yourTenantId.us.auth0.com/ is your Auth0 server address
the /.well-known/openid-configuration is the default address for Auth0 for document location
the jq command (optional) is used to format the JSON output for easier reading and requires the jq JSON processor to be installed.

The configuration metadata is returned in the JSON format:

{
    ...
    "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",
    ...
}

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.

You will need the values of Client ID, Client Secret, and Issuer in the next steps.

Set up NGINX Plus

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.

Ensure that you are using the latest version of NGINX Plus by running the nginx -v command in a terminal:
nginx -v
```
nginx -v
```
The output should match NGINX Plus Release 34 or later:
nginx version: nginx/1.27.4 (nginx-plus-r34)
```
nginx version: nginx/1.27.4 (nginx-plus-r34)
```
Ensure that you have the values of the Client ID, Client Secret, and Issuer obtained during Auth0 Configuration.
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).
In the http {} context, make sure your public DNS resolver is specified with the 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; # ... }
```
http {
    resolver 10.0.0.1 ipv4=on valid=300s;

    # ...
}
```

In the http {} context, define the Auth0 provider named auth0 by specifying the oidc_provider {} context:

http {
    resolver 10.0.0.1 ipv4=on valid=300s;

    oidc_provider auth0 {

        # ...

    }
    # ...
}

In the oidc_provider {} context, specify:
- Your actual Auth0 Client ID obtained in Auth0 Configuration with the client_id directive
- Your Client Secret obtained in Auth0 Configuration with the client_secret directive
- The Issuer URL obtained in Auth0 Configuration with the issuer 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 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_id>; client_secret <client_secret>; } # ... }
```
http {
    resolver 10.0.0.1 ipv4=on valid=300s;

    oidc_provider auth0 {
        issuer        https://yourTenantId.us.auth0.com/;
        client_id     <client_id>;
        client_secret <client_secret>;
    }

    # ...
}
```

Make sure you have configured a server that corresponds to demo.example.com, and there is a location that points to your application (see Step 10) at http://127.0.0.1:8080 that is going to be OIDC-protected:

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;
        }
    }
    # ...
}

Protect this location with Auth0 OIDC by specifying the auth_oidc directive that will point to the auth0 configuration specified in the oidc_provider {} context in Step 5:

# ...
location / {
     auth_oidc auth0;

     # ...

     proxy_pass http://127.0.0.1:8080;
}
# ...

Pass the OIDC claims as headers to the application (Step 10) with the proxy_set_header directive. These claims are extracted from the ID token returned by Auth0:

$oidc_claim_email the e-mail address of the user
$oidc_claim_name - the full name of the user
any other OIDC claim using the $oidc_claim_ variable

# ...
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;
}
# ...

Create a simple test application referenced by the proxy_pass directive which returns the authenticated user’s full name and email upon successful authentication:

# ...
server {
    listen 8080;

    location / {
        return 200 "Hello, $http_name!\nEmail: $http_email\nAuth0 sub: $http_sub\n";
        default_type text/plain;
    }
}

Save the NGINX configuration file and reload the configuration:
nginx -s reload
```
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.

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_id>;
        client_secret <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

Open https://demo.example.com/ in a browser. You will be redirected to the Auth0 sign-in page.
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

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 for details. The solution uses the nginx-openid-connect GitHub repository and NGINX JavaScript files.

Revision History

Version 1 (March 2025) – Initial version (NGINX Plus Release 34)

Last modified April 1, 2025