Release 1.10.0: Access Control rework: entitlements, access policies and anonymization reports

[MoonWorm]

Overview

1.10.0 is a rework of the Access Control plugin, plus the principal resolution that feeds it. Three headline changes:

• Access control you can actually express. Ordered access tiers are gone, replaced by unordered entitlements composed from two levels of ANY_OF / ALL_OF / NONE_OF clauses. Scopes now use the same structure, which let SpEL — and the spring-expression dependency — be dropped entirely. For rules no annotation can express, a new AccessPolicy SPI decides in Java against a context carrying the principal, the operation, the request and the resource.
• A response can now say what it hid. A denied GET returns 200 with the restricted data left out — which a caller cannot tell apart from there being nothing to return. The new opt-in anonymization report closes that gap, adding an accessControl member to meta at one of four levels: that something was hidden, which paths, and which requirement refused each one.
• Anonymization that reaches the whole response. Requirements are now read from the runtime type of each value, so a rule declared on a class applies wherever an instance of it appears — nested, inside collections, arrays and maps, or behind a field declared as an interface, a supertype or Object.
• JWT principal resolution. Three new resolvers — JwtPrincipalResolver, SpringSecurityPrincipalResolver, QuarkusJwtPrincipalResolver — build the principal from token claims, sharing one claim-mapping engine. The Access Control plugin also works in a GraalVM native image, with the Quarkus extension registering your annotated classes at build time.

This release contains breaking changes. They are listed first.

Breaking Changes

Access tiers are now entitlements

Tiers were ordered: holding ADMIN implicitly satisfied a requirement for PARTNER. That ranking could not express "support staff and an admin", and it made every new tier a question about where it sat in the order. Entitlements are plain unordered labels — any string your principal source produces — matched by exact name.

Removed	Replacement
@AccessControlAccessTier	@AccessControlEntitlements + @EntitlementsGroup
AccessTier, AccessTierRegistry, DefaultAccessTierRegistry	none — entitlements are strings, nothing to register
TierRootAdmin, TierAdmin, TierPartner, TierPublic, TierNoAccess	DefaultEntitlements.ROOT_ADMIN / .ADMIN / .PARTNER
Principal#authenticatedClientAccessTier()	Principal#authenticatedClientEntitlements()
X-Authenticated-Client-Access-Tier header	X-Authenticated-Client-Entitlements (space-separated)

// before
@AccessControl(tier = @AccessControlAccessTier(TierAdmin.ADMIN_ACCESS_TIER))

// after
@AccessControl(entitlements = @AccessControlEntitlements(@EntitlementsGroup(ADMIN)))

There is deliberately no label meaning "everyone" or "nobody" (the old PUBLIC / NO_ACCESS tiers). Omit the requirement to demand nothing; name an entitlement no principal carries to deny everyone.

PUBLIC and NO_ACCESS have no direct equivalent, and the ranking is gone: a principal holding ADMIN no longer satisfies a requirement for PARTNER. Grant a principal every entitlement it needs rather than expecting a "higher" one to cover the others.

Scopes dropped SpEL

@AccessControlScopes(requiredScopes = …) and its SpEL expression are replaced by @ScopesGroup clauses with the same modes as entitlements. The spring-expression dependency is gone from the AC plugin's POM.

// before
@AccessControl(scopes = @AccessControlScopes(requiredScopes = {"users.sensitive.read"}))

// after
@AccessControl(scopes = @AccessControlScopes(@ScopesGroup("users.sensitive.read")))

Sparse fieldsets now enumerate inherited fields

JSON:API requires fields[] to address every field of a resource, including inherited ones. Previously only fields declared directly on the attributes class were enumerated, so an inherited field survived a fields[] that should have excluded it. This changes responses for clients already using fields[] against attributes classes that use inheritance.

Access Control

Entitlements are composed, not ranked

A requirement is built from @EntitlementsGroup clauses. Each clause quantifies over entitlement names; @AccessControlEntitlements then quantifies over the clauses, using the same three modes.

Clause mode	Satisfied when the caller holds
ANY_OF (clause default)	at least one of the listed entitlements
ALL_OF	all of the listed entitlements
NONE_OF	none of the listed entitlements

That gives two levels:

@AccessControl(entitlements = @AccessControlEntitlements(
        description = "internal support staff, or a partner integration",
        mode = AccessControlEntitlements.Mode.ANY_OF,
        value = {
                @EntitlementsGroup(value = {ADMIN, "SUPPORT"}, mode = EntitlementsGroup.Mode.ALL_OF),
                @EntitlementsGroup(value = {PARTNER, "INTEGRATOR"}, mode = EntitlementsGroup.Mode.ALL_OF)
        }))

