Add authentication in front of your apps with a reverse proxy using Keycloak and OpenResty

Recently I setup a bunch of apps to assist with malware analysis and realised that I didn't want to expose the applications to the internet directly and wanted a layer of authentication in between my applications and the internet and a reverse proxy was the solution is settled on. 

Using OpenResty and Keycloak I was able to setup a single entry point for my web applications and have it serve as an authentication point before traffic is passed on to my apps preventing people from accessing them without first authenticating. Any requests to the sites will be redirected to an authentication portal where the user then signs on and then is redirected to the application. 

Disclaimer: this guide is intended as a demonstration only and not intended for production systems.

Prerequisite: 

• Ubuntu 22.04
• Application(s) to redirect your traffic to

Step 1 - Installing OpenResty

For this step you should visit the OpenResty official website and choose your Linux package and follow install instructions but i will include install instructions below for completeness.

1.1 - Install some prerequisites needed by adding GPG public keys (could be removed later):

$ sudo apt-get -y install --no-install-recommends wget gnupg ca-certificates

1.2 - import the GPG key:

$ wget -O - https://openresty.org/package/pubkey.gpg | sudo gpg --dearmor -o /usr/share/keyrings/openresty.gpg

1.3 - add the official APT repository:

$ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/openresty.gpg] http://openresty.org/package/ubuntu $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/openresty.list > /dev/null

1.4 - update the APT index:

$ sudo apt-get update

1.5 - install a OpenResty and recommended packages:

$ sudo apt-get -y install --no-install-recommends openresty

Step 2 - Install additional required Lua packages

Install the lua-resty-openidc package with:

$ opm install zmartzone/lua-resty-openidc

2.1 - Install lua-pack

$ sudo apt install luarocks
$ luarocks install lua_pack

Step 3 - Verify OpenResty Install

3.1 - Create a nginx.conf file for testing.

Create a simple plain text file named /usr/local/openresty/conf/nginx.conf with the following contents in it:

worker_processes  1;
error_log logs/error.log;
events {
    worker_connections 1024;
}
http {
    server {
        listen 8080;
        location / {
            default_type text/html;
            content_by_lua_block {
                ngx.say("
hello, world
")
            }
        }
    }
}

3.2 - Start the Nginx server:

 
$ PATH=/usr/local/openresty/nginx/sbin:$PATH
$ export PATH

3.3 - Access the service:

Point your browser to http://localhost:8080/ you should see the following output

 
hello, world

Step 4 - Install KeyCloak

4.1 - Installing KeyCloak on Docker didn't work for me, I think due to hardware issues due to my virtualised environment, so I installed using the bare metal option see here for install guide.

Once KeyCloak is installed run:

 
# bin/kc.sh start-dev

4.2 - Now navigate to 127.0.0.1:8080 and you should be presented with the following screen:

Step 5 - Configure KeyCloak

5.2 - Sign into KeyCloak using the default credentials.

username: admin

password: admin

4.3 - Create a Realm:

A realm manages a set of users, credentials, roles, and groups. A real would be created for each set of applications you want to manage so for myself I need one realm for my malware set of applications.
.

4.4 - Create a Client

Clients are entities that can request Keycloak to authenticate a user. Most often, clients are applications and services that want to use Keycloak to secure themselves and provide a single sign-on solution. So I will need one client for each of the applications I wish to secure behind keycloak.

4.5 - Set Client Authentication to "On"

This defines the type of of the OIDC client. When it's ON, the OIDC type is set to confidential access type. When it's OFF, it is set to public access type. We want it set to "ON" for our client.

4.6 - Create a user for our application

Now we need to create a user so we can authenticate to our application:

4.7 - Set a password for our test user:

Step 5 - Configure OpenResty nginx.conf

Ok now we have KeyCloak installed we need to configure our OpenResty nginx.conf file so it will protect our application.

5.1 - Open the nginx.conf file:

 
$ nano /usr/local/openresty/nginx/conf/nginx.conf

make the following update depending on your application. Here is mine:

 
worker_processes 1;
error_log logs/error.log;

events {
	worker_connections 1-24;
}

http {
	lua_package_path "/usr/local/lib/5.2/?.lua;;";
    
    resolver 8.8.8.8;
    
    server {
    	listen 80;
        server_name 192.168.159.128;
        
        access_by_lua_block {
        
        	local opts = {
            	redirect_uri = "http://192.168.159.130/malware.html",
                discovery = "http://192.168.159.128:8080/realms/malware/.well-knowm/openid-configuration",
                client_id = "app1",
                client_secret = "",
                redirect_uri_scheme = "http",
                logout_path = "/logout",
                redirect_after_logout_uri = "http://192.168.159.128:8080/realms/malware/protocol/openid-connect/logout?",
                redirect_after_logout_with_id_token_hint = false,
                session_contents = {id_token=true}
           }
        -- call introspect for OAuth 2.0 Bearer Access Token validation
        local res, err = require ("resty.openidc").authenticate(opts)
        iff err then
        	ngx.status = 403
            ngx.say(err)
            ngx.exit(ngx.HTTP_FORBIDDEN)
            end
        }
        
        # disable caching by broser
        #
        expires	0;
        add_header Cache-Control private;
	}
}

Step 6 - Test our auth on our application

Ok so we have set KeyCloak to listen to http://192.168.159.128:80. This would be the address that we would forward the public internet to so that they would then be redirected once authenticated.

Navigate to http://192.168.159.128:80 and you should be presented with a KeyCloak logon page.

Input the credentials of your KeyCloak test user you created earlier:

And there you have it!

Hopefully you were redirected to your application as I was.

To logout use the logout URI we specified in the nginx.conf file "http://192.168.159.128:8080/realms/malware/protocol/openid-connect/logout??