Fine-grained access

Fine-grained access lets you grant predefined IAM roles to users and service accounts. The model is simple: you grant a role to a principal on a scope, and the role grants a set of permissions.

Use fine-grained access when a principal needs narrower access than full project or organization admin. For example, you can grant a service account permission to operate compute resources in one project, or limit a user's compute role to a specific set of resources.

How access works

Access decisions use four parts:

• Principal - The user or service account that receives access
• Role - A predefined collection of permissions
• Scope - The project or organization where the role applies
• Resource - The object the principal is trying to access

When a principal makes an API request, evroc IAM checks whether any role binding on the relevant scope grants a role that contains the required permission. If the role is limited to specific resources, the requested resource must also match one of those resource patterns.

Roles are additive. If a principal has several roles on the same scope, the principal receives the union of all permissions granted by those roles.

Principals

A principal is an identity that can receive access. Fine-grained access supports the following principal types:

Role bindings use fully qualified identifiers (FQIDs) for principals. For users, refer to users by their user ID (i.e. not by email address).

Permissions

Permissions represent actions on API resources. A permission name uses the format service.resource.action.

Examples:

• compute.virtualMachines.read
• compute.virtualMachines.start
• iam.roleBindings.read
• iam.roleBindings.write

You don't grant permissions directly. Instead, you grant roles that contain the permissions a principal needs.

Roles

A role is a predefined set of permissions. Role IDs use IAM FQIDs, such as /iam/roles/computeOperator.

Use the roles API to list available roles and see the permissions each role grants:

TOKEN="$(evroc iam get-access-token)"
curl -H "Authorization: Bearer $TOKEN" \
  https://api.evroc.com/iam/v1beta1/roles

For the full role and permission reference, see permissions and roles.

Roles have one of the following scopes:

• Project roles grant access to resources in one project.
• Organization roles grant access to organization-level IAM operations.

Organization roles don't grant access to compute, storage, networking, or other resources inside projects. Grant project roles for project resources.

Role bindings

A role binding grants one or more roles to one principal for a given scope. A scope is either a project or an organization.

Each principal can have one role binding per scope. To grant several roles to the same principal in the same project or organization, add the roles to that principal's existing role binding.

A role binding contains:

• Principal - The identity (e.g. user or service account) receiving access
• Roles - One or more predefined role IDs
• Resources - An optional list of resource FQIDs that limit a role

If you delete a role binding, every role in that binding is revoked for the principal on that scope.

Resource-limited roles

By default, a role applies to every applicable resource in the binding scope. To limit a role, include a resources list on that role entry.

Each resource entry is an FQID. It can match one resource exactly or use * as a wildcard for a single path segment. The service group and scope ID must always be literal values.

Omit resources to grant the role on every applicable resource in the project or organization scope.

Best practices

To make the best and safest use of fine-grained access control, it's important that you follow common IAM best practices. These include:

1. Grant the smallest useful role. Choose the role that matches the work the principal needs to do.
2. Prefer project scope for workload access. Grant organization roles only for organization-level administration.
3. Use service accounts for automation. Grant automation access to a service account instead of a human user's account.
4. Limit high-impact roles to specific resources. Use resource-limited roles when a principal only needs access to a small set of resources.
5. Review role bindings regularly. Remove bindings for users, service accounts, or workloads that no longer need access.

Next steps

• Permissions and roles
• Manage role bindings
• IAM API reference