Skip to main content
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
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;

​
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

​
Configure with Your Auth0 Application Information

Run the configure.sh script inside nginx-openid-connect folder to populate template configuration for your Auth0 application: Next, add your tenant’s logout URL to openid_connect_configuration.conf file

​
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
    ...
}

​
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

​
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;
    }
}
Edit on GitHub