Google Cloud IAM

Google Cloud IAM controls who can do what on Google Cloud projects, folders and organizations. Owlie syncs the principals that hold IAM role bindings under a scope you choose, together with the resources, roles and service accounts those bindings involve. It adds and removes role bindings on resources and on service accounts. Owlie does not create or manage Google Cloud user accounts, because Google Cloud has no API for them. It matches principals to your identities by email, and works alongside the Google Workspace connector.

Capabilities

Capability	Supported	Details
Sync	Yes	Principals, resources, roles, service accounts, service account keys, and the role bindings on resources and on service accounts.
Incremental sync	No	Google's list APIs have no changed-since filter, so each run reads everything again.
Account provisioning	Grants only	Principals are not created, updated, disabled or deleted. Owlie waits for sync to link a person's principal, then writes role bindings.
Grant writes	Yes	Role bindings on projects, folders and organizations, and role bindings on a service account's own IAM policy.
Notifications	No

Authentication

Option	Choose it when
Google Cloud service account	You can create a service account key. Owlie signs a JWT with the key and exchanges it for an access token (the OAuth 2.0 JWT bearer flow).
OAuth (admin consent)	An administrator should sign in with their own Google account and consent. You provide the OAuth client ID and secret of your own client.

Both options request the https://www.googleapis.com/auth/iam and https://www.googleapis.com/auth/cloud-platform scopes. The OAuth option asks for offline access so Google issues a refresh token.

Get credentials from Google Cloud

Prepare the project and permissions

1. In the Google Cloud project the credentials belong to (for a service account key, the project the service account lives in), enable the Identity and Access Management (IAM) API, the Cloud Resource Manager API and the Cloud Asset API.
2. Grant the credentials roles on the scope you will configure. Grant only what the features you use need.

To do this	Standard roles
Sync principals and role bindings	Cloud Asset Viewer (roles/cloudasset.viewer), Security Reviewer (roles/iam.securityReviewer)
List projects and folders under the scope	Browser (roles/browser)
List roles, predefined and custom	Role Viewer (roles/iam.roleViewer)
Sync service accounts and their keys	Service Account Viewer (roles/iam.serviceAccountViewer) on the project
Add and remove role bindings	Security Admin (roles/iam.securityAdmin), or the IAM Admin role of the resource type (project, folder or organization)

Google's IAM roles reference lists the permissions in each role.

Service account

1. Follow Google's guide to create a service account.
2. Create a JSON key for it and keep the client_email and private_key values.
3. Grant the service account the roles above on your scope.

OAuth (admin consent)

1. In the Google Cloud console, create an OAuth client by following Google's OAuth 2.0 guide, and add Owlie's redirect URL to it.
2. Keep the client ID and client secret.
3. The administrator who consents needs the roles above on your scope.

Connect Google Cloud IAM in Owlie

Field	Required	What to enter
Organization / folder / project scope	Yes	The resource whose role bindings Owlie searches and whose resources it syncs: organizations/123456789, folders/123456789 or projects/my-project-123.
Project (service accounts)	For service accounts, keys and project custom roles	The project ID, not its number, such as my-project-123. Owlie syncs this project's service accounts and keys and lists its custom roles.
Service account email	Service account option	The service account's email address.
Private key (PEM)	Service account option	The service account's private key. Owlie stores it as a secret.
OAuth client ID	OAuth option	The client ID of your OAuth client.
OAuth client secret	OAuth option	The client secret. Owlie stores it as a secret.

The project ID must be Google's standard form: 6 to 30 lowercase letters, digits and hyphens, starting with a letter. Legacy domain-scoped project IDs such as example.com:proj are not accepted.

Test connection makes three reads, each for at most one item: the project's service accounts (or the role catalog when no project is set) from the IAM API, IAM policies under the scope from the Cloud Asset API, and the scope's IAM policy from the Cloud Resource Manager API.

Entities

