Monday, 26 October 2015

Getting started with Keycloak - Installing the Keycloak Server

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.sh
or 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.xml
or 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 keycloak
This 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:8080
This 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-cartridge
OpenShift 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.

18 comments:

  1. Nice post.
    The Next Steps section is a very useful addition as usually the next thing i want to know after i get something up and running is how much work would i need to do before i can get into production.

    ReplyDelete
  2. Hi, I am planning set Keycloak 1.6.0.Final with existing Wildfly 9.0.1.Final, but my Wildfly is set in domain mode, now is possible only standalone Wildfly mode? Do you plan add domain mode and when? Thanks.

    ReplyDelete
    Replies
    1. https://issues.jboss.org/browse/KEYCLOAK-2037

      Delete
  3. I tried the keycloak and so far I'm very happy with it. Thanks. I read, that ruby support is targeted and I found a thread on stackoverflow (https://stackoverflow.com/questions/32585792/implementing-single-sign-on-with-keycloak/) about ruby integration with keycloak, maybe it is useful for you.

    Thanks.

    ReplyDelete
    Replies
    1. That looks interesting. I'd be interested in finding out if you get it working with Ruby.

      Delete
  4. I think a JSF example would be very nice.

    ReplyDelete
    Replies
    1. Maybe something like: http://picketlink.org/gettingstarted/first_cdi_app/
      I know there is the demo-template/third-party-cdi. Maybe you can use this as a basis with some explantion.

      Delete
  5. Hi, I already installed keycloak with PostgreSQL. Is there anyway to configure it to install it in a another schema than public?

    ReplyDelete
    Replies
    1. http://keycloak.github.io/docs/userguide/keycloak-server/html/server-installation.html#d4e136 - databaseSchema

      Delete
    2. Sorry, it's the schema property you want to set, not databaseSchema.

      Delete
  6. Small typo in the section that shows how to run on a different port. The '8080' should be '8180' if the offset is 100.

    Run Keycloak on a different port - to use port 8080 instead run
    bin/standalone.sh -Djboss.socket.binding.port-offset=100

    ReplyDelete
  7. Can anybody help with the command to stop the standalone instance. i am not finding it anywhere.

    ReplyDelete
    Replies
    1. Same as how you stop any process (ctrl+C or kill). You can also use jboss-cli do stop it (take a look at https://docs.jboss.org/author/display/WFLY10/Suspend,+Resume+and+Graceful+shutdown)

      Delete
  8. with docker I have this error :

    WFLYSRV0073: Invalid option '--name'

    ReplyDelete
    Replies
    1. Just drop the "--name" as that shouldn't be there.

      Delete
  9. Is there a way to generate a randomized admin password

    ReplyDelete
    Replies
    1. There is no longer a default admin account instead use the add-user-keycloak script to add the initial user. You can easily generate a password to use with this script.

      Delete

Please only add comments directly associated with the post. For general questions use the Keycloak user mailing list.