167 lines
7.2 KiB
Text
167 lines
7.2 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.x.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 where you are deploying the {project_name} Server.
|
|
|
|
====== 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
|
|
----
|
|
|
|
When you see the question `What is your first and last name ?`, supply the DNS name of the machine where you are installing the server. 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]. However, you first need to use the following procedure.
|
|
|
|
.Procedure
|
|
|
|
. 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.
|
|
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 Certificate Authority (CA).
|
|
+
|
|
The CA will issue you a signed certificate and send it to you.
|
|
|
|
. Obtain and import the root certificate of the CA.
|
|
+
|
|
You can download the cert from CA (in other words: root.crt) and import as follows:
|
|
+
|
|
[source]
|
|
----
|
|
$ keytool -import -keystore keycloak.jks -file root.crt -alias root
|
|
----
|
|
|
|
. 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.
|
|
|
|
.Procedure
|
|
|
|
. Edit the _standalone.xml_, _standalone-ha.xml_, or _host.xml_ file to use the keystore and enable HTTPS.
|
|
|
|
. 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>>).
|
|
|
|
. Configure the keystore using the CLI:
|
|
+
|
|
[source]
|
|
----
|
|
$ /subsystem=elytron/key-store=httpsKS:add(relative-to=jboss.server.config.dir,path=keycloak.jks,credential-reference={clear-text=secret},type=JKS)
|
|
$ /subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS,credential-reference={clear-text=secret})
|
|
$ /subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM,protocols=[\"TLSv1.3\"])
|
|
----
|
|
+
|
|
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). Here is an example, which you would repeat for each host:
|
|
+
|
|
[source]
|
|
----
|
|
$ /host=<host_name>/subsystem=elytron/key-store=httpsKS:add(relative-to=jboss.server.config.dir,path=keycloak.jks,credential-reference={clear-text=secret},type=JKS)
|
|
----
|
|
+
|
|
. Modify the `https-listener` to use the `server-ssl-context`previously created:
|
|
+
|
|
[source]
|
|
----
|
|
$ /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=httpsSSC)
|
|
----
|
|
+
|
|
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" ssl-context="httpsSSC"/>
|
|
...
|
|
</subsystem>
|
|
----
|
|
|
|
|