NGINX Plus

By Amin Abbaspour

This tutorial demonstrates how to use the `nginx-openid-connect` module to add authentication and authorization to your NGINX server. We recommend that you log in to follow this quickstart with examples configured for your account.

System Requirements

This tutorial and seed project have been tested with the following:

NGINX Plus R24

Please follow the steps below to configure your application using NGINX Plus to work with Auth0 and Open ID Connect.

Install and Enable nginx-plus-module-njs Module

First, you need to install the nginx-plus-module-njs module for NGINX Plus. Follow the dynamic module installation guide to install packages in your host OS. For Linux distributions that use yum package manager install as follows:

sudo yum install nginx-plus-module-njs jq

Was this helpful?

Once you've installed it, you need to enable it for NGINX by adding the following line near the top of your /etc/nginx/nginx.conf file:

load_module modules/ngx_http_js_module.so;

Was this helpful?

Checkout nginx-openid-connect Template Repository

Clone nginx-openid-connect GitHub repository. This repository comes with a template configuration.

git clone https://github.com/nginxinc/nginx-openid-connect

Was this helpful?

Configure with Your Auth0 Application Information

Run the configure.sh script inside nginx-openid-connect folder to populate template configuration for your Auth0 application:

./configure.sh --auth_jwt_key request \
  --client_id {yourClientId} \
  --pkce_enable \
  https://{yourDomain}/.well-known/openid-configuration

Was this helpful?

Next, add your tenant’s logout URL to openid_connect_configuration.conf file

# openid_connect_configuration.conf
map $host $oidc_logout_redirect {
    default "https://{yourDomain}/v2/logout";
}

Was this helpful?

Set Accept-Encoding Type for Token and JWKS Endpoints

Add Accept-Encoding header in openid_connect.server_conf

# openid_connect.server_conf
location = /_jwks_uri {
    internal;
    ...
    proxy_set_header    Content-Length "";           
    proxy_set_header    Accept-Encoding "gzip";          # this is required
    ...
}

location = /_token {
    internal;
    ...
    proxy_set_header    Content-Type "application/x-www-form-urlencoded";
    proxy_set_header    Accept-Encoding "gzip";          # this is required
    ...
}

Was this helpful?

Copy OpenID Connect Config Files to NGINX Server

You need to copy four files to the config folder of NGINX server machine

sudo cp openid_connect.js \ 
   frontend.conf \
   openid_connect_configuration.conf \
   openid_connect.server_conf /etc/nginx/conf.d

Was this helpful?

Configuring Auth0 Settings

In your application settings add a new "Allowed Callback URLs" that is equal to https://server-fqdn/_codexch.

Then, change "Token Endpoint Authentication Method" to "None" in Auth0 for your Application. This is required for PKCE authorisation code flow.

Passing Headers to Upstream Application

Edit /etc/nginx/conf.d/frontend.conf and add additional headers from id_token to the upstream target:

# frontend.conf
# auth_jwt_claim_set $claim_name https://namespace/key;

server {
    include conf.d/openid_connect.server_conf; # Authorization code flow and Relying Party processing
    error_log /var/log/nginx/error.log debug;  # Reduce severity level as required

    listen 8010; # Use SSL/TLS in production
    
    location / {
        # This site is protected with OpenID Connect
        auth_jwt "" token=$session_jwt;
        error_page 401 = @do_oidc_flow;

        #auth_jwt_key_file $oidc_jwt_keyfile; # Enable when using filename
        auth_jwt_key_request /_jwks_uri; # Enable when using URL

        # Successfully authenticated users are proxied to the backend,
        # with 'sub' claim passed as HTTP header
        proxy_set_header username $jwt_claim_sub;
        proxy_set_header x-email $jwt_claim_email;
        #proxy_set_header x-custom $claim_name;             # namespaced claim

        proxy_pass http://my_backend; # The backend site/app

        access_log /var/log/nginx/access.log main_jwt;
    }
}

Was this helpful?

Did it work?

Any suggestion or typo?

Edit on GitHub