Keycloak Setup in local environment

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. Tokens issued to user will have audience ace-client with their expiry set to 24 hours after being issued.

Verify ACE realm setup (optional)

This is an optional section to verify that above script worked correctly, you can skip this initially 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 'openid' is present in Client scopes tab.
5. Click on Client scopes in left menu and verify if 'openid' exist in Client scopes list.
6. Navigate to 'openid' scope section 'Mappers' and verify that 'Type: Audience' mapper exists.
7. Click on 'Users' tab in Manage section. Click 'View all users' and verify if user with username 'user' is created.
8. Click on the user and then visit 'Credentials' tab.
9. Change the password. This password will be used to generate token for user.
10. Uncheck 'Temporary' checkbox.
11. Save user details.
12. 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

   # Represents the REALM url
   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
   # Represent the realm URL
   ACE_OIDC_ISSUER_BASE_URL=http://localhost:8282/realms/ACE
   ACE_OIDC_AUDIENCE=ace-client

2. ace-runtime-server

   # Same as in `ace-designer`
   ACE_OIDC_ISSUER_BASE_URL=http://localhost:8282/realms/ACE
   ACE_OIDC_AUDIENCE=ace-client

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