keycloak-config-cli icon indicating copy to clipboard operation
keycloak-config-cli copied to clipboard

Config CLI - Keycloak Version Compability

Open ahmetkaygisiz opened this issue 9 months ago • 23 comments

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.

ahmetkaygisiz avatar Jul 21 '25 11:07 ahmetkaygisiz

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.

florianesser-tng avatar Jul 23 '25 08:07 florianesser-tng

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 avatar Jul 31 '25 20:07 col-panic

A short statement on the plans would be really nice. 👍 We are waiting especially for integration of https://github.com/adorsys/keycloak-config-cli/issues/1278 and a resulting release!

col-panic avatar Aug 25 '25 06:08 col-panic

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

AssahBismarkabah avatar Sep 08 '25 13:09 AssahBismarkabah

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)

Sebastian-Gil-wcq avatar Sep 11 '25 01:09 Sebastian-Gil-wcq

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.

AssahBismarkabah avatar Sep 12 '25 15:09 AssahBismarkabah

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"]'

Sebastian-Gil-wcq avatar Sep 15 '25 00:09 Sebastian-Gil-wcq

@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.

AssahBismarkabah avatar Sep 18 '25 14:09 AssahBismarkabah

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

Sebastian-Gil-wcq avatar Oct 01 '25 00:10 Sebastian-Gil-wcq

From what I have seen, with FGAP V2 enabled, Keycloak stores the policies and permission not on the realm-management client anymore but rather on the admin-permissions client. Once FGAP V2 is enabled, importing those on realm-management fails, because this is not the client where does should be imported. E.g. see this partial export:

{
      "clientId": "admin-permissions",
      ...
      "authorizationSettings": {
        "allowRemoteResourceManagement": true,
        "policyEnforcementMode": "ENFORCING",
        "resources": [
           ...
        ],
        "policies": [
          {
            "name": "is-client-viewer",
            "description": "",
            "type": "regex",
            "logic": "POSITIVE",
            "decisionStrategy": "UNANIMOUS",
            "config": {
              "targetContextAttributes": "false",
              "pattern": "true",
              "targetClaim": "client-viewer"
            }
          },
          {
            "name": "all-clients-view",
            "description": "",
            "type": "scope",
            "logic": "POSITIVE",
            "decisionStrategy": "UNANIMOUS",
            "config": {
              "defaultResourceType": "Clients",
              "resources": "[\"Clients\"]",
              "scopes": "[\"view\"]",
              "applyPolicies": "[\"is-client-viewer\"]"
            }
          }
        ],
        ...
      }
    },

When I try to import the permissions on the admin-permissions client, I get different errors though.

antikalk avatar Oct 01 '25 07:10 antikalk

need we help with testing of this are we waiting before it get to production version

jwklijnsma avatar Oct 07 '25 12:10 jwklijnsma

Hello @antikalk @Sebastian-Gil-wcq thank you for the findings, i started testing again and i see the section now from the Migration - meaning from the old config with realm-management authorization we can skip the import with warnings since there is no automatic migration for 26.2+ with FGAP V2 with the FGAP V2 realm we need to recognize this and import to admin-permissions client,

@Sebastian-Gil-wcq from Guide it shows that there is no way to do the automatic migration so the authorization you used for the old config cannot be imported to FGAP V2 and need to be created in the Admin Console then exported. i am currently working on the changes needed on PR

@jwklijnsma please can test on your side to see if its same experience?

AssahBismarkabah avatar Oct 16 '25 12:10 AssahBismarkabah

@Sebastian-Gil-wcq from Guide it shows that there is no way to do the automatic migration so the authorization you used for the old config cannot be imported to FGAP V2 and need to be created in the Admin Console then exported. i am currently working on the changes needed on PR

Automatic migration is not a problem. As long as I can import the current CLI config or there is a guidance how this should be set up - updated https://github.com/adorsys/keycloak-config-cli/blob/72a3c880b0d2ef5975def355324566b17220e40b/docs/FEATURES.md?plain=1#L113 I can make the adjustments in our config, but since so far it was not so obvious how to do that in Keycloak-CLI, we still need to have the user guide / example. Doing anything in admin console is truly not an option, for that exactly reason we use Keycloak CLI - we don't want users to use Admin Console.

Sebastian-Gil-wcq avatar Oct 16 '25 21:10 Sebastian-Gil-wcq

Thank you @Sebastian-Gil-wcq for the clarification. You're absolutely right that Admin Console workarounds aren't acceptable for automation use cases.

