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

Merge pull request #14 from ssilvert/switch-to-standalone-xml

Browse source 
KEYCLOKA-3196: Use WildFly management model for server configuration.
This commit is contained in:
Stian Thorgersen 2016-09-01 06:46:01 +02:00 committed by GitHub
commit 35c266b037
14 changed files with 388 additions and 158 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
SUMMARY.adoc Normal file → Executable file
View file

@ -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]

BIN
images/cli-gui.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 88 KiB

26
topics/cache/disable.adoc vendored
View file

@ -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 <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>
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 <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>.
Here's what the config looks like initially.
[source,json]
[source,xml]
----
"userCache": {
"default" : {
"enabled": true
}
},
<spi name="userCache">
<provider name="default" enabled="true"/>
</spi>
<spi name="realmCache">
<provider name="default" enabled="true"/>
</spi>
"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.

0
topics/clustering/load-balancer.adoc Normal file → Executable file
View file

18
topics/clustering/serialized.adoc
View file

@ -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 <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>.
[source,json]
[source,xml]
----
"dblock": {
"jpa": {
"lockWaitTimeout": 900
}
}
<spi name="dblock">
<provider name="jpa" enabled="true">
<properties>
<property name="lockWaitTimeout" value="900"/>
</properties>
</provider>
</spi>
----
{% if book.community %}

23
topics/config-subsystem.adoc Normal file
View file

@ -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 <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>.
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]
----
<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
<web-context>auth</web-context>
...
</subsystem>
----
Note that anything changed in this subsystem will not take effect until the server is rebooted.

63
topics/config-subsystem/cli-recipes.adoc Normal file
View file

@ -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])
----

59
topics/config-subsystem/configure-spi-providers.adoc Normal file
View file

@ -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]
----
<spi name="dblock">
<default-provider>mongo</default-provider>
<provider name="jpa" enabled="true">
<properties>
<property name="lockWaitTimeout" value="800"/>
</properties>
</provider>
<provider name="mongo" enabled="true">
<properties>
<property name="lockRecheckTime" value="2"/>
<property name="lockWaitTimeout" value="600"/>
</properties>
</provider>
</spi>
----
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]
----
<spi name="eventsStore">
<provider name="jpa" enabled="true">
<properties>
<property name="exclude-events" value="[&quot;EVENT1&quot;,
&quot;EVENT2&quot;]"/>
</properties>
</provider>
</spi>
----
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 `\&quot;`.

101
topics/config-subsystem/start-cli.adoc Normal file
View file

@ -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
----

24
topics/database/hibernate.adoc Normal file → Executable file
View file

@ -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 <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>.
.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"
}
},
<spi name="connectionsJpa">
<provider name="default" enabled="true">
<properties>
<property name="dataSource" value="java:jboss/datasources/KeycloakDS"/>
<property name="initializeEmpty" value="false"/>
<property name="migrationStrategy" value="manual"/>
<property name="migrationExport" value="${jboss.home.dir}/keycloak-database-update.sql"/>
</properties>
</provider>
</spi>
----
Possible configuration options are:

145
topics/mongo.adoc
View file

@ -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 <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>.
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]
----
<spi name="eventsStore">
<default-provider>jpa</default-provider>
<provider name="jpa" enabled="true">
<properties>
<property name="exclude-events" value="[&quot;REFRESH_TOKEN&quot;]"/>
</properties>
</provider>
</spi>
<spi name="realm">
<default-provider>jpa</default-provider>
</spi>
<spi name="user">
<default-provider>jpa</default-provider>
</spi>
<spi name="userSessionPersister">
<default-provider>jpa</default-provider>
</spi>
<spi name="authorizationPersister">
<default-provider>jpa</default-provider>
</spi>
----
"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]
<spi name="eventsStore">
<default-provider>mongo</default-provider>
<provider name="mongo" enabled="true">
<properties>
<property name="exclude-events" value="[&quot;REFRESH_TOKEN&quot;]"/>
</properties>
</provider>
</spi>
<spi name="realm">
<default-provider>mongo</default-provider>
</spi>
<spi name="user">
<default-provider>mongo</default-provider>
</spi>
<spi name="userSessionPersister">
<default-provider>mongo</default-provider>
</spi>
<spi name="authorizationPersister">
<default-provider>mongo</default-provider>
</spi>
----
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"
}
}
<spi name="connectionsMongo">
<provider name="default" enabled="true">
<properties>
<property name="host" value="127.0.0.1"/>
<property name="port" value="27017"/>
<property name="db" value="keycloak"/>
<property name="connectionsPerHost" value="100"/>
<property name="databaseSchema" value="update"/>
</properties>
</provider>
</spi>
----
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"
}
}
<spi name="connectionsMongo">
<provider name="default" enabled="true">
<properties>
<property name="uri" value="mongodb://user:password@127.0.0.1/authentication"/>
<property name="db" value="keycloak"/>
</properties>
</provider>
</spi>
----
will authenticate the user against the authentication database, but store all {{book.project.name}} related data in the keycloak database.

44
topics/network/outgoing.adoc
View file

@ -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 <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>
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 <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>.
.keycloak-server.json HTTP client Config
[source,json]
.HTTP client Config example
[source,xml]
----
"connectionsHttpClient": {
"default": {}
},
<spi name="connectionsHttpClient">
<provider name="default" enabled="true">
<properties>
<property name="connection-pool-size" value="256"/>
</properties>
</provider>
</spi>
----
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 <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>.
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 <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>.
You can add your truststore configuration by using the following template:
[source]
[source,xml]
----
<spi name="truststore">
<provider name="file" enabled="true">
<properties>
<property name="file" value="path to your .jks file containing public certificates"/>
<property name="password" value="password"/>
<property name="hostname-verification-policy" value="WILDCARD"/>
<property name="disabled" value="false"/>
</properties>
</provider>
</spi>
"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:

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

@ -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.
----

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

@ -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.