KEYCLOAK-3196: Use WildFly management model for server configuration (#11)
This commit is contained in:
Stan Silvert
Stian Thorgersen
parent
e5c8491a23
commit
1a8fb3194f
4 changed files with 87 additions and 74 deletions
|
|
@ -25,6 +25,10 @@
|
|||
"link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.0/securing-applications-and-services-guide/"
|
||||
|
||||
},
|
||||
"installguide": {
|
||||
"name": "Server Installation and Configuration Guide",
|
||||
"link": "https://keycloak.gitbooks.io/server-installation-and-configuration/content/"
|
||||
},
|
||||
"apidocs": {
|
||||
"name": "API Documentation",
|
||||
"link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.0/api-documentation/"
|
||||
|
|
|
|||
|
|
@ -25,6 +25,10 @@
|
|||
"link": "https://keycloak.gitbooks.io/securing-client-applications-guide/content/"
|
||||
|
||||
},
|
||||
"installguide": {
|
||||
"name": "Server Installation and Configuration Guide",
|
||||
"link": "https://keycloak.gitbooks.io/server-installation-and-configuration/content/"
|
||||
},
|
||||
"apidocs": {
|
||||
"name": "API Documentation",
|
||||
"link": "http://keycloak.org/docs"
|
||||
|
|
|
|||
|
|
@ -87,16 +87,22 @@ Example service configuration file (`META-INF/services/org.keycloak.events.Event
|
|||
org.acme.provider.MyEventListenerProviderFactory
|
||||
----
|
||||
|
||||
You can configure your provider through `keycloak-server.json`. For example by adding the following to `keycloak-server.json`:
|
||||
You can configure your provider through `standalone.xml`, `standalone-ha.xml`, or `domain.xml`.
|
||||
See the link:{{book.installguide.link}}[{{book.installguide.name}}] for more details on
|
||||
where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file lives.
|
||||
|
||||
[source]
|
||||
For example by adding the following to `standalone.xml`:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
"eventsListener": {
|
||||
"my-event-listener" {
|
||||
"aNumber": 10,
|
||||
"aString": "Foo"
|
||||
}
|
||||
}
|
||||
<spi name="eventsListener">
|
||||
<provider name="my-event-listener" enabled="true">
|
||||
<properties>
|
||||
<property name="aNumber" value="10"/>
|
||||
<property name="aString" value="Foo"/>
|
||||
</properties>
|
||||
</provider>
|
||||
</spi>
|
||||
----
|
||||
|
||||
Then you can retrieve the config in the `ProviderFactory` init method:
|
||||
|
|
@ -202,16 +208,17 @@ Then copy `event-listener-sysout-example.jar` to this folder and create `module.
|
|||
----
|
||||
|
||||
Once you've created the module you need to register this module with Keycloak.
|
||||
This is done by editing keycloak-server.json and adding it to the providers:
|
||||
This is done by editing the keycloak-server subsystem section of
|
||||
`standalone.xml`, `standalone-ha.xml`, or `domain.xml`, and adding it to the providers:
|
||||
|
||||
[source]
|
||||
[source,xml]
|
||||
----
|
||||
{
|
||||
"providers": [
|
||||
...
|
||||
"module:org.keycloak.examples.event-sysout"
|
||||
]
|
||||
}
|
||||
<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
|
||||
<web-context>auth</web-context>
|
||||
<providers>
|
||||
<provider>module:org.keycloak.examples.event-sysout</provider>
|
||||
</providers>
|
||||
...
|
||||
----
|
||||
|
||||
==== Register a provider using file-system
|
||||
|
|
@ -219,62 +226,55 @@ This is done by editing keycloak-server.json and adding it to the providers:
|
|||
To register your provider simply copy the JAR including the ProviderFactory and Provider classes and the provider configuration file to server's root `providers` directory.
|
||||
|
||||
You can also define multiple provider class-path if you want to create isolated class-loaders.
|
||||
To do this edit keycloak-server.json and add more classpath entries to the providers array.
|
||||
To do this edit `standalone.xml`, `standalone-ha.xml`, or `domain.xml` and add more classpath entries to the providers element.
|
||||
For example:
|
||||
|
||||
[source]
|
||||
[source,xml]
|
||||
----
|
||||
{
|
||||
"providers": [
|
||||
"classpath:provider1.jar;lib-v1.jar",
|
||||
"classpath:provider2.jar;lib-v2.jar"
|
||||
]
|
||||
}
|
||||
<providers>
|
||||
<provider>classpath:provider1.jar;lib-v1.jar</provider>
|
||||
<provider>classpath:provider2.jar;lib-v2.jar</provider>
|
||||
</providers>
|
||||
----
|
||||
|
||||
The above example will create two separate class-loaders for providers.
|
||||
The classpath entries follow the same syntax as Java classpath, with ';' separating multiple-entries.
|
||||
Wildcard is also supported allowing loading all jars (files with .jar or .JAR extension) in a folder, for example:
|
||||
|
||||
[source]
|
||||
[source,xml]
|
||||
----
|
||||
{
|
||||
"providers": [
|
||||
"classpath:/home/user/providers/*"
|
||||
]
|
||||
}
|
||||
<providers>
|
||||
<provider>classpath:/home/user/providers/*</provider>
|
||||
</providers>
|
||||
----
|
||||
|
||||
==== Configuring a provider
|
||||
|
||||
You can pass configuration options to your provider by setting them in `keycloak-server.json`.
|
||||
You can pass configuration options to your provider by setting them in `standalone.xml`, `standalone-ha.xml`, or `domain.xml`.
|
||||
For example to set the max value for `my-event-listener` add:
|
||||
|
||||
[source]
|
||||
[source.xml]
|
||||
----
|
||||
{
|
||||
"eventsListener": {
|
||||
"my-event-listener": {
|
||||
"max": 100
|
||||
}
|
||||
}
|
||||
}
|
||||
<spi name="eventsListener">
|
||||
<provider name="my-event-listener" enabled="true">
|
||||
<properties>
|
||||
<property name="max" value="100"/>
|
||||
</properties>
|
||||
</provider>
|
||||
</spi>
|
||||
----
|
||||
|
||||
==== Disabling a provider
|
||||
|
||||
You can disable a provider by setting the enabled field for the provider to false in `keycloak-server.json`.
|
||||
You can disable a provider by setting the enabled attribute for the provider to false
|
||||
in `standalone.xml`, `standalone-ha.xml`, or `domain.xml`.
|
||||
For example to disable the Infinispan user cache provider add:
|
||||
|
||||
[source]
|
||||
[source,xml]
|
||||
----
|
||||
{
|
||||
"userCache": {
|
||||
"infinispan" : {
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
}
|
||||
<spi name="userCache">
|
||||
<provider name="infinispan" enabled="false"/>
|
||||
</spi>
|
||||
----
|
||||
|
||||
=== Available SPIs
|
||||
|
|
@ -286,9 +286,9 @@ If you want to see list of all available SPIs at runtime, you can check `Server
|
|||
|===
|
||||
|SPI|Description
|
||||
|
||||
|Connections Infinispan|Loads and configures Infinispan connections. The default implementation can load connections from the Infinispan subsystem, or alternatively can be manually configured in keycloak-server.json
|
||||
|Connections Jpa|Loads and configures Jpa connections. The default implementation can load datasources from WildFly/EAP, or alternatively can be manually configured in keycloak-server.json
|
||||
|Connections Mongo|Loads and configures MongoDB connections. The default implementation is configured in keycloak-server.json
|
||||
|Connections Infinispan|Loads and configures Infinispan connections. The default implementation can load connections from the Infinispan subsystem, or alternatively can be manually configured in standalone.xml
|
||||
|Connections Jpa|Loads and configures Jpa connections. The default implementation can load datasources from WildFly/EAP, or alternatively can be manually configured in standalone.xml
|
||||
|Connections Mongo|Loads and configures MongoDB connections. The default implementation is configured in standalone.xml
|
||||
|Email Sender|Sends email. The default implementation uses JavaMail
|
||||
|Email Template|Format email and uses Email Sender to send the email. The default implementation uses FreeMarker templates
|
||||
|Events Listener|Listen to user related events for example user login success and failures. Keycloak provides two implementations out of box. One that logs events to the server log and another that can send email notifications to users on certain events
|
||||
|
|
|
|||
|
|
@ -24,15 +24,19 @@ your realm from the drop-down box in the top left corner. Under `Realm Settings`
|
|||
NOTE: To set the theme for the `master` admin console you need to set the admin console theme for the `master` realm. To see the changes to the admin console
|
||||
refresh the page.
|
||||
|
||||
To change the welcome theme you need to edit `keycloak-server.json` (in `standalone/configuration` or `domain/servers/{server name}/configuration`) and add `welcomeTheme` to the theme element, for example:
|
||||
To change the welcome theme you need to edit `standalone.xml`, `standalone-ha.xml`, or `domain.xml`.
|
||||
See the link:{{book.installguide.link}}[{{book.installguide.name}}] for more details on
|
||||
where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file lives.
|
||||
|
||||
[source,json]
|
||||
Add `welcomeTheme` to the theme element, for example:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
"theme": {
|
||||
<theme>
|
||||
...
|
||||
"welcomeTheme": "custom-theme",
|
||||
<welcomeTheme>custom-theme</welcomeTheme>
|
||||
...
|
||||
}
|
||||
</theme>
|
||||
----
|
||||
|
||||
If the server is running you need to restart the server for the changes to the welcome theme to take effect.
|
||||
|
|
@ -61,18 +65,17 @@ When extending a theme you can override individual resources (templates, stylesh
|
|||
need to update your custom template when upgrading to a new release.
|
||||
|
||||
While creating a theme it's a good idea to disable caching as this makes it possible to edit theme resources directly from the `themes` directory without
|
||||
restarting {{book.project.name}}. To do this edit `standalone/configuration/keycloak-server.json` for `theme` set `staticMaxAge` to `-1` and both
|
||||
restarting {{book.project.name}}. To do this edit `standalone.xml`. For `theme` set `staticMaxAge` to `-1` and both
|
||||
`cacheTemplates` and `cacheThemes` to `false`:
|
||||
|
||||
[source,json]
|
||||
[source,xml]
|
||||
----
|
||||
"theme": {
|
||||
<theme>
|
||||
<staticMaxAge>-1</staticMaxAge>
|
||||
<cacheThemes>false</cacheThemes>
|
||||
<cacheTemplates>false</cacheTemplates>
|
||||
...
|
||||
"staticMaxAge": -1,
|
||||
"cacheTemplates": false,
|
||||
"cacheThemes": false,
|
||||
...
|
||||
}
|
||||
</theme>
|
||||
----
|
||||
|
||||
Remember to re-enable caching in production as it will significantly impact performance.
|
||||
|
|
@ -352,21 +355,23 @@ To manually create the module create the directory `modules/org/keycloak/example
|
|||
</module>
|
||||
----
|
||||
|
||||
You also need to register the module with {{book.project.name}}. This is done by editing `keycloak-server.json` (in `standalone/configuration` or `domain/servers/{server name}/configuration`) and adding the module
|
||||
to `theme/module/modules`. For example:
|
||||
You also need to register the module with {{book.project.name}}. This is done by editing `standalone.xml`, `standalone-ha.xml`, or `domain.xml`.
|
||||
See the link:{{book.installguide.link}}[{{book.installguide.name}}] for more details on
|
||||
where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file lives.
|
||||
|
||||
[source]
|
||||
Then and add the module to `theme/module/modules`. For example:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
[
|
||||
"theme": {
|
||||
<theme>
|
||||
...
|
||||
"module": {
|
||||
"modules": [ "org.example.mytheme" ]
|
||||
}
|
||||
}
|
||||
<modules>
|
||||
<module>org.example.mytheme</module>
|
||||
</modules>
|
||||
</theme>
|
||||
----
|
||||
|
||||
If the server is running you need to restart the server after changing `keycloak-server.json`.
|
||||
If the server is running you need to restart the server after changing `standalone.xml`, `standalone-ha.xml`, or `domain.xml`.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
|
|
|
|||
Loading…
Reference in a new issue