176 lines
7.6 KiB
Text
176 lines
7.6 KiB
Text
[[_setting_up_ssl]]
|
|
=== Setting up HTTPS/SSL
|
|
|
|
WARNING: {project_name} is not set up by default to handle SSL/HTTPS.
|
|
It is highly recommended that you either enable SSL on the {project_name} server itself or on a reverse proxy in front of the {project_name} server.
|
|
|
|
This default behavior is defined by the SSL/HTTPS mode of each {project_name} realm. This is discussed in more detail in the
|
|
link:{adminguide_link}[{adminguide_name}], but let's give some context and a brief overview of these modes.
|
|
|
|
external requests::
|
|
{project_name} 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 don't have SSL/HTTPS configured on the server or you try to access {project_name} over HTTP from a non-private IP adress you will get an error.
|
|
|
|
none::
|
|
{project_name} does not require SSL. This should really only be used in development when you are playing around with things.
|
|
|
|
all requests::
|
|
{project_name} requires SSL for all IP addresses.
|
|
|
|
The SSL mode for each realm can be configured in the {project_name} admin console.
|
|
|
|
==== Enabling SSL/HTTPS for the {project_name} Server
|
|
|
|
If you are not using a reverse proxy or load balancer to handle HTTPS traffic for you, you'll need to enable HTTPS
|
|
for the {project_name} server. This involves
|
|
|
|
. Obtaining or generating a keystore that contains the private key and certificate for SSL/HTTP traffic
|
|
. Configuring the {project_name} server to use this keypair and certificate.
|
|
|
|
===== 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 {project_name} Server to.
|
|
|
|
====== Self Signed Certificate
|
|
|
|
In development, you will probably not have a third party signed certificate available to test a {project_name} deployment so you'll need to generate a self-signed one
|
|
using 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://www.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
|
|
29RvyeUVe+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 to import your new CA generated certificate to your keystore:
|
|
|
|
[source]
|
|
----
|
|
|
|
$ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificate.cer
|
|
----
|
|
|
|
===== Configure {project_name} to Use the Keystore
|
|
|
|
Now that you have a Java keystore with the appropriate certificates, you need to configure your {project_name} installation to use it.
|
|
First, you must edit the _standalone.xml_, _standalone-ha.xml_, or _host.xml_ file to use the keystore and enable HTTPS. You may then either move the keystore file to the _configuration/_ directory of your deployment or the file in a location you choose and provide an absolute path to it. If you are using absolute paths, remove the optional `relative-to` parameter from your configuration (See <<_operating-mode, operating mode>>).
|
|
|
|
Add the new `security-realm` element using the CLI:
|
|
|
|
[source]
|
|
|
|
----
|
|
$ /core-service=management/security-realm=UndertowRealm:add()
|
|
|
|
$ /core-service=management/security-realm=UndertowRealm/server-identity=ssl:add(keystore-path=keycloak.jks, keystore-relative-to=jboss.server.config.dir, keystore-password=secret)
|
|
----
|
|
|
|
If using domain mode, the commands should be executed in every host using the `/host=<host_name>/` prefix (in order to create the `security-realm` in all of them), like this, which you would repeat for each host:
|
|
|
|
[source]
|
|
----
|
|
$ /host=<host_name>/core-service=management/security-realm=UndertowRealm/server-identity=ssl:add(keystore-path=keycloak.jks, keystore-relative-to=jboss.server.config.dir, keystore-password=secret)
|
|
----
|
|
|
|
In the standalone or host configuration file, the `security-realms` element should look like this:
|
|
|
|
[source,xml]
|
|
----
|
|
|
|
<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>
|
|
----
|
|
|
|
Next, in the standalone or each domain configuration file, search for any instances of `security-realm`. Modify the `https-listener` to use the created realm:
|
|
|
|
[source]
|
|
----
|
|
$ /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=security-realm, value=UndertowRealm)
|
|
----
|
|
|
|
If using domain mode, prefix the command with the profile that is being used with: `/profile=<profile_name>/`.
|
|
|
|
The resulting element, `server name="default-server"`, which is a child element of `subsystem xmlns="{subsystem_undertow_xml_urn}"`, should contain the following stanza:
|
|
|
|
[source,xml,subs="attributes+"]
|
|
----
|
|
<subsystem xmlns="{subsystem_undertow_xml_urn}">
|
|
<buffer-cache name="default"/>
|
|
<server name="default-server">
|
|
<https-listener name="https" socket-binding="https" security-realm="UndertowRealm"/>
|
|
...
|
|
</subsystem>
|
|
----
|
|
|
|
|