amcsi/keycloak-setup

How to set up a keycloak server and a client for it

Keycloak example

Based on this blog article: https://scalac.io/user-authentication-keycloak-1/

Requirements for keycloak server

Java 8 JDK is needed

Steps

Server

1. Run it
   1. Run bin/download-keycloak.sh to download keycloak.
   2. Run bin/start-keycloak.sh to run the keycloak server.
      1. Pass -Djboss.http.port=<port> as an argument to change the listening port from the default of 8080.
   3. Visit http://localhost:8080.
   4. Create an initial user in the left column.
   5. Enter Administration Console and log in with the user you created.
   6. You will see you are in the Master realm. Create a new, different realm, because Master is meant for super admins that have access to the panel you see, unlike regular users. You create a new realm by hovering over Master on the top left under the logo, then clicking "Add realm".
   7. Give it a name e.g. "Test", then click Create.
2. Let's create a user. Go to Users on the left menu.
   1. Click Add User
   2. Enter something for Username e.g. test.
   3. I suggest you add some Email, and First/Last names as well. These will appear in the demo frontend app after logging in.
   4. Click Save.
   5. Go to the Credentials tab.
   6. Enter a password and confirm it. Make it e.g. "pass".
   7. Turn Temporary off (that would force the user to change their password otherwise).
   8. Click "Set Password", then confirm the dialog.
3. Create a client for frontend access
   1. Go to Clients on the left.
   2. Click Create on the right.
   3. Enter a key for the client e.g. my-react-client
   4. Enter the root URL of your frontend. In this example: http://localhost:3000/.
   5. Click Save. You should be taken to the client detailed edit page.
   6. The defaults should be frontend-ready. Go to the Installation tab, select "Keycloak OIDC JSON" from the dropdown.
   7. Click Download.
   8. Move the downloaded keycloak.json file to public/ in this project. This will let keycloak know which realm and which client your frontend intends to use.

Web app

1. Run npm start to start the React App and go visit the site.
2. Go visit it.
3. Click on "secured component" to see a page that requires you to be logged in.
4. See that you are redirected to the keycloak login page. Login with your test user (username: "test", password: "pass").
5. See that you are in the /secured path and you see your user's details. Congrats!

You can refresh the page, and you'll still be logged in. No state is persisted on your webapp; instead, on each page load you get redirected to the auth server, then redirected back right away with your token.

Changing the theme

It's possible to change the theme, but you'll need to deal with using ftl templating syntax (Java FreeType). Vscode has a plugin for it.

1. Go inside the keycloak folder. Substeps are assumed to be relative to that folder.
   1. Edit standalone/configuration/standalone.xml and set these values for development to make sure there's no caching:

       <staticMaxAge>-1</staticMaxAge>
       <cacheThemes>false</cacheThemes>
       <cacheTemplates>false</cacheTemplates>
   

   3. Restart (❗) the keycloak server for the standalone.xml changes to take effect.
   4. copy themes/keycloak to e.g. themes/example. That's the theme you will need to edit.
   5. In http://localhost:8080 in your realm, go to themes and change your login theme to example. You may need to refresh the page for it to appear.
   6. Save.
   7. Logout and go to the secured page for the login prompt again, or just go to http://localhost:3000/ in a private tab.
   8. The login should look the same as before.
   9. In your theme directory, make some example changes:
      1. Make a CSS change
         1. In login/resources/css/login.css, locate .card-pf { and change the background color from #fff to #aaa (gray).
         2. Copy ../base/login/template.ftl (neighboring theme folder ❗) to login/template.ftl, and edit that file. base is the parent theme, and to make an override, you copy the file you want to override over.
      2. Make an HTML change
         1. Open login/template.ftl
         2. Locate <h1 id="kc-page-title"><#nested "header"></h1> and delete it. This is the title within the login box.
      3. Make a text copy change
         1. Copy to login/messages/messages_en.properties over from its base folder.
         2. Change doLogIn=Log In to doLogIn=Submit.
      4. Save the file changes.
   10. Before refreshing the login page, expect in the white login for for:
       • The box should change to gray from white
       • The title above the form fields should disappear
       • The text for the Log In button on the bottom should change to Submit.
   11. Refresh to see your changes.