Create entitlements in Privileged Access Manager

You can create entitlements to allow temporary privilege elevation for a select set of principals. Keep the following in mind when creating entitlements:

Entitlements can be created at the organization, folder, or project level. Roles granted by an entitlement at each level follow the Google Cloud resource hierarchy. For example, roles granted by an entitlement at the organization level are inherited at the folder and project levels.
If you add a group as a requester to an entitlement, all individual accounts in that group can request a grant of that entitlement. However, only the individual account requesting the grant can receive elevated privileges.
If you add a group as an approver to an entitlement, all individual accounts in that group can approve or deny a grant request.
Basic roles aren't supported.

Caution: Be careful when including the following types of roles in an entitlement:

Roles with permissions to grant and revoke IAM roles (that is, roles with permission names that end in setIamPolicy).
Roles with the iam.roles.update permission, which lets users modify custom roles.

These types of roles contain permissions that could let a user modify their own IAM permissions. As a result, requesting principals can use these roles to increase their own access to resources, or give themselves additional access to resources.

For example, imagine a user that has a custom role with very limited permissions. If this user successfully requests a grant against an entitlement with the Role Administrator role (roles/iam.roleAdmin), then they can use the permissions in that role to add the resourcemanager.projects.setIamPolicy permission to their custom role. This permission would let them grant and revoke all IAM roles for the project, even after the grant expires.

Before you begin

Make sure you have enabled Privileged Access Manager and set up permissions for it.

Create entitlements using the Google Cloud console

To create an entitlement, complete the following instructions:

Go to the Privileged Access Manager page.

Go to Privileged Access Manager
Select the organization, folder, or project you want the entitlement to apply to.
Click the Entitlements tab.
Click Create.
Add the following entitlement details:
- An entitlement name.
- Up to 30 roles to be granted on the organization, folder, or project. You can apply IAM conditions to these roles, as long as they don't match resource tags.
- How long grants can last against the entitlement.
Click Next.
Search for and add up to 20 valid requesting principals for the entitlement. All principal types are supported except allUsers and allAuthenticatedUsers. You can add more than 20 identities by adding them to a group and listing the group in the entitlement.
Choose whether the principals need to provide a justification for the grant request.
Click Next.
Choose to allow role grants without approval, or search for and add valid principals who can approve the request. The valid principal types are as follows:
- Google Accounts
- Google Groups
- Google Workspace domains
- Workforce pool identifiers
If you choose to have approvers, also choose whether the approvers need to provide a justification for approving the grant request. You can add up to 20 approving principals per entitlement. You can add more than 20 identities by adding them to a group and listing the group in the entitlement.
Click Next.
Optional: Add the email addresses of people to notify when the entitlement is available to request, when a grant is pending approval, and when a requester is granted access. Google identities associated with the entitlement, like approvers and requesters, are automatically notified. However, you might want to notify a different set of email addresses, especially if you're using Workforce Identity Federation.
Click Create Entitlement.

Create entitlements programmatically

gcloud

The gcloud beta pam entitlements create command creates an entitlement at the organization, folder, or project level.

Before using any of the command data below, make the following replacements:

ENTITLEMENT_ID: The entitlement ID to create. An ID must be 4-63 characters in length, and use the following characters: [a-z0-9-]. The first character must be a letter.
RESOURCE_TYPE: Optional. The resource type that the entitlement belongs to. Use the value organization, folder, or project.
RESOURCE_ID: Used with RESOURCE_TYPE. The ID of the Google Cloud organization, folder, or project that you want to manage entitlements for. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
SCOPE: The organization, folder, or project to create the entitlement in, in the format of organizations/ORGANIZATION_ID, folders/FOLDER_ID, or projects/PROJECT_ID. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
RESOURCE_MANAGER_RESOURCE_TYPE: Either Organization, Folder, or Project, depending on the scope.
ROLE: The roles to assign when an entitlement is granted.
TIME_IN_SECONDS: The maximum duration a grant lasts, in seconds.
REQUESTING_MEMBER: Principals that can request that the entitlement be granted. All principal types are supported except allUsers and allAuthenticatedUsers.
APPROVING_EMAIL: Optional. Additional email addresses to notify when a grant has been requested. Google identities associated with grant approvers are automatically notified. However, you might want to notify a different set of email addresses, especially if you're using Workforce Identity Federation.
APPROVING_MEMBER: Principals that can approve the entitlement request. The valid principal types are as follows
- User
- Group
- Domain
- Workforce pool identifiers
ADMIN_EMAIL_ADDRESS: Optional. Additional email addresses to notify when a requester is granted access. Google identities associated with grant approvers are automatically notified. However, you might want to notify a different set of email addresses, especially if you're using Workforce Identity Federation.
REQUESTER_EMAIL_ADDRESS: Optional. Additional email addresses to notify when this entitlement is available to request. Google identities associated with grant requesters are automatically notified. However, you might want to notify a different set of email addresses, especially if you're using Workforce Identity Federation.

