Skip to content

IAM

floci-gcp emulates Google Cloud IAM over REST JSON and the shared IAM policy gRPC mixin.

Configuration

Variable Default Description
FLOCI_GCP_SERVICES_IAM_ENABLED true Enable/disable IAM
FLOCI_GCP_SERVICES_IAM_AUTHORIZATION_MODE disabled Set to enforce to evaluate allow policies for the supported services below
FLOCI_GCP_SERVICES_IAM_BOOTSTRAP_ADMIN_MEMBER unset Optional IAM member granted roles/storage.admin on each newly created bucket

Opt-in enforcement

Set FLOCI_GCP_SERVICES_IAM_AUTHORIZATION_MODE=enforce, or floci-gcp.services.iam.authorization-mode: enforce in YAML. The default is disabled: stored policies do not restrict requests. Startup logs always report which mode is active and the supported service list.

Surface IAM enforcement in enforce mode
Resource Manager v1 project metadata and project policies REST JSON; project policies also use the shared IAM gRPC mixin
Cloud Billing v1 project billing info REST JSON GET only; the PUT update is not evaluated. See Cloud Billing IAM enforcement
Cloud Run v2 services and revisions REST JSON service and revision operations; service-policy methods also use the shared IAM gRPC API. See Cloud Run IAM enforcement
GCS buckets Supported REST bucket metadata, IAM-policy, retention-lock, storage-layout, and notification operations; bucket testIamPermissions filters its response
GCS objects Supported REST JSON and XML reads, writes, updates, deletes, listing, compose, copy, rewrite, move, restore, resumable uploads, and XML multipart uploads
Pub/Sub REST JSON and gRPC topic, subscription, snapshot, and policy methods; testIamPermissions filters its response
Cloud Scheduler REST JSON and gRPC job create/get/list/update/delete/pause/resume/run; project policy inheritance. See Scheduler IAM enforcement
Cloud Logging sinks REST JSON and gRPC create/get/list/update/delete for project and organization sinks. Folder and billing-account parents fail closed for evaluated callers; sink IAM policy methods fail closed in enforce mode. See Sink management IAM
Secret Manager REST JSON and gRPC secret and version operations; see Secret Manager IAM enforcement
IAM service accounts and keys REST JSON service-account CRUD, disable and enable, key management, IAM policy methods over REST and shared IAM gRPC, signBlob, and IAM Credentials generateAccessToken, generateIdToken, signBlob, and signJwt
IAM custom roles REST JSON project and organization role create, get, list, patch, delete, and undelete. Bindings to stored custom roles grant their includedPermissions on every surface above except GCS bucket policies. See Custom roles
GCS ACLs and GCS gRPC Not IAM-enforced. Existing downscoped-token CAB checks still apply
Cloud Run jobs, worker pools, instances, invocation and operations, all other services Not IAM-enforced, including any policies those services store

Valid Floci-issued service-account tokens activate IAM evaluation on every supported surface. Mint one through the existing IAM Credentials generateAccessToken endpoint and pass it as Authorization: Bearer TOKEN or through your SDK credentials provider. For plaintext gRPC, Google credentials may refuse an insecure channel before the request reaches the emulator; use a fixed authorization header with the SDK's no-credentials provider, or use the emulator's TLS transport. Anonymous requests and external credentials bypass Resource Manager, Cloud Run, Cloud Logging sinks, Secret Manager, Pub/Sub, and IAM service-account evaluation. GCS evaluation treats those callers as anonymous so allUsers policies work. In enforce mode, an unknown or expired Floci-issued token receives UNAUTHENTICATED; an evaluated caller without a matching grant receives 403 PERMISSION_DENIED over REST or PERMISSION_DENIED over gRPC. GCS applies the Credential Access Boundary before IAM and retains the source principal for IAM evaluation of valid downscoped credentials. Downscoped tokens cannot expand their boundary into project or bucket management permissions.

This is a local permission-testing tool, not an authentication/security boundary. Anonymous or external callers can still mint emulator credentials because those identities bypass policy evaluation. A test using such credentials can pass without exercising IAM.

