Local Keycloaking

So you are new to Keycloak and you have to get it running quickly. You first have to figure out what it is and then how to use it on your machine. This is my tail of getting to know Keycloak from the local setup aspect.

Go get the download.

Now, I am working on a MacBook Pro so everything I do in this article will be from that aspect. Once, you get the tar file downloaded simply double click on it and will be extracted for you. It is kind of like magic, but not.

Now get your terminal window fired up and navigate to the folder that just got extracted. Do an ‘ls’ in the directory and you should have something like this.

Now to start the Keycloak local server, just enter ‘bin/standalone.sh’

When it is done you should be able to open a browser and navigate to ‘http://localhost:8080/auth’

The very first thing you need to do is create your admin user. Since this a local development setup I use the old trusty admin — admin. SO enter username = ‘admin’ and then both password fields = ‘admin’ and you should see a message that the user was created.

Next click the link Administration Console and log in. This will take you to the ‘Master’ realm. You can think of the Master realm as a galaxy and think of Keycloak as the universe it lives in. As a general rule to live by don’t mess with the Master realm.

The first thing we need to do now is add a new realm and call it sample-api.

Select ‘Create’ and you should be taken to the sample-api realm settings page.

Next select ‘Clients’ from the left menu. This is a list of the default clients. Select “Create” from the right side of the grid.

I just went simple with sample-api for the name and for future use Root URL = ‘http://localhost:5000’. Select ‘create’ and you will be taken to the client settings for sample-api.

Select ‘save’. Now, select the newly created ‘Credentials’ tab. Remember this spot you will need this code a little bit later.

Next select the ‘Roles’ tab and then click ‘Add Role’

Add an ‘admin’ role and repeat the process to add a ‘user’ role.

Next, select ‘Roles’ from the lefthand menu and then ‘Add Role’

Add the ‘admin’ role and the ‘user’ role.

Now from the lefthand menu select ‘Users’ and then ‘Add User’

Make sure you flip the ‘Email Verified’ switch and then select ‘Save’. Next select the ‘Role Mappings’ tab. Select ‘sample-api’ from the ‘Client Roles’ dropdown, then add the ‘users’ role to the ‘Assigned Roles’ listbox.

Select the ‘Credentials’ tab to set the password for our test users. Make sure to flip the switch ‘Temporary’ and the select ‘Set Password’

Now rinse and repeat and create ‘Api-admin’ user.

Users are setup and roles are mapped. Now select ‘Realm Settings’ from the left menu. Select ‘OpenID Endpoint Configuration’ from the ‘Endpoints’ text boxes. Copy the address for the token endpoint.

Now open postman and set it to post to the url from above. Enter in the following values for the Body. To get your client secret go back to the Keycloak admin and select ‘Clients’ from the lefthand menu the select ‘sample-api’ from the table. Next, select the ‘Credentials’ tab and copy the ‘Secret’ and put it in postman in the ‘client_secret’ value.

Once you have entered all the values click ‘Send’. Here is the sticking point if I have written this correctly and you have followed it completely then You should get a response similar to the screen shot below.

My next post will expand on this with a Node/Typescript API.