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/overview.adoc[Overview]
|
||||
. link:topics/system-requirements.adoc[System Requirements]
|
||||
. link:topics/installation.adoc[Installation and Configuration of Keycloak Server]
|
||||
. link:topics/openshift.adoc[Running Keycloak Server on OpenShift]
|
||||
. link:topics/installation.adoc[Installation]
|
||||
.. link:topics/installation/system-requirements.adoc[System Requirements]
|
||||
{% 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/clustering.adoc[Clustering]
|
||||
. link:topics/proxy.adoc[Keycloak Security Proxy]
|
||||
|
|
|
|||
|
|
@ -9,8 +9,11 @@
|
|||
"splitter"
|
||||
],
|
||||
"variables": {
|
||||
"community": "true",
|
||||
"product": "false",
|
||||
"project": {
|
||||
"name": "Keycloak"
|
||||
"name": "Keycloak",
|
||||
"version": "1.9.3.Final-SNAPSHOT"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -1,610 +1,5 @@
|
|||
[[_server_installation]]
|
||||
= 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.
|
||||
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}}
|
||||
on the cloud if you prefer that type of deployment.
|
||||
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