more
This commit is contained in:
Bill Burke
parent
a0bc94c1b3
commit
39b2559e64
9 changed files with 675 additions and 633 deletions
|
|
@ -5,9 +5,11 @@
|
||||||
|
|
||||||
. link:topics/preface.adoc[Preface]
|
. link:topics/preface.adoc[Preface]
|
||||||
. link:topics/overview.adoc[Overview]
|
. link:topics/overview.adoc[Overview]
|
||||||
. link:topics/system-requirements.adoc[System Requirements]
|
. link:topics/installation.adoc[Installation]
|
||||||
. link:topics/installation.adoc[Installation and Configuration of Keycloak Server]
|
.. link:topics/installation/system-requirements.adoc[System Requirements]
|
||||||
. link:topics/openshift.adoc[Running Keycloak Server on OpenShift]
|
{% if community %}.. link:topics/installation/distribution-files-community.adoc[Installing Distribution Files] {% endif %}
|
||||||
|
{% if product %}.. link:topics/installation/distribution-files-product.adoc[Installing Distribution Files] {% endif %}
|
||||||
|
.. link:topics/openshift.adoc[Installing on OpenShift]
|
||||||
. link:topics/cache.adoc[Server Cache]
|
. link:topics/cache.adoc[Server Cache]
|
||||||
. link:topics/clustering.adoc[Clustering]
|
. link:topics/clustering.adoc[Clustering]
|
||||||
. link:topics/proxy.adoc[Keycloak Security Proxy]
|
. link:topics/proxy.adoc[Keycloak Security Proxy]
|
||||||
|
|
|
||||||
|
|
@ -9,8 +9,11 @@
|
||||||
"splitter"
|
"splitter"
|
||||||
],
|
],
|
||||||
"variables": {
|
"variables": {
|
||||||
|
"community": "true",
|
||||||
|
"product": "false",
|
||||||
"project": {
|
"project": {
|
||||||
"name": "Keycloak"
|
"name": "Keycloak",
|
||||||
|
"version": "1.9.3.Final-SNAPSHOT"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
@ -1,610 +1,5 @@
|
||||||
[[_server_installation]]
|
= Installation
|
||||||
|
|
||||||
= Installation and Configuration of Keycloak Server
|
This chapter reviews what binaries you need to install to run the {{book.project.name}} Server on a specific machine.
|
||||||
|
It describes the directory structure and files of the distribution. Finally, it describes how to install {{book.project.name}}
|
||||||
== Installation
|
on the cloud if you prefer that type of deployment.
|
||||||
|
|
||||||
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.
|
|
||||||
24
topics/installation/distribution-files-community.adoc
Executable file
24
topics/installation/distribution-files-community.adoc
Executable file
|
|
@ -0,0 +1,24 @@
|
||||||
|
= Installing Distribution Files
|
||||||
|
|
||||||
|
The Keycloak Server has three downloadable distributions:
|
||||||
|
|
||||||
|
* +keycloak-{{book.project.version}}.[zip|tar.gz]+
|
||||||
|
* +keycloak-overlay-{{book.project.version}}.[zip|tar.gz]+
|
||||||
|
* +keycloak-demo-{{book.project.version}}.[zip|tar.gz]+
|
||||||
|
|
||||||
|
The +keycloak-{{book.project.version}}.[zip|tar.gz]+ file is the server only distribution. It contains nothing other than the scripts and binaries
|
||||||
|
to run the Keycloak Server.
|
||||||
|
|
||||||
|
The +keycloak-overlay-{{book.project.version}}.[zip|tar.gz]+ file is a Wildfly Service Pack that allows you to install Keycloak Server on top of an existing
|
||||||
|
Wildfly or JBoss EAP distribution. We suggest that you do not use this file unless you want to install on top of a JBoss EAP distribution.
|
||||||
|
|
||||||
|
The +keycloak-demo-{{book.project.version}}.[zip|tar.gz]+ contains a the server binaries, all documentation and all examples. It is preconfigured with both the
|
||||||
|
OIDC and SAML client application adapters and can deploy any of the distribution examples out of the box with no configuration. This distribution is only
|
||||||
|
recommended for those that want to test drive Keycloak.
|
||||||
|
|
||||||
|
To unpack of these files run the +unzip+ or +gunzip+ and +tar+ utilities.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
15
topics/installation/distribution-files-product.adoc
Executable file
15
topics/installation/distribution-files-product.adoc
Executable file
|
|
@ -0,0 +1,15 @@
|
||||||
|
= Installing Distribution Files
|
||||||
|
|
||||||
|
The Keycloak Server is contained in one distribution file:
|
||||||
|
|
||||||
|
* +RH-SSO-{{book.project.version}}.[zip|tar.gz]+
|
||||||
|
|
||||||
|
The +RH-SSO-{{book.project.version}}.[zip|tar.gz]+ file is the server only distribution. It contains nothing other than the scripts and binaries
|
||||||
|
to run the Keycloak Server.
|
||||||
|
|
||||||
|
To unpack of these files run the +unzip+ or +gunzip+ and +tar+ utilities.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -1,11 +0,0 @@
|
||||||
= Getting Distribution Files
|
|
||||||
|
|
||||||
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]
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
13
topics/installation/system-requirements.adoc
Executable file
13
topics/installation/system-requirements.adoc
Executable file
|
|
@ -0,0 +1,13 @@
|
||||||
|
= System Requirements
|
||||||
|
|
||||||
|
These are the requirements to run the {{book.project.name}} authentication server:
|
||||||
|
|
||||||
|
* Can run on any operating system that runs Java
|
||||||
|
* Java 8 JDK
|
||||||
|
* zip or gzip and tar
|
||||||
|
* Network multicast support if you are clustering {{book.project.name}}.
|
||||||
|
* At least 512M of RAM
|
||||||
|
* At least 1G of diskspace
|
||||||
|
|
||||||
|
{{book.project.name}} can be clustered without multicast, but this requires a bunch of configuration changes. Please see
|
||||||
|
the <<../clustering.adoc#,clustering>> section of this guide for more information.
|
||||||
610
topics/old-installation.adoc
Executable file
610
topics/old-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.
|
||||||
|
|
@ -1,9 +0,0 @@
|
||||||
= System Requirements
|
|
||||||
|
|
||||||
These are the requirements to run the {{book.project.name}} authentication server:
|
|
||||||
|
|
||||||
* Java 8 JDK
|
|
||||||
* Network multicast support if you clustering {{book.project.name}}.
|
|
||||||
|
|
||||||
{{book.project.name}} can be clustered without multicast, but this requires a bunch of configuration changes. Please see
|
|
||||||
the <<_clustering,clustering>> section of this guide for more information.
|
|
||||||
Loading…
Reference in a new issue