The authorization model

Authorization in IAM is composed from a handful of small pieces rather than expressed as a single access list. This page describes each piece and how they fit together. For exact fields, request shapes, and the full set of values, see the API reference.

Role-based access control

IAM uses role-based access control (RBAC). Authority is never attached to an identity directly. Instead, a principal (a user or service account) is named in a binding that grants a role within a scope, optionally narrowed by a policy. The role collects the permissions that authorize individual API actions. A request is allowed only when one binding lines all of this up: the required permission, a scope that covers the target, and any policy conditions satisfied.

flowchart LR
  classDef primary fill:#e8e8ff,stroke:#1100ff,stroke-width:2px,color:#0e0d1a
  classDef accent fill:#e2faec,stroke:#00e64d,stroke-width:2px,color:#0e0d1a
  classDef neutral fill:#ececf1,stroke:#302e45,stroke-width:2px,color:#0e0d1a

  principal["Principal<br/>(user or service account)"]:::accent
  binding["Binding"]:::primary
  role["Role"]:::primary
  permission["Permissions"]:::primary
  scope["Scope"]:::neutral
  policy["Policy (optional)"]:::neutral
  action["API action"]:::accent

  principal -->|named in| binding
  binding -->|grants| role
  binding -->|within| scope
  binding -->|constrained by| policy
  role -->|collects| permission
  permission -->|authorizes| action

The rest of this page describes each piece in turn, then how they combine in the decision.

Principals

A principal is the entity a permission check is run against. There are two kinds: a user, the common case, and a service account, a non-human identity. A principal on its own can do nothing. Authority is always granted through a binding.

Permissions

A permission is the smallest unit of authority. Its name follows the <service>.<resource>.<action> convention:

Permission	Service	Resource	Action
compute.vm.create	compute	vm	create
iam.binding.create	iam	binding	create
iam.token.revoke	iam	token	revoke

Permissions are system-defined and read-only: you can list them and look them up, but you never create one. You reference existing permissions when composing roles. See the permissions catalogue for every permission and the operation it guards.

Roles

A role is a named collection of permissions. Two things classify it:

• Its type: a platform-managed built-in, or a custom role you create. Only custom roles are tied to a particular scope.
• Its stage: where the role sits in its lifecycle (active, deprecated, or disabled). Existing bindings keep working across a stage change, because stage does not by itself change the authorization decision today.

Permissions are attached to a role one at a time, and detached the same way. When you list a role’s permissions you get the full permission records back, so you can render names, services, and descriptions without a follow-up lookup.

Bindings and scopes

A binding is the resource that actually grants authority. It links a principal, a role, a scope, and, optionally, a policy.

The scope sets the resource boundary the grant applies within: a workspace, a group, an organisation, or the whole platform. A binding scoped to a workspace authorizes its role’s permissions only for resources in that workspace. A platform-scoped binding is the broadest: platform-wide grants such as the iam.token.revoke authority that lets an admin revoke another user’s session.

Policies and conditions

A binding can be made conditional by attaching a policy. A policy carries one or more conditions, each of one of three shapes:

• A source-IP condition matches the caller’s address against a list of CIDR ranges, either requiring the caller to be inside the ranges or outside them.
• A time-window condition restricts access to a time window in a named time zone, either within the window or outside it.
• A role condition constrains role delegation. Attached to a binding for iam.binding.create, it ensures the caller can only grant roles whose permissions fall within a listed set of services.

Policies are scoped to a workspace and managed through the API.

The decision

Putting it together, a request for an action is authorized when all of the following hold:

1. the caller is a principal with at least one binding;
2. the bound role contains the required permission;
3. the binding’s scope covers the target resource;
4. every condition in the attached policy, if any, is satisfied.

If no binding satisfies all four, the request is denied.

Invariants

• System roles are immutable. A built-in system role is managed by the platform; only custom roles are tied to a scope and accept permission edits.
• Permissions are a closed, system-defined set. You compose from them; you do not mint new ones.
• Scope is mandatory on a binding. Every binding has a scope; there is no implicit global grant short of a platform-scoped binding.
• A policy never grants; it only constrains. Removing a policy widens a binding; it never narrows it.

Related

• Session tokens: how the authenticated identity is carried on each request.
• Authenticate a user and manage the session: obtain an identity to apply this model to.