diff --git a/SUMMARY.adoc b/SUMMARY.adoc index 7e4200ac59..99e8c66513 100755 --- a/SUMMARY.adoc +++ b/SUMMARY.adoc @@ -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] diff --git a/book.json b/book.json index e0480933da..5dd8eddcf8 100755 --- a/book.json +++ b/book.json @@ -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": { diff --git a/keycloak-images/db-module.png b/keycloak-images/db-module.png new file mode 100755 index 0000000000..1e39af22a8 Binary files /dev/null and b/keycloak-images/db-module.png differ diff --git a/rhsso-images/db-module.png b/rhsso-images/db-module.png new file mode 100755 index 0000000000..a55355c1f0 Binary files /dev/null and b/rhsso-images/db-module.png differ diff --git a/topics/database.adoc b/topics/database.adoc new file mode 100755 index 0000000000..0a22c68337 --- /dev/null +++ b/topics/database.adoc @@ -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] +---- + + + + + + + + + + + + +---- + +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. + diff --git a/topics/manage.adoc b/topics/manage.adoc new file mode 100755 index 0000000000..8f8de1f966 --- /dev/null +++ b/topics/manage.adoc @@ -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. + + + + diff --git a/topics/mongo.adoc b/topics/mongo.adoc new file mode 100755 index 0000000000..400b529102 --- /dev/null +++ b/topics/mongo.adoc @@ -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/`. diff --git a/topics/operating-mode/domain.adoc b/topics/operating-mode/domain.adoc index 61186d08cf..768078f916 100755 --- a/topics/operating-mode/domain.adoc +++ b/topics/operating-mode/domain.adoc @@ -225,7 +225,7 @@ $ add-user.sh To represent the user add the following to the server-identities definition ---- -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] ----