View, update, and delete entitlements in PAM

After you have created an entitlement, you can view, update, or delete it.

Before you begin

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

View, update, and delete entitlements using the Google Cloud console

  1. Go to the Privileged Access Manager page.

    Go to Privileged Access Manager

  2. Select the organization, folder, or project you want to manage entitlements in.

  3. In the Entitlements tab, click the Entitlements for all users tab. Here you can find the available entitlements, the roles they grant, and their valid requesters and approvers.

  4. In the table, click More options in the same row as an entitlement you want to inspect.

    • To view the entitlement details, click View entitlement details.

    • To view grants associated with the entitlement, click View associated grants.

    • To revoke all active grants for the entitlement, click Revoke all grants.

    • To delete the entitlement, click Delete entitlement. You can't delete an entitlement with active grants. You must revoke the grants first.

  5. To update an entitlement, click Edit entitlement in the same row as the entitlement you want to update.

    Keep the following things in mind when updating an entitlement:

    • The updated entitlement configuration only applies to grants requested after the update is made. Approver changes, however, also apply to existing grant requests that haven't yet been approved or denied.

    • When updating an entitlement, you can't change whether approval is needed. If you need to change the approval state, create a new entitlement instead.

    • Changes to an entitlement's requesters and approvers might take a few minutes to propagate.

View entitlements programmatically

To view entitlements programmatically, you can search, list, get, and export them.

List entitlements

gcloud

The gcloud beta pam entitlements list command lists entitlements that belong to a specific scope.

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

  • 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 project, folder, or organization that you want to manage recommendations for. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud beta pam entitlements list \
    --location=global \
    --RESOURCE_TYPE=RESOURCE_ID

Windows (PowerShell)

gcloud beta pam entitlements list `
    --location=global `
    --RESOURCE_TYPE=RESOURCE_ID

Windows (cmd.exe)

gcloud beta pam entitlements list ^
    --location=global ^
    --RESOURCE_TYPE=RESOURCE_ID

You should receive a response similar to the following:

additionalNotificationTargets:
  adminEmailRecipients:
  - alex@example.com
createTime: '2024-03-26T11:07:37.009498890Z'
eligibleUsers:
- principals:
  - user:bola@example.com
etag: 00000000000000000000000000000000000000000000000000000000000=
maxRequestDuration: 3600s
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-03-26T11:07:40.056780645Z'

REST

The PAM API's listEntitlements method lists entitlements that belong to a specific scope.

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

  • SCOPE: The organization, folder, or project that the entitlement is 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.
  • FILTER: Optional. Returns entitlements whose field values match an AIP-160 expression.
  • PAGE_SIZE: Optional. The number of items to return in a response.
  • PAGE_TOKEN: Optional. Which page to start the response from, using a page token returned in a previous response.

HTTP method and URL: 

GET https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements?filter=FILTER&pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN

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/entitlements/ENTITLEMENT_ID",
    "createTime": "2023-11-21T17:28:39.962144708Z",
    "updateTime": "2023-11-21T17:28:43.160309410Z",
    "eligibleUsers": [
      {
        "principals": [
          "user:alex@example.com"
        ]
      }
    ],
    "approvalWorkflow": {
      "manualApprovals": {
        "steps": [
          {
            "approvers": [
              {
                "principals": [
                  "user:bola@example.com"
                ]
              }
            ],
            "approvalsNeeded": 1
          }
        ]
      }
    },
    "privilegedAccess": {
      "gcpIamAccess": {
        "resourceType": "cloudresourcemanager.googleapis.com/Project",
        "resource": "//cloudresourcemanager.googleapis.com/projects/my-project",
        "roleBindings": [
          {
            "role": "roles/storage.admin"
          }
        ]
      }
    },
    "maxRequestDuration": "14400s",
    "state": "AVAILABLE",
    "requesterJustificationConfig": {
      "unstructured": {}
    },
    "additionalNotificationTargets": {
      "adminEmailRecipients": [
        "alex@example.com"
      ]
    },
    "etag": "00000000000000000000000000000000000000000000000000000000000="
  }
]

Get entitlements

gcloud

The gcloud beta pam entitlements describe command retrieves a specific entitlement.

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

  • ENTITLEMENT_ID: The ID of the entitlement you want the details for.
  • 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 project, folder, or organization that you want to manage recommendations for. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud beta pam entitlements describe \
    ENTITLEMENT_ID \
    --location=global \
    --RESOURCE_TYPE=RESOURCE_ID

Windows (PowerShell)

