REST Resource: folders.locations.entitlements

Resource: Entitlement

An entitlement defines the eligibility of a set of users to obtain predefined access for some time possibly after going through an approval workflow.

JSON representation 
{
  "name": string,
  "createTime": string,
  "updateTime": string,
  "eligibleUsers": [
    {
      object (AccessControlEntry)
    }
  ],
  "approvalWorkflow": {
    object (ApprovalWorkflow)
  },
  "privilegedAccess": {
    object (PrivilegedAccess)
  },
  "maxRequestDuration": string,
  "state": enum (State),
  "requesterJustificationConfig": {
    object (RequesterJustificationConfig)
  },
  "additionalNotificationTargets": {
    object (AdditionalNotificationTargets)
  },
  "etag": string
}
Fields
name

string

Identifier. Name of the entitlement. Possible formats:

  • organizations/{organization-number}/locations/{region}/entitlements/{entitlement-id}
  • folders/{folder-number}/locations/{region}/entitlements/{entitlement-id}
  • projects/{project-id|project-number}/locations/{region}/entitlements/{entitlement-id}
createTime

string (Timestamp format)

Output only. Create time stamp.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

Output only. Update time stamp.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
eligibleUsers[]

object (AccessControlEntry)

Optional. Who can create grants using this entitlement. This list should contain at most one entry.
approvalWorkflow

object (ApprovalWorkflow)

Optional. The approvals needed before access are granted to a requester. No approvals are needed if this field is null.
privilegedAccess

object (PrivilegedAccess)

The access granted to a requester on successful approval.
maxRequestDuration

string (Duration format)

Required. The maximum amount of time that access is granted for a request. A requester can ask for a duration less than this, but never more.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
state

enum (State)

Output only. Current state of this entitlement.
requesterJustificationConfig

object (RequesterJustificationConfig)

Required. The manner in which the requester should provide a justification for requesting access.
additionalNotificationTargets

object (AdditionalNotificationTargets)

Optional. Additional email addresses to be notified based on actions taken.
etag

string

An etag is used for optimistic concurrency control as a way to prevent simultaneous updates to the same entitlement. An etag is returned in the response to entitlements.get and the caller should put the etag in the request to entitlements.patch so that their change is applied on the same version. If this field is omitted or if there is a mismatch while updating an entitlement, then the server rejects the request.

AccessControlEntry

AccessControlEntry is used to control who can do some operation.

JSON representation 
{
  "principals": [
    string
  ]
}
Fields
principals[]

string

Optional. Users who are allowed for the operation. Each entry should be a valid v1 IAM principal identifier. The format for these is documented at: https://cloud.google.com/iam/docs/principal-identifiers#v1

ApprovalWorkflow

Different types of approval workflows that can be used to gate privileged access granting.

JSON representation 
{

  // Union field approval_workflow can be only one of the following:
  "manualApprovals": {
    object (ManualApprovals)
  }
  // End of list of possible types for union field approval_workflow.
}
Fields

Union field approval_workflow.

approval_workflow can be only one of the following:
manualApprovals

object (ManualApprovals)

An approval workflow where users designated as approvers review and act on the grants.

ManualApprovals

A manual approval workflow where users who are designated as approvers need to call the ApproveGrant/DenyGrant APIs for a grant. The workflow can consist of multiple serial steps where each step defines who can act as approver in that step and how many of those users should approve before the workflow moves to the next step.

This can be used to create approval workflows such as:

  • Require an approval from any user in a group G.
  • Require an approval from any k number of users from a Group G.
  • Require an approval from any user in a group G and then from a user U.

A single user might be part of the approvers ACL for multiple steps in this workflow, but they can only approve once and that approval is only considered to satisfy the approval step at which it was granted.

JSON representation 
{
  "requireApproverJustification": boolean,
  "steps": [
    {
      object (Step)
    }
  ]
}
Fields
requireApproverJustification

boolean

Optional. Do the approvers need to provide a justification for their actions?
steps[]

object (Step)

Optional. List of approval steps in this workflow. These steps are followed in the specified order sequentially. Only 1 step is supported.

Step

Step represents a logical step in a manual approval workflow.

JSON representation 
{
  "approvers": [
    {
      object (AccessControlEntry)
    }
  ],
  "approvalsNeeded": integer,
  "approverEmailRecipients": [
    string
  ]
}
Fields
approvers[]

object (AccessControlEntry)

Optional. The potential set of approvers in this step. This list must contain at most one entry.
approvalsNeeded

integer

Required. How many users from the above list need to approve. If there aren't enough distinct users in the list, then the workflow indefinitely blocks. Should always be greater than 0. 1 is the only supported value.
approverEmailRecipients[]

string

Optional. Additional email addresses to be notified when a grant is pending approval.

State

Different states an entitlement can be in.

Enums
STATE_UNSPECIFIED Unspecified state. This value is never returned by the server.
CREATING The entitlement is being created.
AVAILABLE The entitlement is available for requesting access.
DELETING The entitlement is being deleted.
DELETED The entitlement has been deleted.
UPDATING The entitlement is being updated.

RequesterJustificationConfig

Defines how a requester must provide a justification when requesting access.

JSON representation 
{

  // Union field justification_type can be only one of the following:
  "notMandatory": {
    object (NotMandatory)
  },
  "unstructured": {
    object (Unstructured)
  }
  // End of list of possible types for union field justification_type.
}
Fields
Union field justification_type. This is a required field and the user must explicitly opt out if a justification from the requester isn't mandatory. justification_type can be only one of the following:
notMandatory

object (NotMandatory)

This option means the requester isn't required to provide a justification.
unstructured

object (Unstructured)

This option means the requester must provide a string as justification. If this is selected, the server allows the requester to provide a justification but doesn't validate it.

NotMandatory

This type has no fields.

The justification is not mandatory but can be provided in any of the supported formats.

Unstructured

This type has no fields.

The requester has to provide a justification in the form of a string.

AdditionalNotificationTargets

AdditionalNotificationTargets includes email addresses to be notified.

JSON representation 
{
  "adminEmailRecipients": [
    string
  ],
  "requesterEmailRecipients": [
    string
  ]
}
Fields
adminEmailRecipients[]

string

Optional. Additional email addresses to be notified when a principal (requester) is granted access.
requesterEmailRecipients[]

string

Optional. Additional email address to be notified about an eligible entitlement.

Methods

create

 Creates a new entitlement in a given project/folder/organization and location.

delete

 Deletes a single entitlement.

get

 Gets details of a single entitlement.

list

 Lists entitlements in a given project/folder/organization and location.

patch

 Updates the entitlement specified in the request.
SearchEntitlements returns entitlements on which the caller has the specified access.