The framework supports child-to-project inheritance and multiple required permission checks. Bucket evaluation includes the owning project's policy; the project cannot be inferred from the projects/_/buckets/... resource name and is read from the stored bucket metadata. Pub/Sub resources, Cloud Run services, and Secret Manager secrets inherit their project policy. Project bindings do not authorize or restrict other services without a registered adapter. testIamPermissions evaluates each requested permission for the same caller and resource; missing resources keep the existing empty-result behavior. Disabled mode and bypass callers retain the existing permission echo.

Bucket policies inherit to objects. Restore requires storage.objects.restore and storage.objects.create, plus storage.objects.delete when it replaces a live object. Move accepts storage.objects.move on the source, or both storage.objects.get and storage.objects.delete, and requires storage.objects.create on the destination. Resumable-upload permissions are established when the session is opened; the session URI then acts as the authorization token for status queries and chunks, including requests without an Authorization header.

XML multipart upload IDs are not authentication tokens. Every initiate, part upload, completion, list, list-parts, and abort request evaluates its documented storage.multipartUploads.* permission. Uploading parts and completing an upload also require storage.objects.create; completion requires storage.objects.delete when it replaces a live object.

For a downscoped token derived from a Floci-issued IAM Credentials impersonated token, Floci preserves the source service-account identity. Object requests first satisfy the token's Credential Access Boundary (CAB), then satisfy the bucket policy for that service account. Consequently, a bucket policy cannot extend a CAB grant, and a CAB cannot extend a bucket-policy grant. A downscoped token from an external source credential has no named IAM identity and, in enforce mode, can match only an allUsers binding.

Bucket enforcement bootstrap

When Floci can resolve a new bucket's caller from a valid Floci-issued impersonated token, it persists a bucket-level roles/storage.admin binding for that service-account member. This lets the creator manage the bucket after the emulator is started with authorization-mode: enforce.

For callers without a resolvable identity, set FLOCI_GCP_SERVICES_IAM_BOOTSTRAP_ADMIN_MEMBER to an IAM member such as serviceAccount:admin@example.iam.gserviceaccount.com. That member receives roles/storage.admin on every subsequently created bucket. Treat this setting as an administrator credential: it is deliberately powerful, and an allUsers value makes every new bucket publicly manageable. The setting accepts only serviceAccount: members, allAuthenticatedUsers, or allUsers.

Supported roles and conditions

The finite catalog includes the implemented-operation permissions from:

  • roles/browser and roles/resourcemanager.projectIamAdmin.
  • roles/owner, roles/editor, and roles/viewer, restricted to the declared service permissions. Editor/viewer permit project metadata and policy reads, but not project policy writes.

In enforce mode, project policies cannot contain allUsers or allAuthenticatedUsers. Such bindings produce INVALID_ARGUMENT on policy writes and when evaluating previously stored project policies. Disabled mode retains permissive policy storage.

The finite catalog also contains roles/storage.objectViewer, roles/storage.objectCreator, roles/storage.objectUser, roles/storage.objectAdmin, and roles/storage.admin for the explicitly enforced bucket and object permissions. Secret Manager roles, permission targets, and inheritance are described in the Secret Manager guide. Uncatalogued roles grant no permissions and do not block known bindings, including when they apply to the caller. Missing resource/operation mappings on an enforcing adapter produce a named FAILED_PRECONDITION. The shared google.iam.v1.IAMPolicy gRPC mixin enforces project, service-account, Cloud Run service, Secret Manager secret, and Pub/Sub topic, subscription, and snapshot policy resources. It rejects resource kinds without a registered mapping for recognized callers in enforce mode. Those policy APIs support anonymous setup calls. Unsupported CEL expressions produce INVALID_ARGUMENT; they are not silently treated as a policy denial.

Version 3 bindings use the existing restricted IAM Conditions profile, including resource service/type/name, string comparisons and prefixes, logical operators, and request-time comparison. The CEL standard library is not enabled. The catalog and condition profile are subsets of Google Cloud IAM.

