I’m writing a tutorial on how to make Single Sign on work with the Play Framework in Scala and how to integrate Silhouette authentication library with Keycloak. (this isn’t published yet though) One part of that tutorial is spinning up a Keycloak server you can run your app against. These are the minimal steps required to get something running.
- Spin up a keycloak server in a local docker instance
- Add a client app with a secret
- Add a test user with a username/password combo
1. Start and configure a local Keycloak server for testing.
The following command requires docker to run. This will start Keycloak locally, listening on port 8080 with the username and password of admin/admin. It uses an InMemory database so be aware that changes are lost when the container is stopped. For this tutorial however this is acceptable.
docker run -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -e DB_VENDOR=H2 -p 8080:8080 -p 9990:9990 jboss/keycloakOnce it’s running you should be able to navigate to http://localhost:8080 to access the main page (shown below)
Click on the “Administration Console” link above and use the username admin and the password admin to log in. Below is a screenshot of the main screen “The Master Realm”. It’s too much work for me to explain how Keycloak and Realms work except to say that one Keycloak instance can manage dozens of upstream and downstream auth providers and applications and each realm is a segregation of users and permissions in some way. The master realm typically controls the auth for the Keycloak instance itself and each app would have it’s own realm. For this tutorial we are going to breeze over this and do the minimum.
Click on “Clients” in the left hand navigation menu. A client is an application that can use the Realm. Think of Keycloak as a database of users. Clients are programs that login to query it. (So clients are user accounts to log in to the “user database” where users are just data.) We’re going to write a Keycloak client app in the next tutorial below so we need to tell Keycloak who we are and how we’re going to connect. Click on Clients and then click Create in the top right corner of the table. See the image below.
Here I’ve entered the ClientId. Make a note of this! I’ve also said what the Root URL for the project is, and for Play applications it’s port 9000 by default. Keycloak needs this because it checks “referers” [sic] and redirects users to and from our site. Therefore it needs to be http://localhost:9000 if that is where your app is running and you’re following my Scala guide. Once you save this new client you will be taken to a screen for configuring it (shown below):
When this page opens you will not have a “Credentials” tab but you need one! You should change the Access type from public to confidential and hit save. Then the credentials tab will appear. The credential page is shown below:
On the credentials tab we can now see the secret. Make a note of this secret.
Now we have a working Keycloak server with a clientId and secret that enables another program to login to this server. What we need next is an actual user account we can use for testing and logging into the app we write ourselves. Lets click on the “Users” tab (Under Manage) and click “Add User” in the top right corner of the users table.
You can fill this form in however you want, I don’t really care, but make a note of the username and email! Save the user. Then go to the Credentials tab shown below
First turn off the temporary option and then enter a password. I recommend “pwd” but whatever you choose make a note of it. Then click Reset Password and confirm the prompt when it opens.
Now you’ve done this, I highly recommend you put an email address against the admin user. It can lead some people who are both configuring the app and testing it at the same time to run into some confusion and doing this helps. For the Scala tutorial you might want to create a user called Sinclair who has the exact email “sinclair@example.com” in order to make the Scala example work right-out-of-the-box but this isn’t that important.
Your system is now minimally functional for the Scala tutorial. I haven’t written this tutorial yet.. so please wait.. If you wander off and change other settings do remember all those settings are lost when you stop the container! When we’ve finished setting up Keycloak we need to take away some details from it to use in our application. So far we should have:
- A client id (keycloak-seed)
- A client secret (different for everyone, mine is 45cb055e-d93c-4a14-a4ce-43c2bc0c1414)
- A user account with a username name and password (mine are sinclair/pwd)
What we need are the special keycloak urls to connect to. Click on Realm under Configure to go back to the main page.
See this link next to Endpoints that says OpenId Endpoint Configuration. Click it and read the json (use a formatter to help you if your browser sucks)
We need and care about the following URLs that we’re going to use in our app:
authorization_endpoint: http://localhost:8080/auth/realms/master/protocol/openid-connect/auth
token_endpoint: http://localhost:8080/auth/realms/master/protocol/openid-connect/token
userinfo_endpoint: http://localhost:8080/auth/realms/master/protocol/openid-connect/userinfo
end_session_endpoint: http://localhost:8080/auth/realms/master/protocol/openid-connect/logoutWe now have a running server and the following information:
- Authorization Endpoint
- Token Endpoint
- UserInfo Endpoint
- End Session Endpoint
- ClientId
- ClientSecret
This is everything we’re going to need in our application, so now we’re ready to move to the Scala part of my tutorial (which is not available yet but will be published soon).