which reads as (ADMIN and SUPPORT) or (PARTNER and INTEGRATOR). ADMIN and PARTNER come from DefaultEntitlements; SUPPORT and INTEGRATOR are plain strings.

The simple case stays short — one clause, default ANY_OF:

@AccessControl(entitlements = @AccessControlEntitlements(@EntitlementsGroup(ADMIN)))

description is optional and quoted back when access is denied, so a log line explains why the requirement exists rather than only naming entitlements:

DEBUG Access denied: 'internal support staff, or a partner integration'
      (ANY_OF[ALL_OF[ADMIN, SUPPORT], ALL_OF[PARTNER, INTEGRATOR]]) is required,
      but the authenticated principal carries [PARTNER].

An empty @EntitlementsGroup({}) is rejected at startup, so a requirement that can never be satisfied fails on boot rather than silently denying every request.

Scopes use the same structure

@ScopesGroup clauses combined by @AccessControlScopes, same three modes, matched by exact name. The clause default is ALL_OF rather than entitlements' ANY_OF, because a scope requirement normally asks for every scope it lists.

@AccessControl(scopes = @AccessControlScopes(
        description = "read access to profiles, or full admin access",
        mode = AccessControlScopes.Mode.ANY_OF,
        value = {
                @ScopesGroup({"users.read", "profiles.read"}),
                @ScopesGroup("admin.full")
        }))

Policies — deciding access in code

Each declarative requirement has a fixed shape. When a rule doesn't fit any of them — reading the caller's attributes, branching on the operation, comparing the caller against the resource — write it as a class:

public class SameTenantPolicy implements AccessPolicy {

    @Override
    public boolean isSatisfiedBy(AccessControlContext context) {
        Object callerTenant = context.principal().attributes().get("tenant");
        return callerTenant != null
                && context.operation().getOperationType() != OperationType.DELETE_RESOURCE;
    }

}

@AccessControl(policy = @AccessControlPolicy(
        value = SameTenantPolicy.class,
        description = "caller's tenant must be set, and may not delete"))

A policy is ordinary code — unlimited nesting, unit-testable without a running app, reusable across as many annotations as you like. It is combined with the other requirements exactly as they are combined with each other: every declared requirement must pass. It runs last, after the cheaper declarative checks have had their chance to deny.

Instances are created once when the access control model is built, so a policy must be stateless, thread-safe, and expose a public no-argument constructor. A class that cannot be constructed fails at startup rather than on the first request that reaches it.

What a policy can see. AccessControlContext follows the vocabulary shared by XACML, AWS Cedar and AWS IAM — who is asking, what they are doing, to what, and under what circumstances:

Accessor	Dimension	Notes
principal()	subject	Never null; attributes() is where a JWT-claims resolver puts its claims
operation()	action	OperationType, ResourceType, RelationshipName
resource()	object	Present outbound only — the resource being emitted
resource(Class)	object	The same, narrowed to a type; empty rather than throwing if it is something else
request()	environment	Headers, filters, includes
stage()	—	INBOUND before data is fetched, OUTBOUND before it is sent

operation() is the dimension no other requirement can reach: it lets a rule turn on what the caller is doing rather than who they are — "internal bookkeeping is visible on a single-resource lookup, but never in a list response".

A policy changes the decision for one annotated element. Replacing AccessControlEvaluator changes it for the whole application — reach for that only when evaluation itself is unusual (an external authorization service, an audit record per decision, caching), and extend DefaultAccessControlEvaluator rather than starting from scratch.

Requirements follow the object, not the field

Requirements are now read from the type of the value actually present, at the moment the response is built. A rule declared on a class therefore applies wherever an instance of that class turns up — held directly, at any depth, inside a container, or behind a field declared as an interface, a supertype or Object.

public class UserAttributes {
    private Address home;              // rule on Address applies
    private List<Address> addresses;   // applies to every element
    private Payment payment;           // applies to whatever CardPayment declares
}

New placements for @AccessControl:

Placement	Effect
Nested object — on a class held by the attributes, or on its fields	Applies wherever an instance of that class appears, at any depth
Collection, array or map element — on the element class or its fields	Applied per element; an element denied entirely is dropped from the container
A runtime type more specific than the field's declared type	Applies — requirements come from the object present, not from how the field was declared

A container is rebuilt only when one of its elements is replaced or dropped. A List comes back as a List, a Map as a Map, an array with the same component type, and sorted types keep their comparator. Two consequences worth knowing: a container's length depends on the caller, and indices do not line up between callers.