Cloud Logging sink management checks project and organization sink methods over REST and gRPC; see sink management IAM. Cloud Logging GCS sinks authorize fresh object creation as their persisted writer principal, including bucket/project policy grants and supported conditions. They do not use the logging caller's credentials. See GCS export.

Service-account enforcement

The following inventory covers the implemented IAM v1 REST methods. Links point at the exact Google API method contract. P is projects/{project}; SA is P/serviceAccounts/{email}; K is SA/keys/{key}.

Method Required permission Authorization target Implemented transport
create iam.serviceAccounts.create P REST POST
list iam.serviceAccounts.list P REST GET
get iam.serviceAccounts.get SA REST GET
update, patch iam.serviceAccounts.update SA REST PUT, PATCH
delete iam.serviceAccounts.delete SA REST DELETE
disable iam.serviceAccounts.disable SA REST POST
enable iam.serviceAccounts.enable SA REST POST
keys.create iam.serviceAccountKeys.create SA REST POST
keys.list iam.serviceAccountKeys.list SA REST GET
keys.get iam.serviceAccountKeys.get K REST GET
keys.delete iam.serviceAccountKeys.delete K REST DELETE
getIamPolicy iam.serviceAccounts.getIamPolicy SA REST POST, shared IAM v1 gRPC
setIamPolicy iam.serviceAccounts.setIamPolicy SA REST POST, shared IAM v1 gRPC
testIamPermissions No prerequisite permission; filters requested permissions through the evaluator SA REST POST, shared IAM v1 gRPC
signBlob iam.serviceAccounts.signBlob SA IAM v1 REST POST
generateAccessToken iam.serviceAccounts.getAccessToken SA IAM Credentials v1 REST POST
generateIdToken iam.serviceAccounts.getOpenIdToken SA IAM Credentials v1 REST POST
Credentials signBlob iam.serviceAccounts.signBlob SA IAM Credentials v1 REST POST
Credentials signJwt iam.serviceAccounts.signJwt SA IAM Credentials v1 REST POST

Service-account policies and project policies participate in each account/key check. Key operations use the account's policy and owning project, with the key name as the evaluation target for get/delete. Account IDs, unique IDs, and the projects/- wildcard resolve through the existing service-account resolver to a canonical email policy key. Authorization resolves names without migrating policies. When the canonical email policy is absent, it reads legacy account-ID, unique-ID, and wildcard-address policies without changing their keys. An existing canonical policy takes precedence, including an empty policy. Policy methods may subsequently adopt legacy policy keys using the existing migration path.

Creation and deletion clear the account's direct policies, including legacy aliases. Account updates, policy writes, migration, and these lifecycle transitions use ordered policy locks, so an update cannot republish a deleted account and a replacement cannot inherit its previous direct policy. Policy reads and writes require an existing account. Permission tests on missing accounts addressed by project ID return an empty permission list, following the shared IAM policy contract. This implements the local resource boundary; Google treats a recreated service account as a separate identity. Floci's email-based principal matching does not reproduce Google's deleted-principal and undelete lifecycle.

The Google IAM roles and permissions reference defines these finite role slices for the implemented permissions:

Role Supported IAM permission slice
roles/iam.serviceAccountAdmin Service-account create, get, list, update, delete, disable, enable, getIamPolicy, setIamPolicy
roles/iam.serviceAccountKeyAdmin Key create, get, list, delete; service-account get, list
roles/iam.serviceAccountUser Service-account get, list; actAs is not an implemented operation
roles/iam.serviceAccountTokenCreator Service-account get, list, getAccessToken, getOpenIdToken, signBlob, signJwt
roles/viewer Service-account get, list, getIamPolicy; key get, list
roles/editor Viewer slice plus service-account create, update, delete, disable, enable and key create, delete
roles/owner Editor slice plus service-account setIamPolicy

Each listed predefined IAM role also contributes resourcemanager.projects.get for the supported Resource Manager adapter. Basic roles do not grant getAccessToken, getOpenIdToken, signBlob, or signJwt. These are explicit slices of Google's roles, not the full production role catalog.

