Keycloak on Openshift

Get started with Keycloak on Openshift

Before you start

Install Red Hat Code Ready Containers and follow the steps in the documentation to install a local OpenShift cluster.

Make sure the cluster is functional by executing the following command:

crc status

If everything is OK you should see an output similar to this:

CRC VM:          Running
OpenShift:       Running
...

Log in as the user developer:

oc login -u developer -p developer

For this guide, we are going to create a new project called keycloak. For that, execute the following command:

oc new-project keycloak

Run Keycloak

To spin up a Keycloak server in your project, execute the following command:

oc process -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/latest/openshift-examples/keycloak.yaml \
    -p KEYCLOAK_USER=admin \
    -p KEYCLOAK_PASSWORD=admin \
    -p NAMESPACE=keycloak \
| oc create -f -

Once the command above completes you should see a message similar to this:

service/secure-keycloak created
route.route.openshift.io/keycloak created
deploymentconfig.apps.openshift.io/keycloak created.

At this point, OpenShift is going to provision a Keycloak pod and related resources. As part of the process, OpenShift will try to pull the Keycloak server image and this might take some time depending on your network connections in case the image is not available yet.

To make sure Keycloak is provisioned, execute the following command:

oc get pods

After a while you should see a message similar to this when the pod is ready:

NAME                READY     STATUS      RESTARTS   AGE
keycloak-1-deploy   0/1       Completed   0          1h
keycloak-1-l9kdx    1/1       Running     0          1h

Once the server is provisioned, run the following command to find out the URLs of Keycloak:

KEYCLOAK_URL=https://$(oc get route keycloak --template='{{ .spec.host }}')/auth &&
echo "" &&
echo "Keycloak:                 $KEYCLOAK_URL" &&
echo "Keycloak Admin Console:   $KEYCLOAK_URL/admin" &&
echo "Keycloak Account Console: $KEYCLOAK_URL/realms/myrealm/account" &&
echo ""

Remember these URLs as you will need them throughout this guide. The URL for the account console won’t work right now as you will need to create the realm first.

Login to the admin console

Go to the Keycloak Admin Console and login with the username and password you created earlier.

Create a realm

A realm in Keycloak is the equivalent of a tenant. It allows creating isolated groups of applications and users. By default there is a a single realm in Keycloak called master. This is dedicated to manage Keycloak and should not be used for your own applications.

Let’s create our first realm.

  1. Open the Keycloak Admin Console

  2. Hover the mouse over the dropdown in the top-left corner where it says Master, then click on Add realm

  3. Fill in the form with the following values:

    • Name: myrealm

  4. Click Create

Add Realm

Create a user

Initially there are no users in a new realm, so let’s create one:

  1. Open the Keycloak Admin Console

  2. Click Users (left-hand menu)

    • Click Add user (top-right corner of table)

  3. Fill in the form with the following values:

    • Username: myuser

    • First Name: Your first name

    • Last Name: Your last name

  4. Click Save

Add User

The user will need an initial password set to be able to login. To do this:

  1. Click Credentials (top of the page)

  2. Fill in the Set Password form with a password

  3. Click ON next to Temporary to prevent having to update password on first login

Set Password

Login to account console

Let’s now try to login to the account console to verify the user is configured correctly.

  1. Open the Keycloak Account Console

  2. Login with myuser and the password you created earlier

You should now be logged-in to the account console where users can manage their accounts.

Keycloak Account Console

Secure your first app

Let’s try to secure our first application. First step is to register this application with your Keycloak instance:

  1. Open the Keycloak Admin Console

  2. Click 'Clients'

  3. Fill in the form with the following values:

  4. Click Save

Add Client

To make it easy for you we have a SPA testing application available on the Keycloak website.

Open https://www.keycloak.org/app/. Change Keycloak URL to the URL of your Keycloak instance. Click Save.

Now you can click Sign in to authenticate to this application using the Keycloak server you started earlier.

Next

Before you go and run Keycloak in production there are a few more things that you will want to do, including:

  • Switch to a production ready database such as PostgreSQL

  • Configure SSL with your own certificates

  • Switch the admin password to a more secure password

For more information check out the Keycloak Documentation.