Keycloak Setup in local environment

Legacy

This guide is outdated since ACE version 24.1.0, to migrate configuration for newer versions see keycloak migration guide

caution

This is guide for Keycloak setup in local environment and is not intended for server environments.

For server use please follow the official documentation of keycloak to start the service Getting started.

Install and start keycloak

Below is an example to start keycloak with Docker compose.

version: "3"
services:
  keycloak:
    image: quay.io/keycloak/keycloak:20.0
    command: start-dev
    ports:
      - "8282:8282"
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=password
      - KC_HTTP_PORT=8282

Setup ACE realm with a test user

Download below script setup-keycloak.sh using below curl command.

curl https://dev.ace-community.sapienspaas.com/scripts/setup-keycloak.sh -o setup-keycloak.sh

Run the script setup-keycloak.sh with below arguments

-b Base url of keycloak eg `https://<Your hostname>`
-u Admin username of keycloak
-p Admin password of keycloak
-r realm name
-f Base url of ACE Designer web

Below is an example:

./setup-keycloak.sh -b http://localhost:8282 -u admin -p password -f http://localhost:5025 -r ACE

This will create realm ACE with user user with password user.

Verify ACE realm setup (optional)

This is an optional section to verify that above script worked correctly, you can skip this initaially and come back later if you are not able to login using the user created above.

1. Login to keylock admin console with admin credentials.
2. In top left corner select ACE realm from dropdown.
3. Click on clients tab and verify if 'ace-client' is present in the list.

4. Click on 'ace-client' in clients list and verify if 'open-id' present in Client scopes tab.

5.Click on Client scopes in left menu and verify if 'open-id' exist in Client scopes list.

4. Click on 'Users' tab in Manage section. Click 'View all users' and verify if user with username 'user' is created.

5. Click on the user and then visit 'Credentials' tab.
6. Change the password. This password will be used to generate token for user.
7. Uncheck 'Temporary' checkbox.
8. Save user details.

9. Visit 'Details' tab for this user and remove all the Required User Actions if present.

Setup ACE Designer to use keycloak

This guide assumes that you have knowledge of ACE services ACE Components

Append configuration below to following services

1. ace-designer

#secret for JWT token encoding
JWT_SECRET=1L1KEb1gB00B5P0rNaNDGrA55
JWT_EXPIRE=60
KEYCLOAK_CLIENTID=ace-client
KEYCLOAK_REALM=ACE
KEYCLOAK_CLIENT_SECRET=4c363dd5-096a-426f-b2d0-db878c49ac02
#<Keycloak public url>, eg `https://<Your hostname>`
KEYCLOAK_AUTH_SERVER_URL=http://localhost:8282
#Designer Web public url
ACE_UI_URL=http://localhost:5025
#Role defined in keycloak to allow access to Designer
KEYCLOAK_DESIGNER_ACCESS_ROLE=

note

KEYCLOAK_DESIGNER_ACCESS_ROLE is optional, if not defined then any Keycloak user can access ACE Designer. If this is defined then same role must be present for the user otherwise user cannot log in to ACE Designer.

2. ace-runtime-server

#secret for JWT token decoding, must match ace-designer secret
JWT_SECRET=1L1KEb1gB00B5P0rNaNDGrA55
#Role defined in keycloak to allow access to Designer
KEYCLOAK_DESIGNER_ACCESS_ROLE=

Docker compose setup

If you are running ace locally using Docker compose with keycloak then follow these steps:

1. Change variable below in above-mentioned ace-designer service configuration.

KEYCLOAK_AUTH_SERVER_URL=http://keycloak:8282

2. Edit your system hosts file and add below entry

127.0.0.1 keycloak

For Windows system

hosts file location for windows is C:\Windows\System32\drivers\etc

After editing the hosts file run below command to reflect the changes immediately

ipconfig /flushdns

Create new user in keycloak (optional)

Script to create new user in keycloak if necessary. This step needs to be performed after all of the above keycloak setup is done.

Step 1 : Install jq command

choco install jq -y

Step 2: Download below script create-user.sh using below curl command.

curl https://dev.ace-community.sapienspaas.com/scripts/create-user.sh -o create-user.sh

Step 3: Run the script create-user.sh with below arguments

-b Base url of keycloak eg `https://<Your hostname>`
-u Admin username of keycloak
-p Admin password of keycloak
-r realm name
-n username for user
-s password for user

Below is an example:

./create-user.sh -b http://localhost:8282 -u admin -p password -n testuser -s testpass -r ACE