The local evaluator exposes resource.service = 'iam.googleapis.com', resource.type = 'iam.googleapis.com/ServiceAccount' (or iam.googleapis.com/Key), and canonical email-based resource.name values. Create/list use the project attributes. Supported equality, prefix, and logical conditions use the shared condition subset. Google does not document these IAM resource attributes in its supported resource attribute table. Treat this as local scope-testing behavior, not proof that the same expression or alias representation works in production. Exact GCP condition evaluation, error messages/metadata, and revocation timing have not been verified live.

Authorization happens in the shared REST filter or gRPC interceptor before the controller invokes an operation. Denied management requests must leave accounts, keys, and policies unchanged; denied credential requests must not issue a token or signing response. The existing filters do not hold policy locks across the subsequent mutation, so they provide no atomic policy-revocation guarantee.

Service-account undelete, key upload, key enable/disable, and IAM v1 signJwt are unimplemented. Only the shared IAM policy gRPC mixin is exposed; IAM admin and IAM Credentials gRPC services are not implemented. Non-empty credential delegation chains fail with FAILED_PRECONDITION for evaluated callers; disabled and bypass callers retain the existing permissive behavior. IAM permissions alone do not define a fixed list of roles a caller may grant; Organization Policy constraints for limiting grants are unsupported.

Custom roles

The IAM v1 projects.roles and organizations.roles REST methods create, read, and manage custom roles. R is projects/{project}/roles/{role} or organizations/{organization}/roles/{role}; P is its parent.

Method Required permission Authorization target Implemented transport
create iam.roles.create P REST POST /v1/{P}/roles
list iam.roles.list P REST GET /v1/{P}/roles
get iam.roles.get R REST GET /v1/{R}
patch iam.roles.update R REST PATCH /v1/{R}
delete iam.roles.delete R REST DELETE /v1/{R}
undelete iam.roles.undelete R REST POST /v1/{R}:undelete

Role targets evaluate their parent's allow policy. The local evaluator exposes resource.type = 'iam.googleapis.com/Role' and the role name for conditions; create and list use the parent's attributes. Organization targets read the policy stored under organizations/{organization}. Resource Manager organization policy methods are not implemented, so evaluated callers are denied organization-role management unless an organization policy was stored through the shared IAM policy gRPC mixin, which accepts organization names only from anonymous and external callers.

The Google IAM roles and permissions reference defines these slices:

Role Supported permission slice
roles/iam.roleAdmin, roles/iam.organizationRoleAdmin iam.roles.create, delete, get, list, undelete, update; resourcemanager.projects.get, getIamPolicy
roles/iam.roleViewer, roles/iam.organizationRoleViewer iam.roles.get, list; resourcemanager.projects.get, getIamPolicy

roles/owner also holds all six iam.roles.* permissions; roles/editor and roles/viewer hold iam.roles.get and iam.roles.list, matching gcloud iam roles describe.

Role definitions

Roles are persisted with the configured storage mode under their full resource name. Create takes the roleId and role fields of the request. Limits and validation follow GCP:

  • Role IDs are 3 to 64 letters, digits, underscores, or periods.
  • The title is limited to 100 UTF-8 bytes, the description to 300, and the role to 3,000 permissions, counting duplicates.
  • Permissions containing * are rejected. Other permissions are stored as sent: GCP also rejects unknown and organization-only permissions with 400 INVALID_ARGUMENT Permission X is not valid., which Floci cannot check without a full permission catalog.
  • stage defaults to ALPHA, which responses omit. includedPermissions also accepts a single string.

List returns the BASIC view without includedPermissions unless view=FULL, hides deleted roles unless showDeleted=true, and pages 300 roles by default; a pageSize above 1,000 or below zero is rejected. Patch applies updateMask (title, description, includedPermissions, stage) or, without a mask, replaces all four and clears the fields absent from the request. A name in the patch body must equal the path. Delete marks the role deleted and undelete restores it; deleted roles are never purged, so their IDs stay reserved.