gcloud beta pam entitlements describe `
    ENTITLEMENT_ID `
    --location=global `
    --RESOURCE_TYPE=RESOURCE_ID

Windows (cmd.exe)

gcloud beta pam entitlements describe ^
    ENTITLEMENT_ID ^
    --location=global ^
    --RESOURCE_TYPE=RESOURCE_ID

You should receive a response similar to the following:

additionalNotificationTargets:
  adminEmailRecipients:
  - alex@example.com
createTime: '2024-03-26T11:07:37.009498890Z'
eligibleUsers:
- principals:
  - user:bola@example.com
etag: 00000000000000000000000000000000000000000000000000000000000=
maxRequestDuration: 3600s
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-03-26T11:07:40.056780645Z'

REST

The PAM API's getEntitlement method retrieves a specific entitlement.

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

  • SCOPE: The organization, folder, or project to get the entitlement from, 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 ID of the entitlement you want the details for.

HTTP method and URL: 

GET https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements/ENTITLEMENT_ID

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/entitlements/ENTITLEMENT_ID",
  "createTime": "2023-11-21T17:28:39.962144708Z",
  "updateTime": "2023-11-21T17:28:43.160309410Z",
  "eligibleUsers": [
    {
      "principals": [
        "user:alex@example.com"
      ]
    }
  ],
  "approvalWorkflow": {
    "manualApprovals": {
      "steps": [
        {
          "approvers": [
            {
              "principals": [
                "user:bola@example.com"
              ]
            }
          ],
          "approvalsNeeded": 1
        }
      ]
    }
  },
  "privilegedAccess": {
    "gcpIamAccess": {
      "resourceType": "cloudresourcemanager.googleapis.com/Project",
      "resource": "//cloudresourcemanager.googleapis.com/projects/my-project",
      "roleBindings": [
        {
          "role": "roles/storage.admin"
        }
      ]
    }
  },
  "maxRequestDuration": "14400s",
  "state": "AVAILABLE",
  "requesterJustificationConfig": {
    "unstructured": {}
  },
  "additionalNotificationTargets": {
    "adminEmailRecipients": [
      "alex@example.com"
    ]
  },
  "etag": "00000000000000000000000000000000000000000000000000000000000="
}

Export entitlements using the gcloud CLI

The gcloud beta pam entitlements export command exports a specific entitlement to a YAML file.

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

  • ENTITLEMENT_ID: The ID of the entitlement to export.
  • FILENAME: The filename to export the entitlement contents to.
  • 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 project, folder, or organization that you want to manage recommendations for. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud beta pam entitlements export \
    ENTITLEMENT_ID \
    --destination=FILENAME.yaml \
    --location=global \
    --RESOURCE_TYPE=RESOURCE_ID

Windows (PowerShell)

gcloud beta pam entitlements export `
    ENTITLEMENT_ID `
    --destination=FILENAME.yaml `
    --location=global `
    --RESOURCE_TYPE=RESOURCE_ID

Windows (cmd.exe)

gcloud beta pam entitlements export ^
    ENTITLEMENT_ID ^
    --destination=FILENAME.yaml ^
    --location=global ^
    --RESOURCE_TYPE=RESOURCE_ID

You should receive a response similar to the following:

Exported [projects/my-project/locations/global/entitlements/ENTITLEMENT_ID] to 'FILENAME.yaml'.

Update entitlements programmatically

Keep the following things in mind when updating an entitlement:

  • The updated entitlement configuration only applies to grants requested after the update is made. Approver changes, however, also apply to existing grant requests that haven't yet been approved or denied.

  • When updating an entitlement, you can't change whether approval is needed. If you need to change the approval state, create a new entitlement instead.

  • Changes to an entitlement's requesters and approvers might take a few minutes to propagate.

gcloud

The gcloud beta pam entitlements update command updates a specific entitlement.

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

  • ENTITLEMENT_ID: The ID of the entitlement to update.
  • 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 project, folder, or organization that you want to manage recommendations for. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
  • FILENAME: A file containing the modified configuration of the entitlement. To create this file, get or export the existing entitlement, save the response in a YAML file, and then modify it to use as the body of your update request. You must include the ETAG in the body to update the latest version of the entitlement. For available fields you can change or add, see Create entitlements programmatically.

Execute the following command:

Linux, macOS, or Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

You should receive a response similar to the following:

Request issued for: [ENTITLEMENT_ID]
Waiting for operation [projects/my-project/locations/global/operations/OPERATION_ID] to complete...done.
Updated entitlement [ENTITLEMENT_ID].
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 updateEntitlement method updates a specific entitlement.

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

  • SCOPE: The organization, folder, or project that the entitlement is 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 ID of the entitlement to update.

  • UPDATED_FIELDS: A comma-separated list of fields that are being updated in the entitlement. For example:

    ?updateMask=privilegedAccess,maxRequestDuration

    For all updatable fields, set the update mask to *.

  • 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.
  • request.json: A file containing the modified configuration of the entitlement. To create this file, get or export the existing entitlement, save the response in file named request.json, and then modify it to use as the body of your update request. You must include the ETAG in the body to update the latest version of the entitlement. For available fields you can change or add, see Create entitlements programmatically.

HTTP method and URL: 

PATCH https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements/ENTITLEMENT_ID?updateMask=UPDATED_FIELDS&requestId=REQUEST_ID

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-25T01:55:02.544562950Z",
    "target": "projects/my-project/locations/global/entitlements/ENTITLEMENT_ID",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v1beta"
  },
  "done": false
}

To check on the progress of an update 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

Delete entitlements programmatically

gcloud

The gcloud beta pam entitlements delete command deletes a specific entitlement.

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

  • ENTITLEMENT_ID: The ID of the entitlement to delete.
  • 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 project, folder, or organization that you want to manage recommendations for. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud beta pam entitlements delete \
    ENTITLEMENT_ID \
    --location=global \
    --RESOURCE_TYPE=RESOURCE_ID

Windows (PowerShell)

gcloud beta pam entitlements delete `
    ENTITLEMENT_ID `
    --location=global `
    --RESOURCE_TYPE=RESOURCE_ID

Windows (cmd.exe)

gcloud beta pam entitlements delete ^
    ENTITLEMENT_ID ^
    --location=global ^
    --RESOURCE_TYPE=RESOURCE_ID

You should receive a response similar to the following:

Delete request issued for: [ENTITLEMENT_ID]
Waiting for operation [projects/my-project/locations/global/operations/OPERATION_ID] to complete...done.
Deleted entitlement [ENTITLEMENT_ID].

REST

The PAM API's deleteEntitlement method deletes a specific entitlement.

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

  • SCOPE: The organization, folder, or project to delete 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 ID of the entitlement to delete.
  • 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.

HTTP method and URL: 

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

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-06T02:28:28.020293460Z",
    "target": "projects/my-project/locations/global/entitlements/ENTITLEMENT_ID",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "v1beta"
  },
  "done": false
}

To check on the progress of a delete 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