Try to build a reverse proxy type configuration with Keycloak (Security Proxy edition)

What to do today

This time on the 7th day of the Keycloak Advent Calendar, we'll try Keycloak's Security Proxy.

Security Proxy is a type of simple reverse proxy (hereinafter referred to as Rivapro) server implemented in Java. The Liverpro server itself replaces Keycloak's client adapter, allowing you to protect the content you proxy to and control access by URL. It is suitable for use when the application server does not support OpenID Connect or SAML, it is difficult to install a client adapter, or the environment does not support the client adapter.

The main functions are as follows.

--HTTP (S) reverse proxy function --OpenID Connect integration with Keycloak server --Content protection for each specific path --Access control by authentication request --Allow or deny specific HTTP methods --Access control by the role of authenticated user --Deny access to specific URLs --Specify a URL that can be accessed without authentication --Information linkage of authenticated users by HTTP header

This time, I will try the procedure for protecting with Security Proxy for the original sample application of Tomcat 8.

Server configuration for operation check

The trial environment this time is like this. A demo realm has been created on the Keycloak server (see article on day 3 [https://qiita.com/tamura__246/items/4290a1035e1adcab733b)), and users with the following roles It is assumed that it exists.

In the exapmles application that comes with Tomcat, it is assumed that the following access control is applied.

The access ports to each server when checking the operation are as follows.

Keycloak server side settings

Add / configure client

1. Log in to the Keycloak admin console.
2. From the left menu bar, select the demo realm.
3. Click Client on the left menu bar. A list of clients is displayed.
4. Press the Create button in the upper right.
5. Enter the following client settings and press the Save button. --Client ID: kc-proxy --Client protocol: openid-connect --Root URL: https://kc-proxy.example.com:18443
6. The kc-proxy setting screen will continue to be displayed. Make the following settings and press the Save button. --Access type: confidential --Valid redirect URI (first): https://kc-proxy.example.com:18443/ --Valid redirect URI (second): https://kc-proxy.example.com:18443/examples/websocket/echo.xhtml : information_source: Valid redirect URI can also be specified by wildcard on Keycloak. However, the OIDC specification requires that it exactly match redirect_uri, so here we specify all possible URLs to redirect to. Therefore, you cannot directly transition from the unlogged-in state to the URL not specified here.
7. Press the Credentials tab.
8. Make a note of the value displayed as secret.

Security Proxy side configuration and startup

Introduction of sample application

As a sample application for checking the cooperation, install Tomcat 8.0 and start it.

cd  /tmp
wget http://ftp.tsukuba.wide.ad.jp/software/apache/tomcat/tomcat-8/v8.5.23/bin/apache-tomcat-8.5.23.tar.gz
tar zxvf apache-tomcat-8.5.23.tar.gz -C /usr/local
cd /usr/local/apache-tomcat-8.5.23/
./bin/startup.sh

Download and deploy Security Proxy

Download the Security Proxy, unzip it to / usr / local, and change it to the extracted directory.

cd  /tmp
wget https://downloads.jboss.org/keycloak/3.3.0.CR2/keycloak-proxy-3.3.0.CR2.zip
unzip keycloak-proxy-3.3.0.CR2.zip -d /usr/local
cd /usr/local/keycloak-proxy-3.3.0.CR2/

Security Proxy configuration file creation

In order to operate Security Proxy, create the following configuration file.

json:/usr/local/keycloak-proxy-3.3.0.CR2/proxy.json

{
    "target-url": "http://localhost:8080",
    "send-access-token": true,
    "bind-address": "{IP address / DNS name to bind}",
    "http-port": "18080",
    "https-port": "18443",
    "applications": [
        {
            "base-path": "/",
            "adapter-config": {
                "realm": "demo",
                "resource": "kc-proxy",
                "auth-server-url": "https://kc-server.example.com:8443/auth",
                "ssl-required" : "external",
                "credentials": {
                    "secret": "{Keycloak server-side secret value}"
                }
            },
            "constraints": [
                {
                    "pattern": "/*",
                    "authenticate": true
                },
                {
                    "pattern": "/examples/jsp/*",
                    "permit": true
                },
                {
                    "pattern": "/examples/websocket/*",
                    "roles-allowed": [
                        "admin"
                    ]
                }
            ]
        }
    ]
}

The meaning of the setting parameters in proxy.json is described below.

basic configuration

applications settings

adapter-config settings

: information_source: Since there are so many adapter-config settings, only the minimum items required for operation check are listed. For other parameters, see Reference "Java Adapter Config".

setting constraint

After creating proxy.json, you can start Security Proxy from the following command.

cd /usr/local/keycloak-proxy-3.3.0.CR2/
java -jar bin/launcher.jar proxy.json

If there is no problem with the configuration file, the following startup message will be displayed.

Home directory: /usr/local/keycloak-proxy-3.3.0.CR2
11 24, 2017 6:44:37 pm org.keycloak.proxy.ProxyServerBuilder initConnections
WARN: Generating temporary SSL cert
11 24, 2017 6:44:45 pm org.xnio.Xnio <clinit>
INFO: XNIO version 3.3.6.Final
11 24, 2017 6:44:45 pm org.xnio.nio.NioXnio <clinit>
INFO: XNIO NIO Implementation Version 3.3.6.Final

Operation check

URL that requires authentication

1. Go to https://kc-proxy.example.com:18443/, which requires authentication.
2. Since you have not logged in to Keycloak, you will be redirected to the login screen.
3. Log in with ID / PW.
4. The top screen of Tomcat is displayed.
5. Go to https://kc-proxy.example.com:18443/examples/servlets/servlet/RequestHeaderExample.
6. You can see that the Keycloak user information is linked to the HTTP header.

URL that does not require authentication

1. Go to https://kc-proxy.example.com:18443/examples/jsp/, which does not require authentication.
2. You can see that you can browse the page without authenticating.

URLs that require the admin role

1. Go to https://kc-proxy.example.com:18443/examples/websocket/echo.xhtml, which requires the admin role.
2. Log in with the ID / PW of the user who has the admin role.
3. https://kc-proxy.example.com:18443/examples/websocket/echo.xhtml is displayed. (If you log in as a user who does not have the admin role, you will get a 403 error)

Summary

This time, I confirmed how to link Keycloak and Security Proxy with ID. Basically, you can check the ID linkage with Keycloak just by placing one json file for setting, so I think that it is useful as a simple operation check of the reverse proxy type.

However, there are some functional deficiencies as a reverse proxy when incorporating the Security Proxy into the system in earnest.

--Only one server can be specified as a proxy transfer destination --No access log --Cannot perform fine control like Apache (URL replacement, header replacement, load balancing, etc.) --Limited items that can be linked as HTTP headers

Therefore, when using a reverse proxy type configuration, by using "Try to build a reverse proxy type configuration with Keycloak (mod_auth_openidc edition)" that I explain in the article on the 8th day, while compensating for the above shortcomings, the reverse proxy Flexible settings are available as.

Reference material

• Keycloak Documentation
• 10. Keycloak Security Proxy
• 2.1.1. Java Adapter Config -NRI OpenStandia Keycloak Japanese Document

footnote

[^ auth-server-url]: When using a self-signed server certificate for ssl connection with Keycloak server, it is necessary to import the server certificate into the Java truststore on the Security Proxy side. (Because the Security Proxy communicates directly with the Keycloak server via SSL)