AC Tool 4.1.1 fails to activate on vanilla Apache Sling 12+: `NoClassDefFoundError: com/adobe/granite/keystore/KeyStoreService`

[ciechanowiec]

Summary

On a vanilla Apache Sling 12+ instance (i.e. one that does not ship Adobe Granite bundles), installing accesscontroltool-bundle 4.1.1 leaves every AC Tool component unable to instantiate. SCR reports each component as satisfied, but every getService() call returns null, so:

• /system/console/actool returns HTTP 404 (the Felix Web Console plugin cannot bind AcToolUiService).
• AcInstallationService (and its AcInstallationServiceInternal/JobExecutor facets) is never delivered.
• The Touch UI servlet at /mnt/overlay/netcentric/actool/content/overview.html cannot resolve.
• In short: the tool is installed but unusable, even though the bundle is Active.

This contradicts the README, which states:

It is also possible to run the AC Tool on Apache Sling 12 or above (ensure system user actool-service has jcr:all permissions on root). When using the AC Tool with Sling, actions in ACE definitions and encrypted passwords cannot be used. […]

and the explicit comment in accesscontroltool-bundle/bnd.bnd:

# allow to run in Sling without AEM bundles
# allow to run without bouncycastle which is only necessary for some edge cases when managing keys
Import-Package: \
com.adobe.granite.crypto;resolution:=optional,\
com.adobe.granite.keystore;resolution:=optional,\
…

The optional imports let the bundle resolve, but they do not protect it from the JVM's eager resolution of field types during reflection (see "Root cause" below).

Environment

• AC Tool: accesscontroltool-bundle 4.1.1 (latest release as of writing)
• Container: vanilla Apache Sling 12+ on Apache Felix, with Apache Felix SCR 2.2.18
• JVM: OpenJDK 25.0.3 (also reproducible on JDK 21)
• No bundle in the framework exports com.adobe.granite.keystore or com.adobe.granite.crypto

Reproduction

1. Start a vanilla Apache Sling 12+ instance.
2. Drop accesscontroltool-bundle-4.1.1.jar into <sling>/launcher/startup (or install it via the Web Console). Do not install any Adobe Granite bundles.
3. After the bundle reaches state Active, observe error.log for entries like the ones in "Observed log output" below.
4. Visit /system/console/components. All AC Tool components show satisfied, none ever become active.
5. Visit /system/console/actool → HTTP 404.
6. Issue any call that consumes AcInstallationService (for example via the AC Tool MBean or a programmatic bundleContext.getService(...)). The ServiceFactory returns null.

The behavior is fully deterministic — stopping and starting the AC Tool bundle re-produces the same sequence of errors.

Observed log output

Excerpt from error.log (timestamps from a single bundle start; full stack trace abbreviated):

*ERROR* AuthorizableInstallerServiceImpl … : Field externalGroupCreatorService cannot be
        found in component class biz.netcentric.cq.tools.actool.authorizableinstaller.impl.
        AuthorizableInstallerServiceImpl. The field will be ignored.
        (org.apache.felix.log.LogException: java.lang.NoClassDefFoundError:
         com/adobe/granite/keystore/KeyStoreService)

org.apache.felix.log.LogException: java.lang.NoClassDefFoundError:
        com/adobe/granite/keystore/KeyStoreService
    at java.base/java.lang.Class.getDeclaredFields0(Native Method)
    at java.base/java.lang.Class.privateGetDeclaredFields(Class.java:2917)
    at java.base/java.lang.Class.getDeclaredField(Class.java:2380)
    at org.apache.felix.scr.impl.inject.field.FieldUtils.getField(FieldUtils.java:157)
    at org.apache.felix.scr.impl.inject.field.FieldUtils.searchField(FieldUtils.java:87)
    at org.apache.felix.scr.impl.inject.field.FieldHandler$NotResolved.resolve(FieldHandler.java:388)
    at org.apache.felix.scr.impl.inject.field.FieldHandler$NotResolved.fieldExists(FieldHandler.java:406)
    at org.apache.felix.scr.impl.inject.field.FieldHandler.fieldExists(FieldHandler.java:463)
    at org.apache.felix.scr.impl.inject.field.FieldHandler$ReferenceMethodImpl.getServiceObject(FieldHandler.java:545)
    …

