delegation_requests

Creates, updates, deletes, gets or lists a delegation_requests resource.

Overview

Name	delegation_requests
Type	Resource
Id	aws.iam.delegation_requests

Fields

The following fields are returned by SELECT queries:

get_delegation_request

Name	Datatype	Description
approver_id	string	The Amazon Resource Name (ARN). ARNs are unique identifiers for Amazon Web Services resources. For more information about ARNs, go to Amazon Resource Names (ARNs) in the Amazon Web Services General Reference.
create_date	string	Creation date (timestamp) of this delegation request.
delegation_request_id	string	The unique identifier for the delegation request.
description	string	Description of the delegation request. This is a message that is provided by the Amazon Web Services partner that filed the delegation request.
expiration_time	string	The expiry time of this delegation request See the Understanding the Request Lifecycle for details on the life time of a delegation request at each state.
notes	string	Notes added to this delegation request, if this request was updated via the UpdateDelegationRequest API.
only_send_by_owner	boolean	A flag indicating whether the SendDelegationToken must be called by the owner of this delegation request. This is set by the requesting partner.
owner_account_id	string	Amazon Web Services account ID of the owner of the delegation request.
owner_id	string	ARN of the owner of this delegation request.
permission_policy	string	JSON content of the associated permission policy of this delegation request.
permissions	string	Contains information about the permissions being delegated in a delegation request.
redirect_url	string	A URL to be redirected to once the delegation request is approved. Partners provide this URL when creating the delegation request.
rejection_reason	string	Reasons for rejecting this delegation request, if this request was rejected. See also RejectDelegationRequest API documentation.
request_message	string	A custom message that is added to the delegation request by the partner. This element is different from the Description element such that this is a request specific message injected by the partner. The Description is typically a generic explanation of what the delegation request is targeted to do.
requestor_id	string	Identity of the requestor of this delegation request. This will be an Amazon Web Services account ID.
requestor_name	string	A friendly name of the requestor.
role_permission_restriction_arns	string	If the PermissionPolicy includes role creation permissions, this element will include the list of permissions boundary policies associated with the role creation. See Permissions boundaries for IAM entities for more details about IAM permission boundaries.
session_duration	integer	The life-time of the requested session credential.
state	string	The state of this delegation request. See the Understanding the Request Lifecycle for an explanation of how these states are transitioned.
updated_time	string	Last updated timestamp of the request.

list_delegation_requests

