To temporarily elevate your privileges, you can request a grant against an entitlement in Privileged Access Manager (PAM) for a fixed duration.
An entitlement contains roles that are granted to you after your grant request is successful. These roles are removed by Privileged Access Manager when the grant ends.
Keep the following in mind when you want to request a grant against an entitlement:
You can only request grants against entitlements that you have been added to. To be added to an entitlement, contact the principal administering the entitlement.
Depending on how it's set up, a grant request might require approval to be granted.
If a grant request requires approval and isn't approved or denied in 24 hours, the grant status is changed to
Expired
. After this, you must make a new grant request if privilege elevation is still required.Successful grant requests might take a few minutes to take effect.
Request a grant using the Google Cloud console
To request a grant against an entitlement, complete the following instructions:
Go to the Privileged Access Manager page.
Select the organization, folder, or project you want to request a grant in.
In the My entitlements tab, find the entitlement to request against, and then click Request grant in the same row.
Provide the following details:
The duration required for the grant, up to the maximum duration set on the entitlement.
If required, a justification for the grant.
Optional: Which email addresses to notify of the grant request. Google identities associated with approvers are automatically notified. However, you might want to notify a different set of email addresses, especially if you're using Workforce Identity Federation.
Click Request grant.
To see your grant history including approval statuses, click the Grants tab, followed by the My grants tab.
Request a grant programmatically
To request a grant against an entitlement, you need to complete the following steps:
Search for available entitlement IDs that you can request grants against.
Request the grant.
Afterward, you can check on the status of your grant to see if it is active, meaning you have received the temporary elevation.
Search available entitlements
gcloud
The
gcloud beta pam entitlements search
command with the grant-requester
caller access
type searches for entitlements you can request a grant against.
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 valueorganization
,folder
, orproject
.RESOURCE_ID
: Used withRESOURCE_TYPE
. The ID of the Google Cloud project, folder, or organization that you want to manage entitlements for. Project IDs are alphanumeric strings, likemy-project
. Folder and organization IDs are numeric, like123456789012
.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud beta pam entitlements search \ --caller-access-type=grant-requester \ --location=global \ --RESOURCE_TYPE=RESOURCE_ID
Windows (PowerShell)
gcloud beta pam entitlements search ` --caller-access-type=grant-requester ` --location=global ` --RESOURCE_TYPE=RESOURCE_ID
Windows (cmd.exe)
gcloud beta pam entitlements search ^ --caller-access-type=grant-requester ^ --location=global ^ --RESOURCE_TYPE=RESOURCE_ID
You should receive a response similar to the following:
additionalNotificationTargets: {} approvalWorkflow: manualApprovals: requireApproverJustification: true steps: - approvalsNeeded: 1 approvers: - principals: - user:alex@example.com createTime: '22024-03-26T11:07:37.009498890Z' etag: ETAG 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: notMandatory: {} state: AVAILABLE updateTime: '2024-03-26T11:07:40.056780645Z'
REST
The Privileged Access Manager API's
searchEntitlements
method with the GRANT_REQUESTER
caller access
type searches for entitlements you can request a grant against.
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 oforganizations/ORGANIZATION_ID
,folders/FOLDER_ID
, orprojects/PROJECT_ID
. Project IDs are alphanumeric strings, likemy-project
. Folder and organization IDs are numeric, like123456789012
.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:search?callerAccessType=GRANT_REQUESTER&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": "ETAG" } ]
Request a grant against an entitlement
gcloud
The
gcloud beta pam grants create
command requests a grant.
Before using any of the command data below, make the following replacements:
ENTITLEMENT_ID
: The entitlement ID to create the grant against.GRANT_DURATION
: The requested length of the grant, in seconds.JUSTIFICATION
: The justification for requesting the grant.EMAIL_ADDRESS
: Optional. Additional email addresses to notify of the grant request. Google identities associated with approvers are automatically notified. However, you might want to notify a different set of email addresses, especially if you're using Workforce Identity Federation.RESOURCE_TYPE
: Optional. The resource type that the entitlement belongs to. Use the valueorganization
,folder
, orproject
.RESOURCE_ID
: Used withRESOURCE_TYPE
. The ID of the Google Cloud project, folder, or organization that you want to manage entitlements for. Project IDs are alphanumeric strings, likemy-project
. Folder and organization IDs are numeric, like123456789012
.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud beta pam grants create \ --entitlement=ENTITLEMENT_ID \ --requested-duration="GRANT_DURATIONs" \ --justification="JUSTIFICATION" \ --location=global \ [--additional-email-recipients=EMAIL_ADDRESS_1, EMAIL_ADDRESS_2] \ --RESOURCE_TYPE=RESOURCE_ID
Windows (PowerShell)
gcloud beta pam grants create ` --entitlement=ENTITLEMENT_ID ` --requested-duration="GRANT_DURATIONs" ` --justification="JUSTIFICATION" ` --location=global ` [--additional-email-recipients=EMAIL_ADDRESS_1, EMAIL_ADDRESS_2] ` --RESOURCE_TYPE=RESOURCE_ID
Windows (cmd.exe)
gcloud beta pam grants create ^ --entitlement=ENTITLEMENT_ID ^ --requested-duration="GRANT_DURATIONs" ^ --justification="JUSTIFICATION" ^ --location=global ^ [--additional-email-recipients=EMAIL_ADDRESS_1, EMAIL_ADDRESS_2] ^ --RESOURCE_TYPE=RESOURCE_ID
You should receive a response similar to the following:
Created [GRANT_ID].
REST
The Privileged Access Manager API's
createGrant
method requests a grant.
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 oforganizations/ORGANIZATION_ID
,folders/FOLDER_ID
, orprojects/PROJECT_ID
. Project IDs are alphanumeric strings, likemy-project
. Folder and organization IDs are numeric, like123456789012
.ENTITLEMENT_ID
: The entitlement ID to create the grant against.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.GRANT_DURATION
: The requested length of the grant, in seconds.JUSTIFICATION
: The justification for requesting the grant.EMAIL_ADDRESS
: Optional. Additional email addresses to notify of the grant request. Google identities associated with approvers 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/ENTITLEMENT_ID/grants?requestId=REQUEST_ID
Request JSON body:
{ "requestedDuration": "GRANT_DURATIONs", "justification": { "unstructuredJustification": "JUSTIFICATION" }, "additionalEmailRecipients": [ "EMAIL_ADDRESS_1", "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/entitlements/ENTITLEMENT_ID/grants/GRANT_ID", "createTime": "2024-03-06T03:08:49.330577625Z", "updateTime": "2024-03-06T03:08:49.330577625Z", "requester": "bola@example.com", "requestedDuration": "3600s", "justification": { "unstructuredJustification": "Emergency service for outage" }, "state": "APPROVAL_AWAITED", "timeline": { "events": [ { "eventTime": "2024-03-06T03:08:49.462765846Z", "requested": { "expireTime": "2024-03-07T03:08:49.462765846Z" } } ] }, "privilegedAccess": { "gcpIamAccess": { "resourceType": "cloudresourcemanager.googleapis.com/Project", "resource": "//cloudresourcemanager.googleapis.com/projects/my-project", "roleBindings": [ { "role": "roles/storage.admin" } ] } }, "additionalEmailRecipients": [ "alex@example.com" ] }
Check your grant request status
gcloud
The
gcloud beta pam grants search
command used with the had-created
caller
relationship searches for grants you have created. To check their status,
look for the state
field in the response.
Before using any of the command data below, make the following replacements:
ENTITLEMENT_ID
: The ID of the entitlement that the grant belongs to.RESOURCE_TYPE
: Optional. The resource type that the entitlement belongs to. Use the valueorganization
,folder
, orproject
.RESOURCE_ID
: Used withRESOURCE_TYPE
. The ID of the Google Cloud project, folder, or organization that you want to manage entitlements for. Project IDs are alphanumeric strings, likemy-project
. Folder and organization IDs are numeric, like123456789012
.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud beta pam grants search \ --entitlement=ENTITLEMENT_ID \ --caller-relationship=had-created \ --location=global \ --RESOURCE_TYPE=RESOURCE_ID
Windows (PowerShell)
gcloud beta pam grants search ` --entitlement=ENTITLEMENT_ID ` --caller-relationship=had-created ` --location=global ` --RESOURCE_TYPE=RESOURCE_ID
Windows (cmd.exe)
gcloud beta pam grants search ^ --entitlement=ENTITLEMENT_ID ^ --caller-relationship=had-created ^ --location=global ^ --RESOURCE_TYPE=RESOURCE_ID
You should receive a response similar to the following:
additionalEmailRecipients: - bola@example.com createTime: '2024-03-07T00:34:32.557017289Z' justification: unstructuredJustification: Renaming a file to mitigate issue #312 name: projects/my-project/locations/global/entitlements/ENTITLEMENT_ID/grants/GRANT_ID privilegedAccess: gcpIamAccess: resource: //cloudresourcemanager.googleapis.com/projects/my-project resourceType: cloudresourcemanager.googleapis.com/Project roleBindings: - role: roles/storage.admin requestedDuration: 3600s requester: cruz@example.com state: DENIED timeline: events: - eventTime: '2024-03-07T00:34:32.793769042Z' requested: expireTime: '2024-03-08T00:34:32.793769042Z' - denied: actor: alex@example.com reason: Issue has already been resolved eventTime: '2024-03-07T00:36:08.309116203Z' updateTime: '2024-03-07T00:34:32.926967128Z'
Grants can have the following statuses:
Status | Description |
---|---|
ACTIVATING | The grant is in the process of being activated. |
ACTIVATION_FAILED | Privileged Access Manager couldn't grant the roles due to a non-retriable error. |
ACTIVE | The grant is active and the principal has access to the resources permitted by the roles. |
APPROVAL_AWAITED | The grant request is waiting on a decision from an approver. |
DENIED | The grant request has been denied by an approver. |
ENDED | The grant has ended and the roles have been removed from the principal. |
EXPIRED | The grant request has expired, as approval wasn't given within 24 hours. |
REVOKED | The grant is revoked, and the principal no longer has access to the resources permitted by the roles. |
REVOKING | The grant is in the process of being revoked. |
REST
The Privileged Access Manager API's
searchGrants
method used with the HAD_CREATED
caller
relationship searches for grants you have created. To check their status,
look for the state
field in the response.
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 oforganizations/ORGANIZATION_ID
,folders/FOLDER_ID
, orprojects/PROJECT_ID
. Project IDs are alphanumeric strings, likemy-project
. Folder and organization IDs are numeric, like123456789012
.ENTITLEMENT_ID
: The ID of the entitlement that the grant belongs to.FILTER
: Optional. Returns grants 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/ENTITLEMENT_ID/grants:search?callerRelationship=HAD_CREATED&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:
{ "grants": [ { "name": "projects/my-project/locations/global/entitlements/ENTITLEMENT_ID/grants/GRANT_ID", "createTime": "2024-03-06T03:08:49.330577625Z", "updateTime": "2024-03-06T03:08:49.625874598Z", "requester": "alex@example.com", "requestedDuration": "3600s", "justification": { "unstructuredJustification": "Emergency service for outage" }, "state": "APPROVAL_AWAITED", "timeline": { "events": [ { "eventTime": "2024-03-06T03:08:49.462765846Z", "requested": { "expireTime": "2024-03-07T03:08:49.462765846Z" } } ] }, "privilegedAccess": { "gcpIamAccess": { "resourceType": "cloudresourcemanager.googleapis.com/Project", "resource": "//cloudresourcemanager.googleapis.com/projects/my-project", "roleBindings": [ { "role": "roles/storage.admin" } ] } }, "additionalEmailRecipients": [ "bola@google.com" ] } ] }
Grant statuses are detailed in the following table.
Status | Description |
---|---|
ACTIVATING | The grant is in the process of being activated. |
ACTIVATION_FAILED | Privileged Access Manager couldn't grant the roles due to a non-retriable error. |
ACTIVE | The grant is active and the principal has access to the resources permitted by the roles. |
APPROVAL_AWAITED | The grant request is waiting on a decision from an approver. |
DENIED | The grant request has been denied by an approver. |
ENDED | The grant has ended and the roles have been removed from the principal. |
EXPIRED | The grant request has expired, as approval wasn't given within 24 hours. |
REVOKED | The grant is revoked, and the principal no longer has access to the resources permitted by the roles. |
REVOKING | The grant is in the process of being revoked. |