> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Map IAM policy bindings

The iamPolicy kind syncs explicit GCP IAM allow-policy bindings through Cloud Asset Inventory's searchAllIamPolicies method.

A GCP policy holds a list of bindings, and each binding grants one role to one or more members. The integration expands them so that Port holds one entity per member grant, which lets you search and report on who holds which role on which resource.

This kind is not part of the integration's default mapping, so we will add both the blueprint and the mapping configuration ourselves.

This kind needs an extra permission

The integration's service account needs cloudasset.assets.searchAllIamPolicies on every project in scope. The Cloud Asset Viewer role (roles/cloudasset.viewer) includes it. A project the service account cannot read IAM policies on fails the resync, and Port then skips the deletion phase for every kind in your configuration until you grant the permission.

What is included​

The iamPolicy kind returns the bindings attached directly to a resource. Keep these boundaries in mind when you model access:

  • Grants attached to folders and organizations are not returned, because the integration searches each project's scope.
  • Inherited access is not resolved. A member who reaches a resource through a project-level or folder-level grant does not appear on that resource.
  • Deny policies are not included, only allow policies.

Create the blueprint​

Create the following blueprint in Port. It represents a single grant, and relates to both the project the policy lives in and the resource the policy is attached to.

IAM policy binding blueprint (click to expand)
{
"identifier": "gcpIamPolicyBinding",
"description": "One resource-level GCP IAM allow-policy binding: one member granted one role on one resource. Folder- and organization-level grants are not included, and inherited access is not resolved.",
"title": "GCP IAM Policy Binding",
"icon": "GoogleCloud",
"schema": {
"properties": {
"role": {
"type": "string",
"title": "Role",
"description": "The IAM role granted, e.g. roles/storage.objectViewer"
},
"member": {
"type": "string",
"title": "Member",
"description": "The principal the role is granted to, e.g. serviceAccount:a@b.iam.gserviceaccount.com"
},
"resource": {
"type": "string",
"title": "Resource",
"description": "Full resource name the policy is attached to"
},
"assetType": {
"type": "string",
"title": "Asset Type",
"description": "GCP asset type of the resource, e.g. iam.googleapis.com/ServiceAccount"
},
"condition": {
"type": "object",
"title": "Condition",
"description": "The IAM condition attached to this binding, if any"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {
"project": {
"target": "gcpProject",
"title": "Project",
"required": false,
"many": false
},
"cloudResource": {
"title": "Cloud Resource",
"target": "gcpCloudResource",
"required": false,
"many": false
}
}
}

Create the integration configuration​

Add the following block to your integration configuration. Replace the assetTypes list with the asset types whose bindings you want to ingest.

Mapping configuration for IAM policy bindings (click to expand)
resources:
- kind: iamPolicy
selector:
query: "true"
assetTypes:
- iam.googleapis.com/ServiceAccount
port:
itemsToParse: '(.policy.bindings // []) | map(. as $b | $b.members[] | {role: $b.role, member: ., condition: $b.condition})'
entity:
mappings:
identifier: '(.resource + "|" + .item.role + "|" + .item.member + ((.item.condition // {}) | tojson)) | @base64'
title: '.item.member + " -> " + .item.role + " on " + (.resource | split("/") | last)'
blueprint: '"gcpIamPolicyBinding"'
properties:
role: .item.role
member: .item.member
resource: .resource
assetType: .asset_type
condition: .item.condition
relations:
project: .project
cloudResource: 'select(.asset_type != "cloudresourcemanager.googleapis.com/Project") | (.resource | sub("^//[^/]+/"; ""))'

The configuration structure​

  • The kind field is iamPolicy. It is a kind name used by the integration, not a GCP asset type.

    resources:
    - kind: iamPolicy
    selector:
    ...
  • The assetTypes selector is required, and it limits the search to the asset types you list.

    resources:
    - kind: iamPolicy
    selector:
    query: "true"
    assetTypes:
    - iam.googleapis.com/ServiceAccount
    - storage.googleapis.com/Bucket

    GCP searches every asset type when the list is omitted, which can produce tens of thousands of entities from a single organization. The integration requires the list so that you choose the blast radius. Use the asset type strings from the Cloud Asset supported resource types.

  • The policyQuery selector is optional, and it passes a server-side filter to GCP. For example, the following value returns only grants held by service accounts.

    resources:
    - kind: iamPolicy
    selector:
    query: "true"
    assetTypes:
    - iam.googleapis.com/ServiceAccount
    policyQuery: "memberTypes:serviceAccount"

    The supported syntax is documented in searching IAM policies.

  • The itemsToParse field expands one policy into one item per member grant, and each item is then available under .item in the mappings.

    port:
    itemsToParse: '(.policy.bindings // []) | map(. as $b | $b.members[] | {role: $b.role, member: ., condition: $b.condition})'
  • The identifier field is base64 encoded, because IAM uniqueness is the combination of resource, role, member and condition, and a condition expression can contain characters that Port does not accept in an identifier. The readable form of the grant is kept in the entity title.

Relating a grant to its resource

The cloudResource relation strips the Cloud Asset Inventory prefix from .resource, because gcpCloudResource entities are identified by the inner GCP resource name. A grant on //iam.googleapis.com/projects/my-project/serviceAccounts/sa@my-project.iam.gserviceaccount.com relates to the cloud resource projects/my-project/serviceAccounts/sa@my-project.iam.gserviceaccount.com.

The select guard excludes cloudresourcemanager.googleapis.com/Project. A project's own IAM policy produces a grant whose resource is the project itself, and projects are ingested as gcpProject entities identified by the project number, so a gcpCloudResource target would never resolve. Those grants carry the project relation instead.

For every other asset type, the relation resolves only if you also ingest that asset type as a resource. When the target does not exist, createMissingRelatedEntities creates a placeholder entity, and placeholders are not removed by later resyncs. Add the asset types you grant on to your cloudResource mapping before you ingest their bindings.

Sample payload and resulting entities​

The payload below is a single result from searchAllIamPolicies for a service account that carries two bindings.

Sample IAM policy payload (click to expand)
{
"resource": "//iam.googleapis.com/projects/my-project/serviceAccounts/sa@my-project.iam.gserviceaccount.com",
"project": "projects/123456789012",
"policy": {
"bindings": [
{
"role": "roles/iam.serviceAccountAdmin",
"members": [
"serviceAccount:sa@my-project.iam.gserviceaccount.com"
]
},
{
"role": "roles/owner",
"members": [
"serviceAccount:sa@my-project.iam.gserviceaccount.com"
]
}
]
},
"asset_type": "iam.googleapis.com/ServiceAccount",
"folders": [
"folders/210987654321"
],
"organization": "organizations/109876543210"
}

The two bindings produce two entities, one per member grant.

Resulting Port entities (click to expand)
[
{
"identifier": "Ly9pYW0uZ29vZ2xlYXBpcy5jb20vcHJvamVjdHMvbXktcHJvamVjdC9zZXJ2aWNlQWNjb3VudHMvc2FAbXktcHJvamVjdC5pYW0uZ3NlcnZpY2VhY2NvdW50LmNvbXxyb2xlcy9pYW0uc2VydmljZUFjY291bnRBZG1pbnxzZXJ2aWNlQWNjb3VudDpzYUBteS1wcm9qZWN0LmlhbS5nc2VydmljZWFjY291bnQuY29te30=",
"title": "serviceAccount:sa@my-project.iam.gserviceaccount.com -> roles/iam.serviceAccountAdmin on sa@my-project.iam.gserviceaccount.com",
"blueprint": "gcpIamPolicyBinding",
"properties": {
"role": "roles/iam.serviceAccountAdmin",
"member": "serviceAccount:sa@my-project.iam.gserviceaccount.com",
"resource": "//iam.googleapis.com/projects/my-project/serviceAccounts/sa@my-project.iam.gserviceaccount.com",
"assetType": "iam.googleapis.com/ServiceAccount",
"condition": null
},
"relations": {
"project": "projects/123456789012",
"cloudResource": "projects/my-project/serviceAccounts/sa@my-project.iam.gserviceaccount.com"
}
},
{
"identifier": "Ly9pYW0uZ29vZ2xlYXBpcy5jb20vcHJvamVjdHMvbXktcHJvamVjdC9zZXJ2aWNlQWNjb3VudHMvc2FAbXktcHJvamVjdC5pYW0uZ3NlcnZpY2VhY2NvdW50LmNvbXxyb2xlcy9vd25lcnxzZXJ2aWNlQWNjb3VudDpzYUBteS1wcm9qZWN0LmlhbS5nc2VydmljZWFjY291bnQuY29te30=",
"title": "serviceAccount:sa@my-project.iam.gserviceaccount.com -> roles/owner on sa@my-project.iam.gserviceaccount.com",
"blueprint": "gcpIamPolicyBinding",
"properties": {
"role": "roles/owner",
"member": "serviceAccount:sa@my-project.iam.gserviceaccount.com",
"resource": "//iam.googleapis.com/projects/my-project/serviceAccounts/sa@my-project.iam.gserviceaccount.com",
"assetType": "iam.googleapis.com/ServiceAccount",
"condition": null
},
"relations": {
"project": "projects/123456789012",
"cloudResource": "projects/my-project/serviceAccounts/sa@my-project.iam.gserviceaccount.com"
}
}
]

The project relation maps from the payload's own project field, which GCP returns as the project number. This matches the identifier of the gcpProject entities the integration creates.