Configuring per-resource authorization

Every grant must be valid: exactly one of principal and principal_role, a known operation and resource_pattern_type, and a boolean deny. A file with an invalid grant is rejected as a whole, because skipping an invalid deny rule would grant access you meant to forbid: Apicurio Registry does not start, or keeps the previous grants on reload.

In artifact names, the characters % and / in the group ID are written as %25 and %2F, so the first / always separates the group from the artifact ID. For example, artifact x in group team-a/sub is named team-a%2Fsub/x, while artifact sub/x in group team-a is named team-a/sub/x. Artifact IDs and group names are not escaped.

Patterns are matched against the complete name. For example, the prefix team-a/ matches every artifact in group team-a (but not in group team-a/sub), and the prefix team-a/internal- matches only the artifacts in team-a whose ID starts with internal-.

Matching is case-sensitive on every storage variant, in direct access and in search results. Some databases, such as MySQL and SQL Server, look up group and artifact IDs case-insensitively, so a request for TEAM-A/My-Schema can address the stored artifact team-a/my-schema. Such a request is authorized against the stored IDs, so changing the case of an ID never gets around a grant or deny rule.

admin implies write, and write implies read. The operation required by each API operation matches its RBAC level: reads require read, and changes, including deletes, require write. A few operations require admin, such as dropping Iceberg namespaces, tables, and views.

Some operations need both:

Most deployments need both. For example, to give a user full access to team-a:

Deny rules use the same fields with "deny": true. If a deny rule matches, access is denied even if an allow rule also matches. Deny rules apply to search results as well as direct access.

Alice can read and write all artifacts in team-a except team-a/secret-schema.

A deny rule denies its operation and every operation that implies it:

Apicurio Registry checks the grants file for changes at the interval set by apicurio.auth.resource-based-authorization.grants.reload-every and applies changes without a restart. If the changed file is not valid JSON, is not an object, or has no grants array, Apicurio Registry logs an error and keeps using the previously loaded grants.

Some operations read or write artifacts other than the one addressed by the request. These artifacts are authorized as if the caller accessed them directly:

Each team sees and modifies only its own schemas:

All developers read shared schemas; only the platform team modifies them:

RBAC administrators bypass per-resource authorization. A user with the sr-readonly role can never write, whatever their grants. To control write access with grants, give users the sr-developer role and use grants to choose which resources they can change.

By default, the recorded owner of an artifact or group has access to it whatever the grants, whether or not owner-only authorization (apicurio.auth.owner-only-authorization) is enabled. Set apicurio.auth.resource-based-authorization.owner-bypass.enabled to false to make grants the only per-resource authority. Owners also see their own resources in search results and can read content used by their artifacts. With the Elasticsearch search index, searches that require the index (content and structure searches) include at most 1000 of the caller’s owned artifacts that are not otherwise covered by grants. A resource without a recorded owner does not grant this exception to anyone.

When owner-only authorization is enabled, it applies as well to resources named in a request body, such as Iceberg rename targets and published MCP servers: only the owner can change them, even if other users have matching grants.

The creator of an artifact becomes its owner, but creating it requires write on both the group and the artifact name, so the owner bypass cannot be used to get around a deny on that name.

These settings skip the RBAC check for reads; per-resource authorization still applies:

Reports that cover the whole registry and cannot be filtered per resource, such as the GitOps status and validation tasks, are available only to callers who are not restricted by grants (administrators).

Users identified as administrators by the admin override (apicurio.auth.admin-override.*) bypass per-resource authorization. When apicurio.authn.proxy-header.trust-proxy-authorization is true, requests authenticated by proxy headers bypass all local authorization, including grants.

When OpenTelemetry metrics are enabled, Apicurio Registry exports the counter apicurio.authz.decisions, with the attributes:

Denied point-access decisions are logged at INFO level to the io.apicurio.registry.audit.authz logger:

To disable these messages, set quarkus.log.category."io.apicurio.registry.audit.authz".level=OFF.

Check, in order:

Check whether the user is an RBAC administrator or has a role listed in config.admin_roles, whether the user owns the resources (see owner-bypass.enabled), and, for unauthenticated callers, what the $anonymous role is granted.

Apicurio Registry fails to start when per-resource authorization is enabled and the grants file path is not set, the file does not exist, or the file is not valid grants data. The startup error names the file and the problem.