LocalCloud Cloud IAM Local Emulator
Get started
local.cloud / agents
Read this page as Markdown ↗
local.cloud — Cloud IAM Local Emulator .md Open tab

Cloud IAM

Identity and Access Management connects principals, roles, and permissions to resources. It defines who can perform which actions in a Google Cloud project.

When to use Cloud IAM

Typical uses

Use when resource access depends on which user or service account is making a request, and policies must be managed and tested as part of provisioning.

Examples

  • Role and service-account provisioning
  • Policy-aware application tests

Explore another service

View all

Example usage

Service ID: cloudiam. Starts by default. Use an already running LocalCloud runtime for the examples below.

Export the local project and mapped endpoints in your client process, then use the client settings below. First-time setup

# Export GOOGLE_CLOUD_PROJECT and IAM_EMULATOR_HOST
eval "$(localcloud env)"

REST gateway examples use the generated HTTP address in SERVICE_USAGE_EMULATOR_HOST; native SDKs can use a different protocol.

Java · REST

List service accounts

List service accounts; IAM identifies application principals so you can manage their permissions.

Call the Google Cloud REST API with the JDK HTTP client. Requires JDK 17+. Results reflect resources already created in your local project.

Discovery check · reads existing local state.

Save as Hello.java

import java.net.URI;
import java.net.http.*;
import java.time.Duration;
import java.util.Objects;

public class Hello {
  public static void main(String[] args) throws Exception {
    var project = Objects.requireNonNull(System.getenv("GOOGLE_CLOUD_PROJECT"));
    var endpoint = Objects.requireNonNull(System.getenv("SERVICE_USAGE_EMULATOR_HOST"));
    var url = URI.create(endpoint.replaceAll("/+$", "") + "/v1/projects/" + project + "/serviceAccounts");
    var request = HttpRequest.newBuilder(url).timeout(Duration.ofSeconds(30)).GET().build();
    var client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
    var response = client.send(request, HttpResponse.BodyHandlers.ofString());
    if (response.statusCode() >= 400) {
      throw new IllegalStateException(response.statusCode() + ": " + response.body());
    }
    System.out.println(response.body());
  }
}

Run the example

java Hello.java

Verify the result

The request succeeds. An empty list or no printed rows is valid before matching resources exist. Continue with the documented workflows for a resource test.

Verify a resource workflow by creating isolated state, performing the operation, and reading the result back. Run cleanup even after a failure; delete only test-owned resources.

Connection failed? Check localcloud status --verbose, enabled services, and client exports. Stop accidental Google Cloud calls; correct local routing before retrying.

Documented workflows

  • Allow policies, permission checks, supported conditions, and project inheritance

    Set a project allow policy and test permissions with the chosen local principal. Exercise supported conditions and inheritance in strict mode to check denied paths as well as successful calls.

  • Custom roles and grantable-role queries

    Create a custom role, update its included permissions, and inspect grantable roles. Apply it to a fixture principal and check the permissions the application requests.

  • Service-account metadata, key enable/disable, and testable-permission queries

    Create a service-account resource, inspect testable permissions, and enable or disable an owned key. Read back the state used by provisioning and credential-management code.

  • Local access/ID tokens, impersonation, and blob/JWT signing

    Issue local access or ID tokens, impersonate a service account, or sign a blob or JWT. Verify token audience, issuer, and signature at your local receiver.

  • OIDC workload identity pools, providers, and token exchange

    Create an OIDC workload identity pool and provider, then exchange a test subject token. Check provider matching and the resulting local principal before using its credential.

Service boundaries

  • Enforcement depends on service, transport, and IAM mode; open/permissive mode is not access control
  • No full CEL, organization/folder ancestry, or deny policies; federation uses local OIDC providers
  • Tokens use the local issuer/JWKS, without Google authority
Agent testing

Use Cloud IAM with an AI agent

Before the agent changes application logic, have it create local Cloud IAM state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

Configure this repo

Set up this repository to use LocalCloud for local GCP development. First read https://local.cloud/ai/agents.md, then inspect this repo, identify the GCP services and SDK language, configure emulator environment variables, and run the narrowest integration test against localhost. Do not use real GCP credentials or production endpoints.

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

Agent resources has more prompts and the AGENTS.md template.

Related guides

Desktop view