Save the following content in a file called entitlement.yaml:

privilegedAccess:
  gcpIamAccess:
    resourceType: cloudresourcemanager.googleapis.com/RESOURCE_MANAGER_RESOURCE_TYPE
    resource: //cloudresourcemanager.googleapis.com/SCOPE
    roleBindings:
    - role: ROLE_1
    - role: ROLE_2
maxRequestDuration: TIME_IN_SECONDSs
eligibleUsers:
- principals:
  - REQUESTING_MEMBER_1
  - REQUESTING_MEMBER_2
approvalWorkflow:
  manualApprovals:
    requireApproverJustification: true
    steps:
    - approvalsNeeded: 1
      approverEmailRecipients:
      - APPROVING_EMAIL_1
      - APPROVING_EMAIL_2
      approvers:
      - principals:
        - APPROVING_MEMBER_1
        - APPROVING_MEMBER_2
requesterJustificationConfig:
  unstructured: {}
additionalNotificationTargets:
  adminEmailRecipients:
  - ADMIN_EMAIL_ADDRESS_1
  - ADMIN_EMAIL_ADDRESS_2
  requesterEmailRecipients:
  - REQUESTER_EMAIL_ADDRESS_1
  - REQUESTER_EMAIL_ADDRESS_2

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud beta pam entitlements create \
    ENTITLEMENT_ID \
    --entitlement-file=entitlement.yaml \
    --location=global \
    --RESOURCE_TYPE=RESOURCE_ID

Windows (PowerShell)

gcloud beta pam entitlements create `
    ENTITLEMENT_ID `
    --entitlement-file=entitlement.yaml `
    --location=global `
    --RESOURCE_TYPE=RESOURCE_ID

Windows (cmd.exe)

gcloud beta pam entitlements create ^
    ENTITLEMENT_ID ^
    --entitlement-file=entitlement.yaml ^
    --location=global ^
    --RESOURCE_TYPE=RESOURCE_ID

You should receive a response similar to the following:

Create request issued for: [ENTITLEMENT_ID]
Waiting for operation [projects/my-project/locations/global/operations/OPERATION_ID] to complete...done.
Created entitlement [ENTITLEMENT_ID].
additionalNotificationTargets: {}
approvalWorkflow:
  manualApprovals:
    requireApproverJustification: true
    steps:
    - approvalsNeeded: 1
      approvers:
      - principals:
        - user:alex@example.com
createTime: '2024-04-09T02:39:37.011866832Z'
eligibleUsers:
- principals:
  - user:bola@example.com
etag: 00000000000000000000000000000000000000000000000000000000000=
maxRequestDuration: 7200s
name: projects/my-project/locations/global/entitlements/ENTITLEMENT_ID
privilegedAccess:
  gcpIamAccess:
    resource: //cloudresourcemanager.googleapis.com/projects/my-project
    resourceType: cloudresourcemanager.googleapis.com/Project
    roleBindings:
    - role: roles/storage.admin
requesterJustificationConfig:
  unstructured: {}
state: AVAILABLE
updateTime: '2024-04-09T02:39:40.066770306Z'

REST

The Privileged Access Manager API's createEntitlement method creates an entitlement at the organization, folder, or project level.

Before using any of the request data, make the following replacements:

