[[_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>>). . 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=/` 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=/core-service=management/security-realm=UndertowRealm/server-identity=ssl:add(keystore-path=keycloak.jks, keystore-relative-to=jboss.domain.config.dir, keystore-password=secret) ---- + In the standalone or host configuration file, the `security-realms` element should look like this: + [source,xml] ---- ---- . 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=/`. + 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+"] ---- ... ----