keycloak-scim/topics/network/https.adoc

=== Setting up HTTPS/SSL

WARNING:  {{book.project.name}} is not set up by default to handle SSL/HTTPS.
          It is highly recommended that you either enable SSL on the {{book.project.name}} server itself or on a reverse proxy in front of the {{book.project.name}} server.

{{book.project.name}} can run out of the box without SSL/HTTPS 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 {{book.project.name}} out of the box via a non-private IP address you will get an error.

This default behavior is defined by the SSL/HTTPS mode of each {{book.project.name}} realm.  This is discussed in more detail in the
link:{{book.adminguide.link}}[{{book.adminguide.name}}], but let's give some context and a brief overview of these modes.

external::
  {{book.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 try to access {{book.project.name}} from a non-private IP adress you will get an error.

none::
  {{book.project.name}} does not require SSL.  This should really only be used in development when you are playing around with things.

all::
  {{book.project.name}} requires SSL for all IP addresses.

The SSL mode for each realm can be configured in the {{book.project.name}} admin console.

==== Enable HTTPS/SSL with a Reverse Proxy

It is general best practice that {{book.project.name}} will be run in a cluster with a reverse proxy or hardware load balancer
setting in front of {{book.project.name}} server instances.

To enable SSL/HTTPS in this deployment scenario, it is important that you make sure your reverse proxy sets the `X-Forwarded-For` and `X-Forwarded-Proto` headers on the requests made to {{book.project.name}}.
To make sure that {{book.project.name}} honors these headers, you need to enable the `proxy-address-forwarding` setting of the {{book.project.name}} http connector in {{book.project.name}} configuration.
Assuming that your reverse proxy doesn't use port 8443 for SSL you also need to configure what port http traffic is redirected to.

. Open _standalone.xml_, _standalone-ha.xml_, or _domain.xml_ file (depends on your <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>).

. Add `proxy-address-forwarding` and `redirect-socket` to the `http-listener` element:

[source]
----
<subsystem xmlns="urn:jboss:domain:undertow:3.0">
    ...
    <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>
----

Also remember that when running in <<fake/../../operating-mode/domain.adoc#_domain-mode,domain mode>> what `socket-binding-group`
you modify depends on how you have your server groups configured.

==== Enabling SSL/HTTPS for the {{book.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 {{book.project.name}} server.  This involves

. Obtaining or generating a keystore that contains the private key and certificate for SSL/HTTP traffic
. Configuring the {{book.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 Keycloak Server to.

====== Self Signed Certificate

In development, you will probably not have a third party signed certificate available to test a {{book.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://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 {{book.project.name}} to Use the Keystore

Now that you have a Java keystore with the appropriate certificates, you need to configure your {{book.project.name}} installation to use it.
First step is to move the keystore file to the _configuration/_ directory of your deployment and to edit the _standalone.xml_, _standalone-ha.xml_ or _domain.xml_ file to use
the keystore and enable HTTPS.  (See <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>).

In the standalone or domain configuration file, search for the `security-realms` element and 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:`) and add:

[source]
----
<subsystem xmlns="urn:jboss:domain:undertow:3.0">
   <buffer-cache name="default"/>
   <server name="default-server">
      <https-listener name="https" socket-binding="https" security-realm="UndertowRealm"/>
   ...
</subsystem>
----