Create entitlements in PAM

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.

Before you begin

Make sure you have enabled PAM and set up permissions for it.

Create entitlements using the Google Cloud console

To create an entitlement, complete the following instructions:

  1. Go to the Privileged Access Manager page.

    Go to Privileged Access Manager

  2. Select the organization, folder, or project you want the entitlement to apply to.

  3. Click the Entitlements tab.

  4. Click Create.

  5. Add the following entitlement details:

    • An entitlement name.

    • Up to 20 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.

  6. Click Next.

  7. Search for and add up to 20 valid requesting principals for the entitlement. All principal types are supported except allUsers and allAuthenticatedUsers.

  8. Choose whether the principals need to provide a justification for the grant request.

  9. Click Next.

  10. 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 identities per entitlement.

  11. Click Next.

  12. 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.

  13. 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 recommendations 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 PAM 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:

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

What's next