Hiding a field never modifies your object

The plugin builds a copy of the attributes object with the denied fields left null and puts the copy in the response, so the instance your Resource returned comes back untouched — an application is free to return a cached or shared attributes object. Copies are made only along the path to a hidden field, and only when something is actually hidden; when a caller may see everything, the original is passed straight through and nothing is allocated.

Building the copy does not call your constructor, so constructors that validate, normalise, or take arguments in a different order than the fields are declared all work. Records are the one exception: their components cannot be written after construction, so a record is rebuilt through its canonical constructor.

The Sparse Fieldsets plugin now works the same way, through the shared ObjectCopier.

Telling a caller something was hidden

A denied GET returns 200 with the restricted data left out, which a caller cannot tell apart from there being nothing to return. jsonapi4j.ac.anonymizationReport closes that gap by adding an accessControl member to the response meta:

{
  "meta": { "accessControl": { "anonymized": true } },
  "data": { "id": "1", "type": "users",
    "attributes": { "fullName": "John Doe" },
    "meta": { "accessControl": { "anonymized": true, "fields": [
      { "path": "attributes.creditCardNumber",    "reason": "INSUFFICIENT_SCOPES" },
      { "path": "attributes.addresses[0].zip",    "reason": "INSUFFICIENT_SCOPES" }
    ]}}
  }
}

Four levels, each saying strictly more than the one before:

Level	What a response carries
NONE	Nothing. Responses are exactly as they were before this existed. Default.
INDICATOR	That something was hidden, without saying what.
FIELDS	The paths that were hidden, indexed into containers as addresses[0].zip.
FIELDS_AND_REASONS	Also the error code of the requirement that refused each path.

The top level of the document carries the indicator; each resource names its own hidden paths in its own meta. The member appears only when something was actually hidden, so its absence alongside an empty data means there genuinely was nothing to return — which is the question the feature exists to answer.

The report is written after anonymization and is not itself subject to it, so it survives on a resource whose meta was withheld.

This discloses. Saying that something was hidden confirms that something is there. FIELDS_AND_REASONS goes further and tells a caller which entitlement or scope would reveal each field — excellent for a partner integrating against your API, and a map of your authorization model for anyone probing it. Turn it on deliberately, and prefer the lowest level that answers your callers' question.

Denials name what failed

For a GET, a denied request returns 200 with the restricted data omitted — a 403 would fail the whole response including the parts the caller is allowed to see, and would break compound documents. For everything else, a denied request returns 403 with an error code naming what failed:

Requirement that failed	Error code
entitlements	INSUFFICIENT_ENTITLEMENTS
scopes	INSUFFICIENT_SCOPES
authenticated, ownership, policy	FORBIDDEN

Entitlements and scopes are named because they tell a caller different things — one needs different credentials, the other a differently-scoped token. Ownership stays generic deliberately: reporting "you are not the owner" would confirm that the resource exists and that somebody else holds it. A custom evaluator can report any ErrorCode it likes, including its own.

Rules that cannot take effect

