more
This commit is contained in:
parent
d69a6e4c5c
commit
6355629639
8 changed files with 220 additions and 1 deletions
|
@ -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]
|
||||
|
|
|
@ -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
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
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
62
topics/database.adoc
Executable 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
53
topics/manage.adoc
Executable 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
95
topics/mongo.adoc
Executable 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/`.
|
|
@ -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]
|
||||
----
|
||||
|
|
Loading…
Reference in a new issue