Chapter 4. Managing the subsystem configuration

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.

Red Hat Single Sign-On 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:

<spi name="myspi">
    <default-provider>myprovider</default-provider>
    <properties>
        <property name="spi-foo" value="spi-bar"/>
    </properties>
    <provider name="myprovider" enabled="true">
        <properties>
            <property name="foo" value="bar"/>
        </properties>
    </provider>
    <provider name="mysecondprovider" enabled="true">
        <properties>
            <property name="foo" value="foo"/>
        </properties>
    </provider>
</spi>

<spi name="myspi">
    <default-provider>myprovider</default-provider>
    <properties>
        <property name="spi-foo" value="spi-bar"/>
    </properties>
    <provider name="myprovider" enabled="true">
        <properties>
            <property name="foo" value="bar"/>
        </properties>
    </provider>
    <provider name="mysecondprovider" enabled="true">
        <properties>
            <property name="foo" value="foo"/>
        </properties>
    </provider>
</spi>

Here we have two providers defined for the SPI myspi. The default-provider is listed as myprovider. 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.

The SPI properties can be used to specify SPI-specific configuration properties. As an example, the user, client and role SPIs allow the configuration of storage provider timeouts in milliseconds through the storageProviderTimeout property, as follows:

<spi name="user">
    <properties>
        <property name="storageProviderTimeout" value="10000"/>
    </properties>
</spi>

<spi name="user">
    <properties>
        <property name="storageProviderTimeout" value="10000"/>
    </properties>
</spi>

Also notice that each provider defines its own set of configuration properties. The fact that both providers above have a property called foo 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 eventsStore SPI:

<spi name="eventsStore">
    <provider name="jpa" enabled="true">
        <properties>
            <property name="exclude-events" value="[&quot;EVENT1&quot;,
                                                    &quot;EVENT2&quot;]"/>
        </properties>
    </provider>
</spi>

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

Follow the steps in Server Developer Guide for more details on custom providers and the configuration of providers.

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 JBoss EAP CLI, you need to run jboss-cli.

.../bin/jboss-cli.sh

$ .../bin/jboss-cli.sh

> ...\bin\jboss-cli.bat

> ...\bin\jboss-cli.bat

This will bring you to a prompt like this:

[disconnected /]

[disconnected /]

If you wish to execute commands on a running server, you will first execute the connect command.

[disconnected /] connect
connect
[standalone@localhost:9990 /]

[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 an admin username and password. See the JBoss EAP Configuration Guide for more details on how to make things more secure if you are uncomfortable with that setup.

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-server command with the config file you wish to change.

[disconnected /] embed-server --server-config=standalone.xml
[standalone@embedded /]

[disconnected /] embed-server --server-config=standalone.xml
[standalone@embedded /]

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.

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.

/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheThemes,value=false)
/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheTemplates,value=false)

/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, you can follow the Scripts menu in CLI GUI, or execute the script from the command line as follows:

.../bin/jboss-cli.sh --file=turn-off-caching.cli

$ .../bin/jboss-cli.sh --file=turn-off-caching.cli

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

/subsystem=keycloak-server/:write-attribute(name=web-context,value=myContext)

/subsystem=keycloak-server/:write-attribute(name=web-context,value=myContext)

**/theme=defaults/:write-attribute(name=default,value=myTheme)

**/theme=defaults/:write-attribute(name=default,value=myTheme)

**/spi=mySPI/:add
**/spi=mySPI/provider=myProvider/:add(enabled=true)

**/spi=mySPI/:add
**/spi=mySPI/provider=myProvider/:add(enabled=true)

**/spi=mySPI/provider=myProvider/:write-attribute(name=enabled,value=false)

**/spi=mySPI/provider=myProvider/:write-attribute(name=enabled,value=false)

**/spi=mySPI/:write-attribute(name=default-provider,value=myProvider)

**/spi=mySPI/:write-attribute(name=default-provider,value=myProvider)

**/spi=mySPI/:map-put(name=properties, key=storageProviderTimeout, value=10000)

**/spi=mySPI/:map-put(name=properties, key=storageProviderTimeout, value=10000)

**/spi=mySPI/:map-remove(name=properties, key=storageProviderTimeout)

**/spi=mySPI/:map-remove(name=properties, key=storageProviderTimeout)

**/spi=dblock/:add(default-provider=jpa)
**/spi=dblock/provider=jpa/:add(properties={lockWaitTimeout => "900"},enabled=true)

**/spi=dblock/:add(default-provider=jpa)
**/spi=dblock/provider=jpa/:add(properties={lockWaitTimeout => "900"},enabled=true)

**/spi=dblock/provider=jpa/:map-put(name=properties,key=lockWaitTimeout,value=3)

**/spi=dblock/provider=jpa/:map-put(name=properties,key=lockWaitTimeout,value=3)

**/spi=dblock/provider=jpa/:map-remove(name=properties,key=lockRecheckTime)

**/spi=dblock/provider=jpa/:map-remove(name=properties,key=lockRecheckTime)

**/spi=eventsStore/provider=jpa/:map-put(name=properties,key=exclude-events,value=[EVENT1,EVENT2])

**/spi=eventsStore/provider=jpa/:map-put(name=properties,key=exclude-events,value=[EVENT1,EVENT2])