Permalink
Fetching contributors…
Cannot retrieve contributors at this time
252 lines (195 sloc) 7.73 KB

{project_name} Security Proxy

{project_name} has an HTTP(S) proxy that you can put in front of web applications and services where it is not possible to install the {project_name} adapter. You can set up URL filters so that certain URLs are secured either by browser login and/or bearer token authentication. You can also define role constraints for URL patterns within your applications.

Proxy Install and Run

Download the {project_name} proxy distribution from the {project_name} download pages and unzip it.

$ unzip keycloak-proxy-dist.zip

To run it you must have a proxy config file (which we’ll discuss in a moment).

$ java -jar bin/launcher.jar [your-config.json]

If you do not specify a path to the proxy config file, the launcher will look in the current working directory for the file named proxy.json

Proxy Configuration

Here’s an example configuration file.

{
    "target-url": "http://localhost:8082",
    "target-request-timeout": "60000",
    "send-access-token": true,
    "bind-address": "localhost",
    "http-port": "8080",
    "https-port": "8443",
    "keystore": "classpath:ssl.jks",
    "keystore-password": "password",
    "key-password": "password",
    "applications": [
        {
            "base-path": "/customer-portal",
            "error-page": "/error.html",
            "adapter-config": {
                "realm": "demo",
                "resource": "customer-portal",
                "realm-public-key": "MIGfMA0GCSqGSIb",
                "auth-server-url": "http://localhost:8081/auth",
                "ssl-required" : "external",
                "principal-attribute": "name",
                "credentials": {
                    "secret": "password"
                }
            }
            ,
            "constraints": [
                {
                    "pattern": "/users/*",
                    "roles-allowed": [
                        "user"
                    ]
                },
                {
                    "pattern": "/admins/*",
                    "roles-allowed": [
                        "admin"
                    ]
                },
                {
                    "pattern": "/users/permit",
                    "permit": true
                },
                {
                    "pattern": "/users/deny",
                    "deny": true
                }
            ]
        }
    ]
}

Basic Config

The basic configuration options for the server are as follows:

target-url

The URL this server is proxying. REQUIRED.

target-request-timeout

The timeout (in ms) for the proxied request. OPTIONAL. Default is 30000.

send-access-token

Boolean flag. If true, this will send the access token via the KEYCLOAK_ACCESS_TOKEN header to the proxied server. OPTIONAL. Default is false.

bind-address

DNS name or IP address to bind the proxy server’s sockets to. OPTIONAL. The default value is localhost

http-port

Port to listen for HTTP requests. If you do not specify this value, then the proxy will not listen for regular HTTP requests. OPTIONAL.

https-port

Port to listen for HTTPS requests. If you do not specify this value, then the proxy will not listen for HTTPS requests. OPTIONAL.

keystore

Path to a Java keystore file that contains private key and certificate for the server to be able to handle HTTPS requests. Can be a file path, or, if you prefix it with classpath: it will look for this file in the classpath. OPTIONAL. If you have enabled HTTPS, but have not defined a keystore, the proxy will auto-generate a self-signed certificate and use that.

buffer-size

HTTP server socket buffer size. Usually the default is good enough. OPTIONAL.

buffers-per-region

HTTP server socket buffers per region. Usually the default is good enough. OPTIONAL.

io-threads

Number of threads to handle IO. Usually default is good enough. OPTIONAL. The default is the number of available processors * 2.

worker-threads

Number of threads to handle requests. Usually the default is good enough. OPTIONAL. The default is the number of available processors * 16.

Application Config

Next under the applications array attribute, you can define one or more applications per host you are proxying.

base-path

The base context root for the application. Must start with '/'. REQUIRED.

error-page

If the proxy has an error, it will display the target application’s error page relative URL. OPTIONAL. This is a relative path to the base-path. In the example above it would be /customer-portal/error.html.

adapter-config

REQUIRED. Same configuration as any other {project_name} adapter.

proxy-address-forwarding

Enable usage of X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto when hosted behind another proxy/load-balancer.

Constraint Config

Next under each application you can define one or more constraints in the constraints array attribute. A constraint defines a URL pattern relative to the base-path. You can deny, permit, or require authentication for a specific URL pattern. You can specify roles allowed for that path as well. More specific constraints will take precedence over more general ones.

pattern

URL pattern to match relative to the base-path of the application. Must start with '/'. REQUIRED. You may only have one wildcard and it must come at the end of the pattern.

  • Valid: /foo/bar/* and /foo/*.txt

  • Not valid: /*/foo/*.

roles-allowed

Array of strings of roles allowed to access this url pattern. OPTIONAL.

methods

Array of strings of HTTP methods that will exclusively match this pattern and HTTP request. OPTIONAL.

excluded-methods

Array of strings of HTTP methods that will be ignored when match this pattern. OPTIONAL.

deny

Deny all access to this URL pattern. OPTIONAL.

permit

Permit all access without requiring authentication or a role mapping. OPTIONAL.

permit-and-inject

Permit all access, but inject the headers, if user is already authenticated. OPTIONAL.

authenticate

Require authentication for this pattern, but no role mapping. OPTIONAL.

Header Names Config

Next under the list of applications you can override the defaults for the names of the header fields injected by the proxy (see {project_name} Identity Headers). This mapping is optional.

keycloak-subject

e.g. MYAPP_USER_ID

keycloak-username

e.g. MYAPP_USER_NAME

keycloak-email

e.g. MYAPP_USER_EMAIL

keycloak-name

e.g. MYAPP_USER_ID

keycloak-access-token

e.g. MYAPP_ACCESS_TOKEN

{project_name} Identity Headers

When forwarding requests to the proxied server, {project_name} Proxy will set some additional headers with values from the OIDC identity token it received for authentication.

KEYCLOAK_SUBJECT

User id. Corresponds to JWT sub and will be the user id {project_name} uses to store this user.

KEYCLOAK_USERNAME

Username. Corresponds to JWT preferred_username.

KEYCLOAK_EMAIL

Email address of user if set.

KEYCLOAK_NAME

Full name of user if set.

KEYCLOAK_ACCESS_TOKEN

Send the access token in this header if the proxy was configured to send it. This token can be used to make bearer token requests. Header field names can be configured using a map of header-names in configuration file:

{
    "header-names" {
        "keycloak-subject": "MY_SUBJECT"
    }
}