This is the first post in a series of getting started guides. In this first post we will look at how to install the Keycloak server. Next time we will look at how to create and secure a simple REST service using Keycloak. Then we'll look at how to create a simple HTML5 application that adds sign on using Keycloak and invokes the REST service. After that we'll see what guides I feel like writing (or what guides are requested by the community), but a few topics I'd like to visit include configuring Keycloak, enabling social login and hybrid mobile application. I'd also like to deploy the basic REST service and HTML5 application using Docker as well as with OpenShift.
If you have any problems getting the steps in this guide working or you have some suggestions to improvements feel free to add a comment below. Also, if you have any requests for future guides add a comment about that.
Keycloak comes in a few different flavors. There's a standalone server that can be installed by simply extracting an archive. You can also start Keycloak on Docker or on OpenShift. You can also install Keycloak into an existing WildFly server.
Standalone installation
The simplest way to get Keycloak up and running unless you're using Docker or OpenShift is to use the standalone bundle. This is a simple archive (zip or tar.gz) that is installed by simply extracting it into a directory. All you need in advance is Java 8 installed (Java 7 works as well, but we'll soon require Java 8 for the server).
To install the archive first to go downloads and download either
keycloak-1.6.0.Final.tar.gz or
keycloak-1.6.0.Final.zip.
Once the download is completed extract this into a directory somewhere.
To start the server open the directory you extracted Keycloak into and run
keycloak-1.6.0.Final/bin/standalone.shor if you are using Windows
keycloak-1.6.0.Final/bin/standalone.bat
You should now have the Keycloak server up and running. To check that it's working open http://localhost:8080/auth. Then click on Admin Console the username is admin and password is admin. You'll be asked to change the default password when you login.
One thing to note is that Keycloak runs by default on port 8080. For production this is generally not a problem as you should run Keycloak on a dedicated machine. However, for development you may quite likely want to run another web server for your applications which often use port 8080 as well. You have a few choices in this case:
-
Run Keycloak on a different port - to use port 8080 instead run
bin/standalone.sh -Djboss.socket.binding.port-offset=100
-
Run Keycloak on another hostname - to expose on 127.0.0.2 (you can also add "localhost2" entry in hosts file for convenience) run
bin/standalone.sh -b 127.0.0.2 -bmanagement=127.0.0.2
- Run Keycloak inside WildFly - Keycloak requires a specific version of WildFly, but if that works you can deploy both Keycloak server and your JavaEE apps to the same WildFly instance.
- Run Keycloak on a separate machine or VM
- Run Keycloak on Docker
- Run Keycloak on OpenShift
Install into existing WildFly
Installing Keycloak into an existing WildFly installation can be convenient for JavaEE developers as you will have everything available in one process. It's also possible to do this in production, but we generally recommend having a separate standalone installation of Keycloak. Having it as a separate instance makes it easier to upgrade and scale. Keycloak also requires a specific version of Wildfly (for 1.6.0.Final Keycloak requires WildFly 9.0.1.Final). Finally, with regards to security it's a good idea to isolate your authentication server from your applications.
To install Keycloak into Wildfly you should first have WildFly 9.0.1.Final installed. Then you should download
keycloak-overlay-1.6.0.Final.tar.gz or
keycloak-overlay-1.6.0.Final.zip.
Once you've downloaded the Keycloak overlay archive simply extract this into the WildFly home directory.
To start WildFly with Keycloak run
bin/standalone.sh --server-config=standalone-keycloak.xmlor if you are on Windows
bin/standalone.bat --server-config=standalone-keycloak.xml.
You should now have Keycloak server up and running. To check that it's working open http://localhost:8080/auth. Then click on Admin Console the username is admin and password is admin. You'll be asked to change the default password when you login.
Install on Docker
To start Keycloak on Docker simply run
docker run jboss/keycloak --name keycloakThis will download the Keycloak image from Docker Hub and start Keycloak and name the container keycloak. To find the IP address of the Docker container you can run
docker inspect --format='.NetworkSettings.IPAddress' keycloak
You can also expose Keycloak on localhost if you want. To do this run
docker run jboss/keycloak --name keycloak -p 8080:8080This will expose Keycloak on
localhost:8080. If you want to expose Keycloak on a different port replace the first 8080
with the port you want to expose it on.
You should now have Keycloak server up and running. To check that it's working open http://DOCKER-IP:8080/auth or
http://localhost:8080/auth if you exposed it on localhost with -p.
Then click on Admin Console the username is admin and password is admin. You'll be asked to
change the default password when you login.
Install on OpenShift
This one is nice and simple. Assuming you have OpenShift CLI tools installed just run
rhc app create keycloak http://cartreflect-claytondev.rhcloud.com/github/keycloak/openshift-keycloak-cartridgeOpenShift will start the Keycloak gear for you and output the URL you can access Keycloak on. You'll even have https already setup. You can also start it from the OpenShift web console, simply use
http://cartreflect-claytondev.rhcloud.com/github/keycloak/openshift-keycloak-cartridge as the cartridge
url.
Next steps
Once you have Keycloak installed there's a few things you should do. At least you should do these prior to going to production. This includes:
- Database configuration - by default Keycloak uses an embedded H2 database. For production we recommend we you replace this with a standalone database. We support MySQL, PostgreSQL, Oracle and a few more. To configure the database refer to the Keycloak user guide.
- SSL configuration - to prevent exposing credentials and tokens Keycloak requires all communication to be done over HTTPS. You should also make sure that at least the services you protect with Keycloak are invoked over HTTPS. For details on how to enable SSL refer to the Keycloak user guide.
- Clustering - to increase availability and scalability we recommend running Keycloak in a cluster with at least two nodes. For details on how to enable clustering refer to the Keycloak user guide.
- Change admin password - Keycloak requests that you change the default admin password when you first login. Make sure this is done before exposing Keycloak outside of your local network.