*ERROR* AuthorizableInstallerServiceImpl … : Field [decryptionService] not found; Component will fail
*ERROR* AuthorizableInstallerServiceImpl … : Field [externalGroupCreatorService] not found; Component will fail
*ERROR* AuthorizableInstallerServiceImpl … : Field [impersonationInstallerService] not found; Component will fail
*ERROR* AuthorizableInstallerServiceImpl … : Field [repository] not found; Component will fail
*ERROR* AuthorizableInstallerServiceImpl … : Field [resourceResolverFactory] not found; Component will fail
*ERROR* FrameworkEvent ERROR (Service factory returned null. (Component:
        biz.netcentric.cq.tools.actool.authorizableinstaller.impl.AuthorizableInstallerServiceImpl))

*WARN* AcInstallationServiceImpl … : Could not get service from ref
       [biz.netcentric.cq.tools.actool.authorizableinstaller.AuthorizableInstallerService]
*ERROR* Service factory returned null. (Component: AcInstallationServiceImpl)

*WARN* AcToolUiService … : Could not get service from ref
       [AcInstallationService, AcInstallationServiceInternal, JobExecutor]
*ERROR* Service factory returned null. (Component: AcToolUiService)

*WARN* AcToolWebconsolePlugin … : Could not get service from ref [AcToolUiService]
*ERROR* Service factory returned null. (Component: AcToolWebconsolePlugin)

Root cause

AuthorizableInstallerServiceImpl declares an optional, dynamic reference to com.adobe.granite.keystore.KeyStoreService as a typed field
(source, line 108):

import com.adobe.granite.keystore.KeyStoreNotInitialisedException; // line 64
import com.adobe.granite.keystore.KeyStoreService;                 // line 65
…
@Reference(cardinality = ReferenceCardinality.OPTIONAL,
           policy = ReferencePolicy.DYNAMIC,
           policyOption = ReferencePolicyOption.GREEDY)
volatile KeyStoreService keyStoreService;                          // line 108

OSGi resolution is fine — the bundle wires up with the import unbound because com.adobe.granite.keystore is declared resolution:=optional in bnd.bnd.

The problem arises later, when Felix SCR introspects the class to bind references. Apache Felix SCR FieldUtils.searchField calls Class.getDeclaredField(name), which the JVM implements via the native Class.getDeclaredFields0(boolean publicOnly). That native method walks the constant pool of the class, eagerly resolving the declared type of every field — including the KeyStoreService field. Because no bundle in a vanilla Sling distribution exports com.adobe.granite.keystore, the bundle's classloader cannot resolve Lcom/adobe/granite/keystore/KeyStoreService; and throws NoClassDefFoundError.

Apache Felix SCR catches the failure and marks the field as NotResolved in its FieldHandler cache. From that point on, every subsequent lookup against any field of the class returns "not found" (FieldHandler$NotResolved.fieldExists → false), regardless of whether that field's own type is resolvable. The same AuthorizableInstallerServiceImpl therefore reports Field [decryptionService] not found; Component will fail, Field [repository] not found; Component will fail, etc., even though decryptionService, repository, and resourceResolverFactory are perfectly ordinary Sling types.

Once AuthorizableInstallerServiceImpl cannot be instantiated, every downstream consumer cascades:

AuthorizableInstallerServiceImpl  (null)
  └── AcInstallationServiceImpl   (null — @Reference AuthorizableInstallerService)
       └── AcToolUiService        (null — @Reference AcInstallationServiceInternal)
            ├── AcToolTouchUiServlet
            └── AcToolWebconsolePlugin  → /system/console/actool returns 404

The components show as satisfied only because SCR's reference-cardinality check is independent of class loading — the optional 0..1 keyStoreService reference is correctly satisfied by "0 providers", and all other references find matching services. The failure mode is purely on the class-introspection path.

Why CI does not catch this

The CI matrix in .github/workflows/maven.yml resolves the bundle against target-osgi-environment/minimum-environment/minimum-aem.bndrun, which pulls in AEM/Granite bundles via com.adobe.aem:uber-jar. In that resolution context, com.adobe.granite.keystore is exported by com.adobe.granite.crypto.api (or equivalent), the optional import wires up, and field-type resolution succeeds. There appears to be no equivalent minimum-sling.bndrun exercising a true vanilla Sling 12 distribution, so the regression is invisible to the matrix.

Suggested fixes (alternatives)

Pick one — any of these resolves the symptom:

1. Ship a small accesscontroltool-sling-shim bundle alongside accesscontroltool-bundle (or as an optional artifact). It exports com.adobe.granite.keystore and com.adobe.granite.crypto packages containing stub types (KeyStoreService, KeyStoreNotInitialisedException, CryptoSupport, CryptoException) whose method bodies are unreachable on Sling. Users would deploy this on Sling but not on AEM.

