Adding an enforcing service
IAM enforcement uses one decision point, IamAuthorizationService, behind REST
and gRPC transport adapters. The gRPC interceptor is installed in
GrpcServerManager.bind, which is the actual Vert.x service registration path.
The global-interceptor annotation also covers Quarkus-managed registrations.
An annotation alone does not cover the dynamically bound controllers.
Resource Manager projects, Cloud Billing project billing-info reads, Cloud Run v2 services and revisions, Secret Manager
secrets and versions, Pub/Sub, Cloud Scheduler jobs, Cloud Logging project and organization
sink management, IAM service-account/key management and direct access-token
issuance, IAM project and organization custom-role management, and GCS bucket/object
operations are integrated. Bindings to stored custom roles grant their includedPermissions
through every adapter except in GCS bucket policies; see Custom roles. IAM policy methods also
use REST and the shared IAM gRPC mixin; the IAM inventory
lists exact methods, permission targets, role slices, and local condition limits. Cloud Run
service-policy methods use REST and the shared IAM gRPC API. Secret Manager secret
policy methods work over REST and gRPC. GCS invokes the shared evaluator from its
service-level authorization path so JSON filtering does not bypass its
lock-sensitive lifecycle coordination. Cloud Logging GCS export uses the same GCS service path
with the persisted sink writer as a trusted internal principal. It uses no request credential
bypass. Sink management checks the caller's emulator-issued service-account credential over
REST and gRPC; see the sink IAM inventory.
Service extension contract
- Add an
@ApplicationScopedimplementation ofIamAuthorizationAdapterin the owning service package. Constructor injection is supported. - Declare the REST controller classes and fully qualified gRPC service names. Duplicate transport ownership fails registration. The shared IAM gRPC mixin dispatches through the adapter's resource factory.
- Translate each REST handler and protobuf request to an
IamOperation. Both transports must use the samecheckstable. An unfamiliar operation must throwunsupported(...). Explicit permission-free methods may return an empty list. gRPC services overridegrpcOperation(String, Message)and read request fields through typed protobuf getters. The default rejects unmapped gRPC operations. - Return every required
IamPermissionCheck, including checks on other resources. Create/list operations usually check the parent; verify the exact upstream contract. Do not guess permissions from method names. Each check is conjunctive. - Implement
resourcewith exact accepted names, service/type/name CEL attributes, and the existing policy storage key. Return empty for resources owned by other adapters. UseIamResource.projectChildfor project inheritance; do not expose internal policy keys to CEL. Versioned resources can have a parent policy key. SetIamResource.inheritOrganizationPolicyonly when recorded organization ancestry is supported by the service. It defaults to false for existing adapters. - Contribute a finite predefined role map and exact
basicRolesslices. Basic-role permissions are explicitly contributed by each service, never inferred by the shared catalog. Do not use wildcard permission grants. Bindings with roles outside the finite catalog that are not active custom roles applying to the policy's project or organization are skipped as complete, non-granting bindings before condition validation; they must not block grants from known bindings or policy recovery. - Reuse
IamServicepolicy storage and its existing resource-existence resolvers.testPermissionsroutes registered resources through the evaluator. OverridevalidatePolicyfor service-specific binding constraints; it runs on policy writes and before evaluation in enforce mode and must not perform I/O. Custom-role bindings are checked on writes by the shared service, aftervalidatePolicy, for every resource the adapter registers. A service using different policy storage needs a reviewed integration before advertising enforcement; registering a resource factory alone is insufficient. OverridepermissionDeniedwhen upstream evidence requires a service-specific denial response. OverridesupportsIamPolicyMethodto reject policy methods that the upstream service does not expose. - Add the service to the documentation and coverage matrix. Startup coverage is derived from registered adapters. Update the explicit exclusions in the startup message when expanding beyond the current scope.
The current REST transport adapter buffers and restores JSON request bodies. It is not an XML, multipart, raw-media, or HTTP/protobuf authorization parser. Add an appropriate transport adapter for those formats while retaining the shared decision point. Likewise, streams that address resources after their initial message need explicit state handling and tests. Pub/Sub StreamingPull retains the first subscription name, checks every message and delivery, and rejects a repeated subscription field in later messages. GCS intentionally does not register its REST controllers with that filter. Its authorization service calls the same evaluator after applying GCS-specific credential handling. XML, media, upload, and service-layer paths use that entry point instead of relying on the JSON filter.
Required tests
- Allowed operation, forbidden permission on the same resource, ungranted sibling, condition exclusion, project inheritance, and cross-project isolation.
- Independent REST and gRPC negative assertions, plus the same requests with the feature disabled. Cover each advertised transport with real clients.
testIamPermissions, policy-mutation escalation, unknown resources/operations, malformed/expired credentials, and unsupported CEL constructs.- An uncatalogued role by itself denies normally, a known grant still succeeds beside an uncatalogued role for the same caller, and the policy remains recoverable.
- Multi-resource operations, streaming entry points, and side-effect absence after denial, where applicable.
- Inventory controller methods so adding a handler cannot silently bypass the map.
- Temporarily bypass the service's authorization call and run its negative tests. Record that they failed with successful requests where denials were expected, restore the implementation, and rerun the passing suite.
The root integration suite exercises generated GCP gRPC clients and REST JSON in
both modes. compatibility-tests/sdk-test-java also contains IamEnforcementTest
using the official Resource Manager v1 REST SDK and generated IAM v1 gRPC client.
It expects disabled mode by default. Against
an enforcing server set FLOCI_GCP_IAM_TEST_ENFORCEMENT=true in the test process.
This test-only variable does not enable server enforcement. The Java compatibility CI job
runs the default suite and then this test against a separate enforcing native emulator.
Storage and concurrency
Policies use the global IAM store under the exact resource key; service stores
use project routing. GCS retains the lifecycle invariant from its owning service:
the IAM policy lock is acquired before the bucket mutation lock, and bucket creation
holds the bucket lock through initial-policy persistence and durable rollback.
Bucket policy mutation acquires the bucket and owning-project policy locks in global
stripe order, revalidates bucket ownership, and holds both locks through authorization
and the policy write. Object mutations acquire every applicable bucket and owning-project
policy lock in the same global order before entering the storage mutation lock. The
shared REST filter and gRPC interceptor do not hold a lock
across authorization and the subsequent service mutation. Other service integrations
must use the service-level ordered-lock entry point when that consistency is required.
Cloud Logging holds its sink lock before acquiring the ordered destination policy locks
and GCS bucket/object locks, serializing delivery with sink configuration changes.
Secret Manager holds the secret lock before the ordered project and secret policy
locks across authorization and the secret or version operation.
Custom-role definitions are serialized among themselves but not with these policy
locks, and evaluation reads them without a lock. Each read sees the latest stored
definition, so a role edit, disable, delete, or undelete applies to reads after it is
stored, and one decision that overlaps the change can observe both versions. A role
activated between those reads has its condition evaluated without prior validation; an
unsupported condition then fails closed in the evaluator rather than with
INVALID_ARGUMENT.
Upstream evidence
The Resource Manager v1, Cloud Run v2, and Secret Manager v1 protocol and role contracts are defined by these upstream references:
- Resource Manager v1 project get project policy constraints, and Resource Manager roles.
- IAM resource attributes, expression protobuf, and Google API errors.
- Cloud Run role permissions and Cloud Run service IAM methods.
- Cloud Run v2 service proto, revision proto, and REST discovery document.
- Secret Manager v1 service proto and Secret Manager access control.
The REST client implementation is in the Resource Manager v1 Java SDK source. The Cloud Run client HTTP JSON mappings are in the Java service stub and revision stub. The shared policy transport uses the IAM v1 policy proto.
Denial codes and permission requirements follow these contracts. Exact production message text, error metadata, revocation timing, and alias resolution are not compatibility guarantees.
IAM service-account evidence
- IAM v1 discovery document and IAM admin proto.
- IAM roles and permissions, including the basic-role membership listed for each checked permission.
- Credentials v1 discovery document and Credentials proto.
- Credentials signBlob
and signJwt
permission references;
iam.serviceAccounts.getOpenIdTokenforgenerateIdTokencomes from the Pub/Sub proto and the Cloud Run roles. - IAM REST Java SDK source and Credentials HTTP JSON stub.
IamServiceAccountAuthorizationServiceTest inventories the implemented handlers
and permission targets. The service-account integration tests exercise denial
state, conditions, policy escalation, alias resolution, role slices, and disabled
controls. IamServiceAccountIamEnforcementTest exercises official IAM REST,
Credentials HTTP JSON, and generated shared IAM policy gRPC clients in both modes.
The compatibility workflow runs it against its isolated enforcing native server.
Local evidence does not establish production IAM condition or Organization Policy
compatibility.
IAM custom-role evidence
- IAM admin proto
Role,RoleView,Role.RoleLaunchStage, and the create, get, list, update, delete, and undelete request messages and HTTP bindings, and the IAM v1 discovery document. - Method permissions on projects.roles and organizations.roles, and the role slices in IAM roles and permissions.
- Understanding custom roles and creating custom roles for scope, limits, disabled and deleted behavior, and role ID reuse.
- IAM REST Java SDK source
Projects.RolesandOrganizations.Rolesrequest builders.
IamRoleAuthorizationServiceTest inventories the role handlers and permission targets.
IamCustomRoleEnforceIntegrationTest and IamCustomRoleDisabledIntegrationTest share one
contract covering management denials without mutation, conditions, Pub/Sub REST and gRPC
grants, filtered testIamPermissions, cross-project and cross-organization bindings, and
revocation. IamCustomRoleIamEnforcementTest repeats the management, Pub/Sub grant, filtering,
boundary, and revocation paths with the official IAM, Resource Manager, and Pub/Sub
REST clients and the generated Pub/Sub gRPC client. It also covers resource-name
conditions on project and organization role management and on custom-role grants over
Pub/Sub REST and gRPC, including unchanged resources after denied mutations and the
same requests with enforcement disabled.
The following were checked against live GCP (IAM v1 REST, one organization and one
project under a folder): basic-role
iam.roles.* membership from gcloud iam roles describe; error codes and messages for
duplicate IDs, reused deleted IDs, stale etags, deleted-role updates and deletes,
undeleting an active role, invalid role IDs, titles, descriptions, stages, views, update
masks, role names, page sizes, permission counts, and wrongly typed fields; malformed and
non-string etags; byte-based length limits; error precedence for stale etags on deleted
roles; unmasked patch replacement; per-method permissions and targets for a caller holding
roles/iam.roleViewer; exact custom-role grants and testIamPermissions filtering on a
Pub/Sub topic; revocation timing; organization-role management permissions and targets
with and without roles/iam.organizationRoleViewer; and policy-write rejection of
another project's role and of new grants to deleted roles. GCP also allowed an
organization role in a project under a folder, which Floci does not model.
The IAM v1 Java REST client sends an empty form content type for bodyless policy reads and deletes. The matching IAM REST handlers accept that empty-body path as well as JSON; payload-bearing operations retain their JSON contract. This behavior is exercised by the unmodified official SDK request builders above; the shared Google Java request builder uses empty content for bodyless custom POST methods.
Cloud Scheduler evidence
- Scheduler v1 proto and HTTP JSON SDK stub.
- REST create,
list,
and resume
define parent targets and the
cloudscheduler.jobs.enablepermission. - Scheduler access control and role permissions.
SchedulerIamAuthorizationAdapterServiceTest inventories all eight handlers and
RPCs. SchedulerIamEnforcementTest uses the official Java client over REST and
gRPC, with restricted emulator-issued credentials, positive controls, denial state
assertions, observed Pub/Sub delivery after permitted/denied runs, JSON null
normalization, domain-scoped project names, and disabled-mode controls. The compatibility workflow includes it
in the isolated enforcing native run. See the Scheduler inventory
for local condition semantics and unsupported targets.
Cloud Logging sink evidence
- ConfigServiceV2 proto and Cloud Logging access control.
- The Logging v2 discovery document,
revision
20261023, exposes only create, delete, get, list, patch, and update on sinks. The service configuration declares no IAM policy mixin. Sink IAM policy methods therefore fail closed in enforce mode. - Logging v2 REST sink methods and the official Java REST SDK source.
gcloud iam roles describemetadata for all elevenroles/logging.*predefined roles: admin and configWriter grant all five sink permissions, viewer and privateLogViewer grant get and list, and the other seven grant no sink permissions. The published Logging roles reference also lists these four supported role slices.- Basic-role metadata: owner grants all five sink permissions; editor and viewer grant only get and list.
- Live project checks with the official Java REST and gRPC clients showed that
create evaluates the future sink name, list evaluates the project parent, and get, update,
and delete evaluate the existing sink name. A
resource.servicecondition matchedlogging.googleapis.com; aresource.typecondition matchedlogging.googleapis.com/LogSinkfor create, get, and list. Live organization checks confirmed all five RPCs and six REST forms with sink-name, parent-name, service, and type conditions. Organization REST denials returned HTTP 403 withPERMISSION_DENIED,IAM_PERMISSION_DENIEDingoogle.rpc.ErrorInfo, and the denied permission and resource in metadata; gRPC returnedPERMISSION_DENIED.
| Parent | REST JSON v2 | ConfigServiceV2 gRPC | Live authorization target |
|---|---|---|---|
| Project | Create, list, get, PUT, PATCH, delete | Create, list, get, update, delete | Future sink for create, parent for list, named sink otherwise |
| Organization | Create, list, get, PUT, PATCH, delete | Create, list, get, update, delete | Future sink for create, parent for list, named sink otherwise |
The live organization probe also confirmed that every method denies an unbound service account
after IAM propagation. The Java SDK checks use disabled sinks with a non-delivering destination;
they do not require log traffic. The emulator matches the observed authorization decisions and
transport status classes. Logging sink permission denials include the observed message,
legacy REST forbidden reason, and google.rpc.ErrorInfo permission and resource metadata
on REST and gRPC. Other error fields and headers have not been checked for exact parity.
An additional live project sink probe under a test organization was
denied over REST and gRPC with no binding. An organization-level
roles/logging.configWriter binding then permitted the same GetSink calls without a project
binding. The emulator applies this inheritance to Logging sinks when Resource Manager has
recorded the project-to-organization parent relationship.
CloudLoggingIamAuthorizationAdapterServiceTest inventories REST handlers and gRPC
requests. LoggingSinkIamEnforcementTest uses the official Java gRPC client;
LoggingSinkRestIamEnforcementTest uses the official Java REST discovery client.
Both exercise project and organization parents, conditional create grants, resource-name
scoping for sink and parent operations, unbound and insufficient-role denials, unchanged resources and
policies after denials, and disabled-mode controls.
The gRPC suite also verifies that sink policy reads, writes, and permission queries fail closed
for existing and missing sinks in enforce mode. Running that rejection test against a
disabled-mode server with enforce-mode expectations fails because the request succeeds.
Trusted setup can write organization parent policies through the shared
IAM mixin; evaluated callers retain the existing FAILED_PRECONDITION for bare
organization policy reads and writes.
Temporarily removing the create permission check made the conditional-create denial
assertion fail with a successful request; restoring the check made the suite pass.
The compatibility workflow includes both in its isolated enforcing native stage.
See the sink IAM inventory.