Creating a custom access level

You can use custom access levels in Access Context Manager to control access to Google Cloud resources by using boolean expressions written in a subset of Common Expression Language (CEL). You can evaluate request attributes—such as originating network project, IP address, identity, and device data from third-party security services—to enforce fine-grained, context-aware access requirements.

To use device attributes in custom access level expressions, you must have a paid subscription. For details about building CEL expressions, see the custom access level specification. After you create a custom access level, you can manage it in the same way as a basic access level.

Before you begin

• Create an access policy for your organization.

Create a custom access level

You can create a custom access level using the Google Cloud console, the gcloud command-line tool, the REST API, or RPC.

Console

To create a custom access level using the Google Cloud console, do the following:

1. Open the Access Context Manager page in the Google Cloud console.

   Open the Access Context Manager page

2. If you are prompted, select your organization.

3. At the top of the Access Context Manager page, click New.

4. In the New Access Level pane:

   1. In the Access level title box, enter a title for the access level. The title must be at most 50 characters, start with a letter, and can contain only numbers, letters, underscores, and spaces.

   2. Following Create Conditions in, select Advanced Mode.

   3. In the Conditions section, enter the expressions for your custom access level. The condition must resolve to a single boolean value.

      For examples and more information about Common Expression Language (CEL) support and custom access levels, see the Custom access level specification.

   4. Click Save.

gcloud

To create a custom access level using the gcloud command-line tool, use the gcloud access-context-manager levels create command.

gcloud access-context-manager levels create LEVEL_NAME \
--title=TITLE \
--custom-level-spec=FILE \
--description=DESCRIPTION \
--policy=POLICY_NAME

Replace the following:

• LEVEL_NAME: a unique name for the access level. The name must begin with a letter and include only letters, numbers, and underscores. The name can be a maximum of 50 characters.

• TITLE: the short, human-readable title for the access level.

• FILE: a YAML file that contains your CEL expression formatted as a single key-value pair: expression: "CEL_EXPRESSION".

  For examples and more information about Common Expression Language (CEL) support and custom access levels, see the Custom access level specification.

• DESCRIPTION: a human-readable description of the access level.

• POLICY_NAME: the numeric name of your organization's access policy.

Optionally, you can include any of the gcloud-wide flags.

custom-level-spec YAML file

When you use the gcloud command-line tool to create a custom access level, you must provide a YAML file for the custom-level-spec option. The YAML file defines a CEL expression that resolves to a single boolean value. The YAML file must contain a single key-value pair formatted as expression: "CEL_EXPRESSION". The value for expression must be a string.

Example YAML file

expression: "device.encryption_status == DeviceEncryptionStatus.ENCRYPTED && (origin.region_code in ['US'] || device.is_admin_approved_device)"

Example command

gcloud access-context-manager levels create Custom_Trust \
    --custom-level-spec=customspec.yaml \
    --description="Custom access level for corp." \
    --title="Custom Trust Level" \
    --policy=1521580097614100

REST

To create a custom access level using the REST API, use the accessPolicies.accessLevels.create method.

Request body

In the request body for the call, include an instance of the AccessLevel object.

{
  "name": string,
  "title": string,
  "description": string,
  "custom": {
    "expr": {
      "expression": string,
      "title": string,
      "description": string
    }
  }
}

For the custom field, create an object that includes the CEL expressions for your custom access level. The complete expression must resolve to a boolean value. The title and description fields are optional.

Example

{
  "name": "example_custom_level",
  "title": "Example custom level",
  "description": "An example custom access level.",
  "custom":  {
    "expr": {
      "expression": "device.is_corp_owned == true || (device.os_type != OsType.OS_UNSPECIFIED && device.is_admin_approved_device == true)",
      "title": "Check for known devices",
      "description": "Permits requests from corp-owned devices and admin-approved devices with a known OS."
    }
  }
}

RPC

To create a custom access level using RPC, call CreateAccessLevel.

For the access_level field, include an instance of AccessLevel.

Fields
name	Type string Description Required. The resource name for the access level. The POLICY_ID is the numeric name of your organization's access policy. The SHORT_NAME must begin with a letter, and include only letters, numbers, and underscores. Format: accessPolicies/policy_id/accessLevels/short_name
title	Type string Description A human-readable label for the access level. Access levels must have unique names.
description	Type string Description A description of the access level.
custom	Type string Description The CEL expressions for your custom access level. The complete expression must resolve to a boolean value.

Examples of custom access levels

This section provides examples of custom access levels.

Restrict access based on source project

You can restrict access to resources to only allow requests originating from specific Google Cloud projects and related tenant projects. Project-based access restriction is useful for securing interactions by workload identities, which are non-human identities that belong to a Google Cloud project. Workload identities include service accounts, Workload Identity Federation identities, managed workload identities, and agent identities.

The following expression grants access if the request comes from projects/123456789:

originatesFromProjects(origin, ["projects/123456789"])

Restrict workload identity access to its own network project

You can restrict a workload identity so that it can make only requests from networks that are associated with a Google Cloud project that owns the workload identity. The project can be a top-level project or tenant projects of the top-level project. Project-based access restriction is useful for securing workload identity interactions. Unlike originatesFromProjects, you don't need to specify project numbers in the expression, which lets you reuse the same access level across multiple projects.

The following expression grants access if the originating network project (or its associated tenant projects) matches the project that owns the calling workload identity:

request.auth.matchesNetworkProject(origin)