2. Remove the typed field from AuthorizableInstallerServiceImpl and replace it with a bind/unbind method whose parameter type is hidden behind an interface that lives inside the AC Tool bundle. The Adobe Granite type would only be referenced from inside the method body, where lazy resolution applies. Example:

   @Reference(cardinality = OPTIONAL, policy = DYNAMIC,
              policyOption = GREEDY,
              service = Object.class,                       // erased type
              target = "(objectClass=com.adobe.granite.keystore.KeyStoreService)")
   private volatile Object keyStoreService;                  // no granite types in class signature

   (or use bind/unbind methods that take ServiceReference<?> and call KeyStoreService only from inside method bodies that are protected with try { … } catch (NoClassDefFoundError) { … } if needed).

3. Move the keystore feature into a separate "AEM-only" sub-bundle so the core AC Tool bundle has no compile-time reference to com.adobe.granite.*.

4. Add a minimum-sling.bndrun to the CI matrix that exercises a real vanilla Sling 12 environment, so this class of failure cannot reach a release again, and document any required shims in docs/Installation.md.

Workaround for downstream users

Until upstream chooses a fix, users on vanilla Sling can deploy a tiny "stub" OSGi bundle that exports the missing Granite packages, e.g.:

// com/adobe/granite/keystore/KeyStoreService.java
package com.adobe.granite.keystore;
public interface KeyStoreService { /* never invoked on Sling */ }

// com/adobe/granite/keystore/KeyStoreNotInitialisedException.java
package com.adobe.granite.keystore;
public class KeyStoreNotInitialisedException extends Exception { }

…packaged as an OSGi bundle that exports com.adobe.granite.keystore (and the analogous classes for com.adobe.granite.crypto). Because the AC Tool's optional imports are then wired, the JVM can resolve the field types, SCR introspection succeeds, all AC Tool components become active, and the tool is fully functional — including /system/console/actool and the install hook.

This works because the relevant @Reference cardinality is 0..1: SCR will never actually bind a KeyStoreService instance (none are registered), so no method on the stub is ever invoked.

[kwin]

@ciechanowiec Can you try with the proposed fix from #879?

[ciechanowiec]

@kwin ,

I rebuilt accesscontroltool-bundle from the feature/make-keystoreservice-optional branch and deployed it into a vanilla Apache Sling / Jackrabbit Oak stack (no AEM, no Adobe Granite bundles on the classpath; Felix SCR 2.2.18, oak-core-spi 1.90.0).

The bundle has always resolved on plain Sling - its Import-Package for com.adobe.granite.* is resolution:=optional, so OSGi wiring is not the problem. PR #879 fixes the next layer up by making the DS-level KeyStoreService reference optional, which lets the installer side become satisfied without an Adobe keystore. That works.

What still doesn't work is component activation: two AC Tool components reach satisfied but never active, because they trip class-loading the moment SCR / Aries JMX reflects on them. Net effect: the JMX MBean and the authorizable installer are unusable on Sling 12.

Blocker 1 - AceServiceMBeanImpl extends an Adobe-Granite-only class

AceServiceMBeanImpl (and the AceServiceMBean interface) depend on three classes that only exist in the Adobe Granite JMX bundle:

// AceServiceMBeanImpl.java

import com.adobe.granite.jmx.annotation.AnnotatedStandardMBean;

public class AceServiceMBeanImpl extends AnnotatedStandardMBean implements AceServiceMBean { ...
}

// AceServiceMBean.java
import com.adobe.granite.jmx.annotation.Description;
import com.adobe.granite.jmx.annotation.Name;

Because AnnotatedStandardMBean appears as a superclass, an optional Import-Package doesn't rescue us - the moment SCR / Aries JMX whiteboard instantiates the component, the JVM has to resolve the superclass and throws:

Caused by: java.lang.NoClassDefFoundError: com/adobe/granite/jmx/annotation/AnnotatedStandardMBean
    at java.base/java.lang.ClassLoader.defineClass1(Native Method)
    ...
    at org.apache.felix.scr.impl.manager.AbstractComponentManager.initDependencyManagers(...)
Caused by: java.lang.ClassNotFoundException:
  com.adobe.granite.jmx.annotation.AnnotatedStandardMBean
    not found by biz.netcentric.cq.tools.accesscontroltool.bundle [321]

A natural replacement already ships with Sling/Oak

Apache Jackrabbit Oak provides a similar base class on every Sling 12 / Oak deployment:

• org.apache.jackrabbit.oak.commons.jmx.AnnotatedStandardMBean (in org.apache.jackrabbit:oak-core-spi)
• matching annotations org.apache.jackrabbit.oak.api.jmx.Description and org.apache.jackrabbit.oak.api.jmx.Name (in oak-api).