Several @AccessControl placements enforce nothing — a requirement on a primitive field (a primitive can't hold "absent"), on a static field, on a field that shadows an inherited one of the same name, or a bare @AccessControl declaring no requirement at all. These are now reported once, when the access control model for a class is first built, naming the class and field involved.

Set jsonapi4j.ac.failOnMisconfiguration=true and each raises AccessControlMisconfigurationException instead of logging. Off by default, because turning a warning into a failure would break an application already running with a rule that quietly does nothing. It earns its keep in tests and CI.

Despite the name, this is not startup validation: requirements on a resource, operation or relationship class are read when the plugin registers, but an attributes class is only known once a response carries one — so most are raised on the first request that touches the resource.

New properties

Property	Default	Description
jsonapi4j.ac.failOnMisconfiguration	false	Reject access control that is declared but cannot take effect, instead of only logging it
jsonapi4j.ac.anonymizationReport	NONE	How much a response says about what was hidden: NONE, INDICATOR, FIELDS, FIELDS_AND_REASONS

Performance

Annotation-derived access control models are now cached per class rather than rebuilt per request, and ReflectionUtils caches more of its traversal. Both plugins allocate nothing when a caller may see everything.

Principal Resolution

JsonApi4j never authenticates anyone — verifying credentials is the job of your web framework or gateway. A PrincipalResolver answers the narrower question: given a request that has already passed authentication, who is the caller and what are they allowed to do?

1.10.0 ships three new resolvers alongside the header-based default:

Resolver	Reads from	Token verified?	Module
DefaultPrincipalResolver	X-Authenticated-* headers	Upstream — trusts the gateway	jsonapi4j-rest
JwtPrincipalResolver	Authorization: Bearer …	No — decodes only	jsonapi4j-rest
SpringSecurityPrincipalResolver	SecurityContextHolder	Yes, by Spring Security	jsonapi4j-rest-springboot
QuarkusJwtPrincipalResolver	injected JsonWebToken	Yes, by Quarkus OIDC	jsonapi4j-rest-quarkus

DefaultPrincipalResolver remains active out of the box. The other three are opt-in: you declare one as a bean and it takes precedence. This is deliberate — auto-selecting a JWT resolver because a security library happens to be on the classpath would silently change behaviour for applications that authenticate at the gateway and forward headers.

// Spring Boot — requires spring-boot-starter-oauth2-resource-server
@Bean
public PrincipalResolver jsonapi4jPrincipalResolver() {
    return SpringSecurityPrincipalResolver.withEntitlementsClaim("entitlements");
}

// Quarkus — requires quarkus-oidc or quarkus-smallrye-jwt
@Produces
@Singleton
public PrincipalResolver principalResolver(JsonWebToken jwt) {
    return QuarkusJwtPrincipalResolver.withEntitlementsClaim(jwt, "entitlements");
}

JwtPrincipalResolver does not validate tokens. It base64-decodes the payload of whatever bearer token arrives and maps the claims — no signature, no expiry, no issuer, no audience. Use it only where something in front of the application has already rejected invalid tokens, and prefer SpringSecurityPrincipalResolver or QuarkusJwtPrincipalResolver, which cannot produce a principal from an unverified token at all.

Principal carries four things

Method	Purpose
authenticatedUserId()	Identifies the caller. Also used for ownership checks.
authenticatedClientEntitlements()	Unordered entitlement labels.
authenticatedClientScopes()	Fine-grained OAuth2 scopes.
attributes()	Everything else the token carried — email, tenant, expiry. Read by access control policies.

attributes() is new, and is what makes ABAC policies useful: it is where a JWT-claims resolver puts the claims a policy then branches on. The header-based DefaultPrincipalResolver leaves it empty.

Claim mapping

All three JWT resolvers share one engine, ClaimsPrincipalMapper, so claim configuration behaves identically no matter which you use.

Principal field	Default claim	Notes
authenticatedUserId()	sub	RFC 7519. Override for providers that prefer oid or email.
authenticatedClientScopes()	scope, falling back to scp	Space-delimited string or array of strings; scp covers Azure AD
authenticatedClientEntitlements()	entitlements	A jsonapi4j convention, not a standard
attributes()	all claims	Exposed as an unmodifiable map

Nested claims work too: a name containing dots is looked up literally first, then treated as a path into nested objects — so both Keycloak's realm_access.roles and Auth0's namespaced https://api4.pro/roles resolve correctly.

Entitlements need an explicit claim

The most common cause of unexpected 403s after switching to a JWT resolver. JWT defines no standard claim for entitlements. JsonApi4j reads entitlements by convention, but no identity provider emits that claim on its own. If it is missing, every principal resolves no entitlements at all and every operation guarded by @AccessControl(entitlements = …) is denied — even for a perfectly valid token.

The plugin now says so explicitly, once per process, distinguishing "carries no entitlement at all" from "carries entitlements that aren't the required ones":

WARN  Access denied: OR[ADMIN] is required, but the authenticated principal carries no entitlement at all.
      The configured PrincipalResolver resolved none — when using a JWT resolver, check that issued tokens
      actually carry the configured entitlements claim.

Anonymous callers never trigger it: having no entitlement is the expected state for them. Because a misspelling on either side looks exactly like a legitimate denial, both sides are logged at DEBUG. The same pair of diagnostics exists for scopes.

Thread safety

The resolver is called once per request and a single instance serves every request, so implementations must be thread-safe and must resolve everything from the request argument rather than caching state on the resolver itself. AuthenticatedPrincipalContextHolder now clears the principal at the end of every request, so nothing carries over between requests served by the same pooled thread.

Native Image (GraalVM / Quarkus)

Building the redacted copy instantiates your attributes class reflectively, which a native image allows only for classes registered ahead of time. The Quarkus extension now registers them for you by scanning for @AccessControl at build time.

One thing to know: Quarkus indexes your application module automatically but not its dependencies. If your attributes classes live in a separate jar, that jar has to carry a Jandex index or the registration finds nothing. Build one into it with the Jandex Maven plugin:

<plugin>
    <groupId>io.smallrye</groupId>
    <artifactId>jandex-maven-plugin</artifactId>
    <version>3.5.3</version>
    <executions>
        <execution>
            <id>make-index</id>
            <goals>
                <goal>jandex</goal>
            </goals>
        </execution>
    </executions>
</plugin>

That keeps the concern with the module owning the classes, so every consuming application picks it up without configuration. If you cannot change the producing jar, index it from the consuming application instead:

quarkus.index-dependency.my-domain.group-id=com.example
quarkus.index-dependency.my-domain.artifact-id=my-domain

If access control is enabled and no @AccessControl is found in the index, the build logs a warning naming both options. A native-image smoke test now runs in CI.

Sparse Fieldsets

• fields[] applies inside collections, arrays and maps. fields[users]=addresses.zip names a field of every element — zip is kept in each address, other fields of each address are dropped. Elements themselves are never removed (unlike access control, which drops a denied element).
• Inherited fields are enumerated, as JSON:API requires — see Breaking Changes.
• Excluding a field no longer modifies your object, matching the Access Control plugin, through the shared ObjectCopier.
• A path through a field that is null on this resource is still a valid path: whether it exists is decided by the type, not the data.
• Map keys are not addressable — only values are narrowed.
• When an attributes class cannot be copied (a dynamic proxy, say), all of its fields are returned and a warning is logged. Sparse fieldsets is a convenience over response shape, never a security control, so it does not fail the request.

Validation & Spec Conformance

• Validation failures can carry their own HTTP status. JSON:API requires 409 Conflict when a request body is aimed at the wrong collection, and 403 Forbidden when a create request supplies its own id and the server does not accept client-generated ids. Both are now enforced, via a new withHttpStatus on the fluent assertions — available to your own validators too, for cases like a 409 on a duplicate.

  .withResourceTypeValidator(type -> type
          .isNotBlank()
          .withHttpStatus(HttpStatusCodes.SC_409_CONFLICT.getCode())
          .withErrorCode(DefaultErrorCodes.CONFLICT)
          .withDetail("resource type does not belong to this collection")
          .isEqualTo(request.getTargetResourceType().getType()))

  A failure carrying its own status is reported alone. Collecting exists to tell a client everything wrong at once, which works only while the errors share a status — a JSON:API document carries many error objects but one HTTP status. So such a failure short-circuits, and anything collected before it is dropped.

• New error code CLIENT_GENERATED_ID_NOT_SUPPORTED.

• withHttpStatus applies to the assertion that follows it and is cleared once that assertion has run, exactly like withErrorCode and withDetail — so order matters.

Other Changes

• A configuration file with everything in it. Each sample app now ships a config file listing every property with its default, so the whole surface is visible in one place rather than assembled from tables — application.yaml (Spring Boot), application.properties (Quarkus), jsonapi4j.yaml (Servlet). Copy one and delete what you don't need; every value shown is the default, so removing a line changes nothing.
• Sample apps cover write operations on nested collections — User → addresses create and update, with tests.
• A shadowed field name now resolves to the most-derived declaration instead of the inherited one, and access control declared on the shadowed one is reported.
• Expanded documentation across access control, principal resolution, error handling, write operations and compound documents.

Migration Checklist

1. Replace @AccessControlAccessTier with @AccessControlEntitlements + @EntitlementsGroup; replace TierXxx constants with DefaultEntitlements.
2. Grant principals every entitlement they need — the old ranking is gone.
3. Rename the X-Authenticated-Client-Access-Tier header to X-Authenticated-Client-Entitlements wherever your gateway sets it.
4. Replace @AccessControlScopes(requiredScopes = …) with @ScopesGroup clauses.
5. If you use fields[] against attributes classes with inheritance, re-check those responses — inherited fields are now excludable.
6. Update any direct import of ObjectCopier to jsonapi4j-base.
7. Switching to a JWT resolver? Configure the entitlements claim explicitly — see Entitlements need an explicit claim.
8. Recommended for CI: set jsonapi4j.ac.failOnMisconfiguration=true.

Resources

• Documentation: https://api4.pro/
• Access Control plugin: https://api4.pro/access-control-plugin/
• Principal Resolution: https://api4.pro/principal-resolution/
• Sparse Fieldsets plugin: https://api4.pro/sparse-fieldsets-plugin/
• Error Handling: https://api4.pro/error-handling/
• Configuration: https://api4.pro/configuration/
• Release notes: https://github.com/MoonWorm/jsonapi4j/releases/tag/v1.10.0