diff --git a/SUMMARY.adoc b/SUMMARY.adoc old mode 100644 new mode 100755 index c6f78e7b4c..6143adb43f --- a/SUMMARY.adoc +++ b/SUMMARY.adoc @@ -12,7 +12,10 @@ .. 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/manage.adoc[Managing Config at Runtime] +. link:topics/config-subsystem.adoc[Managing Configuration] +.. link:topics/config-subsystem/configure-spi-providers.adoc[Configure SPI Providers] +.. link:topics/config-subsystem/start-cli.adoc[Start CLI] +.. link:topics/config-subsystem/cli-recipes.adoc[CLI Recipes] . link:topics/database.adoc[Relational Database Setup] .. link:topics/database/checklist.adoc[Setup Checklist] .. link:topics/database/jdbc.adoc[JDBC Setup] diff --git a/images/cli-gui.png b/images/cli-gui.png new file mode 100644 index 0000000000..0e9a29b37d Binary files /dev/null and b/images/cli-gui.png differ diff --git a/topics/cache/disable.adoc b/topics/cache/disable.adoc index 95d45abebf..c685b77574 100755 --- a/topics/cache/disable.adoc +++ b/topics/cache/disable.adoc @@ -1,28 +1,26 @@ === Disabling Caching -To disable the realm or user cache, you must edit the `keycloak-server.json` file in your distribution. Where -this file lives depends on your <> +To disable the realm or user cache, you must edit the `standalone.xml`, `standalone-ha.xml`, + or `domain.xml` file in your distribution. The location of this file +depends on your <>. Here's what the config looks like initially. -[source,json] +[source,xml] ---- - "userCache": { - "default" : { - "enabled": true - } - }, + + + + + + + - "realmCache": { - "default" : { - "enabled": true - } - }, ---- -To disable the cache set the `enabled` field to false for the cache you want to disable. You must reboot your +To disable the cache set the `enabled` attribute to false for the cache you want to disable. You must reboot your server for this change to take effect. diff --git a/topics/clustering/load-balancer.adoc b/topics/clustering/load-balancer.adoc old mode 100644 new mode 100755 diff --git a/topics/clustering/serialized.adoc b/topics/clustering/serialized.adoc index 30b827b046..aa67aaf292 100755 --- a/topics/clustering/serialized.adoc +++ b/topics/clustering/serialized.adoc @@ -8,15 +8,19 @@ A DB lock is used to prevent start actions from conflicting with one another whe By default, the maximum timeout for this lock is 900 seconds. If a node is waiting on this lock for more than the timeout it will fail to boot. -Typically you won't need to increase/decrease the default value, but just in case it's possible to configure it in `keycloak-server.json`: +Typically you won't need to increase/decrease the default value, but just in case it's possible to configure it in +`standalone.xml`, `standalone-ha.xml`, or `domain.xml` file in your distribution. The location of this file +depends on your <>. -[source,json] +[source,xml] ---- -"dblock": { - "jpa": { - "lockWaitTimeout": 900 - } -} + + + + + + + ---- {% if book.community %} diff --git a/topics/config-subsystem.adoc b/topics/config-subsystem.adoc new file mode 100644 index 0000000000..c7fb0c870e --- /dev/null +++ b/topics/config-subsystem.adoc @@ -0,0 +1,23 @@ +[[_manage_config]] + +== Manage Subsystem Configuration + +Low-level configuration of {{book.project.name}} is done by editing the + `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file +in your distribution. The location of this file +depends on your <>. + +While there are endless settings you can configure here, this section will focus on +configuration of the _keycloak-server_ subsystem. No matter which configuration file +you are using, configuration of the _keycloak-server_ subsystem is the same. + +The keycloak-server subsystem is typically declared toward the end of the file like this: +[source,xml] +---- + + auth + ... + +---- + +Note that anything changed in this subsystem will not take effect until the server is rebooted. \ No newline at end of file diff --git a/topics/config-subsystem/cli-recipes.adoc b/topics/config-subsystem/cli-recipes.adoc new file mode 100644 index 0000000000..577bf6ede7 --- /dev/null +++ b/topics/config-subsystem/cli-recipes.adoc @@ -0,0 +1,63 @@ +[[_cli_recipes]] + +=== CLI Recipes +Here are some configuration tasks and how to perform them with CLI commands. +Note that in all but the first example, we use the wildcard path `**` to mean +you should substitute or the path to the keycloak-server subsystem. + +For standalone, this just means: + +`**` = `/subsystem=keycloak-server` + +For domain mode, this would mean something like: + +`**` = `/profile=auth-server-clustered/subsystem=keycloak-server` + +==== Change the web context of the server +[source] +---- +/subsystem=keycloak-server/:write-attribute(name=web-context,value=myContext) +---- +==== Set the global default theme +[source] +---- +**/theme=defaults/:write-attribute(name=default,value=myTheme) +---- +==== Add a new SPI and a provider +[source] +---- +**/spi=mySPI/:add +**/spi=mySPI/provider=myProvider/:add(enabled=true) +---- +==== Disable a provider +[source] +---- +**/spi=mySPI/provider=myProvider/:write-attribute(name=enabled,value=false) +---- +==== Change the default provider for an SPI +[source] +---- +**/spi=mySPI/:write-attribute(name=default-provider,value=myProvider) +---- +==== Configure the dblock SPI with both jpa and mango providers +[source] +---- +**/spi=dblock/:add(default-provider=jpa) +**/spi=dblock/provider=jpa/:add(properties={lockWaitTimeout => "900"},enabled=true) +**/spi=dblock/provider=mongo/:add(properties={lockRecheckTime => "2",lockWaitTimeout => "800"},enabled=true) +---- +==== Add or change a single property value for a provider +[source] +---- +**/spi=dblock/provider=mongo/:map-put(name=properties,key=lockRecheckTime,value=3) +---- +==== Remove a single property from a provider +[source] +---- +**/spi=dblock/provider=mongo/:map-remove(name=properties,key=lockRecheckTime) +---- +==== Set values on a provider property of type `List` +[source] +---- +**/spi=eventsStore/provider=jpa/:map-put(name=properties,key=exclude-events,value=[EVENT1,EVENT2]) +---- \ No newline at end of file diff --git a/topics/config-subsystem/configure-spi-providers.adoc b/topics/config-subsystem/configure-spi-providers.adoc new file mode 100644 index 0000000000..f9c1032db0 --- /dev/null +++ b/topics/config-subsystem/configure-spi-providers.adoc @@ -0,0 +1,59 @@ +[[_config_spi_providers]] + +=== Configure SPI Providers + +The specifics of each configuration setting is discussed elsewhere in +context with that setting. However, it is useful to understand the format used +to declare settings on SPI providers. + +{{book.project.name}} is a highly modular system that allows great +flexibility. There are more than 50 service provider interfaces (SPIs), and +you are allowed to swap out implementations of each SPI. An implementation of +an SPI is known as a _provider_. + +All elements in an SPI declaration are optional, but a full SPI declaration + looks like this: +[source,xml] +---- + + mongo + + + + + + + + + + + + +---- +Here we have two providers defined for the SPI `dblock`. The `default-provider` +is listed as `mongo`. However it is up to the SPI to decide how it will treat +this setting. Some SPIs allow more than one provider and some do not. So +`default-provider` can help the SPI to choose. + +Also notice that each provider defines its own set of configuration properties. +The fact that both providers above have a property called `lockWaitTimeout` is just a +coincidence. + +The type of each property value is interpreted by the provider. However, there +is one exception. Consider the `jpa` provider for the `eventStore` API: +[source,xml] +---- + + + + + + + +---- +We see that the value begins and ends with square brackets. That means that +the value will be passed to the provider as a list. In this example, the system will pass the +provider a list with two element values _EVENT1_ and _EVENT2_. To add more values +to the list, just separate each list element with a comma. Unfortunately, +you do need to escape the quotes surrounding each list element with `\"`. \ No newline at end of file diff --git a/topics/config-subsystem/start-cli.adoc b/topics/config-subsystem/start-cli.adoc new file mode 100644 index 0000000000..980f6619ab --- /dev/null +++ b/topics/config-subsystem/start-cli.adoc @@ -0,0 +1,101 @@ +[[_start_cli]] + +=== Start the {{book.appserver.name}} CLI +Besides editing the configuration by hand, you also have the option of changing +the configuration by issuing commands via the _jboss-cli_ tool. CLI allows +you to configure servers locally or remotely. And it is especially useful when +combined with scripting. + +To start the {{book.appserver.name}} CLI, you need to run `jboss-cli`. + +.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 /] +---- + +If you wish to execute commands on a running server, you will first +execute the `connect` command. + +.connect +[source] +---- +[disconnected /] connect +connect +[standalone@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. + +=== CLI Embedded Mode + +If you do happen to be on the same machine as your standalone server and you want to +issue commands while the server is not active, you can embed the server into CLI and make +changes in a special mode that disallows incoming requests. To do this, first +execute the `embed` command with the config file you wish to change. + +.embed +[source] +---- +[disconnected /] embed-server --server-config=standalone.xml +[standalone@embedded /] +---- + +=== CLI GUI Mode + +The CLI can also run in GUI mode. GUI mode launches a Swing application that +allows you to graphically view and edit the entire management model of a _running_ server. +GUI mode is especially useful when you need help formatting your CLI commands and learning +about the options available. The GUI can also retrieve server logs from a local or +remote server. + +.Start in GUI mode +[source] +---- +$ .../bin/jboss-cli.sh --gui +---- +_Note: to connect to a remote server, you pass the `--connect` option as well. +Use the --help option for more details._ + +After launching GUI mode, you will probably want to scroll down to find the node, +`subsystem=keycloak-server`. If you right-click on the node and click +`Explore subsystem=keycloak-server`, you will get a new tab that shows only +the keycloak-server subsystem. + +image:../../images/cli-gui.png[] + +=== CLI Scripting + +The CLI has extensive scripting capabilities. A script is just a text +file with CLI commands in it. Consider a simple script that turns off theme +and template caching. + +.turn-off-caching.cli +[source] +---- +/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheThemes,value=false) +/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheTemplates,value=false) +---- +To execute the script, I can follow the `Scripts` menu in CLI GUI, or execute the +script from the command line as follows: +[source] +---- +$ .../bin/jboss-cli.sh --file=turn-off-caching.cli +---- \ No newline at end of file diff --git a/topics/database/hibernate.adoc b/topics/database/hibernate.adoc old mode 100644 new mode 100755 index 7b8805d510..08cb626437 --- a/topics/database/hibernate.adoc +++ b/topics/database/hibernate.adoc @@ -1,19 +1,23 @@ === Database Configuration -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. +The configuration for this component lies in the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file +in your distribution. The location of this file +depends on your <>. .Database Config -[source,json] +[source,xml] ---- -"connectionsJpa": { - "default": { - "dataSource": "java:jboss/datasources/KeycloakDS", - "initializeEmpty": false, - "migrationStrategy": "manual", - "migrationExport": "${jboss.home.dir}/keycloak-database-update.sql" - } -}, + + + + + + + + + + ---- Possible configuration options are: diff --git a/topics/mongo.adoc b/topics/mongo.adoc index 95f2b84c73..ed2b826f4b 100755 --- a/topics/mongo.adoc +++ b/topics/mongo.adoc @@ -5,82 +5,78 @@ You are not stuck with using a RDBMS for persisting data. {{book.project.name}} provides a 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. +To configure {{book.project.name}} to use Mongo, you need to edit the `standalone.xml`, +`standalone-ha.xml`, or `domain.xml` file in your distribution. The location of this file +depends on your <>. -Open the _keycloak-server.json_ file. Look for the following JSON snippets and replace all the _jpa_ providers with _mongo_ . This is the area you will be modifying +Open the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file. Look for the following XML snippets and replace all the _jpa_ providers with _mongo_ . This is the area you will be modifying to use Mongo. -[source,json] +[source,xml] +---- + + jpa + + + + + + + + jpa + + + jpa + + + jpa + + + jpa + + ---- -"eventsStore": { - "provider": "jpa", - "jpa": { - "exclude-events": [ "REFRESH_TOKEN" ] - } -}, +Change that XML snippet to use Mongo: -"realm": { - "provider": "jpa" -}, - -"user": { - "provider": "jpa" -}, - -"userSessionPersister": { - "provider": "jpa" -}, - -"authorizationPersister": { - "provider": "jpa" -}, +[source,xml] ---- - -Change that JSON snippet to use Mongo: - -[source,json] + + mongo + + + + + + + + mongo + + + mongo + + + mongo + + + mongo + ---- +After that, add the snippet like this where you can configure details about your Mongo database: -"eventsStore": { - "provider": "mongo", - "mongo": { - "exclude-events": [ "REFRESH_TOKEN" ] - } -}, - -"realm": { - "provider": "mongo" -}, - -"user": { - "provider": "mongo" -}, - -"userSessionPersister": { - "provider": "mongo" -}, - -"authorizationPersister": { - "provider": "mongo" -}, +[source,xml] ---- -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. @@ -99,15 +95,16 @@ Please note that the database specified within the URI is only used for authenti To change the database used by {{book.project.name}} you have to set `db` property as before. Therefore, a configuration like the following -[source] +[source,xml] ---- - -"connectionsMongo": { - "default": { - "uri": "mongodb://user:password@127.0.0.1/authentication", - "db": "keycloak" - } -} + + + + + + + + ---- will authenticate the user against the authentication database, but store all {{book.project.name}} related data in the keycloak database. diff --git a/topics/network/outgoing.adoc b/topics/network/outgoing.adoc index cbf55fd797..6623175f84 100755 --- a/topics/network/outgoing.adoc +++ b/topics/network/outgoing.adoc @@ -2,16 +2,20 @@ === Outgoing HTTP Requests The {{book.project.name}} server often needs to make non-browser HTTP requests to the applications and services it secures. -The auth server manages these outgoing connections by maintaining an HTTP client connection pool. There are some thing -you'll need to configure in the _keycloak-server.json_. Where this file lives depends on your <> +The auth server manages these outgoing connections by maintaining an HTTP client connection pool. There are some things +you'll need to configure in `standalone.xml`, `standalone-ha.xml`, or `domain.xml`. The location of this file +depends on your <>. - -.keycloak-server.json HTTP client Config -[source,json] +.HTTP client Config example +[source,xml] ---- -"connectionsHttpClient": { - "default": {} -}, + + + + + + + ---- Possible configuration options are: @@ -72,20 +76,24 @@ You can use _keytool_ to create a new truststore file or add trusted host certif $ keytool -import -alias HOSTDOMAIN -keystore truststore.jks -file host-certificate.cer ---- -The truststore is configured within the _keycloak-server.json_ file. The location of this file depends on your <>. +The truststore is configured within the `standalone.xml`, +`standalone-ha.xml`, or `domain.xml` file in your distribution. The location of this file +depends on your <>. You can add your truststore configuration by using the following template: -[source] +[source,xml] ---- + + + + + + + + + + -"truststore": { - "file": { - "file": "path to your .jks file containing public certificates", - "password": "password", - "hostname-verification-policy": "WILDCARD", - "disabled": false - } -} ---- Possible configuration options for this setting are: diff --git a/topics/operating-mode/standalone-ha.adoc b/topics/operating-mode/standalone-ha.adoc index 339f8282d2..81540b04f1 100755 --- a/topics/operating-mode/standalone-ha.adoc +++ b/topics/operating-mode/standalone-ha.adoc @@ -44,15 +44,4 @@ $ .../bin/standalone.sh --server-config=standalone-ha.xml [source] ---- > ...\bin\standalone.bat --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 when you want to make a change here. - -WARNING: Any changes you make to this file while the server is running will not take effect. You'll need to reboot the - server. - - - +---- \ No newline at end of file diff --git a/topics/operating-mode/standalone.adoc b/topics/operating-mode/standalone.adoc index f6141705aa..325003c6d8 100755 --- a/topics/operating-mode/standalone.adoc +++ b/topics/operating-mode/standalone.adoc @@ -33,31 +33,12 @@ $ .../bin/standalone.sh The bulk of this guide walks you through how to configure infrastructure level aspects of {{book.project.name}}. These aspects are configured in a configuration file that is specific to the application server that {{book.project.name}} is a -derivative of. In the standalone operation mode, this file lives in _.../standalone/configuration/standalone.xml_. +derivative of. In the standalone operation mode, this file lives in _.../standalone/configuration/standalone.xml_. This file +is also used to configure non-infrastructure level things that are specific to {{book.project.name}} components. .Standalone Config File image:../../{{book.images}}/standalone-config-file.png[] 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}} components. This configuration is located within -the file.../standalone/configuration/keycloak-server.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[] - -WARNING: Any changes you make to this file while the server is running will not take effect. You'll need to reboot the - server. - - - - - - - + the link:{{book.appserver.admindoc.link}}[{{book.appserver.admindoc.name}}] for more information. \ No newline at end of file