Consider swapping the three imports in AceServiceMBeanImpl / AceServiceMBean over to these Oak types.

Blocker 2 - AuthorizableInstallerServiceImpl references KeyStoreNotInitialisedException

Even with PR #879 making the KeyStoreService reference optional, the AuthorizableInstallerServiceImpl activate method still fails during DS method discovery because the class statically references a Granite keystore exception type:

*WARN* [FelixLogListener] biz.netcentric.cq.tools.actool.authorizableinstaller.impl.AuthorizableInstallerServiceImpl
  bundle biz.netcentric.cq.tools.accesscontroltool.bundle:4.1.2.202605141455 (321)
  : Failure looking up method activate(org.osgi.service.component.ComponentContext) ...
  (java.lang.NoClassDefFoundError: com/adobe/granite/keystore/KeyStoreNotInitialisedException)
    at java.base/java.lang.Class.getDeclaredMethods0(Native Method)
    at java.base/java.lang.Class.privateGetDeclaredMethods(Class.java:3010)
    at org.apache.felix.scr.impl.inject.methods.BaseMethod.getMethod(BaseMethod.java:359)
    ...
    at org.apache.felix.scr.impl.inject.methods.ActivateMethod.invoke(ActivateMethod.java:315)

Same shape as Blocker 1, but on a Granite exception class. Class.getDeclaredMethods0() triggers linkage of every type referenced in any method signature on the class - so a single method that throws KeyStoreNotInitialisedException (or takes/returns it) kills activate() lookup, and DS quietly assumes there is no activate method. resolution:=optional on the package import doesn't help once SCR uses reflection.

Bottom line

PR #879 makes the DS-level keystore dependency optional, which is real progress, but does not yet make AC Tool functional on plain Sling. Two more pieces are needed:

1. Replace the hard superclass / annotation dependency on com.adobe.granite.jmx.annotation.* with Oak's equivalent (org.apache.jackrabbit.oak.commons.jmx.AnnotatedStandardMBean plus org.apache.jackrabbit.oak.api.jmx.{Description,Name}), already present on every Sling/Oak and AEM runtime.
2. Ensure no method signature in any component class statically references com.adobe.granite.keystore.* types (KeyStoreNotInitialisedException is the one currently biting).

Happy to test any further branch you push.

[kwin]

@ciechanowiec I updated the PR, please try again.

[ciechanowiec]

@kwin ,

Thanks a lot for the quick turnaround on this - I really appreciate the work you've put into the branch.

I confirmed the resolution failure on a stock Apache Sling instance (no AEM). After installing the bundle from feature/make-keystoreservice-optional (HEAD 48ca5936, "Remove Granite JMX dependency for JMX beans"), the bundle stays in Installed state with:

org.apache.jackrabbit.oak.commons.jmx,version=[1.1,2) -- Cannot be resolved

Root cause: that commit added import org.apache.jackrabbit.oak.commons.jmx.AnnotatedStandardMBean in AceServiceMBeanImpl. Since the parent pom pins oak.version=1.22.16 (where the package is at @Version("1.2.0")), bnd's default consumer policy produces [1.1, 2). But in Apache Jackrabbit Oak the package was bumped to 2.0.0 in commit 42b0a70d30 / OAK-10274 ("remove Guava from public API"), back on 2023-07-22 - so any Oak from roughly 1.46 onward (and obviously all current 2.x) exports oak.commons.jmx;version=2.0.0, which falls outside [1.1, 2). On my vanilla Apache Sling instance the oak-core-spi 2.0.0 bundle is the only exporter of the package at 2.0.0, hence the resolver failure.

Worth noting that despite the major bump, the only API actually removed in that package was a deprecated ManagementOperation.newManagementOperation overload taking com.google.common.base.Supplier. AnnotatedStandardMBean itself is unchanged, so AC Tool's usage is binary-compatible across 1.x and 2.x.

Happy to test any follow-up commit on this branch against my Sling setup and report back - just ping me here and I'll turn it around quickly. Thanks again!

[kwin]

I see regarding JMX however I consider JMX nice to have but not strictly necessary to use ACTool. Do the other parts work now (once I would make the JMX import optional)?

[ciechanowiec]

@kwin,

1. With JMX made optional, the bundle resolves and the AC Tool runs. Console output attached for reference.

2. While making the JMX import optional, could you also widen the accepted version range so that oak.commons.jmx 2.0 is included? It would be great to keep JMX wired in - and as noted in the previous comment, AnnotatedStandardMBean is binary-compatible across the 1.x → 2.x bump.

[ciechanowiec]

@kwin , thank you for the fix. Is it possible to have the latest version of the library released to Maven soon?