Name	Datatype	Description
approver_id	string	The Amazon Resource Name (ARN). ARNs are unique identifiers for Amazon Web Services resources. For more information about ARNs, go to Amazon Resource Names (ARNs) in the Amazon Web Services General Reference.
create_date	string	Creation date (timestamp) of this delegation request.
delegation_request_id	string	The unique identifier for the delegation request.
description	string	Description of the delegation request. This is a message that is provided by the Amazon Web Services partner that filed the delegation request.
expiration_time	string	The expiry time of this delegation request See the Understanding the Request Lifecycle for details on the life time of a delegation request at each state.
notes	string	Notes added to this delegation request, if this request was updated via the UpdateDelegationRequest API.
only_send_by_owner	boolean	A flag indicating whether the SendDelegationToken must be called by the owner of this delegation request. This is set by the requesting partner.
owner_account_id	string	Amazon Web Services account ID of the owner of the delegation request.
owner_id	string	ARN of the owner of this delegation request.
permission_policy	string	JSON content of the associated permission policy of this delegation request.
permissions	string	Contains information about the permissions being delegated in a delegation request.
redirect_url	string	A URL to be redirected to once the delegation request is approved. Partners provide this URL when creating the delegation request.
rejection_reason	string	Reasons for rejecting this delegation request, if this request was rejected. See also RejectDelegationRequest API documentation.
request_message	string	A custom message that is added to the delegation request by the partner. This element is different from the Description element such that this is a request specific message injected by the partner. The Description is typically a generic explanation of what the delegation request is targeted to do.
requestor_id	string	Identity of the requestor of this delegation request. This will be an Amazon Web Services account ID.
requestor_name	string	A friendly name of the requestor.
role_permission_restriction_arns	string	If the PermissionPolicy includes role creation permissions, this element will include the list of permissions boundary policies associated with the role creation. See Permissions boundaries for IAM entities for more details about IAM permission boundaries.
session_duration	integer	The life-time of the requested session credential.
state	string	The state of this delegation request. See the Understanding the Request Lifecycle for an explanation of how these states are transitioned.
updated_time	string	Last updated timestamp of the request.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_delegation_request	select	DelegationRequestId, region	DelegationPermissionCheck	Retrieves information about a specific delegation request. If a delegation request has no owner or owner account, GetDelegationRequest for that delegation request can be called by any account. If the owner account is assigned but there is no owner id, only identities within that owner account can call GetDelegationRequest for the delegation request. Once the delegation request is fully owned, the owner of the request gets a default permission to get that delegation request. For more details, see Managing Permissions for Delegation Requests.
list_delegation_requests	select	region	OwnerId, Marker, MaxItems	Lists delegation requests based on the specified criteria. If a delegation request has no owner, even if it is assigned to a specific account, it will not be part of the ListDelegationRequests output for that account. For more details, see Managing Permissions for Delegation Requests.
create_delegation_request	insert	RequestorWorkflowId, NotificationChannel, SessionDuration, region	OwnerAccountId, Description, Permissions, RequestMessage, RedirectUrl, OnlySendByOwner	Creates an IAM delegation request for temporary access delegation. This API is not available for general use. In order to use this API, a caller first need to go through an onboarding process described in the partner onboarding documentation.
associate_delegation_request	update	DelegationRequestId, region		Associates a delegation request with the current identity. If the partner that created the delegation request has specified the owner account during creation, only an identity from that owner account can call the AssociateDelegationRequest API for the specified delegation request. Once the AssociateDelegationRequest API call is successful, the ARN of the current calling identity will be stored as the ownerId of the request. If the partner that created the delegation request has not specified the owner account during creation, any caller from any account can call the AssociateDelegationRequest API for the delegation request. Once this API call is successful, the ARN of the current calling identity will be stored as the ownerId and the Amazon Web Services account ID of the current calling identity will be stored as the ownerAccount of the request. For more details, see Managing Permissions for Delegation Requests.
accept_delegation_request	exec	DelegationRequestId, region		Accepts a delegation request, granting the requested temporary access. Once the delegation request is accepted, it is eligible to send the exchange token to the partner. The SendDelegationToken API has to be explicitly called to send the delegation token. At the time of acceptance, IAM records the details and the state of the identity that called this API. This is the identity that gets mapped to the delegated credential. An accepted request may be rejected before the exchange token is sent to the partner.
reject_delegation_request	exec	DelegationRequestId, region	Notes	Rejects a delegation request, denying the requested temporary access. Once a request is rejected, it cannot be accepted or updated later. Rejected requests expire after 7 days. When rejecting a request, an optional explanation can be added using the Notes request parameter. For more details, see Managing Permissions for Delegation Requests.
send_delegation_token	exec	DelegationRequestId, region		Sends the exchange token for an accepted delegation request. The exchange token is sent to the partner via an asynchronous notification channel, established by the partner. The delegation request must be in the ACCEPTED state when calling this API. After the SendDelegationToken API call is successful, the request transitions to a FINALIZED state and cannot be rolled back. However, a user may reject an accepted request before the SendDelegationToken API is called. For more details, see Managing Permissions for Delegation Requests.
update_delegation_request	exec	DelegationRequestId, region	Notes	Updates an existing delegation request with additional information. When the delegation request is updated, it reaches the PENDING_APPROVAL state. Once a delegation request has an owner, that owner gets a default permission to update the delegation request. For more details, see Managing Permissions for Delegation Requests.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
DelegationRequestId	string	The unique identifier of the delegation request to update.
NotificationChannel	string	The notification channel for updates about the delegation request. At this time,only SNS topic ARNs are accepted for notification. This topic ARN must have a resource policy granting SNS:Publish permission to the IAM service principal (iam.amazonaws.com). See partner onboarding documentation for more details.
RequestorWorkflowId	string	The workflow ID associated with the requestor. This is the unique identifier on the partner side that can be used to track the progress of the request. IAM maintains a uniqueness check on this workflow id for each request - if a workflow id for an existing request is passed, this API call will fail.
SessionDuration	integer	The duration for which the delegated session should remain active, in seconds. The active time window for the session starts when the customer calls the SendDelegationToken API.
region	string	AWS region (default: us-east-1)
DelegationPermissionCheck	boolean	Specifies whether to perform a permission check for the delegation request. If set to true, the GetDelegationRequest API call will start a permission check process. This process calculates whether the caller has sufficient permissions to cover the asks from this delegation request. Setting this parameter to true does not guarantee an answer in the response. See the PermissionCheckStatus and the PermissionCheckResult response attributes for further details.
Description	string	A description of the delegation request.
Marker	string	Use this parameter only when paginating results and only after you receive a response indicating that the results are truncated. Set it to the value of the Marker element in the response that you received to indicate where the next call should start.
MaxItems	integer	Use this only when paginating results to indicate the maximum number of items you want in the response. If additional items exist beyond the maximum you specify, the IsTruncated response element is true. If you do not include this parameter, the number of items defaults to 100. Note that IAM may return fewer results, even when there are more results available. In that case, the IsTruncated response element returns true, and Marker contains a value to include in the subsequent call that tells the service where to continue from.
Notes	string	Additional notes or comments to add to the delegation request.
OnlySendByOwner	boolean	Specifies whether the delegation token should only be sent by the owner. This flag prevents any party other than the owner from calling SendDelegationToken API for this delegation request. This behavior becomes useful when the delegation request owner needs to be present for subsequent partner interactions, but the delegation request was sent to a more privileged user for approval due to the owner lacking sufficient delegation permissions.
OwnerAccountId	string	The Amazon Web Services account ID this delegation request is targeted to. If the account ID is not known, this parameter can be omitted, resulting in a request that can be associated by any account. If the account ID passed, then the created delegation request can only be associated with an identity of that target account.
OwnerId	string	The owner ID to filter delegation requests by.
Permissions	object	The permissions to be delegated in this delegation request.
RedirectUrl	string	The URL to redirect to after the delegation request is processed. This URL is used by the IAM console to show a link to the customer to re-load the partner workflow.
RequestMessage	string	A message explaining the reason for the delegation request. Requesters can utilize this field to add a custom note to the delegation request. This field is different from the description such that this is to be utilized for a custom messaging on a case-by-case basis. For example, if the current delegation request is in response to a previous request being rejected, this explanation can be added to the request via this field.

