libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases Packages Activity Actions

2nd draft

Browse source
This commit is contained in:
Bill Burke 2016-04-29 12:09:09 -04:00
parent f45ef1efec
commit eca440d1e7
16 changed files with 108 additions and 97 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
SUMMARY.adoc
View file

@ -1,6 +1,5 @@
= Summary
. link:topics/preface.adoc[Preface]
. link:topics/overview.adoc[Overview]
.. link:topics/overview/recommended-reading.adoc[Recommended Reading]
. link:topics/installation.adoc[Installation]

9
book.json
View file

@ -13,8 +13,8 @@
"product": false,
"images": "keycloak-images",
"appserver": {
"name": "JBoss EAP",
"version": "6.4",
"name": "Wildfly",
"version": "10",
"admindoc": {
"name": "JBoss EAP Administration and Configuration Guide",
"link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/"
@ -57,6 +57,11 @@
"link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Development_Guide/sect-Java_Persistence_API_JPA.html#sect-Configuration2"
}
},
"developerguide": {
"name": "Keycloak Server Developer Guide",
"link": "https://keycloak.gitbooks.io/server-developer-guide/content/"
},
"adminguide": {
"name": "Keycloak Adminstration Guide",

12
topics/database/datasource.adoc
View file

@ -1,8 +1,8 @@
=== Modify the {{book.project.name}} Datasource
After declaring your JDBC driver, you have to modify the existing datasource configuration that {{book.project.name}} uses
to connect to the built-in embedded database. You'l need to change it to connect to your new external database. You'll do
this within the same configuration file and XML block that you registered your JDBC driver. Here's an example
to connect it to your new external database. You'll do
this within the same configuration file and XML block that you registered your JDBC driver in. Here's an example
that set's up the connection to your new database:
.Declare Your JDBC Drivers
@ -27,8 +27,8 @@ that set's up the connection to your new database:
</subsystem>
----
Search for the +datasource+ definition for +KeycloakDS+. You'll first need to specify the +connection-url+. The
documentation for your vendor's JDBC implementation will tell you the connection URL you should provide there.
Search for the +datasource+ definition for +KeycloakDS+. You'll first need to modify the +connection-url+. The
documentation for your vendor's JDBC implementation should specify the format for this connection URL value.
Next define the +driver+ you will use. This is the logical name of the JDBC driver you declared in the previous section of this
chapter.
@ -37,10 +37,10 @@ It is expensive to open a new connection to a database ever time you want to per
implementation maintains a pool of open connections. The +max-pool-size+ specifies the maximum number of connections it will pool.
You may want to change the value of this depending on the load of your system.
Finally, or PostgreSQL at least, you need to define the database username and password that is needed to connect to the database. You
Finally, with PostgreSQL at least, you need to define the database username and password that is needed to connect to the database. You
may be worried that this is in clear text in the example. There are methods to obfuscate this, but this is beyond the
scope of this guide.
NOTE: For more information and details features of datasources, please see the link:{{book.appserver.datasource.link}}[the datasource configuration chapter]
of the {{book.appserver.admindoc.name}}.
of the {{book.appserver.admindoc.name}}.

4
topics/database/hibernate.adoc
View file

@ -1,7 +1,7 @@
=== Hibernate Configuration
The Hibernate persistence API is already pre-configured out of the box. It is rare to have to modify the configuration for it.
To configure Hibernate, you need to edit the _keycloak-server.json_ file. If you are running
The Hibernate persistence API is already pre-configured out of the box and rarely needs to be changed.
The configuration for this component lies in the _keycloak-server.json_ file. If you are running
in standalone mode, this file is in the _.../standalone/configuration_ directory. If you are running in domain mode
this file will live in the _.../domain/servers/{server name}/configuration_ directory.

24
topics/database/jdbc.adoc
View file

@ -1,13 +1,14 @@
=== Package the JDBC Driver
Find and download the JDBC driver JAR for your RDBMS. Before you can use this driver, you must package it up into a module.
Find and download the JDBC driver JAR for your RDBMS. Before you can use this driver, you must package it up into a module
and install it into the server.
Modules define JARs that are loaded into the {{book.project.name}} classpath and the dependencies those JARs have on
other modules. They are pretty simple to set up.
Within the _.../modules/system/layers/keycloak/_ directory of your
{{book.project.name}} distribution, you need to create a directory structure to hold your module definition. The convention is use the Java package name
of the JDBC driver for the name of the directory structure. For PostgreSQL, create the directory _org/postgresql/main_. Copy your database
driver JAR into this directory and also create an empty _module.xml_ file.
driver JAR into this directory and create an empty _module.xml_ file within it too.
.Module Directory
image:../../{{book.images}}/db-module.png[]
@ -32,28 +33,20 @@ After you have done this, open up the _module.xml_ file and create the following
----
The module name should match the directory structure of your module. So, _org/postgresql_ maps to +org.postgresql+. The
+resource-root path+ attribute should specify the JAR filename. The rest are just the normal dependencies that
+resource-root path+ attribute should specify the JAR filename of the driver. The rest are just the normal dependencies that
any JDBC driver JAR would have.
=== Declare and Load JDBC Driver
The next thing you have to do is declare your newly packaged JDBC driver into your deployment profile so that it loads and becomes
available. Where you perform this action depends on your <<fake/../operating-mode.adoc#_operating-mode,operating mode>>. If you're
available when the server boots up. Where you perform this action depends on your <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>. If you're
deploying in standard mode, edit _.../standalone/configuration/standalone.xml_. If you're deploying in standard clustering
mode, edit _.../standalone/configuration/standalone-ha.xml_. If you're deploying in domain mode, edit
_.../domain/configuration/domain.xml_. In domain mode, you'll need to make sure you edit the profile you are using:
_.../domain/configuration/domain.xml_. In domain mode, you'll need to make sure you edit the profile you are using: either
+auth-server-standalone+ or +auth-server-clustered+
.Domain Profile
[source,xml]
----
<profile name="auth-server-clustered">
...
</profile>
----
Within the profile, search for the +drivers+ XML block within the +datasources+ subsystem. You should see
a pre-defined driver declared for the H2 JDBC driver. There is where you'll declare the JDBC driver for your external
a pre-defined driver declared for the H2 JDBC driver. This is where you'll declare the JDBC driver for your external
database.
.JDBC Drivers
@ -72,7 +65,8 @@ database.
----
Within the +drivers+ XML block you'll need to declare an additional JDBC driver. It needs to have a +name+ which
you can choose to be anything you want. You have to define the module the new JDBC driver classes are defined in. Finally
you can choose to be anything you want. You specify the +module+ attribute which points to the +module+ package you
created earlier for the driver JAR. Finally
you have to specify the driver's Java class. Here's an example of installing PostgreSQL driver that lives in the module
example defined earlier in this chapter.

5
topics/installation.adoc
View file

@ -1,5 +1,4 @@
== Installation
This chapter reviews what binaries you need to install to run the {{book.project.name}} Server on a specific machine.
It describes the directory structure and files of the distribution. Finally, it describes how to install {{book.project.name}}
on the cloud if you prefer that type of deployment.
Installing {{book.project.name}} is as simple as downloading it and unzipping it. This chapter reviews system requirements
as well as the directory structure of the distribution.

8
topics/installation/directory-structure.adoc
View file

@ -11,20 +11,20 @@ _bin/_::
This contains various scripts to either boot the server or perform some other management action on the server.
_domain/_::
This contains configuration files and working directory when running {{book.project.name}} in <<fake/../../domain-mode.adoc#,domain mode>>.
This contains configuration files and working directory when running {{book.project.name}} in <<fake/../../operating-mode/domain.adoc#_domain-mode,domain mode>>.
_modules/_::
These are all the Java libraries used by the server.
_providers/_::
If you are writing extensions to keycloak, you can put your extensions here. See the link:http://not-implemented-yet[Server Developer Guide] for more information on this.
If you are writing extensions to keycloak, you can put your extensions here. See the link:{{book.developerguide.link}}[{{book.developerguide.name] for more information on this.
_standalone/_::
This contains configuration files and working directory when running {{book.project.name}} in <<fake/../../standalone-mode.adoc#,standalone mode>>.
This contains configuration files and working directory when running {{book.project.name}} in <<fake/../../operating-mode/standalone.adoc#_standalone-mode,standalone mode>>.
_themes/_::
This directory contains all the html, style sheets, javascript files, and images used to display any UI screen displayed by the server.
Here you can modify an existing theme or create your own. See the link:http://not-implemented-yet[Server Developer Guide] for more information on this.
Here you can modify an existing theme or create your own. See the link:{{book.developerguide.link}}[{{book.developerguide.name] for more information on this.

6
topics/installation/distribution-files-community.adoc
View file

@ -10,13 +10,13 @@ The 'keycloak-{{book.project.version}}.[zip|tar.gz]' file is the server only dis
to run the Keycloak Server. To unpack this file just run your operating system's +unzip+ or +gunzip+ and +tar+ utilities.
The 'keycloak-overlay-{{book.project.version}}.[zip|tar.gz]' file is a Wildfly Service Pack that allows you to install Keycloak Server on top of an existing
Wildfly or JBoss EAP distribution. We suggest that you do not use this file unless you want to install on top of a JBoss EAP distribution. We do not support
Wildfly or JBoss EAP distribution. We suggest that you do not use this distribution unless you want to install on top of the latest JBoss EAP distribution. We do not support
users that want to run their applications and Keycloak on the same server instance. To install the Keycloak Service Pack, just unzip it in the root directory
of your JBoss EAP distribution.
The 'keycloak-demo-{{book.project.version}}.[zip|tar.gz]' contains a the server binaries, all documentation and all examples. It is preconfigured with both the
The 'keycloak-demo-{{book.project.version}}.[zip|tar.gz]' contains the server binaries, all documentation and all examples. It is preconfigured with both the
OIDC and SAML client application adapters and can deploy any of the distribution examples out of the box with no configuration. This distribution is only
recommended for those that want to test drive Keycloak.
recommended for those that want to test drive Keycloak. We do not support users that run the demo distribution in production.
To unpack of these files run the +unzip+ or +gunzip+ and +tar+ utilities.

4
topics/installation/distribution-files-product.adoc
View file

@ -1,11 +1,11 @@
=== Installing Distribution Files
The Keycloak Server is contained in one distribution file:
The {{book.project.name}} Server is contained in one distribution file:
* 'RH-SSO-{{book.project.version}}.[zip|tar.gz]'
The 'RH-SSO-{{book.project.version}}.[zip|tar.gz]' file is the server only distribution. It contains nothing other than the scripts and binaries
to run the Keycloak Server.
to run the {{book.project.name}} Server.
To unpack of these files run the +unzip+ or +gunzip+ and +tar+ utilities.

6
topics/installation/system-requirements.adoc
View file

@ -7,9 +7,9 @@ These are the requirements to run the {{book.project.name}} authentication serve
* zip or gzip and tar
* At least 512M of RAM
* At least 1G of diskspace
* Network multicast support on your machine if you want to run in a cluster out of the box. {{book.project.name}} can
be clustered without multicast, but this requires a bunch of configuration changes. Please see
the <<fake/../../clustering.adoc#_clustering,clustering>> section of this guide for more information.
* A shared external database like Postgres, MySql, Oracle, etc. {{book.project.name}} requires an external shared
database if you want to run in a cluster. Please see the <<fake/../../database.adoc#_database,database configuration>> section of this guide for more information.
* Network multicast support on your machine if you want to run in a cluster. {{book.project.name}} can
be clustered without multicast, but this requires a bunch of configuration changes. Please see
the <<fake/../../clustering.adoc#_clustering,clustering>> section of this guide for more information.

3
topics/operating-mode.adoc
View file

@ -4,8 +4,7 @@
Before deploying {{book.project.name}} in a production environment you need to decide which type of operating mode
you are going to use. Will you run {{book.project.name}} within a cluster? Do you want a centralized way to manage
your server configurations? This is where deciding the operating mode comes in. This decision
effects how you configure databases, configure caching and even how you boot the server.
your server configurations? Your choice of operating mode effects how you configure databases, configure caching and even how you boot the server.
TIP: The {{book.project.name}} is built on top of the {{book.appserver.name}} Application Server. This guide will only
go over the basics for deployment within a specific mode. If you want specific information on this, a better place

71
topics/operating-mode/domain.adoc
View file

@ -1,6 +1,8 @@
[[_domain-mode]]
=== Domain Clustered Mode
Domain mode is a way to centrally manage and publish the configuration for your servers.
Running a cluster in standard mode can quickly become aggravating as the cluster grows in size. Every time you need
to make a configuration change, you have perform it on each node in the cluster. Domain mode solves this problem by providing
a central place to store and publish configuration. It can be quite complex to set up, but it is worth it in the end.
@ -46,11 +48,11 @@ where the domain profile and server group for the {{book.project.name}} server a
.domain.xml
image:../../{{book.images}}/domain-file.png[]
NOTE: Any changes you make to this file while the domain controller is running will not take effect and may even be overwritten
WARNING: Any changes you make to this file while the domain controller is running will not take effect and may even be overwritten
by the server. Instead use the the command line scripting or the web console of {{book.appserver.name}}. See
the link:{{book.appserver.admindoc.link}}[{{book.appserver.admindoc.name}}] for more information.
Let's look at some aspects of this _domain.xml_ file. The +auth-server+ +profile+ XML block is where you are going to make the bulk of your configuration decisions.
Let's look at some aspects of this _domain.xml_ file. The +auth-serve-standalone+ and +auth-server-clustered+ +profile+ XML block is where you are going to make the bulk of your configuration decisions.
You'll be configuring things here like network connections, caches, and database connections.
@ -58,12 +60,36 @@ You'll be configuring things here like network connections, caches, and database
[source,xml]
----
<profiles>
<profile name="auth-server">
<profile name="auth-server-standalone">
...
</profile>
<profile name="auth-server-clustered">
...
</profile>
----
The +ha-sockets+ +socket-binding-group+ defines the default port mappings for various connectors that are opened with each
The +auth-server-standalone+ profile is a non-clustered setup. The +auth-server-clustered+ profile is the clustered setup.
If you scroll down further, you'll see various +socket-binding-groups+ defined.
.socket-binding-grous
[source,xml]
----
<socket-binding-groups>
<socket-binding-group name="standard-sockets" default-interface="public">
...
</socket-binding-group>
<socket-binding-group name="ha-sockets" default-interface="public">
...
</socket-binding-group>
<!-- load-balancer-sockets should be removed in production systems and replaced with a better softare or hardare based one -->
<socket-binding-group name="load-balancer-sockets" default-interface="public">
...
</socket-binding-group>
</socket-binding-groups>----
This config defines the default port mappings for various connectors that are opened with each
{{book.project.name}} server instance. Any value that contains +${...}+ is a value that can be overriden on the command line
with the +-D+ switch, i.e.
@ -79,7 +105,14 @@ binds a +socket-binding-group+ to the server group.
[source,xml]
----
<server-groups>
<server-group name="auth-server-group" profile="auth-server">
<!-- load-balancer-group should be removed in production systems and replaced with a better softare or hardare based one -->
<server-group name="load-balancer-group" profile="load-balancer">
<jvm name="default">
<heap size="64m" max-size="512m"/>
</jvm>
<socket-binding-group ref="load-balancer-sockets"/>
</server-group>
<server-group name="auth-server-group" profile="auth-server-clustered">
<jvm name="default">
<heap size="64m" max-size="512m"/>
</jvm>
@ -97,8 +130,9 @@ _host-master.xml_ and _host-slave.xml_. _host-master.xml_ is configured to boot
one {{book.project.name}} server instance. _host-slave.xml_ is configured to talk to the domain controller and boot up
one {{book.project.name}} server instance.
NOTE: You should remove the load balancer server from _host-master.xml_. The load balancer included is really not that
production ready and doesn't work as smoothly as something like Apache HTTPD + mod-cluster or a hardward based one.
NOTE: The load balancer is not a required service. It exists so that you can easily test drive clustering on your development
machine. While usable in production, you have the option of replacing it if you have a different hardware or software
based load balancer you want to use.
.Host Controller Config
image:../../{{book.images}}/host-files.png[]
@ -152,7 +186,7 @@ image:../../{{book.images}}/domain-json-config.png[]
When running the server in domain mode, there is a specific script you need to run to boot the server depending on your
operating system. These scripts live in the _bin/_ directory of the server distribution.
.Standalone Boot Scripts
.Domain Boot Script
image:../../{{book.images}}/domain-boot-files.png[]
To boot the server:
@ -173,22 +207,25 @@ When running the boot script you will need pass in the host controlling configur
+--host-config+ switch.
[[_clustered-domain-example]]
==== Running the Clustered Domain Example
==== Clustered Domain Example
The example domain that comes with {{book.project.name}} was meant to run on one machine. It starts a:
* domain controller
* HTTP load balancer
You can test drive clustering using the out-of-the-box _domain.xml_ configuration. This example
domain is meant to run on one machine and boots up:
* a domain controller
* an HTTP load balancer
* 2 {{book.project.name}} server instances
To simulate running a cluster on two machines, you'll run the +domain.sh+ script twice to start two separate
host controllers. The first will be the master host controller. It start a domain controller, an HTTP load balancer, and one
host controllers. The first will be the master host controller which will start a domain controller, an HTTP load balancer, and one
{{book.project.name}} authentication server instance. The second will be a slave host controller that only starts
up an authentication server instance.
===== Setup Secure Master Slave Connection
===== Setup Slave Connection to Domain Controller
Before you can boot things up though, you have to configure the slave host controller so that it can talk securely to the domain
controller to obtain the centralized configuration. To set up a secure connection, you have to create a server admin user and a secret that
controller. If you do not do this, then the slave host will not be able to obtain the centralized configuration from the domain controller.
To set up a secure connection, you have to create a server admin user and a secret that
will be shared between the master and the slave. You do this by running the +.../bin/add-user.sh+ script.
When you run the script select +Management User+ and answer +yes+ when it asks you if the new user is going to be used
@ -225,7 +262,7 @@ $ add-user.sh
To represent the user add the following to the server-identities definition <secret value="bWdtdDEyMyE=" />
----
Now cut and paste the secret value into the _.../domain/configuration/host-slave.xml_ file:
Now cut and paste the secret value into the _.../domain/configuration/host-slave.xml_ file as follows:
[source,xml]
----
@ -239,7 +276,7 @@ Now cut and paste the secret value into the _.../domain/configuration/host-slave
===== Run the Boot Scripts
Since we're simulating running on two separate machines, you'll run the boot script twice:
Since we're simulating a two node cluster on one development machine, you'll run the boot script twice:
.Boot up master
[source,shell]

16
topics/operating-mode/standalone-ha.adoc
View file

@ -3,14 +3,14 @@
=== Standalone Clustered Mode
Standalone clustered operation mode is for when you want to run {{book.project.name}} within a cluster. This mode
requires that you have a copy of each distribution for each node you want to run in the cluster. While very easy to
deploy initially, this mode can become cumbersome if you end up having a large cluster because you will have to
modify the configuration in each node anytime you need to make a change.
requires that you have a copy of the {{book.project.name}} distribution on each machine you want to run a server instance.
This mode can be very easy to deploy initially, but can become quite cumbersome. To make a configuration change
you'll have to modify each distribution on each machine. For a large cluster this can become time consuming and error prone.
==== Standalone Clustered Configuration
The distribution has a mostly pre-configured app server configuration file for running within a cluster. It has all the specific
infrasture settings you need to configure networking, databases, caches, and discovery. This file resides
infrastructure settings for networking, databases, caches, and discovery. This file resides
in _.../standalone/configuration/standalone-ha.xml_. There's a few things missing from this configuration.
You can't run {{book.project.name}} in a cluster without a configuring a shared database connection. You also need to
deploy some type of load balancer in front of the cluster. The <<fake/../../clustering.adoc#_clustering,clustering>> and
@ -19,11 +19,11 @@ deploy some type of load balancer in front of the cluster. The <<fake/../../clu
.Standalone HA Config
image:../../{{book.images}}/standalone-ha-config-file.png[]
NOTE: Any changes you make to this file while the server is running will not take effect and may even be overwritten
WARNING: Any changes you make to this file while the server is running will not take effect and may even be overwritten
by the server. Instead use the the command line scripting or the web console of {{book.appserver.name}}. See
the link:{{book.appserver.admindoc.link}}[{{book.appserver.admindoc.name}}] for more information.
==== Standalone Boot Script
==== Standalone Clustered Boot Script
You use the same boot scripts to start {{book.project.name}} as you do in standalone mode. The difference is that
you pass in an additional flag to point to the HA config file.
@ -48,9 +48,9 @@ $ .../bin/standalone.sh --server-config=standalone-ha.xml
==== Standalone Clustered {{book.project.name}} JSON Configuration
The {{book.project.name}} specific json configure file resides in the same place as in standalone mode: _.../standalone/configuration/keycloak.json_.
Like _standalone-ha.xml_ you have to modify this file in each distribution in your cluster in order for changes to take effect.
Like _standalone-ha.xml_ you have to modify this file in each distribution in your cluster when you want to make a change here.
NOTE: Any changes you make to this file while the server is running will not take effect. You'll need to reboot the
WARNING: Any changes you make to this file while the server is running will not take effect. You'll need to reboot the
server.

10
topics/operating-mode/standalone.adoc
View file

@ -2,7 +2,7 @@
=== Standalone Mode
Standalone operating mode is only useful when you want to run one, and only one {{book.project.name}} server instance.
It cannot be made to run in a cluster and all caches are non-distributed and local-only. It is not recommended that
It is not usable for clustered deployments and all caches are non-distributed and local-only. It is not recommended that
you use standalone mode in production as you will have a single point of failure. If your standalone mode server goes down,
users will not be able to log in. This mode is really only useful to test drive and play with the features of {{book.project.name}}
@ -37,21 +37,21 @@ derivative of. In the standalone operation mode, this file lives in _.../standa
.Standalone Config File
image:../../{{book.images}}/standalone-config-file.png[]
NOTE: Any changes you make to this file while the server is running will not take effect and may even be overwritten
WARNING: Any changes you make to this file while the server is running will not take effect and may even be overwritten
by the server. Instead use the the command line scripting or the web console of {{book.appserver.name}}. See
the link:{{book.appserver.admindoc.link}}[{{book.appserver.admindoc.name}}] for more information.
==== Standalone {{book.project.name}} JSON Configuration
{{book.project.name}} has a json configuration file that is specific to {{book.project.name}} this is located within
_.../standalone/configuration/keycloak.json_. This file is used to configure non-infrastructure level things that are
{{book.project.name}} has a json configuration file that is specific to {{book.project.name}} components. This configuration is located within
the file_.../standalone/configuration/keycloak.json_. This file is used to configure non-infrastructure level things that are
only applicable to {{book.project.name}}
.Standalone {{book.project.name}} Config File
image:../../{{book.images}}/standalone-json-config-file.png[]
NOTE: Any changes you make to this file while the server is running will not take effect. You'll need to reboot the
WARNING: Any changes you make to this file while the server is running will not take effect. You'll need to reboot the
server.

4
topics/overview/recommended-reading.adoc
View file

@ -6,5 +6,5 @@ goes over the basics for infrastructure-level configuration. It is highly recom
for {{book.appserver.name}} and its sub projects. Here are some links to that documentation:
* link:{{book.appserver.admindoc.link}}[{{book.appserver.admindoc.name}}]
* link:{{book.cache.admindoc.link}}[{{book.cache.admindoc.name}}]
* link:{{book.jpa.admindoc.link}}[{{book.jpa.admindoc.name}}]
* link:{{book.caching.admindoc.link}}[{{book.caching.admindoc.name}}]
* link:{{book.jpa.admindoc.link}}[Hibernate JPA Configuration]

22
topics/preface.adoc
View file

@ -1,22 +0,0 @@
== Preface
In some of the example listings, what is meant to be displayed on one line does not fit inside the available page width.These lines have been broken up. A '\' at the end of a line means that a break has been introduced to fit in the page, with the following lines indented.
So:
[source]
----
Let's pretend to have an extremely \
long line that \
does not fit
This one is short
----
Is really:
[source]
----
Let's pretend to have an extremely long line that does not fit
This one is short
----