Supporting Multiple post.logout.redirect.uris in Keycloak Config CLI

In Keycloak configurations, setting up clients with multiple logout redirect URIs can be a challenging task. This guide provides a step-by-step solution to support multiple post.logout.redirect.uris in Keycloak using the Keycloak Config CLI. We’ll dive into why this issue arises, the approach to overcome it, and a practical example on implementing it in your configuration file.

Problem Statement

The Keycloak attribute post.logout.redirect.uris is often used to specify URLs that the client can redirect to after logout. However, by default, Keycloak Config CLI expects this attribute to be a single string rather than an array. This causes an error when trying to add multiple URIs, which typically looks like this:

YAML

clientId: my-client1
protocol: openid-connect
attributes:
  post.logout.redirect.uris:
    - /URI1
    - /URI2
    - /URI3

OR

JSON

{
  "clientId": "my-client1",
  "protocol": "openid-connect",
  "attributes": {
    "post.logout.redirect.uris": [
      "/URI1",
      "/URI2",
      "/URI3"
    ]
  }
}

Keycloak Config CLI throws an error because it cannot deserialize the array, expecting a string instead: The error looks like this

Cannot deserialize value of type java.lang.String from Array value (token JsonToken.START_ARRAY)
at [Source: UNKNOWN; byte offset: #UNKNOWN] (through reference chain: de.adorsys.keycloak.config.model.RealmImport["clients"]->java.util.ArrayList[6]->org.keycloak.representations.idm.ClientRepresentation["attributes"]->java.util.LinkedHashMap["post.logout.redirect.uris"])

Solution Overview

To work around this limitation, the Keycloak suggests using a delimiter, ##, to separate multiple URIs in a single string. The Keycloak Config CLI then processes this string and recognizes it as multiple URIs based on the delimiter. This allows you to specify multiple logout URIs in one configuration line.

How to Implement Multiple post.logout.redirect.uris

Step 1: Update Your JSON Configuration

To configure multiple logout redirect URIs, add them as a single string in your JSON configuration file, separating each URI with ### Here’s an example:

YAML

realm: "your-realm"
clients:
  - clientId: "your-client-id"
    enabled: true
    redirectUris:
      - "https://app1.example.com/callback"
      - "https://app2.example.com/callback"
      - "https://app3.example.com/callback"
    webOrigins:
      - "https://app1.example.com"
      - "https://app2.example.com"
      - "https://app3.example.com"
    attributes:
      post.logout.redirect.uris: "https://app1.example.com/logout##https://app2.example.com/logout##https://app3.example.com/logout"
    protocol: "openid-connect"
    publicClient: false
    standardFlowEnabled: true
    implicitFlowEnabled: false
    directAccessGrantsEnabled: true
    serviceAccountsEnabled: false
    authorizationServicesEnabled: false
    fullScopeAllowed: true

JSON

{
  "realm": "your-realm",
  "clients": [
    {
      "clientId": "your-client-id",
      "enabled": true,
      "redirectUris": [
        "https://app1.example.com/callback",
        "https://app2.example.com/callback",
        "https://app3.example.com/callback"
      ],
      "webOrigins": [
        "https://app1.example.com",
        "https://app2.example.com",
        "https://app3.example.com"
      ],
      "attributes": {
        "post.logout.redirect.uris": "https://app1.example.com/logout##https://app2.example.com/logout##https://app3.example.com/logout"
      },
      "protocol": "openid-connect",
      "publicClient": false,
      "standardFlowEnabled": true,
      "implicitFlowEnabled": false,
      "directAccessGrantsEnabled": true,
      "serviceAccountsEnabled": false,
      "authorizationServicesEnabled": false,
      "fullScopeAllowed": true
    }
  ]
}

This approach uses the ## delimiter to separate multiple logout URIs within a single string.

Step 2: Load Your Configuration

Once you've updated your JSON file with the ## delimiter, use Keycloak Config CLI to import your realm configuration. If the configuration is correctly set up, Keycloak will recognize each URI in post.logout.redirect.uris as a separate redirect URI.

Step 3: Verify in the Keycloak Admin Console

To confirm the configuration, open your Keycloak Admin Console and navigate to the relevant client. In the Settings tab, check the "Post Logout Redirect URIs" section to see if each URI is listed individually. If the delimiter is handled correctly, you should see each URI separated, allowing Keycloak to redirect to any of them post-logout.

Why Use a Delimiter?

The Keycloak Config CLI does not support arrays directly for this attribute due to serialization constraints. The delimiter approach provides a flexible workaround, allowing you to specify multiple URIs while retaining compatibility with the CLI’s existing deserialization logic.