SELECT examples

get_delegation_request

Retrieves information about a specific delegation request. If a delegation request has no owner or owner account, GetDelegationRequest for that delegation request can be called by any account. If the owner account is assigned but there is no owner id, only identities within that owner account can call GetDelegationRequest for the delegation request. Once the delegation request is fully owned, the owner of the request gets a default permission to get that delegation request. For more details, see Managing Permissions for Delegation Requests.

SELECT
approver_id,
create_date,
delegation_request_id,
description,
expiration_time,
notes,
only_send_by_owner,
owner_account_id,
owner_id,
permission_policy,
permissions,
redirect_url,
rejection_reason,
request_message,
requestor_id,
requestor_name,
role_permission_restriction_arns,
session_duration,
state,
updated_time
FROM aws.iam.delegation_requests
WHERE DelegationRequestId = '{{ DelegationRequestId }}' -- required
AND region = '{{ region }}' -- required
AND DelegationPermissionCheck = '{{ DelegationPermissionCheck }}'
;

list_delegation_requests

Lists delegation requests based on the specified criteria. If a delegation request has no owner, even if it is assigned to a specific account, it will not be part of the ListDelegationRequests output for that account. For more details, see Managing Permissions for Delegation Requests.

SELECT
approver_id,
create_date,
delegation_request_id,
description,
expiration_time,
notes,
only_send_by_owner,
owner_account_id,
owner_id,
permission_policy,
permissions,
redirect_url,
rejection_reason,
request_message,
requestor_id,
requestor_name,
role_permission_restriction_arns,
session_duration,
state,
updated_time
FROM aws.iam.delegation_requests
WHERE region = '{{ region }}' -- required
AND OwnerId = '{{ OwnerId }}'
AND Marker = '{{ Marker }}'
AND MaxItems = '{{ MaxItems }}'
;

