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

Configurining access roles

Since ACE version 25.6.0, it is possible to limit which keycloak users can access development ACE.

The variable ACE_ACCESS_ROLE can be set at service level. If the user trying to access ACE does not have the appropriate role configured, access will be denied.

The ACE_ACCESS_ROLE variable can be configured on both ace-designer and ace-runtime-server services.

Typically, we can configure ACE_ACCESS_ROLE=my-ace-role for ace-runtime-server, so that everyone can view ACE, but only select users can execute the APIs and flows.

Setup keycloak role claim

The goal of this setup is to stop users without the necessary role to execute development apis and flows. The assigned roles should ultimately appear in the "ace/role" claim.

The only pre-requisite is to already have configured a realm and client ('ACE' and 'ace-client' in the guide) for ACE.

Keycloak setup

1. Navigate to the realm with the ACE client.
2. Navigate to 'Realm roles' -> 'Create role'. For the purpose of this tutorial, name the role 'execute-apis'.
3. Navigate to 'Clients' -> 'ace-client' -> 'Client scopes' -> 'ace-client-dedicated' (if not here, create a separate scope).
4. From the 'ace-client-dedicated' scope navigate to 'Add mapper'. Create a predefined configuration and add a 'realm roles' mapper.
5. Open the 'realm roles' mapping and edit 'Token Claim Name' to be 'ace/role'. Save the mapping.

Keycloak role assignment

At this point, the mapping is done, but no roles have been assigned. To assign a role, do the following:

1. Navigate to the realm
2. Navigate to 'Users' -> 'name-of-your-user' -> 'Role mapping' -> 'Assign role'
3. From here, search for the 'execute-apis' role. Select it and assign it.

Service configuration

To configure ACE itself to handle this role, configure ACE_ACCESS_ROLE=execute-apis on the ace-runtime-server service. At this point, when trying to run a flow or API, you will either be allowed or denied access depending on your account roles.