Enhanced Modern Applications and MicroServices SSO with NGINX

momahdy · ‎29-Mar-2023

Use case intro
Lab setup
UDF lab Link
NGINX Plus configurations
Auth0 Configurations
Additional learning links

Use case intro

NGINX Plus adds Single Sign-On Access feature on top of NGINX well-known flexibility of deployment whether containerized micro application, as a caching node, reverse proxy infront of multiple applications or other types of implementations.

In this article we will go through a scenario where a user is trying to access application via NGINX Plus reverse proxy with Single Sign-On feature.

Testing flow,

User access the application URL (http://nginxsso-app.f5-local.demo/).
NGINX Plus redirects user to Auth0 for authentication.
User to provide credentials to Auth0.
Auth0 verifies the credentials and redirect the browser back to NGINX Plus instance.
NGINX Plus validates the received code exchange flow and pass the traffic to the application.

Lab setup

UDF lab Link

https://udf.f5.com/b/e5c321ce-3b7b-4d9b-a032-06236a3d19a6#documentation

NGINX Plus configurations

We will start with installing NGINX Plus, How to install NGINX Plus ?
Then enable Single Sign-On module and download OpenID Connector to automate the creation of OpenID configurations via the below commands,

#For Ubuntu 
sudo apt install nginx-plus-module-njs jq
#For Centos 
sudo yum install nginx-plus-module-njs jq
#Then update file /etc/nginx/nginx.conf and add the below line 
load_module modules/ngx_http_js_module.so;

#Then install OpenID connector 
git clone https://github.com/nginxinc/nginx-openid-connect
cd nginx-openid-connect

Once the above steps are done, we have our NGINX Plus ready.

Auth0 Configurations

This can be found also through NGINX documentation via SSO Auth0

Note, Follow the NGINX guide till step 4 for Application creation.

Once you have the application ready at Auth0, head to Quick Start tab

In the Quick Start tab, you will be presented with the configuration lines to configure NGINX Plus for this specific application.

# Checkout nginx-openid-connect template repository
git clone https://github.com/nginxinc/nginx-openid-connect

#Add Auth0 configurations 
./configure.sh --auth_jwt_key request \
  --client_id ############### \
  --pkce_enable \
  https://#########.eu.auth0.com/.well-known/openid-configuration

#Add tenant's logout url to openid_connect_configuration.conf
map $host $oidc_logout_redirect {
    default "https://dev-i8eatgnr2ik7hr68.eu.auth0.com/v2/logout";
}

#Add Accept-Encoding type for the Token and JWKS Endpoints 
# 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 
sudo cp openid_connect.js \ 
   frontend.conf \
   openid_connect_configuration.conf \
   openid_connect.server_conf /etc/nginx/conf.d

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

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

Now, we have both our application and NGINX Plus ready for testing.

Additional learning links

In this section, I'm listing some of the useful learning videos that can help with additional features to the setup.

Leveraging Kubernetes for Authentication and Authorization

How NGINX code is constructred ?

Open ID Manual approach (not using Github repo mentioned above) and deep dive in OAuth with NGINX Plus.

DevCentral