INSERT examples

create_delegation_request

Creates an IAM delegation request for temporary access delegation. This API is not available for general use. In order to use this API, a caller first need to go through an onboarding process described in the partner onboarding documentation.

INSERT INTO aws.iam.delegation_requests (
RequestorWorkflowId,
NotificationChannel,
SessionDuration,
region,
OwnerAccountId,
Description,
Permissions,
RequestMessage,
RedirectUrl,
OnlySendByOwner
)
SELECT 
'{{ RequestorWorkflowId }}',
'{{ NotificationChannel }}',
'{{ SessionDuration }}',
'{{ region }}',
'{{ OwnerAccountId }}',
'{{ Description }}',
'{{ Permissions }}',
'{{ RequestMessage }}',
'{{ RedirectUrl }}',
'{{ OnlySendByOwner }}'
RETURNING
console_deep_link,
delegation_request_id
;

Manifest

# Description fields are for documentation purposes
- name: delegation_requests
props:
  - name: RequestorWorkflowId
    value: "{{ RequestorWorkflowId }}"
    description: Required parameter for the delegation_requests resource.
  - name: NotificationChannel
    value: "{{ NotificationChannel }}"
    description: Required parameter for the delegation_requests resource.
  - name: SessionDuration
    value: {{ SessionDuration }}
    description: Required parameter for the delegation_requests resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the delegation_requests resource.
  - name: OwnerAccountId
    value: "{{ OwnerAccountId }}"
    description: The Amazon Web Services account ID this delegation request is targeted to. If the account ID is not known, this parameter can be omitted, resulting in a request that can be associated by any account. If the account ID passed, then the created delegation request can only be associated with an identity of that target account.
    description: The Amazon Web Services account ID this delegation request is targeted to. If the account ID is not known, this parameter can be omitted, resulting in a request that can be associated by any account. If the account ID passed, then the created delegation request can only be associated with an identity of that target account.
  - name: Description
    value: "{{ Description }}"
    description: A description of the delegation request.
    description: A description of the delegation request.
  - name: Permissions
    value: "{{ Permissions }}"
    description: The permissions to be delegated in this delegation request.
    description: The permissions to be delegated in this delegation request.
  - name: RequestMessage
    value: "{{ RequestMessage }}"
    description: A message explaining the reason for the delegation request. Requesters can utilize this field to add a custom note to the delegation request. This field is different from the description such that this is to be utilized for a custom messaging on a case-by-case basis. For example, if the current delegation request is in response to a previous request being rejected, this explanation can be added to the request via this field.
    description: A message explaining the reason for the delegation request. Requesters can utilize this field to add a custom note to the delegation request. This field is different from the description such that this is to be utilized for a custom messaging on a case-by-case basis. For example, if the current delegation request is in response to a previous request being rejected, this explanation can be added to the request via this field.
  - name: RedirectUrl
    value: "{{ RedirectUrl }}"
    description: The URL to redirect to after the delegation request is processed. This URL is used by the IAM console to show a link to the customer to re-load the partner workflow.
    description: The URL to redirect to after the delegation request is processed. This URL is used by the IAM console to show a link to the customer to re-load the partner workflow.
  - name: OnlySendByOwner
    value: {{ OnlySendByOwner }}
    description: Specifies whether the delegation token should only be sent by the owner. This flag prevents any party other than the owner from calling SendDelegationToken API for this delegation request. This behavior becomes useful when the delegation request owner needs to be present for subsequent partner interactions, but the delegation request was sent to a more privileged user for approval due to the owner lacking sufficient delegation permissions.
    description: Specifies whether the delegation token should only be sent by the owner. This flag prevents any party other than the owner from calling SendDelegationToken API for this delegation request. This behavior becomes useful when the delegation request owner needs to be present for subsequent partner interactions, but the delegation request was sent to a more privileged user for approval due to the owner lacking sufficient delegation permissions.