The original issue reported HTTP 501 errors when importing configurations with fine-grained admin permissions on Keycloak 26.2+. Investigation revealed the following, Keycloak 26.2 introduced FGAP V2 as default, fundamentally changing the permission architecture(Discussion on this change). V1 (pre-26.2) stored permissions in the realm-management client, while V2 (26.2+) stores them in the admin-permissions client with a new authorizationSchema section. Auto-migration is impossible per Keycloak migration documentation due to model incompatibilities. my initial fix Gracefully handled the error handling prevented crashes but didn't support V2 imports, i just updated the pr to support V2 permission imports with authorizationSchema detection though this change is causing some test failures for other versions in the pipeline that needs to be fixed, it now

  • Prevents HTTP 501 crashes
  • Handles realm-management (V1) by skipping with warnings (auto-migration impossible per Keycloak)
  • Handles admin-permissions (V2) with authorizationSchema and imports successfully
  • Provides clear messages explaining behavior

Testing Results (Keycloak 26.3.3)

Test 1: V1 config (realm-management)

java -jar target/keycloak-config-cli.jar \
  --keycloak.url=http://localhost:8080 \
  --keycloak.user=admin \
  --keycloak.password=admin123 \
  --import.files.locations=test-fgap-v2-config.yml
2025-10-17T10:07:18.632+01:00  INFO 219933 --- [           main] d.a.k.config.KeycloakConfigApplication   : Starting KeycloakConfigApplication v6.4.1-SNAPSHOT using Java 21.0.6 with PID 219933 (/home/assah/dev/kccli/keycloak-config-cli/target/keycloak-config-cli.jar started by assah in /home/assah/dev/kccli/keycloak-config-cli)
2025-10-17T10:07:18.639+01:00  INFO 219933 --- [           main] d.a.k.config.KeycloakConfigApplication   : No active profile set, falling back to 1 default profile: "default"
2025-10-17T10:07:19.613+01:00  INFO 219933 --- [           main] d.a.k.config.KeycloakConfigApplication   : Started KeycloakConfigApplication in 1.573 seconds (process running for 2.417)
2025-10-17T10:07:20.577+01:00  INFO 219933 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:test-fgap-v2-config.yml'
2025-10-17T10:07:22.419+01:00  WARN 219933 --- [           main] d.a.k.c.s.c.ClientPermissionResolver     : HTTP 501 Not Implemented when enabling permissions for client 'f3a8cfa4-8323-42c1-8db4-6de4ac1638d8' in realm 'api' - The client resource does not support Fine-Grained admin permissions API (likely FGAP V2 active or not supported)
2025-10-17T10:07:22.558+01:00  WARN 219933 --- [           main] a.k.c.s.ClientAuthorizationImportService : Cannot create authorization resource 'client.resource.f3a8cfa4-8323-42c1-8db4-6de4ac1638d8' for client 'realm-management' - Authorization API not supported (likely FGAP V2 active). Authorization will be handled at realm level.
2025-10-17T10:07:22.608+01:00  WARN 219933 --- [           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-10-17T10:07:22.637+01:00  WARN 219933 --- [           main] a.k.c.s.ClientAuthorizationImportService : Cannot create authorization policy 'manage.permission.client.f3a8cfa4-8323-42c1-8db4-6de4ac1638d8' for client 'realm-management' - Authorization API not supported (likely FGAP V2 active). Authorization will be handled at realm level.
2025-10-17T10:07:22.736+01:00  INFO 219933 --- [           main] d.a.k.config.KeycloakConfigRunner        : keycloak-config-cli ran in 00:02.429.

Realm, roles, and clients imported successfully. V1 authorization skipped (expected behavior).

Image Image

Test 2: V2 config with authorizationSchema

java -jar target/keycloak-config-cli.jar \
  --keycloak.url=http://localhost:8080 \
  --keycloak.user=admin \
  --keycloak.password=admin123 \
  --import.files.locations=test-fgap-v2-admin-permissions-config.yml
2025-10-17T10:17:30.940+01:00  INFO 232401 --- [           main] d.a.k.config.KeycloakConfigApplication   : Starting KeycloakConfigApplication v6.4.1-SNAPSHOT using Java 21.0.6 with PID 232401 (/home/assah/dev/kccli/keycloak-config-cli/target/keycloak-config-cli.jar started by assah in /home/assah/dev/kccli/keycloak-config-cli)
2025-10-17T10:17:30.947+01:00  INFO 232401 --- [           main] d.a.k.config.KeycloakConfigApplication   : No active profile set, falling back to 1 default profile: "default"
2025-10-17T10:17:32.052+01:00  INFO 232401 --- [           main] d.a.k.config.KeycloakConfigApplication   : Started KeycloakConfigApplication in 1.751 seconds (process running for 2.654)
2025-10-17T10:17:33.207+01:00  INFO 232401 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:test-fgap-v2-admin-permissions-config.yml'
2025-10-17T10:17:35.157+01:00  INFO 232401 --- [           main] a.k.c.s.ClientAuthorizationImportService : Skipping V1 authorization import for 'admin-permissions' client in realm 'api-v2' - FGAP V2 uses the management/permissions API  Configure fine-grained admin permissions via the Admin Console Permissions section.
2025-10-17T10:17:35.252+01:00  INFO 232401 --- [           main] d.a.k.config.KeycloakConfigRunner        : keycloak-config-cli ran in 00:02.330.
➜  keycloak-config-cli git:(fix-issue-1305-FGAP-returns-501-for-keycloak-26.2.0+) ✗ 

Permission successfully created and visible in Keycloak Permissions UI.

Image Image

Configuration for V2

You can now write V2 configs declaratively. See updated for complete guide with examples.

Key structure:

realm: my-realm
adminPermissionsEnabled: true
clients:
  - clientId: admin-permissions
    authorizationSettings:
      policies:
        - name: my-permission
          type: scope
          config:
            defaultResourceType: Clients
            scopes: '["manage"]'
      authorizationSchema:  # ← Required for V2
        resourceTypes:
          Clients:
            type: Clients
            scopes: [view, manage]

Note: Resource type definitions (Groups, Users, Clients, Roles) are auto-managed by Keycloak and will show as skipped during import. This is expected behavior.

Test Configs Used

V1 Config (realm-management):

clients:
  - clientId: realm-management
    authorizationSettings:
      resources:
        - name: client.resource.$canary-client
          type: Client
          scopes: [view, manage, configure, map-roles, token-exchange, map-roles-client-scope, map-roles-composite]
      policies:
        - name: canary-client-manager-role-policy
          type: role
          config:
            roles: '[{"id":"canary-client-manager","required":true}]'

V2 Config (admin-permissions with authorizationSchema):

clients:
  - clientId: admin-permissions
    authorizationSettings:
      policies:
        - name: test-pem
          type: scope
          config:
            defaultResourceType: Clients
            resources: '["client-uuid"]'
            scopes: '["map-roles"]'
      authorizationSchema:
        resourceTypes:
          Clients:
            scopes: [view, manage, map-roles]

cc: @jwklijnsma @antikalk

AssahBismarkabah avatar Oct 17 '25 16:10 AssahBismarkabah

@AssahBismarkabah i will check tomorrow

jwklijnsma avatar Oct 20 '25 10:10 jwklijnsma

@AssahBismarkabah works for me realm include subrealm is working.

jwklijnsma avatar Oct 20 '25 19:10 jwklijnsma

Thanks for testing that out @jwklijnsma , the coverage check on the pipeline still seem to be failing for some reasons, currently looking into it.

AssahBismarkabah avatar Oct 20 '25 19:10 AssahBismarkabah

Just to add my two cents. I noticed that after upgrading to the new Keycloak, realm-management client is still there, and it still holds all the settings. This is not the case for a new realm where realm-management client exists but authorization tab is absent. That is probably what Keycloak means when they say there is no migration strategy. To sort that out, as a part of migration strategy, we should probably reset those settings as well. Probably the easiest way would be to just reset authorizationServicesEnabled flag and reset authorizationSettings. I will test this further once we have a new version of keycloak-cli

  - clientId: realm-management
     authorizationServicesEnabled: false
     authorizationSettings: null
Image Image

Sebastian-Gil-wcq avatar Oct 20 '25 23:10 Sebastian-Gil-wcq

Hi @Sebastian-Gil-wcq , ok after the testing then we can find a way to proceed, currently waiting on some reviews from the PR https://github.com/adorsys/keycloak-config-cli/pull/1322

@jwklijnsma @antikalk a review and test will be appreciated.

AssahBismarkabah avatar Oct 26 '25 14:10 AssahBismarkabah

@AssahBismarkabah works for me

jwklijnsma avatar Oct 27 '25 11:10 jwklijnsma

@AssahBismarkabah is the eta for new release, do need help are more testing ?

jwklijnsma avatar Nov 11 '25 13:11 jwklijnsma

Hi @jwklijnsma I've just finalized the changes for FGAP V2 support in the PR. It would be great if you could help review and test the changes to ensure everything is working as expected on your end. Once we have that verified and merged, we can look at making a release.

AssahBismarkabah avatar Nov 20 '25 15:11 AssahBismarkabah

@AssahBismarkabah it works

jwklijnsma avatar Nov 24 '25 12:11 jwklijnsma