Error codes: duplicate IDs return ALREADY_EXISTS; reusing a deleted role's ID, updating or deleting a deleted role, and undeleting an active one return FAILED_PRECONDITION; unknown roles return NOT_FOUND; a mismatched etag on update, delete, or undelete returns ABORTED. On a deleted role, update reports the stale etag first and delete reports the deleted state first; undelete reports an active role before a stale etag. These codes and messages, including those for malformed or non-string etags, out-of-range page sizes, invalid update masks and role names, and fields of the wrong JSON type, were checked against GCP. Two cases were not observed: a non-string includedPermissions entry reuses Permission X is not valid., and a malformed etag in a patch body reuses the malformed-etag message. Denial messages use the shared enforcement text, not GCP's per-method wording. Predefined GET /v1/roles and the IAM admin gRPC role methods are not implemented.

Effective permissions

A binding to a custom role grants exactly the role's stored includedPermissions, under the same conditions as any other binding, for every operation an enforcing adapter checks. Defining a role does not implement an operation.

  • A project role grants only through allow policies stored on that project or on resources whose names are under projects/{project}/.
  • An organization role grants through policies of projects whose recorded Resource Manager parent is that organization (parent.type organization). Its own organization policy is evaluated only for organization-role management; organization policies do not inherit to projects.
  • GCS bucket policies have no project in their resource name, so custom-role bindings in bucket policies grant nothing. Bindings on the owning project's policy still apply to its buckets.
  • Missing, DISABLED, and deleted roles grant nothing. Edits, disabling, deletion, and undeletion apply to the next authorization decision for existing bindings and credentials, and survive restarts with persistent storage. GCP applied each of these within about a second in live checks.

Project identity and ancestry

  • A project policy is stored and evaluated under the project ID: projects/{number} of a known project reads, writes and inherits the same policy as projects/{id}, over REST and the shared IAM gRPC mixin. Role names and other resource policy keys keep the project segment as sent, so a role under projects/{number} and its project ID name different stored roles, and a role under projects/{number} does not grant through project policies. Organization roles grant only through policies keyed by a project ID.
  • Organization role requests name no project, so Service Usage gates them on the request's project context, which is the default project unless the request names one.
  • Folder and organization ancestry is modelled only as a project's direct parent. Projects without a parent, projects under a folder, and unknown projects grant nothing for organization roles, although GCP lets projects under a folder use their organization's roles.
  • The recorded parent is set by Resource Manager update, which checks only resourcemanager.projects.update on the project, and by a create that adopts a project first registered implicitly, which checks only resourcemanager.projects.create. Neither checks a permission on the destination, so moving a project under an organization activates that organization's roles in bindings the project already holds.
  • A project in DELETE_REQUESTED keeps its custom roles: they can still be managed and still grant, and its recorded parent still scopes organization roles.

Policy writes

In enforce mode, setIamPolicy on a resource with an enforcing adapter (projects, Pub/Sub topics, subscriptions and snapshots, Secret Manager secrets, Cloud Run services, and service accounts, over REST and the shared IAM gRPC API) checks each role-member grant that is not already in the stored policy and rejects it with 400 INVALID_ARGUMENT when it binds:

  • a custom role defined in another project, or an organization role in a project whose recorded parent is another organization or that was created without a parent: Role (NAME) does not exist in the resource's hierarchy.
  • a custom role that does not exist: Role (NAME) does not exist in resource's hierarchy.
  • a deleted custom role: Cannot add new grants to deleted role (NAME).

Grants already in the stored policy are kept, so bindings to a role deleted later stay in the policy and grant nothing. Placements the emulator cannot decide are accepted: organization roles in projects under a folder, in projects registered implicitly, or in unknown projects, and project numbers that are not registered. Predefined roles are not checked. In disabled mode, and for resources without an enforcing adapter (GCS bucket policies, Cloud Functions, Cloud Run jobs, worker pools and instances, organization policies), all bindings are stored as sent.

A binding to a missing, deleted, or disabled custom role is skipped without checking its condition. Creating, undeleting, or enabling that role makes the binding apply, and an unsupported condition on it then fails the member's evaluated requests on that policy with INVALID_ARGUMENT until the binding is removed by a caller that bypasses evaluation or the role is disabled again.