SCOPE: The organization, folder, or project to create the entitlement in, in the format of organizations/ORGANIZATION_ID, folders/FOLDER_ID, or projects/PROJECT_ID. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
ENTITLEMENT_ID: The entitlement ID to create. An ID must be 4-63 characters in length, and use the following characters: [a-z0-9-]. The first character must be a letter.
REQUEST_ID: Optional. Must be a non-zero UUID. If the server receives a request with a request ID, it checks if another request with that ID has already been completed within the last 60 minutes. If so, the new request is ignored.
RESOURCE_MANAGER_RESOURCE_TYPE: Either Organization, Folder, or Project, depending on the scope.
ROLE: The roles to assign when an entitlement is granted.
TIME_IN_SECONDS: The maximum duration a grant lasts, in seconds.
REQUESTING_MEMBER: Principals that can request the entitlement be granted. All principal types are supported except allUsers and allAuthenticatedUsers.
APPROVING_MEMBER: Principals that can approve the entitlement request. The valid principal types are as follows
- User
- Group
- Domain
- Workforce pool identifiers
APPROVING_EMAIL: Optional. Additional email addresses to notify when a grant has been requested. Google identities associated with grant approvers are automatically notified. However, you might want to notify a different set of email addresses, especially if you're using Workforce Identity Federation.
ADMIN_EMAIL_ADDRESS: Optional. Additional email addresses to notify when a requester is granted access. Google identities associated with grant approvers are automatically notified. However, you might want to notify a different set of email addresses, especially if you're using Workforce Identity Federation.
REQUESTER_EMAIL_ADDRESS: Optional. Additional email addresses to notify when this entitlement is available to request. Google identities associated with grant requesters are automatically notified. However, you might want to notify a different set of email addresses, especially if you're using Workforce Identity Federation.

HTTP method and URL:

POST https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements?entitlementId=ENTITLEMENT_ID&requestId=REQUEST_ID

Request JSON body:

{
  "privilegedAccess": {
    "gcpIamAccess": {
      "resourceType": "cloudresourcemanager.googleapis.com/RESOURCE_MANAGER_RESOURCE_TYPE",
      "resource": "//cloudresourcemanager.googleapis.com/SCOPE",
      "roleBindings": [
        {
          "role": "ROLE_1"
        },
        {
          "role": "ROLE_2"
        }
      ]
    }
  },
  "maxRequestDuration": "TIME_IN_SECONDSs",
  "eligibleUsers": [
    {
      "principals": [
        "REQUESTING_MEMBER_1",
        "REQUESTING_MEMBER_2",
        ...
      ]
    }
  ],
  "approvalWorkflow": {
    "manualApprovals": {
      "requireApproverJustification": true,
      "steps": [
        {
          "approvers": [
            {
              "principals": [
                "APPROVING_MEMBER_1",
                "APPROVING_MEMBER_2",
                ...
              ]
            }
          ],
          "approvalsNeeded": 1,
          "approverEmailRecipients": [
            "APPROVING_EMAIL_1",
            "APPROVING_EMAIL_2",
            ...
          ]
        }
      ]
    }
  },
  "requesterJustificationConfig": {
    "unstructured": {
    }
  },
  "additionalNotificationTargets": {
    "adminEmailRecipients": [
      "ADMIN_EMAIL_ADDRESS_1",
      "ADMIN_EMAIL_ADDRESS_2",
      ...
    ],
    "requesterEmailRecipients": [
      "REQUESTER_EMAIL_ADDRESS_1",
      "REQUESTER_EMAIL_ADDRESS_2",
      ...
    ]
  }
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements?entitlementId=ENTITLEMENT_ID&requestId=REQUEST_ID"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements?entitlementId=ENTITLEMENT_ID&requestId=REQUEST_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
    "name": "projects/my-project/locations/global/operations/OPERATION_ID",
    "metadata": {
      "@type": "type.googleapis.com/google.cloud.privilegedaccessmanager.v1beta.OperationMetadata",
      "createTime": "2024-03-05T03:35:14.596739353Z",
      "target": "projects/my-project/locations/global/entitlements/ENTITLEMENT_ID",
      "verb": "create",
      "requestedCancellation": false,
      "apiVersion": "v1beta"
    },
    "done": false
}

To check on the progress of a create operation, you can send a GET request to the following endpoint:

https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/operations/OPERATION_ID

Send a GET request to the following endpoint to list all operations:

https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/operations

Terraform

You can use Terraform to create entitlements. For more information, see google_privileged_access_manager_entitlement in the Terraform documentation.

Create entitlements in Privileged Access Manager

Before you begin

Create entitlements using the Google Cloud console

Create entitlements programmatically

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Terraform

What's next