proxy docs
This commit is contained in:
parent
d7dfacabfa
commit
cdd751a38b
2 changed files with 279 additions and 0 deletions
|
@ -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>
|
||||
|
|
277
docbook/reference/en/en-US/modules/proxy.xml
Executable file
277
docbook/reference/en/en-US/modules/proxy.xml
Executable file
|
@ -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>
|
Loading…
Reference in a new issue