STS exchanges and metadata credentials retain their existing emulator behavior. The OAuth /token exchange authenticates a service-account JWT only in enforce mode; see OAuth token exchange. Anonymous/external credential bypass makes this emulator a local testing tool, not a security boundary. IAM v1 signBlob returns the keyId and signature fields required by its contract. IAM v1 and Credentials signing share the emulator's per-account RSA key described in Sign Blob. This is a local key, not a Google-managed production credential.

OAuth token exchange

The token endpoint (/token and the legacy /oauth2/v4/token) exchanges a service-account JWT for an access token with the jwt-bearer grant described in Using OAuth 2.0 for Server to Server Applications. With the default disabled mode it returns a token for any assertion, and that token is not a recognized identity. In enforce mode the assertion is checked as below, and every refusal is 400 except the disabled account's 401. The checks run in the order Google's token endpoint runs them, so an assertion with several faults gets the answer of the first: an assertion signed with an unrelated key still gets the audience, timeframe, missing claim and empty scope answers below, and only one that passes them gets Invalid JWT Signature.. The messages Google's documentation does not list were measured against https://oauth2.googleapis.com/token in the review of #644.

  • The assertion must be three Base64url segments, the first two JSON objects; otherwise the response is invalid_request with Bad Request.
  • iss must name an existing service account; otherwise, including for a deleted account, the response is invalid_grant with Invalid grant: account not found.
  • aud must be https://oauth2.googleapis.com/token, the legacy https://www.googleapis.com/oauth2/v4/token, or the emulator URL the request was sent to, so that a credential whose token_uri points at the emulator works. A missing or other audience gets invalid_grant with Invalid JWT: Failed audience check..
  • iat and exp must be set, or the response is invalid_grant with Invalid JWT: iat (issued at) is not set. or Invalid JWT: exp (expiration time) is not set.. exp must not precede iat, must be at most 65 minutes after it, and must not have passed, and iat must not be more than 5 minutes ahead of the emulator's clock (Google refuses an iat 10 minutes ahead and accepts one 2 minutes ahead); otherwise the response is invalid_grant with Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your iat and exp values in the JWT claim.
  • scope must be a non-empty string; a missing or blank one gets invalid_scope with Invalid OAuth scope or ID token audience provided., which Google documents for "No scopes were requested (empty list of scopes)", and a JSON array gets invalid_scope with Empty or missing scope not allowed..
  • The JWT must be signed with RS256 by a user-managed key of the account, created through keys.create and still valid, or by its Google-managed key, as IAM Credentials signJwt signs: Google's domain-wide delegation best practices say "Using service account keys is not necessary to perform domain-wide delegation. Use the signJwt API instead.", and that delegation is obtained by exchanging the signed JWT at the token endpoint. The kid header is tried first; "if an incorrect Key ID is specified, all keys associated with the service account are tried". Otherwise, including for a deleted key, the response is invalid_grant with Invalid JWT Signature., which Google documents for a key "not associated with the service account identified by the client email or the key that was used has been deleted, disabled, or has expired".
  • Every scope must be a Google OAuth 2.0 scope; otherwise the response is invalid_scope with Invalid OAuth scope or ID token audience provided., which Google documents for "one of the requested scopes doesn't exist (i.e. is invalid)." The scopes are checked against the bundled catalog described below, so a scope of an API Floci does not emulate is accepted.
  • The account must not be disabled; otherwise the response is 401 with disabled_client and The OAuth client was disabled., the row of the "JWT error codes" table of Using OAuth 2.0 for Server to Server Applications for "The key used to sign the JWT assertion is disabled", resolved by enabling the service account. This answer comes from Google's documentation and was not measured: the table gives no HTTP status, so Floci answers 401, as Google does for other client errors such as invalid_client, and checks it last. This check and the one on iss run again under the lock that revocation takes, against the account whose key verified the assertion, so an account deleted or disabled while its assertion is checked gets no token. An account created with the same email in the meantime is not that account: the assertion gets invalid_grant with Invalid grant: account not found, as for a deleted account.
  • The access token is valid for 3600 seconds and acts as the service account on every enforcing surface, like a token from IAM Credentials generateAccessToken.

