diff --git a/server_installation/topics.adoc b/server_installation/topics.adoc index 754bb62ca7..c7d36b4fdb 100644 --- a/server_installation/topics.adoc +++ b/server_installation/topics.adoc @@ -45,7 +45,4 @@ include::topics/cache.adoc[] include::topics/cache/eviction.adoc[] include::topics/cache/replication.adoc[] include::topics/cache/disable.adoc[] -include::topics/cache/clear.adoc[] -ifeval::[{project_community}==true] -include::topics/proxy.adoc[] -endif::[] +include::topics/cache/clear.adoc[] \ No newline at end of file diff --git a/server_installation/topics/proxy.adoc b/server_installation/topics/proxy.adoc deleted file mode 100644 index 85df6f36fc..0000000000 --- a/server_installation/topics/proxy.adoc +++ /dev/null @@ -1,251 +0,0 @@ - -[[_proxy]] -== {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. -[source] ----- - -$ unzip keycloak-proxy-dist.zip ----- - -To run it you must have a proxy config file (which we'll discuss in a moment). -[source] ----- - -$ 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. -[source,json] ----- - -{ - "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. -// See <<_adapter_config,Adapter Config>> - -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: [x-]`/foo/bar/*` and [x-]`/foo/*.txt` - * Not valid: [x-]`/*/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 <<_identity_headers, {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 - -[[_identity_headers]] -=== {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: -+ -[source,json] ----- - -{ - "header-names" { - "keycloak-subject": "MY_SUBJECT" - } -} -----