keycloak-uncached
Changes
docbook/reference/en/en-US/modules/proxy.xml 277(+277 -0)
Details
diff --git a/docbook/reference/en/en-US/master.xml b/docbook/reference/en/en-US/master.xml
index c9a6f21..e6cd953 100755
--- a/docbook/reference/en/en-US/master.xml
+++ b/docbook/reference/en/en-US/master.xml
@@ -39,6 +39,7 @@
<!ENTITY Clustering SYSTEM "modules/clustering.xml">
<!ENTITY ApplicationClustering SYSTEM "modules/application-clustering.xml">
<!ENTITY MultiTenancy SYSTEM "modules/multi-tenancy.xml">
+ <!ENTITY Proxy SYSTEM "modules/proxy.xml">
]>
<book>
@@ -135,6 +136,7 @@ This one is short
&SecurityVulnerabilities;
&Clustering;
&ApplicationClustering;
+ &Proxy;
&Migration;
</book>
docbook/reference/en/en-US/modules/proxy.xml 277(+277 -0)
diff --git a/docbook/reference/en/en-US/modules/proxy.xml b/docbook/reference/en/en-US/modules/proxy.xml
new file mode 100755
index 0000000..62848ec
--- /dev/null
+++ b/docbook/reference/en/en-US/modules/proxy.xml
@@ -0,0 +1,277 @@
+<chapter id="proxy">
+ <title>Keycloak Security Proxy</title>
+ <para>
+ Keycloak has an HTTP(S) proxy that you can put in front of web applications and services where it is not possible
+ to install the keycloak 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.
+ </para>
+ <section>
+ <title>Proxy Install and Run</title>
+ <para>Download the keycloak proxy distribution from the Keycloak download pages and unzip it.
+<programlisting>
+$ unzip keycloak-proxy-dist.zip
+</programlisting>
+ </para>
+ <para>
+ To run it you must have a proxy config file (which we'll discuss in a moment).
+<programlisting>
+$ java -jar bin/launcher.jar [your-config.json]
+</programlisting>
+ </para>
+ <para>
+ 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 <literal>proxy.json</literal>
+ </para>
+ </section>
+ <section>
+ <title>Proxy Configuration</title>
+ <para>
+ Here's an example configuration file.
+<programlisting><![CDATA[
+{
+ "target-url": "http://localhost:8082",
+ "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
+ }
+ ]
+ }
+ ]
+}]]>
+</programlisting>
+ </para>
+ <section>
+ <title>Basic Config</title>
+ <para>
+ The basic configuration options for the server are as follows:
+ <variablelist>
+ <varlistentry>
+ <term>target-url</term>
+ <listitem>
+ <para>
+ The URL this server is proxying <emphasis>REQUIRED.</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>bind-address</term>
+ <listitem>
+ <para>
+ DNS name or IP address to bind the proxy server's sockets to.
+ <emphasis>OPTIONAL.</emphasis>. The default value is <emphasis>localhost</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>http-port</term>
+ <listitem>
+ <para>
+ Port to listen for HTTP requests. If you do not specify this value, then the proxy will
+ not listen for regular HTTP requests.
+ <emphasis>OPTIONAL.</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>https-port</term>
+ <listitem>
+ <para>
+ Port to listen for HTTPS requests. If you do not specify this value, then the proxy will
+ not listen for HTTPS requests.
+ <emphasis>OPTIONAL.</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>keystore</term>
+ <listitem>
+ <para>
+ 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 <literal>classpath:</literal>
+ it will look for this file in the classpath.
+ <emphasis>OPTIONAL.</emphasis>. If you have enabled HTTPS, but have not defined a keystore, the proxy
+ will auto-generate a self-signed certificate and use that.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>buffer-size</term>
+ <listitem>
+ <para>
+ HTTP server socket buffer size. Usually the default is good enough. <emphasis>OPTIONAL.</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>buffers-per-region</term>
+ <listitem>
+ <para>
+ HTTP server socket buffers per region. Usually the default is good enough. <emphasis>OPTIONAL.</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>io-threads</term>
+ <listitem>
+ <para>
+ Number of threads to handle IO. Usually default is good enough. <emphasis>OPTIONAL.</emphasis>.
+ The default is the number of available processors * 2.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>worker-threads</term>
+ <listitem>
+ <para>
+ Number of threads to handle requests. Usually the default is good enough. <emphasis>OPTIONAL.</emphasis>.
+ The default is the number of available processors * 16.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </section>
+ <section>
+ <title>Application Config</title>
+ <para>
+ Next under the <literal>applications</literal> array attribute, you can define one or more applications per host you are proxying.
+ <variablelist>
+ <varlistentry>
+ <term>base-path</term>
+ <listitem>
+ <para>
+ The base context root for the application. Must start with '/' <emphasis>REQUIRED.</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>error-page</term>
+ <listitem>
+ <para>
+ If the proxy has an error, it will display the target application's error page relative URL <emphasis>OPTIONAL.</emphasis>.
+ This is a relative path to the base-path. In the example above it would be <literal>/customer-portal/error.html</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>adapter-config</term>
+ <listitem>
+ <para>
+ <emphasis>REQUIRED.</emphasis>. Same configuration as any other keycloak adapter. See <link linkend='adapter-config'>Adapter Config</link>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <section>
+ <title>Constraint Config</title>
+
+ <para>
+ Next under each application you can define one or more constraints in the <literal>constraints</literal> 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.
+ <variablelist>
+ <varlistentry>
+ <term>pattern</term>
+ <listitem>
+ <para>
+ URL pattern to match relative to the base-path of the application. Must start with '/' <emphasis>REQUIRED.</emphasis>.
+ You may only have one wildcard and it must come at the end of the pattern. Valid <literal>/foo/bar/*</literal> and <literal>/foo/*.txt</literal>
+ Not valid: <literal>/*/foo/*</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>roles-allowed</term>
+ <listitem>
+ <para>
+ Array of strings of roles allowed to access this url pattern. <emphasis>OPTIONAL.</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>methods</term>
+ <listitem>
+ <para>
+ Array of strings of HTTP methods that will exclusively match this pattern and HTTP request. <emphasis>OPTIONAL.</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>excluded-methods</term>
+ <listitem>
+ <para>
+ Array of strings of HTTP methods that will be ignored when match this pattern. <emphasis>OPTIONAL.</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>deny</term>
+ <listitem>
+ <para>
+ Deny all access to this URL pattern. <emphasis>OPTIONAL.</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>permit</term>
+ <listitem>
+ <para>
+ Permit all access without requiring authentication or a role mapping. <emphasis>OPTIONAL.</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>authenticate</term>
+ <listitem>
+ <para>
+ Require authentication for this pattern, but no role mapping. <emphasis>OPTIONAL.</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </section>
+ </section>
+ </section>
+</chapter>
\ No newline at end of file