libre.sh/keycloak-scim
2
0
Fork 0
Code Issues 14 Pull requests Releases Packages Activity Actions 6

proxy docs

Browse source
This commit is contained in:
Bill Burke 2016-05-04 11:06:04 -04:00
parent 52a365835f
commit 70e31a7546
3 changed files with 119 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

125
topics/clustering/load-balancer.adoc
View file

@ -1,10 +1,113 @@
=== Setting Up a Load Balancer === Setting Up a Load Balancer or Proxy
This section only covers configuring the built in load balancer that is discussed in the This section discusses a number of things you need to configure before you can put a reverse proxy or load balancer
in front of your clustered {{book.project.name}} deployment. It also covers configuring the built in load balancer that
was <<fake/../../operating-mode/domain.adoc#_clustered-domain-example, Clustered Domain Example>>.
==== Identifying Client IP Addresses
A few features in {{book.project.name}} rely on the fact that the remote
address of the HTTP client connecting to the authentication server is the real IP address of the client machine. This can
be problematic when you have a reverse proxy or loadbalancer in front of your {{book.project.name}} authentication server.
The usual setup is that you have a frontend proxy sitting on a public network that load balances and forwards requests
to backend {{book.project.name}} server instances that sin on a private network. There is some extra configuration you have to do in this scenario
so that the actual client IP address is forwarded to and processed by the {{book.project.name}} server instances. Specifically:
* Configure your reverse proxy (loadbalancer) to properly set `X-Forwarded-For` and `X-Forwarded-Proto` HTTP headers.
* Configure the authentication server to read the client's IP address from `X-Forwarded-For header`.
Configuring your proxy to generate the `X-Forwarded-For` and `X-Forwarded-Proto` HTTP headers is beyond the scope of this
guide. Take extra precautions to ensure that the
`X-Forwared-For` header is set by your proxy. If your proxy isn't configured correctly, then _rogue_ clients can set this header themselves and trick {{book.project.name}}
into thinking the client is connecting from a different IP address than it actually is. This becomes really important if you are doing
any black or white listing of IP addresses.
Beyond the proxy itself, there are a few things you need to configure on the {{book.project.name}} side of things.
If your proxy is forwarding requests via the HTTP protocol, then you need to configure {{book.project.name}} to pull the client's
IP address from the `X-Forwarded-For` header rather than from the network packet.
To do this, open up the profile configuration file (_standalone.xml, _standalone-ha.xml_, or _domain.xml_ depending on your
<<fake/../../operating-mode.adoc#_operating-mode, operating mode>>) and look for the `"urn:jboss:domain:undertow:3.0` XML block.
.`X-Forwarded-For` HTTP Config
[source,xml]
----
<subsystem xmlns="urn:jboss:domain:undertow:3.0">
<buffer-cache name="default"/>
<server name="default-server">
<ajp-listener name="ajp" socket-binding="ajp"/>
<http-listener name="default" socket-binding="http" redirect-socket="https"
proxy-address-forwarding="true"/>
...
</server>
...
</subsystem>
----
Add the `proxy-address-forwarding` attribute to the `http-listener` element. Set the value to `true`.
If your proxy is using the AJP protocol instead of HTTP to forward requests (i.e. Apache HTTPD + mod-cluster), then you have
to configure things a little differently. Instead of modifying the `http-listener`, you need to add a filter to
pull this information from the AJP packets.
.`X-Forwarded-For` AJP Config
[source,xml]
----
<<subsystem xmlns="urn:jboss:domain:undertow:3.0">
<buffer-cache name="default"/>
<server name="default-server">
<ajp-listener name="ajp" socket-binding="ajp"/>
<http-listener name="default" socket-binding="http" redirect-socket="https"/>
<host name="default-host" alias="localhost">
...
<filter-ref name="proxy-peer"/>
</host>
</server>
...
<filters>
...
<filter name="proxy-peer"
class-name="io.undertow.server.handlers.ProxyPeerAddressHandler"
module="io.undertow.core" />
</filters>
</subsystem>
----
==== Enable HTTPS/SSL with a Reverse Proxy
Assuming that your reverse proxy doesn't use port 8443 for SSL you also need to configure what port HTTPS traffic is redirected to.
[source,xml]
----
<subsystem xmlns="urn:jboss:domain:undertow:3.0">
...
<http-listener name="default" socket-binding="http"
proxy-address-forwarding="true" redirect-socket="proxy-https"/>
...
</subsystem>
----
Add the `redirect-socket` attribute to the `http-listener` element. The value should be `proxy-https` which points to a
socket binding you also need to define.
Then add a new `socket-binding` element to the `socket-binding-group` element:
[source]
----
<socket-binding-group name="standard-sockets" default-interface="public"
port-offset="${jboss.socket.binding.port-offset:0}">
...
<socket-binding name="proxy-https" port="443"/>
...
</socket-binding-group>
----
==== Using the Built-In Load Balancer
This section covers configuring the built in load balancer that is discussed in the
<<fake/../../operating-mode/domain.adoc#_clustered-domain-example, Clustered Domain Example>>. <<fake/../../operating-mode/domain.adoc#_clustered-domain-example, Clustered Domain Example>>.
The link:{{book.appserver.loadbalancer.link}}[the load balancer] chapter of the {{book.appserver.loadbalancer.name}}
has information on using some other software based load balancers that may help you.
The <<fake/../../operating-mode/domain.adoc#_clustered-domain-example, Clustered Domain Example>> is only designed to run The <<fake/../../operating-mode/domain.adoc#_clustered-domain-example, Clustered Domain Example>> is only designed to run
on one machine. To bring up a slave on another host, you'll need to on one machine. To bring up a slave on another host, you'll need to
@ -14,7 +117,9 @@ on one machine. To bring up a slave on another host, you'll need to
the _standalone/_ directory. the _standalone/_ directory.
. Edit the _host-slave.xml_ file to change the bind addresses used or override them on the command line . Edit the _host-slave.xml_ file to change the bind addresses used or override them on the command line
==== Register a New Host With Load Balancer
===== Register a New Host With Load Balancer
Let's look first at registering the new host slave with the load balancer configuration in _domain.xml_. Open this Let's look first at registering the new host slave with the load balancer configuration in _domain.xml_. Open this
file and go to the undertow configuration in the `load-balancer` profile. Add a new `host` definition called file and go to the undertow configuration in the `load-balancer` profile. Add a new `host` definition called
@ -60,7 +165,7 @@ binding needs to point to the host and port of the new host.
</socket-binding-group> </socket-binding-group>
---- ----
==== Master Bind Addresses ===== Master Bind Addresses
Next thing you'll have to do is to change the `public` and `management` bind addresses for the master host. Either Next thing you'll have to do is to change the `public` and `management` bind addresses for the master host. Either
edit the _domain.xml_ file as discussed in the <<fake/../../network/bind-address.adoc#_bind-address, Bind Addresses>> chapter edit the _domain.xml_ file as discussed in the <<fake/../../network/bind-address.adoc#_bind-address, Bind Addresses>> chapter
@ -71,7 +176,7 @@ or specify these bind addresses on the command line as follows:
$ domain.sh --host-config=host-master.xml -Djboss.bind.address=192.168.0.2 -Djboss.bind.address.management=192.168.0.2 $ domain.sh --host-config=host-master.xml -Djboss.bind.address=192.168.0.2 -Djboss.bind.address.management=192.168.0.2
---- ----
==== Host Slave Bind Addresses ===== Host Slave Bind Addresses
Next you'll have to change the `public`, `management`, and domain controller bind addresses (`jboss.domain.master-address`). Either edit the Next you'll have to change the `public`, `management`, and domain controller bind addresses (`jboss.domain.master-address`). Either edit the
_host-slave.xml_ file or specify them on the command line as follows: _host-slave.xml_ file or specify them on the command line as follows:
@ -88,5 +193,11 @@ The values of `jboss.bind.address` and `jboss.bind.addres.management` pertain to
The value of `jboss.domain.master.address` need to be the IP address of the domain controller which is the management address The value of `jboss.domain.master.address` need to be the IP address of the domain controller which is the management address
of the master host. of the master host.
==== Configuring Other Load Balancers
The link:{{book.appserver.loadbalancer.link}}[the load balancer] chapter of the {{book.appserver.loadbalancer.name}}
has information on using some other software based load balancers that may help you.

2
topics/network/bind-address.adoc
View file

@ -20,7 +20,7 @@ The `-b` switch sets the IP bind address for any public interfaces.
Alternatively, if you don't want to set the bind address at the command line, you can edit the profile configuration of your deployment. Alternatively, if you don't want to set the bind address at the command line, you can edit the profile configuration of your deployment.
Open up the profile configuration file (_standalone.xml or _domain.xml_ depending on your Open up the profile configuration file (_standalone.xml or _domain.xml_ depending on your
<<fake/../../operating-mode.adoc#_operating-mode, operating mode>> and look for the `interfaces` XML block. <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>) and look for the `interfaces` XML block.
[source,xml] [source,xml]
---- ----

39
topics/network/https.adoc
View file

@ -22,45 +22,6 @@ all::
The SSL mode for each realm can be configured in the {{book.project.name}} admin console. The SSL mode for each realm can be configured in the {{book.project.name}} admin console.
==== Enable HTTPS/SSL with a Reverse Proxy
It is general best practice that {{book.project.name}} will be run in a cluster with a reverse proxy or hardware load balancer
setting in front of {{book.project.name}} server instances.
To enable SSL/HTTPS in this deployment scenario, it is important that you make sure your reverse proxy sets the `X-Forwarded-For` and `X-Forwarded-Proto` headers on the requests made to {{book.project.name}}.
To make sure that {{book.project.name}} honors these headers, you need to enable the `proxy-address-forwarding` setting of the {{book.project.name}} http connector in {{book.project.name}} configuration.
Assuming that your reverse proxy doesn't use port 8443 for SSL you also need to configure what port http traffic is redirected to.
. Open _standalone.xml_, _standalone-ha.xml_, or _domain.xml_ file (depends on your <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>).
. Add `proxy-address-forwarding` and `redirect-socket` to the `http-listener` element:
[source]
----
<subsystem xmlns="urn:jboss:domain:undertow:3.0">
...
<http-listener name="default" socket-binding="http"
proxy-address-forwarding="true" redirect-socket="proxy-https"/>
...
</subsystem>
----
Then add a new `socket-binding` element to the `socket-binding-group` element:
[source]
----
<socket-binding-group name="standard-sockets" default-interface="public"
port-offset="${jboss.socket.binding.port-offset:0}">
...
<socket-binding name="proxy-https" port="443"/>
...
</socket-binding-group>
----
Also remember that when running in <<fake/../../operating-mode/domain.adoc#_domain-mode,domain mode>> what `socket-binding-group`
you modify depends on how you have your server groups configured.
==== Enabling SSL/HTTPS for the {{book.project.name}} Server ==== Enabling SSL/HTTPS for the {{book.project.name}} Server
If you are not using a reverse proxy or load balancer to handle HTTPS traffic for you, you'll need to enable HTTPS If you are not using a reverse proxy or load balancer to handle HTTPS traffic for you, you'll need to enable HTTPS