The response has no scope field.

The scope catalog, src/main/resources/oauth/oauth-scopes.json, is the union of the scopes that every API version listed by the Google API Discovery directory (all versions, not only the preferred ones) declares under auth.oauth2.scopes, plus email, openid and profile, which OAuth 2.0 Scopes for Google APIs lists under "Google Sign-In". The file names its sources and its generation date. To regenerate it, run python3 tools/regen_oauth_scopes.py from the repository root; it uses only the Python standard library and the network, and nothing reads the network at build or test time.

Remaining limitations

  • Object-list conditions authorize the bucket-level storage.objects.list permission but do not filter returned objects.
  • GCS gRPC and ACL operations are not restricted by IAM allow policies. Signed-URL identity is also outside the evaluator: because the emulator does not cryptographically verify V4 signatures, signed URLs are treated as anonymous and can access only resources granted to allUsers in enforce mode.
  • Conditional GCS bindings require UBLA. A bucket update cannot disable, remove, or partially clear UBLA while conditional bindings remain configured. The full UBLA lifecycle is not implemented.
  • Organization/folder inheritance, deny policies, principal access boundaries, group/domain membership expansion, workforce/workload identities, and organization policy constraints are not implemented.
  • Service-account address aliases resolve to canonical email policy names, and a known project's number resolves to its project ID for project policies. Other resource names are evaluated as requested, so projects/{number}/... child resources keep their own policy keys.
  • Only declared operation permissions are checked. Dependent service-agent, actAs, push-authentication, BigQuery export, CMEK, and other cross-service grants are not validated. This emulator cannot prove those configurations work in GCP.
  • Shared REST/gRPC interceptors do not hold policy locks through business mutations. GCS object operations and Logging GCS export use service-level locks through publication; other integrations must provide their own consistency boundary.
  • The emulator does not validate that a predefined role is grantable on the policy resource. Custom-role bindings are checked as described in Policy writes. Unsupported permissions in a known role are absent from the catalog.

See Adding an enforcing service for the shared extension contract, test requirements, and upstream evidence.

Quick Start

gcloud config set project floci-local

# Create a service account
gcloud iam service-accounts create my-sa \
    --display-name="My Service Account"

# List service accounts
gcloud iam service-accounts list

# Create a key
gcloud iam service-accounts keys create key.json \
    --iam-account=my-sa@floci-local.iam.gserviceaccount.com

# Delete a key
gcloud iam service-accounts keys delete KEY_ID \
    --iam-account=my-sa@floci-local.iam.gserviceaccount.com
# Create service account
curl -X POST http://localhost:4588/v1/projects/floci-local/serviceAccounts \
  -H "Content-Type: application/json" \
  -d '{"accountId":"my-sa","serviceAccount":{"displayName":"My SA"}}'

# List service accounts
curl http://localhost:4588/v1/projects/floci-local/serviceAccounts

# Get service account
curl http://localhost:4588/v1/projects/floci-local/serviceAccounts/my-sa@floci-local.iam.gserviceaccount.com

# Delete service account
curl -X DELETE http://localhost:4588/v1/projects/floci-local/serviceAccounts/my-sa@floci-local.iam.gserviceaccount.com

Service Accounts

Service accounts follow the GCP naming convention:

projects/{project}/serviceAccounts/{account}@{project}.iam.gserviceaccount.com

The - wildcard can replace the project ID in any service account or key name (projects/-/serviceAccounts/{EMAIL_ADDRESS|UNIQUE_ID}), which is what Terraform sends. The owning project is resolved from the account, and resource names in responses carry the real project. As on GCP, a missing account or key addressed through - returns 403 PERMISSION_DENIED instead of 404 NOT_FOUND.

Disabling a service account

