This commit is contained in:
Bill Burke 2016-04-26 23:02:53 -04:00
parent d69a6e4c5c
commit 6355629639
8 changed files with 220 additions and 1 deletions

View file

@ -17,6 +17,11 @@
.. link:topics/operating-mode/standalone.adoc[Standalone Mode]
.. link:topics/operating-mode/standalone-ha.adoc[Standalone Clustered Mode]
.. link:topics/operating-mode/domain.adoc[Domain Clustered Mode]
. link:topics/management.adoc[Managing Config at Runtime]
. link:topics/database.adoc[Relational Database Setup]
{% if book.community %}
. link:topics/mongo.adoc[Mongo DB Setup]
{% endif %}
. link:topics/cache.adoc[Server Cache]
. link:topics/clustering.adoc[Clustering]
. link:topics/management.adoc[Runtime Management]

View file

@ -18,6 +18,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/"
},
"datasource": {
"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/chap-Datasource_Management.html"
}
},
"caching": {

BIN
keycloak-images/db-module.png Executable file

Binary file not shown.

After

Width:  |  Height:  |  Size: 8.3 KiB

BIN
rhsso-images/db-module.png Executable file

Binary file not shown.

After

Width:  |  Height:  |  Size: 8.6 KiB

62
topics/database.adoc Executable file
View file

@ -0,0 +1,62 @@
[[_database]]
== Relational Database Setup
Out of the box, {{book.project.name}} persists its data using the Hibernate JPA set of APIs on top of an embedded Java based relational database.
The built-in database is not viable in high load and high concurrency situations. It cannot be used in a cluster either. It is
highly recommended that you replace the default embedded database with a more scalable and reliable solution like PostgreSQL or MySql. This
chapter will show you how to configure {{book.project.name}} to use an external relational database. It will also discuss
how you can configure the Hibernate JPA persistence abstraction that sits on top of your RDBMS.
NOTE: Datasource configuration is covered much more thoroughly within the link:{{book.appserver.database.link}}[the datasource configuration chapter]
of the {{book.appserver.admindoc.name}}.
=== RDBMS Checklist
These are the steps you will need to perform to get an RDBMS configured for {{book.project.name}}.
. Locate and download a JDBC driver for your database
. Package the driver JAR into a module and install this module into the server
. Declare the JDBC driver in the configuration profile of the server
. Modify the datasource configuration to use your database's JDBC driver
. Modify the datasource configuration to define the connection parameters to your database
This chapter will use PostgresSQL for all its examples. Other databases follow the same steps for installation.
=== 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.
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.
.Module Directory
image:../../{{book.images}}/db-module.png[]
After you have done this, open up the _module.xml_ file and create the following XML
.Module XML
[source,xml]
----
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.3" name="org.postgresql">
<resources>
<resource-root path="postgresql-9.4.1208.jar"/>
</resources>
<dependencies>
<module name="javax.api"/>
<module name="javax.transaction.api"/>
</dependencies>
</module>
----
The module name should match the directory structure of your module. _org/postgresql_ maps to +org.postgresql+. The
+resource-root path+ attribute should specify the JAR filename. The rest are just the normal dependencies that
any JDBC driver JAR would have.

53
topics/manage.adoc Executable file
View file

@ -0,0 +1,53 @@
[[_app_server_cli]]
== Manage Configuration at Runtime
In the upcoming chapters, you'll often be provided two options for applying application server configuration changes to your deployment. You'll be
shown how to edit the _standalone.xml_ or _domain.xml_ directly. This must be done when the server (or servers) are offline.
Additionally, you may be shown how to apply config changes on a running server using the app server's command line interface ({{books.appserver.name}} CLI). This chapter discusses
how you will do this.
=== Start the {{books.appserver.name}} CLI
To start the {{books.appserver.name}} CLI, you need to run the +jboss-cli+ script.
.Linux/Unix
[source]
----
$ .../bin/jboss-cli.sh
----
.Windows
[source]
----
> ...\bin\jboss-cli.bat
----
This will bring you to a prompt like this:
.Prompt
[source]
----
[disconnected /]
----
There's a few commands you can execute without a running standalone server or domain controller, but usually you will
have to have those services booted up before you can execute CLI commands. To connect to a running server simply
execute the +connect+ command.
.connect
[source]
----
[disconnected /] connect
connect
[domain@localhost:9990 /]
----
You may be thinking to yourself, "I didn't enter in any username or password!". If you run +jboss-cli+ on the same machine
as your running standalone server or domain controller and your account has appropriate file permissions, you do not have
to setup or enter in a admin username and password. See the link:{{book.appserver.admindoc.link}}[{{book.appserver.admindoc.name}}]
for more details on how to make things more secure if you are uncomfortable with that setup.

95
topics/mongo.adoc Executable file
View file

@ -0,0 +1,95 @@
[[_mongo]]
== Mongo DB Setup
You are not stuck with using a RDBMS for persisting data. {{book.project.name}}
provides http://www.mongodb.com[MongoDB] based model implementation.
To configure {{book.project.name}} to use Mongo, you need to edit 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.
[source,json]
----
"eventsStore": {
"provider": "jpa",
"jpa": {
"exclude-events": [ "REFRESH_TOKEN" ]
}
},
"realm": {
"provider": "jpa"
},
"user": {
"provider": "${keycloak.user.provider:jpa}"
},
----
to:
[source,json]
----
"eventsStore": {
"provider": "mongo",
"mongo": {
"exclude-events": [ "REFRESH_TOKEN" ]
}
},
"realm": {
"provider": "mongo"
},
"user": {
"provider": "mongo"
},
----
And at the end of the file add the snippet like this where you can configure details about your Mongo database:
[source,json]
----
"connectionsMongo": {
"default": {
"host": "127.0.0.1",
"port": "27017",
"db": "keycloak",
"connectionsPerHost": 100,
"databaseSchema": "update"
}
}
----
All configuration options are optional.
Default values for host and port are localhost and 27017.
Default name of database is `keycloak` . You can also specify properties `user` and `password` if you want authenticate against your MongoDB.
If user and password are not specified, Keycloak will connect unauthenticated to your MongoDB.
Finally there is set of optional configuration options, which can be used to specify connection-pooling capabilities of Mongo client.
Supported int options are: `connectionsPerHost`, `threadsAllowedToBlockForConnectionMultiplier`, `maxWaitTime`, `connectTimeout` `socketTimeout`.
Supported boolean options are: `socketKeepAlive`, `autoConnectRetry`.
Supported long option is `maxAutoConnectRetryTime`.
See http://api.mongodb.org/java/2.11.4/com/mongodb/MongoClientOptions.html[Mongo documentation] for details about those options and their default values.
Alternatively, you can configure MongoDB using a MongoDB http://docs.mongodb.org/manual/reference/connection-string/[connection URI].
In this case, you define all information concerning the connection and authentication within the URI, as described in the MongoDB documentation.
Please note that the database specified within the URI is only used for authentication.
To change the database used by keycloak you have to set `db` property as before.
Therefore, a configuration like the following
[source]
----
"connectionsMongo": {
"default": {
"uri": "mongodb://user:password@127.0.0.1/authentication",
"db": "keycloak"
}
}
----
will authenticate the user against the authentication database, but store all keycloak related data in the keycloak database.
==== MongoDB Replica Sets
In order to use a mongo replica set for Keycloak, one has to use URI based configuration, which supports the definition of replica sets out of the box: `mongodb://host1:27017,host2:27017,host3:27017/`.

View file

@ -225,7 +225,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:
[source,xml]
----