Entity	In Google Cloud IAM	Identifier	Key attributes	Sync	Create	Update	Delete	Grants (as target)
Principal	A user, service account, group or domain that holds a role binding under the scope. The account entity.	email	email, kind, displayName	Yes	No	No	No	No
Role	A predefined or custom IAM role.	name	name, title, stage	Yes	No	No	No	role_binding, service_account_role
Resource	A project, folder or organization that IAM policies attach to.	name	name, displayName, type	Yes	No	No	No	No
Service account key	A user-managed key of a service account.	name	name, keyType, validBeforeTime, disabled	Yes	No	No	No	No
Service account	An application identity in the configured project.	name	email, displayName, disabled	Yes	No	No	No	No

Principals are discovered from Cloud Asset searchAllIamPolicies. Users match your identities by email. Service accounts, groups and domains are synced but are not treated as people. Owlie skips allUsers, allAuthenticatedUsers, deleted: members, convenience members such as projectOwner: and federated principal:// identities.

Resource names are the canonical ones Google returns (projects/{number}), even when you configure the scope with a project ID. An organization or folder scope is walked through Resource Manager, listing the projects and folders under each parent.

Grant kinds

Grant kind	In Google Cloud IAM	Principal → target	Writable	Qualifiers
role_binding	A principal holds a role on a project, folder or organization.	Principal → Role	Yes	resource: required, the project, folder or organization. memberType: user, serviceAccount, group or domain; default user.
service_account_role	A principal holds a role on a service account's own IAM policy (who may use or impersonate it).	Principal → Role	Yes	resource: required, the service account's resource name. memberType: as above.

Each resource's own policy is read with getIamPolicy, so the bindings of a resource are exactly the bindings set on it. Bindings on descendants are read on their own resources.

Provisioning behavior and limits

Owlie reads a policy at version 3 and writes it back with the etag it read. A write that loses the etag race (HTTP 409 ABORTED) re-reads the policy and tries once more.

Owlie manages only unconditional bindings. Adding a role reports the binding as already present only when the member is in an unconditional binding of that role. Removing a role takes the member out of every unconditional binding of the role and drops any binding that becomes empty. Bindings with an IAM condition are not synced as Grants and a write never edits them.

Warning: if a principal still holds the role through a conditional binding, a remove does not report the access gone. It writes the unconditional removal when there is one, then fails with a message that the principal still has the role through a conditional binding that Owlie does not manage. Remove those bindings in Google Cloud.

A policy that cannot be read, including a 404, fails the write. Owlie never reads a failed read as "already gone".

Owlie does not:

• create or manage human user accounts;
• write Policy Bindings v3, because their asynchronous long-running operations cannot be confirmed;
• write or sync IAM Conditions;
• generate service account keys, because creating a key returns a private key that must not pass through the connector;
• manage Google Groups membership. Use the Google Workspace connector for that.

An organization with a very large number of folders makes the resource cursor large, because the cursor carries the queue of folders still to list.

Troubleshooting

Symptom	Cause and fix
Identity and Access Management (IAM) API is not enabled, or the same for the Cloud Resource Manager API or the Cloud Asset API	The API is off in the project. Enable it in the Google Cloud console and retry. Google's own message, which carries the enable link, follows the sentence.
Google Cloud rejected the credentials while reading ...	Google answered 401. Check the service account email and private key, or reconnect OAuth.
The credentials are valid but may not read ...	Google answered 403 PERMISSION_DENIED. Grant the credentials the roles listed above on the scope or project.
Google Cloud could not read ... Check that the scope and project exist.	Google answered 404. Check the scope and the project ID.
The scope must look like projects/my-project-123, folders/123 or organizations/123456	The scope field is malformed. Use one of the three forms.
A project must be configured to sync service accounts (or ... to sync service account keys)	Service accounts and keys sync only for the configured project. Set the project ID.
the principal still has the role through a conditional binding that Owlie does not manage, or The principal has this role only through a conditional binding that Owlie does not manage, so nothing was removed.	The remove found the role held through an IAM condition. Remove the conditional binding in Google Cloud.
The IAM policy changed since it was read (etag mismatch).	Another change landed between Owlie's read and write, twice in a row. Run the change again.

Changelog

Google Cloud IAM is at connector version 1. Owlie displays its changelog in the integration catalog.