Skip to main content
Version: ACE 5

Migration from 5.35 to 24.1.0

Keycloak

This is a guide for migrating Keycloak configuration from ACE version 5.35.* to 24.1.0.

Since version 24.1.0, ACE is moving away from generating its own tokens for developer authorization and instead using a long-lived access token granted by the OIDC provider - Keycloak or other generic OpenID connect provider, such as Auth0.

This streamlines the ACE authorization process and makes it easier to configure token behavior directly from the provider, improving security.

Migration​

Update ENVIRONMENT VARIABLES​

  1. Remove the following ENVs from all services. It is no longer necessary to generate your own secret or timeout.

    -JWT_EXPIRE=999
    -JWT_SECRET=my-generated-secret

  2. Add the following ENVs to both ace-designer and ace-runtime-server

    # ex: `http://keycloak/realms/ACE` if the `KEYCLOAK_AUTH_SERVER_URL=http://keycloak` and `KEYCLOAK_REALM=ACE` 
    +ACE_OIDC_ISSUER_BASE_URL=<KEYCLOAK_AUTH_SERVER_URL>/realms/<KEYCLOAK_REALM>
    +ACE_OIDC_AUDIENCE=<KEYCLOAK_CLIENTID>

Update KEYCLOAK AUDIENCE​

Text guide​

It is necessary to update the ACE client scope to do an audience mapping. To proceed, find out the following:

  1. What Realm is ACE client in?
  2. Which Client is set up for ACE?
  3. What Client scope is used for ACE client?

With this information, ACE client audience mapper can be configured.

  1. Navigate to the ACE Realm
  2. Navigate to the Client scope used for ACE client (e.g., openid).
  3. Configure an audience mapper for the scope and set Included Client Audience to the name of the ACE client and save.

Visual guide​

Find client mappers Select audience mapper Configure audience and save

Update KEYCLOAK TIMEOUT​

Visual guide​

The token timeout now has to be configured from keycloak in the dedicated ACE realm. Recommended timeout is 1 day or previous value used for JWT_EXPIRE variable.

Configure the session timeout Configure the access token timeout

Debugging​

  • After changes are applied, make sure to re-log into ACE for user session to be updated.
  • Check that new ENVs are added in both ace-designer and ace-runtime-server.
  • Validate that ACE_OIDC_ISSUER_BASE_URL is accessible.
  • Validate that the url <ACE_OIDC_ISSUER_BASE_URL>/.well-known/openid-configuration is accessible, which is required for public key discovery.
  • If users get logged out too quickly, the access token and session timeout has to be configured as seen here.
  • In case of hard to resolve issues, forward ace-designer logs to the ACE support chat.