serviceAccounts.disable and serviceAccounts.enable set the account's output-only disabled field, which responses include only while it is true, as proto3 JSON omits a false field. Both return an empty JSON object, and disabling a disabled account or enabling an enabled one has no effect. Addressed by its unique ID, the request acts only on the account with that ID: if it is deleted while the request runs, the answer is 404 NOT_FOUND, also when an account with the same email has been created in the meantime. As the disable reference documents, "Existing access tokens for the service account are rejected", and after the account is re-enabled "its existing access tokens will be accepted". In enforce mode, a Floci-issued token of a disabled account, or a downscoped token derived from one, is refused on every enforcing surface with 401 UNAUTHENTICATED over REST, or UNAUTHENTICATED over gRPC, and the message Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project. This is Google's answer for the ACCOUNT_STATE_INVALID reason of google/api/error_reason.proto: "the account associated with the provided access token is in an invalid state, such as disabled or deleted". The response does not carry the ErrorInfo detail Google attaches, whose metadata names the API service and method called. Deleting an account in enforce mode revokes its Floci-issued tokens, which are then refused the same way, also after an account with the same email is created again. Revocation is serialized with generateAccessToken, the token endpoint's jwt-bearer grant and STS token exchanges, so a token minted while the account is being deleted is revoked with the others, and one requested after it is refused.

As the reference says "requests for new access tokens will fail", IAM Credentials generateAccessToken, generateIdToken, signBlob and signJwt, and IAM v1 signBlob (with payload or bytesToSign, under projects/- or the account's project), refuse a disabled target account in enforce mode with the same response, instead of issuing a token or a signature. In disabled mode the field is stored and returned, and neither tokens nor IAM Credentials requests are affected.

Service Account Keys

# Create key
curl -X POST \
  http://localhost:4588/v1/projects/floci-local/serviceAccounts/my-sa@floci-local.iam.gserviceaccount.com/keys \
  -H "Content-Type: application/json" \
  -d '{}'

# List keys
curl http://localhost:4588/v1/projects/floci-local/serviceAccounts/my-sa@floci-local.iam.gserviceaccount.com/keys

IAM Policy Bindings

# Grant Secret Manager access to a service account
gcloud secrets add-iam-policy-binding my-secret \
    --member="serviceAccount:my-sa@floci-local.iam.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"

Sign Blob (V4 Signed URLs)

The IAM SignBlob endpoint is used by the GCS SDK to generate V4 pre-signed URLs:

URL signedUrl = storage.signUrl(
    BlobInfo.newBuilder("my-bucket", "hello.txt").build(),
    15, TimeUnit.MINUTES,
    Storage.SignUrlOption.withV4Signature());

SignBlob ({"bytesToSign": "<base64>"}) returns {"keyId", "signature"}: an RSASSA-PKCS1-v1_5 SHA-256 signature made with the service account's Google-managed RSA-2048 key. Each account gets one such key the first time it signs, kept until the account is deleted, and the same key signs for the IAM Credentials signBlob, signJwt and generateIdToken methods.

The signing key is not returned by ListServiceAccountKeys (real IAM lists it as a SYSTEM_MANAGED key), so its public half cannot be read back and signatures cannot be verified against it locally. Nothing in floci-gcp verifies them: GCS checks a signed URL's expiry, not its signature.

Supported Operations

  • CreateServiceAccount
  • GetServiceAccount
  • ListServiceAccounts
  • UpdateServiceAccount
  • PatchServiceAccount
  • DeleteServiceAccount
  • DisableServiceAccount, EnableServiceAccount
  • CreateServiceAccountKey (real RSA-2048 key pair; returns JSON key file)
  • GetServiceAccountKey
  • ListServiceAccountKeys
  • DeleteServiceAccountKey
  • GetIamPolicy
  • SetIamPolicy
  • TestIamPermissions
  • SignBlob
  • CreateRole, GetRole, ListRoles, UpdateRole, DeleteRole, UndeleteRole for project and organization custom roles

generateAccessToken (the iamcredentials.googleapis.com API used by ImpersonatedCredentials) is provided by the separate IAM Credentials service, toggled with FLOCI_GCP_SERVICES_IAMCREDENTIALS_ENABLED.