keycloak-scim/server_installation/topics/network/https.adoc

[[_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>
----

For more information on configuring TLS refer to the https://docs.wildfly.org/25/WildFly_Elytron_Security.html#configure-ssltls[WildFly documentation].