UPDATE examples

associate_delegation_request

Associates a delegation request with the current identity. If the partner that created the delegation request has specified the owner account during creation, only an identity from that owner account can call the AssociateDelegationRequest API for the specified delegation request. Once the AssociateDelegationRequest API call is successful, the ARN of the current calling identity will be stored as the ownerId of the request. If the partner that created the delegation request has not specified the owner account during creation, any caller from any account can call the AssociateDelegationRequest API for the delegation request. Once this API call is successful, the ARN of the current calling identity will be stored as the ownerId and the Amazon Web Services account ID of the current calling identity will be stored as the ownerAccount of the request. For more details, see Managing Permissions for Delegation Requests.

UPDATE aws.iam.delegation_requests
SET 
-- No updatable properties
WHERE 
DelegationRequestId = '{{ DelegationRequestId }}' --required
AND region = '{{ region }}' --required;

Lifecycle Methods

accept_delegation_request

Accepts a delegation request, granting the requested temporary access. Once the delegation request is accepted, it is eligible to send the exchange token to the partner. The SendDelegationToken API has to be explicitly called to send the delegation token. At the time of acceptance, IAM records the details and the state of the identity that called this API. This is the identity that gets mapped to the delegated credential. An accepted request may be rejected before the exchange token is sent to the partner.

EXEC aws.iam.delegation_requests.accept_delegation_request 
@DelegationRequestId='{{ DelegationRequestId }}' --required, 
@region='{{ region }}' --required
;

reject_delegation_request

Rejects a delegation request, denying the requested temporary access. Once a request is rejected, it cannot be accepted or updated later. Rejected requests expire after 7 days. When rejecting a request, an optional explanation can be added using the Notes request parameter. For more details, see Managing Permissions for Delegation Requests.

EXEC aws.iam.delegation_requests.reject_delegation_request 
@DelegationRequestId='{{ DelegationRequestId }}' --required, 
@region='{{ region }}' --required, 
@Notes='{{ Notes }}'
;

send_delegation_token

Sends the exchange token for an accepted delegation request. The exchange token is sent to the partner via an asynchronous notification channel, established by the partner. The delegation request must be in the ACCEPTED state when calling this API. After the SendDelegationToken API call is successful, the request transitions to a FINALIZED state and cannot be rolled back. However, a user may reject an accepted request before the SendDelegationToken API is called. For more details, see Managing Permissions for Delegation Requests.

EXEC aws.iam.delegation_requests.send_delegation_token 
@DelegationRequestId='{{ DelegationRequestId }}' --required, 
@region='{{ region }}' --required
;

update_delegation_request

Updates an existing delegation request with additional information. When the delegation request is updated, it reaches the PENDING_APPROVAL state. Once a delegation request has an owner, that owner gets a default permission to update the delegation request. For more details, see Managing Permissions for Delegation Requests.

EXEC aws.iam.delegation_requests.update_delegation_request 
@DelegationRequestId='{{ DelegationRequestId }}' --required, 
@region='{{ region }}' --required, 
@Notes='{{ Notes }}'
;