initial move
14
SUMMARY.adoc
Executable file
|
@ -0,0 +1,14 @@
|
|||
== Keycloak Reference Guide
|
||||
|
||||
//. link:topics/templates/document-attributes.adoc[]
|
||||
:imagesdir: images
|
||||
|
||||
. link:topics/preface.adoc[Preface]
|
||||
. link:topics/Overview.adoc[Overview]
|
||||
. link:topics/server-installation.adoc[Installation and Configuration of Keycloak Server]
|
||||
. link:topics/openshift.adoc[Running Keycloak Server on OpenShift]
|
||||
. link:topics/cache.adoc[Server Cache]
|
||||
. link:topics/clustering.adoc[Clustering]
|
||||
. link:topics/proxy.adoc[Keycloak Security Proxy]
|
||||
|
||||
|
BIN
images/add-provider-dialog.png
Executable file
After Width: | Height: | Size: 88 KiB |
BIN
images/add-provider-select.png
Executable file
After Width: | Height: | Size: 59 KiB |
BIN
images/domain-mode.png
Executable file
After Width: | Height: | Size: 103 KiB |
BIN
images/email-simple-example.png
Executable file
After Width: | Height: | Size: 15 KiB |
BIN
images/identity_broker_flow.png
Executable file
After Width: | Height: | Size: 21 KiB |
BIN
images/keycloak_logo.png
Executable file
After Width: | Height: | Size: 18 KiB |
BIN
images/update-server-config-dialog.png
Executable file
After Width: | Height: | Size: 66 KiB |
BIN
images/update-server-config-select.png
Executable file
After Width: | Height: | Size: 80 KiB |
58
topics/cache.adoc
Executable file
|
@ -0,0 +1,58 @@
|
|||
= Server Cache
|
||||
|
||||
By default, Keycloak caches realm metadata and users.
|
||||
There are two separate caches, one for realm metadata (realm, application, client, roles, etc...) and one for users.
|
||||
These caches greatly improves the performance of the server.
|
||||
|
||||
== Eviction and Expiration
|
||||
|
||||
By default the user cache contains a maximum of 10000 entries.
|
||||
This is not 10000 users, but 10000 entries in the cache.
|
||||
You can change the maximum number of entries by editing the server configuration `standalone.xml` or `standalone-ha.xml`.
|
||||
Locate the element `cache-container name="keycloak"` and change the eviction policy for the `users` cache.
|
||||
For more information see https://docs.jboss.org/author/display/WFLY10/Infinispan+Subsystem[Infinispan Subsystem documentation].
|
||||
|
||||
== Disabling Caches
|
||||
|
||||
To disable the realm or user cache, you must edit the `keycloak-server.json` file in your distribution.
|
||||
Here's what the config looks like initially.
|
||||
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
"userCache": {
|
||||
"infinispan" : {
|
||||
"enabled": true
|
||||
}
|
||||
},
|
||||
|
||||
"realmCache": {
|
||||
"infinispan" : {
|
||||
"enabled": true
|
||||
}
|
||||
},
|
||||
----
|
||||
|
||||
To disable the cache set the enabled field to false for the cache you want to disable:
|
||||
[source]
|
||||
----
|
||||
|
||||
"userCache": {
|
||||
"infinispan" : {
|
||||
"enabled": false
|
||||
}
|
||||
},
|
||||
|
||||
"realmCache": {
|
||||
"infinispan" : {
|
||||
"enabled": false
|
||||
}
|
||||
},
|
||||
----
|
||||
|
||||
== Clear Caches
|
||||
|
||||
To clear the realm or user cache, go to the Keycloak admin console Realm Settings->Cache Config page.
|
||||
On this page you can clear the realm cache or the user cache.
|
||||
This will clear the caches for all realms and not only the selected realm.
|
44
topics/openshift.adoc
Executable file
|
@ -0,0 +1,44 @@
|
|||
[[_openshift]]
|
||||
|
||||
= Running Keycloak Server on OpenShift
|
||||
|
||||
Keycloak provides a OpenShift cartridge to make it easy to get it running on OpenShift.
|
||||
If you don't already have an account or don't know how to create applications go to https://www.openshift.com/ first.
|
||||
You can create the Keycloak instance either with the web tool or the command line tool, both approaches are described below.
|
||||
|
||||
WARNING: It's important that immediately after creating a Keycloak instance you open the `Administration Console` and login to reset the password.
|
||||
If this is not done anyone can easily gain admin rights to your Keycloak instance.
|
||||
|
||||
== Create Keycloak instance with the web tool
|
||||
|
||||
. Open https://openshift.redhat.com/app/console/applications and click on `Add Application`.
|
||||
. Scroll down to the bottom of the page to find the `Code Anything` section.
|
||||
. Insert `http://cartreflect-claytondev.rhcloud.com/github/keycloak/openshift-keycloak-cartridge` into the `URL to a cartridge definition` field and click on `Next`.
|
||||
. Fill in the following form and click on `Create Application`.
|
||||
. Click on `Continue to the application overview page`.
|
||||
. Under the list of applications you should find your Keycloak instance and the status should be `Started`.
|
||||
. Click on it to open the Keycloak servers homepage.
|
||||
|
||||
== Create Keycloak instance with the command-line tool
|
||||
|
||||
. Run the following command from a terminal:
|
||||
|
||||
[source]
|
||||
----
|
||||
rhc app create <APPLICATION NAME> http://cartreflect-claytondev.rhcloud.com/github/keycloak/openshift-keycloak-cartridge
|
||||
----
|
||||
|
||||
. Replace `<APPLICATION NAME>` with the name you want (for example keycloak).
|
||||
|
||||
Once the instance is created the rhc tool outputs details about it.
|
||||
Open the returned `URL` in a browser to open the Keycloak servers homepage.
|
||||
|
||||
== Next steps
|
||||
|
||||
The Keycloak servers homepage shows the Keycloak logo and `Welcome to Keycloak`.
|
||||
There is also a link to the `Administration Console`.
|
||||
Open that and log in using username `admin` and password `admin`.
|
||||
On the first login you are required to change the password.
|
||||
|
||||
TIP: On OpenShift Keycloak has been configured to only accept requests over https.
|
||||
If you try to use http you will be redirected to https.
|
20
topics/preface.adoc
Executable file
|
@ -0,0 +1,20 @@
|
|||
= Preface
|
||||
|
||||
In some of the example listings, what is meant to be displayed on one line does not fit inside the available page width.These lines have been broken up. A '\' at the end of a line means that a break has been introduced to fit in the page, with the following lines indented.
|
||||
So:
|
||||
|
||||
[source]
|
||||
----
|
||||
Let's pretend to have an extremely \
|
||||
long line that \
|
||||
does not fit
|
||||
This one is short
|
||||
----
|
||||
Is really:
|
||||
|
||||
[source]
|
||||
----
|
||||
Let's pretend to have an extremely long line that does not fit
|
||||
This one is short
|
||||
----
|
||||
|
238
topics/proxy.adoc
Executable file
|
@ -0,0 +1,238 @@
|
|||
[[_proxy]]
|
||||
= Keycloak Security Proxy
|
||||
|
||||
Keycloak has an HTTP(S) proxy that you can put in front of web applications and services where it is not possible to install the keycloak adapter.
|
||||
You can set up URL filters so that certain URLs are secured either by browser login and/or bearer token authentication.
|
||||
You can also define role constraints for URL patterns within your applications.
|
||||
|
||||
== Proxy Install and Run
|
||||
|
||||
Download the keycloak proxy distribution from the Keycloak download pages and unzip it.
|
||||
[source]
|
||||
----
|
||||
|
||||
$ unzip keycloak-proxy-dist.zip
|
||||
----
|
||||
|
||||
To run it you must have a proxy config file (which we'll discuss in a moment).
|
||||
[source]
|
||||
----
|
||||
|
||||
$ java -jar bin/launcher.jar [your-config.json]
|
||||
----
|
||||
|
||||
If you do not specify a path to the proxy config file, the launcher will look in the current working directory for the file named `proxy.json`
|
||||
|
||||
== Proxy Configuration
|
||||
|
||||
Here's an example configuration file.
|
||||
[source]
|
||||
----
|
||||
|
||||
{
|
||||
"target-url": "http://localhost:8082",
|
||||
"send-access-token": true,
|
||||
"bind-address": "localhost",
|
||||
"http-port": "8080",
|
||||
"https-port": "8443",
|
||||
"keystore": "classpath:ssl.jks",
|
||||
"keystore-password": "password",
|
||||
"key-password": "password",
|
||||
"applications": [
|
||||
{
|
||||
"base-path": "/customer-portal",
|
||||
"error-page": "/error.html",
|
||||
"adapter-config": {
|
||||
"realm": "demo",
|
||||
"resource": "customer-portal",
|
||||
"realm-public-key": "MIGfMA0GCSqGSIb",
|
||||
"auth-server-url": "http://localhost:8081/auth",
|
||||
"ssl-required" : "external",
|
||||
"principal-attribute": "name",
|
||||
"credentials": {
|
||||
"secret": "password"
|
||||
}
|
||||
}
|
||||
,
|
||||
"constraints": [
|
||||
{
|
||||
"pattern": "/users/*",
|
||||
"roles-allowed": [
|
||||
"user"
|
||||
]
|
||||
},
|
||||
{
|
||||
"pattern": "/admins/*",
|
||||
"roles-allowed": [
|
||||
"admin"
|
||||
]
|
||||
},
|
||||
{
|
||||
"pattern": "/users/permit",
|
||||
"permit": true
|
||||
},
|
||||
{
|
||||
"pattern": "/users/deny",
|
||||
"deny": true
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
----
|
||||
|
||||
=== Basic Config
|
||||
|
||||
The basic configuration options for the server are as follows:
|
||||
|
||||
target-url::
|
||||
The URL this server is proxying _REQUIRED._.
|
||||
|
||||
send-access-token::
|
||||
Boolean flag.
|
||||
If true, this will send the access token via the KEYCLOAK_ACCESS_TOKEN header to the proxied server. _OPTIONAL._.
|
||||
Default is false.
|
||||
|
||||
bind-address::
|
||||
DNS name or IP address to bind the proxy server's sockets to. _OPTIONAL._.
|
||||
The default value is _localhost_
|
||||
|
||||
http-port::
|
||||
Port to listen for HTTP requests.
|
||||
If you do not specify this value, then the proxy will not listen for regular HTTP requests. _OPTIONAL._.
|
||||
|
||||
https-port::
|
||||
Port to listen for HTTPS requests.
|
||||
If you do not specify this value, then the proxy will not listen for HTTPS requests. _OPTIONAL._.
|
||||
|
||||
keystore::
|
||||
Path to a Java keystore file that contains private key and certificate for the server to be able to handle HTTPS requests.
|
||||
Can be a file path, or, if you prefix it with `classpath:` it will look for this file in the classpath. _OPTIONAL._.
|
||||
If you have enabled HTTPS, but have not defined a keystore, the proxy will auto-generate a self-signed certificate and use that.
|
||||
|
||||
buffer-size::
|
||||
HTTP server socket buffer size.
|
||||
Usually the default is good enough. _OPTIONAL._.
|
||||
|
||||
buffers-per-region::
|
||||
HTTP server socket buffers per region.
|
||||
Usually the default is good enough. _OPTIONAL._.
|
||||
|
||||
io-threads::
|
||||
Number of threads to handle IO.
|
||||
Usually default is good enough.
|
||||
_OPTIONAL._.
|
||||
The default is the number of available processors * 2.
|
||||
|
||||
worker-threads::
|
||||
Number of threads to handle requests.
|
||||
Usually the default is good enough. _OPTIONAL._.
|
||||
The default is the number of available processors * 16.
|
||||
|
||||
=== Application Config
|
||||
|
||||
Next under the `applications` array attribute, you can define one or more applications per host you are proxying.
|
||||
|
||||
base-path::
|
||||
The base context root for the application.
|
||||
Must start with '/' _REQUIRED._.
|
||||
|
||||
error-page::
|
||||
If the proxy has an error, it will display the target application's error page relative URL _OPTIONAL._.
|
||||
This is a relative path to the base-path.
|
||||
In the example above it would be `/customer-portal/error.html`.
|
||||
|
||||
adapter-config::
|
||||
_REQUIRED._.
|
||||
Same configuration as any other keycloak adapter.
|
||||
See <<_adapter_config,Adapter Config>>
|
||||
|
||||
==== Constraint Config
|
||||
|
||||
Next under each application you can define one or more constraints in the `constraints` array attribute.
|
||||
A constraint defines a URL pattern relative to the base-path.
|
||||
You can deny, permit, or require authentication for a specific URL pattern.
|
||||
You can specify roles allowed for that path as well.
|
||||
More specific constraints will take precedence over more general ones.
|
||||
|
||||
pattern::
|
||||
URL pattern to match relative to the base-path of the application.
|
||||
Must start with '/' _REQUIRED._.
|
||||
You may only have one wildcard and it must come at the end of the pattern.
|
||||
Valid `/foo/bar/*` and `/foo/*.txt` Not valid: `/*/foo/*`.
|
||||
|
||||
roles-allowed::
|
||||
Array of strings of roles allowed to access this url pattern. _OPTIONAL._.
|
||||
|
||||
methods::
|
||||
Array of strings of HTTP methods that will exclusively match this pattern and HTTP request. _OPTIONAL._.
|
||||
|
||||
excluded-methods::
|
||||
Array of strings of HTTP methods that will be ignored when match this pattern. _OPTIONAL._.
|
||||
|
||||
deny::
|
||||
Deny all access to this URL pattern. _OPTIONAL._.
|
||||
|
||||
permit::
|
||||
Permit all access without requiring authentication or a role mapping. _OPTIONAL._.
|
||||
|
||||
permit-and-inject::
|
||||
Permit all access, but inject the headers, if user is already authenticated._OPTIONAL._.
|
||||
|
||||
authenticate::
|
||||
Require authentication for this pattern, but no role mapping. _OPTIONAL._.
|
||||
|
||||
=== Header Names Config
|
||||
|
||||
Next under the list of applications you can override the defaults for the names of the header fields injected by the proxy (see Keycloak Identity Headers). This mapping is optional.
|
||||
|
||||
keycloak-subject::
|
||||
e.g.
|
||||
MYAPP_USER_ID
|
||||
|
||||
keycloak-username::
|
||||
e.g.
|
||||
MYAPP_USER_NAME
|
||||
|
||||
keycloak-email::
|
||||
e.g.
|
||||
MYAPP_USER_EMAIL
|
||||
|
||||
keycloak-name::
|
||||
e.g.
|
||||
MYAPP_USER_ID
|
||||
|
||||
keycloak-access-token::
|
||||
e.g.
|
||||
MYAPP_ACCESS_TOKEN
|
||||
|
||||
== Keycloak Identity Headers
|
||||
|
||||
When forwarding requests to the proxied server, Keycloak Proxy will set some additional headers with values from the OIDC identity token it received for authentication.
|
||||
|
||||
KEYCLOAK_SUBJECT::
|
||||
User id.
|
||||
Corresponds to JWT `sub` and will be the user id Keycloak uses to store this user.
|
||||
|
||||
KEYCLOAK_USERNAME::
|
||||
Username.
|
||||
Corresponds to JWT `preferred_username`
|
||||
|
||||
KEYCLOAK_EMAIL::
|
||||
Email address of user if set.
|
||||
|
||||
KEYCLOAK_NAME::
|
||||
Full name of user if set.
|
||||
|
||||
KEYCLOAK_ACCESS_TOKEN::
|
||||
Send the access token in this header if the proxy was configured to send it.
|
||||
This token can be used to make bearer token requests. Header field names can be configured using a map of `header-names` in configuration file:
|
||||
[source]
|
||||
----
|
||||
|
||||
{
|
||||
"header-names" {
|
||||
"keycloak-subject": "MY_SUBJECT"
|
||||
}
|
||||
}
|
||||
----
|
610
topics/server-installation.adoc
Executable file
|
@ -0,0 +1,610 @@
|
|||
[[_server_installation]]
|
||||
|
||||
= Installation and Configuration of Keycloak Server
|
||||
|
||||
== Installation
|
||||
|
||||
Keycloak Server has three downloadable distributions.
|
||||
To run the Keycloak server you need to have Java 8 already installed.
|
||||
|
||||
* keycloak-.[zip|tar.gz]
|
||||
* keycloak-overlay-.[zip|tar.gz]
|
||||
* keycloak-demo-.[zip|tar.gz]
|
||||
|
||||
[[_server_install]]
|
||||
=== Install Standalone Server
|
||||
|
||||
For production and for non-JavaEE developers we recommend using the standalone Keycloak server.
|
||||
All you need to do is to download `keycloak-.zip` or `keycloak-.tar.gz`, unpackage and start to have a Keycloak server up and running.
|
||||
|
||||
To install first download either the zip or tar.gz and extract.
|
||||
Then start by running either:
|
||||
|
||||
[source]
|
||||
----
|
||||
keycloak-/bin/standalone.sh
|
||||
----
|
||||
or:
|
||||
|
||||
[source]
|
||||
----
|
||||
keycloak-/bin/standalone.bat
|
||||
----
|
||||
|
||||
[[_overlay_install]]
|
||||
=== Install on existing WildFly or JBoss EAP
|
||||
|
||||
Keycloak can be installed into an existing installations of WildFly or JBoss EAP . To do this download `keycloak-overlay-.zip` or `keycloak-overlay-.tar.gz`.
|
||||
Once downloaded extract into the root directory of your installation.
|
||||
|
||||
To add Keycloak to existing standalone.xml server config run:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
bin/jboss-cli.sh --file=bin/keycloak-install.cli
|
||||
----
|
||||
To add Keycloak to existing standalone-ha.xml server config run:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
bin/jboss-cli.sh --file=bin/keycloak-install-ha.cli
|
||||
----
|
||||
If you want to add Keycloak to a different server config edit `keycloak-install.cli` or `keycloak-install-ha.cli` and change the name of the server config.
|
||||
|
||||
=== Install Development Bundle
|
||||
|
||||
The demo bundle contains everything you need to get started with Keycloak including documentation and examples.
|
||||
To install it first download `keycloak-demo-.zip` or `keycloak-demo-.tar.gz`.
|
||||
Once downloaded extract it inside `keycloak-demo-` you'll find `keycloak` which contains a full WildFly server with Keycloak Server and Adapters included.
|
||||
You'll also find `docs` and `examples` which contains everything you need to get started developing applications that use Keycloak.
|
||||
|
||||
To start WildFly with Keycloak run:
|
||||
|
||||
[source]
|
||||
----
|
||||
keycloak-/bin/standalone.sh
|
||||
----
|
||||
or:
|
||||
|
||||
[source]
|
||||
----
|
||||
keycloak-/bin/standalone.bat
|
||||
----
|
||||
|
||||
== Configuring the Server
|
||||
|
||||
Although the Keycloak Server is designed to run out of the box, there's some things you'll need to configure before you go into production.
|
||||
Specifically:
|
||||
|
||||
* Configuring Keycloak to use a production database
|
||||
* Setting up SSL/HTTPS
|
||||
* Enforcing HTTPS connections
|
||||
|
||||
=== Admin User
|
||||
|
||||
To access the admin console to configure Keycloak you need an account to login.
|
||||
There is no built in user, instead you have to first create an admin account.
|
||||
This can done either by opening http://localhost:8080/auth (creating a user through the browser can only be done through localhost) or you can use the add-user script from the command-line.
|
||||
|
||||
The `add-user` script creates a temporary file with the details of the user, which are imported at startup.
|
||||
To add a user with this script run:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
bin/add-user.[sh|bat] -r master -u <username> -p <password>
|
||||
----
|
||||
Then restart the server.
|
||||
For `keycloak-overlay`, please make sure to use:
|
||||
|
||||
[source]
|
||||
----
|
||||
bin/add-user-keycloak.[sh|bat] -r master -u <username> -p <password>
|
||||
----
|
||||
|
||||
=== Relational Database Configuration
|
||||
|
||||
You might want to use a better relational database for Keycloak like PostgreSQL or MySQL.
|
||||
You might also want to tweak the configuration settings of the datasource.
|
||||
Please see the https://docs.jboss.org/author/display/WFLY8/DataSource+configuration[Wildfly] documentation on how to do this.
|
||||
|
||||
Keycloak runs on a Hibernate/JPA backend which is configured in the `standalone/configuration/keycloak-server.json`.
|
||||
By default the setting is like this:
|
||||
|
||||
[source]
|
||||
----
|
||||
"connectionsJpa": {
|
||||
"default": {
|
||||
"dataSource": "java:jboss/datasources/KeycloakDS",
|
||||
"databaseSchema": "update"
|
||||
}
|
||||
},
|
||||
----
|
||||
Possible configuration options are:
|
||||
|
||||
dataSource::
|
||||
JNDI name of the dataSource
|
||||
|
||||
jta::
|
||||
boolean property to specify if datasource is JTA capable
|
||||
|
||||
driverDialect::
|
||||
Value of Hibernate dialect.
|
||||
In most cases you don't need to specify this property as dialect will be autodetected by Hibernate.
|
||||
|
||||
databaseSchema::
|
||||
Specify if schema should be updated or validated.
|
||||
Valid values are "update" and "validate" ("update is default).
|
||||
|
||||
showSql::
|
||||
Specify whether Hibernate should show all SQL commands in the console (false by default)
|
||||
|
||||
formatSql::
|
||||
Specify whether Hibernate should format SQL commands (true by default)
|
||||
|
||||
globalStatsInterval::
|
||||
Will log global statistics from Hibernate about executed DB queries and other things.
|
||||
Statistics are always reported to server log at specified interval (in seconds) and are cleared after each report.
|
||||
|
||||
schema::
|
||||
Specify the database schema to use
|
||||
|
||||
===== Tested databases
|
||||
|
||||
Here is list of RDBMS databases and corresponding JDBC drivers, which were tested with Keycloak.
|
||||
Note that Hibernate dialect is usually set automatically according to your database, but you have possibility to override if default dialect doesn't work correctly.
|
||||
You can setup dialect by adding property `driverDialect` to the `keycloak-server.json` into `connectionsJpa` section (see above).
|
||||
|
||||
.Tested databases
|
||||
[cols="1,1,1", frame="all", options="header"]
|
||||
|===
|
||||
| Database
|
||||
| JDBC driver
|
||||
| Hibernate Dialect
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|===
|
||||
|
||||
=== MongoDB based model
|
||||
|
||||
Keycloak provides http://www.mongodb.com[MongoDB] based model implementation, which means that your identity data will be saved in MongoDB instead of traditional RDBMS.
|
||||
To configure Keycloak to use Mongo open `standalone/configuration/keycloak-server.json` in your favourite editor, then change:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
"eventsStore": {
|
||||
"provider": "jpa",
|
||||
"jpa": {
|
||||
"exclude-events": [ "REFRESH_TOKEN" ]
|
||||
}
|
||||
},
|
||||
|
||||
"realm": {
|
||||
"provider": "jpa"
|
||||
},
|
||||
|
||||
"user": {
|
||||
"provider": "${keycloak.user.provider:jpa}"
|
||||
},
|
||||
----
|
||||
to:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
"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]
|
||||
----
|
||||
|
||||
"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/`.
|
||||
|
||||
=== Outgoing Server HTTP Requests
|
||||
|
||||
Keycloak server needs to invoke on remote HTTP endpoints to do things like backchannel logouts and other management functions.
|
||||
Keycloak maintains a HTTP client connection pool which has various configuration settings you can specify before boot time.
|
||||
This is configured in the `standalone/configuration/keycloak-server.json`.
|
||||
By default the setting is like this:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
"connectionsHttpClient": {
|
||||
"default": {}
|
||||
},
|
||||
----
|
||||
Possible configuration options are:
|
||||
|
||||
establish-connection-timeout-millis::
|
||||
Timeout for establishing a socket connection.
|
||||
|
||||
socket-timeout-millis::
|
||||
If an outgoing request does not receive data for this amount of time, timeout the connection.
|
||||
|
||||
connection-pool-size::
|
||||
How many connections can be in the pool (128 by default).
|
||||
|
||||
max-pooled-per-route::
|
||||
How many connections can be pooled per host (64 by default).
|
||||
|
||||
connection-ttl-millis::
|
||||
Maximum connection time to live in milliseconds.
|
||||
Not set by default.
|
||||
|
||||
max-connection-idle-time-millis::
|
||||
Maximum time the connection might stay idle in the connection pool (900 seconds by default). Will start background cleaner thread of Apache HTTP client.
|
||||
Set to -1 to disable this checking and the background thread.
|
||||
|
||||
disable-cookies::
|
||||
`true` by default.
|
||||
When set to true, this will disable any cookie caching.
|
||||
|
||||
client-keystore::
|
||||
This is the file path to a Java keystore file.
|
||||
This keystore contains client certificate for two-way SSL.
|
||||
|
||||
client-keystore-password::
|
||||
Password for the client keystore.
|
||||
This is _REQUIRED_ if `client-keystore` is set.
|
||||
|
||||
client-key-password::
|
||||
_Not supported yet, but we will support in future versions. Password for the client's key.
|
||||
This is _REQUIRED_ if `client-keystore` is set.
|
||||
|
||||
[[_truststore]]
|
||||
=== Securing Outgoing Server HTTP Requests
|
||||
|
||||
When Keycloak connects out to remote HTTP endpoints over secure https connection, it has to validate the other server's certificate in order to ensure it is connecting to a trusted server.
|
||||
That is necessary in order to prevent man-in-the-middle attacks.
|
||||
|
||||
How certificates are validated is configured in the `standalone/configuration/keycloak-server.json`.
|
||||
By default truststore provider is not configured, and any https connections fall back to standard java truststore configuration as described in https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html[
|
||||
Java's JSSE Reference Guide] - using `javax.net.ssl.trustStore system property`, otherwise `cacerts` file that comes with java is used.
|
||||
|
||||
Truststore is used when connecting securely to identity brokers, LDAP identity providers, when sending emails, and for backchannel communication with client applications.
|
||||
Some of these facilities may - in case when no trusted certificate is found in your configured truststore - fallback to using the JSSE provided truststore.
|
||||
The default JavaMail API implementation used to send out emails behaves in this way, for example.
|
||||
|
||||
You can add your truststore configuration by using the following template:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
"truststore": {
|
||||
"file": {
|
||||
"file": "path to your .jks file containing public certificates",
|
||||
"password": "password",
|
||||
"hostname-verification-policy": "WILDCARD",
|
||||
"disabled": false
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
Possible configuration options are:
|
||||
|
||||
file::
|
||||
The value is the file path to a Java keystore file.
|
||||
HTTPS requests need a way to verify the host of the server they are talking to.
|
||||
This is what the trustore does.
|
||||
The keystore contains one or more trusted host certificates or certificate authorities.
|
||||
Truststore file should only contain public certificates of your secured hosts.
|
||||
This is _REQUIRED_ if `disabled` is not true.
|
||||
|
||||
password::
|
||||
Password for the truststore.
|
||||
This is _REQUIRED_ if `disabled` is not true.
|
||||
|
||||
hostname-verification-policy::
|
||||
`WILDCARD` by default.
|
||||
For HTTPS requests, this verifies the hostname of the server's certificate.
|
||||
`ANY` means that the hostname is not verified. `WILDCARD` Allows wildcards in subdomain names i.e.
|
||||
*.foo.com. `STRICT` CN must match hostname exactly.
|
||||
|
||||
disabled::
|
||||
If true (default value), truststore configuration will be ignored, and certificate checking will fall back to JSSE configuration as described.
|
||||
If set to false, you must configure `file`, and `password` for the truststore.
|
||||
|
||||
You can use _keytool_ to create a new truststore file and add trusted host certificates to it:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
$ keytool -import -alias HOSTDOMAIN -keystore truststore.jks -file host-certificate.cer
|
||||
----
|
||||
|
||||
[[_ssl_modes]]
|
||||
=== SSL/HTTPS Requirement/Modes
|
||||
|
||||
WARNING: Keycloak is not set up by default to handle SSL/HTTPS.
|
||||
It is highly recommended that you either enable SSL on the Keycloak server itself or on a reverse proxy in front of the Keycloak server.
|
||||
|
||||
Keycloak can run out of the box without SSL so long as you stick to private IP addresses like localhost, 127.0.0.1, 10.0.x.x, 192.168.x.x, and 172..16.x.x.
|
||||
If you try to access Keycloak from a non-IP adress you will get an error.
|
||||
|
||||
Keycloak has 3 SSL/HTTPS modes which you can set up in the admin console under the Settings->Login page and the `Require SSL` select box.
|
||||
Each adapter config should mirror this server-side setting.
|
||||
See adapter config section for more details.
|
||||
|
||||
external::
|
||||
Keycloak can run out of the box without SSL so long as you stick to private IP addresses like localhost, 127.0.0.1, 10.0.x.x, 192.168.x.x, and 172..16.x.x.
|
||||
If you try to access Keycloak from a non-IP adress you will get an error.
|
||||
|
||||
none::
|
||||
Keycloak does not require SSL.
|
||||
|
||||
all::
|
||||
Keycloak requires SSL for all IP addresses.
|
||||
|
||||
=== SSL/HTTPS Setup
|
||||
|
||||
First enable SSL on Keycloak or on a reverse proxy in front of Keycloak.
|
||||
Then configure the Keycloak Server to enforce HTTPS connections.
|
||||
|
||||
==== Enable SSL on Keycloak
|
||||
|
||||
The following things need to be done
|
||||
|
||||
* keytool
|
||||
* Enable Wildfly to use this certificate and turn on SSL/HTTPS.
|
||||
|
||||
===== Creating the Certificate and Java Keystore
|
||||
|
||||
In order to allow HTTPS connections, you need to obtain a self signed or third-party signed certificate and import it into a Java keystore before you can enable HTTPS in the web container you are deploying the Keycloak Server to.
|
||||
|
||||
====== Self Signed Certificate
|
||||
|
||||
In development, you will probably not have a third party signed certificate available to test a Keycloak deployment so you'll need to generate a self-signed on.
|
||||
Generate one is very easy to do with the `keytool` utility that comes with the Java jdk.
|
||||
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
$ keytool -genkey -alias localhost -keyalg RSA -keystore keycloak.jks -validity 10950
|
||||
Enter keystore password: secret
|
||||
Re-enter new password: secret
|
||||
What is your first and last name?
|
||||
[Unknown]: localhost
|
||||
What is the name of your organizational unit?
|
||||
[Unknown]: Keycloak
|
||||
What is the name of your organization?
|
||||
[Unknown]: Red Hat
|
||||
What is the name of your City or Locality?
|
||||
[Unknown]: Westford
|
||||
What is the name of your State or Province?
|
||||
[Unknown]: MA
|
||||
What is the two-letter country code for this unit?
|
||||
[Unknown]: US
|
||||
Is CN=localhost, OU=Keycloak, O=Test, L=Westford, ST=MA, C=US correct?
|
||||
[no]: yes
|
||||
----
|
||||
|
||||
You should answer `What is your first and last name ?` question with the DNS name of the machine you're installing the server on.
|
||||
For testing purposes, `localhost` should be used.
|
||||
After executing this command, the `keycloak.jks` file will be generated in the same directory as you executed the `keytool` command in.
|
||||
|
||||
If you want a third-party signed certificate, but don't have one, you can obtain one for free at http://cacert.org[cacert.org].
|
||||
You'll have to do a little set up first before doing this though.
|
||||
|
||||
The first thing to do is generate a Certificate Request:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
$ keytool -certreq -alias yourdomain -keystore keycloak.jks > keycloak.careq
|
||||
----
|
||||
|
||||
Where `yourdomain` is a DNS name for which this certificate is generated for.
|
||||
Keytool generates the request:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
-----BEGIN NEW CERTIFICATE REQUEST-----
|
||||
MIIC2jCCAcICAQAwZTELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk1BMREwDwYDVQQHEwhXZXN0Zm9y
|
||||
ZDEQMA4GA1UEChMHUmVkIEhhdDEQMA4GA1UECxMHUmVkIEhhdDESMBAGA1UEAxMJbG9jYWxob3N0
|
||||
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr7kck2TaavlEOGbcpi9c0rncY4HhdzmY
|
||||
Ax2nZfq1eZEaIPqI5aTxwQZzzLDK9qbeAd8Ji79HzSqnRDxNYaZu7mAYhFKHgixsolE3o5Yfzbw1
|
||||
29Rvy+eUVe+WZxv5oo9wolVVpdSINIMEL2LaFhtX/c1dqiqYVpfnvFshZQaIg2nL8juzZcBjj4as
|
||||
H98gIS7khql/dkZKsw9NLvyxgJvp7PaXurX29fNf3ihG+oFrL22oFyV54BWWxXCKU/GPn61EGZGw
|
||||
Ft2qSIGLdctpMD1aJR2bcnlhEjZKDksjQZoQ5YMXaAGkcYkG6QkgrocDE2YXDbi7GIdf9MegVJ35
|
||||
2DQMpwIDAQABoDAwLgYJKoZIhvcNAQkOMSEwHzAdBgNVHQ4EFgQUQwlZJBA+fjiDdiVzaO9vrE/i
|
||||
n2swDQYJKoZIhvcNAQELBQADggEBAC5FRvMkhal3q86tHPBYWBuTtmcSjs4qUm6V6f63frhveWHf
|
||||
PzRrI1xH272XUIeBk0gtzWo0nNZnf0mMCtUBbHhhDcG82xolikfqibZijoQZCiGiedVjHJFtniDQ
|
||||
9bMDUOXEMQ7gHZg5q6mJfNG9MbMpQaUVEEFvfGEQQxbiFK7hRWU8S23/d80e8nExgQxdJWJ6vd0X
|
||||
MzzFK6j4Dj55bJVuM7GFmfdNC52pNOD5vYe47Aqh8oajHX9XTycVtPXl45rrWAH33ftbrS8SrZ2S
|
||||
vqIFQeuLL3BaHwpl3t7j2lMWcK1p80laAxEASib/fAwrRHpLHBXRcq6uALUOZl4Alt8=
|
||||
-----END NEW CERTIFICATE REQUEST-----
|
||||
----
|
||||
|
||||
Send this ca request to your CA.
|
||||
The CA will issue you a signed certificate and send it to you.
|
||||
Before you import your new cert, you must obtain and import the root certificate of the CA.
|
||||
You can download the cert from CA (ie.: root.crt) and import as follows:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
$ keytool -import -keystore keycloak.jks -file root.crt -alias root
|
||||
----
|
||||
|
||||
Last step is import your new CA generated certificate to your keystore:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
$ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificate.cer
|
||||
----
|
||||
|
||||
===== Installing the keystore to WildFly
|
||||
|
||||
Now that you have a Java keystore with the appropriate certificates, you need to configure your Wildfly installation to use it.
|
||||
First step is to move the keystore file to a directory you can reference in configuration.
|
||||
I like to put it in `standalone/configuration`.
|
||||
Then you need to edit `standalone/configuration/standalone.xml` to enable SSL/HTTPS.
|
||||
|
||||
To the `security-realms` element add:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
<security-realm name="UndertowRealm">
|
||||
<server-identities>
|
||||
<ssl>
|
||||
<keystore path="keycloak.jks" relative-to="jboss.server.config.dir" keystore-password="secret" />
|
||||
</ssl>
|
||||
</server-identities>
|
||||
</security-realm>
|
||||
----
|
||||
|
||||
Find the element `server name="default-server"` (it's a child element of `subsystem xmlns="urn:jboss:domain:undertow:1.0"`) and add:
|
||||
|
||||
[source]
|
||||
----
|
||||
<https-listener name="https" socket-binding="https" security-realm="UndertowRealm"/>
|
||||
----
|
||||
|
||||
Check the https://docs.jboss.org/author/display/WFLY8/Undertow+(web)+subsystem+configuration[Wildfly Undertow] documentation for more information on fine tuning the socket connections.
|
||||
|
||||
==== Enable SSL on a Reverse Proxy
|
||||
|
||||
Follow the documentation for your web server to enable SSL and configure reverse proxy for Keycloak.
|
||||
It is important that you make sure the web server sets the `X-Forwarded-For` and `X-Forwarded-Proto` headers on the requests made to Keycloak.
|
||||
Next you need to enable `proxy-address-forwarding` on the Keycloak http connector.
|
||||
Assuming that your reverse proxy doesn't use port 8443 for SSL you also need to configure what port http traffic is redirected to.
|
||||
|
||||
===== Configure WildFly
|
||||
|
||||
. Open `standalone/configuration/standalone.xml` in your favorite editor.
|
||||
|
||||
. First add `proxy-address-forwarding` and `redirect-socket` to the `http-listener` element:
|
||||
|
||||
[source]
|
||||
----
|
||||
<subsystem xmlns="urn:jboss:domain:undertow:1.1">
|
||||
...
|
||||
<http-listener name="default" socket-binding="http"
|
||||
proxy-address-forwarding="true" redirect-socket="proxy-https"/>
|
||||
...
|
||||
</subsystem>
|
||||
----
|
||||
|
||||
Then add a new `socket-binding` element to the `socket-binding-group` element:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
<socket-binding-group name="standard-sockets" default-interface="public"
|
||||
port-offset="${jboss.socket.binding.port-offset:0}">
|
||||
...
|
||||
<socket-binding name="proxy-https" port="443"/>
|
||||
...
|
||||
</socket-binding-group>
|
||||
----
|
||||
|
||||
Check the https://docs.jboss.org/author/display/WFLY8/Undertow+(web)+subsystem+configuration[WildFly] documentation for more information.
|
||||
|
||||
== Keycloak server in Domain Mode
|
||||
|
||||
In domain mode, you start the server with the "domain" command instead of the "standalone" command.
|
||||
In this case, the Keycloak subsystem is defined in domain/configuration/domain.xml instead of standalone/configuration.standalone.xml.
|
||||
Inside domain.xml, you will see more than one profile.
|
||||
The Keycloak subsystem is defined for all initial profiles.
|
||||
|
||||
THe server is also added to server profiles.
|
||||
By default two servers are started in the main-server-group which uses the full profile.
|
||||
|
||||
You need to make sure `domain/servers/SERVER NAME/configuration` is identical for all servers in a group.
|
||||
|
||||
To deploy custom providers and themes you should deploys these as modules and make sure the modules are available to all servers in the group.
|
||||
See <<_providers,Providers>> and <<_themes,Themes>> sections for more information on how to do this.
|
||||
|
||||
== Installing Keycloak Server as Root Context
|
||||
|
||||
The Keycloak server can be installed as the default web application.
|
||||
In doing so, the server can be referenced at `http://mydomain.com/` instead of `http://mydomain.com/auth`.
|
||||
|
||||
To do this, add the `default-web-module` attribute in the Undertow subystem in standalone.xml.
|
||||
|
||||
[source]
|
||||
----
|
||||
|
||||
<subsystem xmlns="urn:jboss:domain:undertow:2.0">
|
||||
<server name="default-server">
|
||||
<host name="default-host" alias="localhost" default-web-module="keycloak-server.war">
|
||||
<location name="/" handler="welcome-content"/>
|
||||
</host>
|
||||
----
|
||||
|
||||
`keycloak-server.war` is the runtime name of the Keycloak server application.
|
||||
Note that the WAR file does not exist as a file.
|
||||
If its name changes (ie. `keycloak-server.war`) in the future, find its new name from the Keycloak log entry with `runtime-name:`.
|
||||
|
||||
|
||||
|
||||
NOTE: If you have run your server before altering the root context, your database will contain references to the old /auth context. Your clients may also have incorrect references.
|
||||
To fix this on the server side, you will need to export your database to json, make corrections, and then import.
|
||||
Client-side `keycloak.json` files will need to be updated manually as well.
|