SDK for PHP V3

IAM Toolbox (Preview) 2018-05-10

Client: Aws\IAMToolbox\IAMToolboxClient
Service ID: iam-toolbox
Version: 2018-05-10

This page describes the parameters and results for the operations of the IAM Toolbox (Preview) (2018-05-10), and shows how to use the Aws\IAMToolbox\IAMToolboxClient object to call the described operations. This documentation is specific to the 2018-05-10 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

GetRequestAuthorizationDetails ( array $params = [] )
Retrieves the authorization details for a specific access denied request.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

GetRequestAuthorizationDetails

Operations

GetRequestAuthorizationDetails 

$result = $client->getRequestAuthorizationDetails([/* ... */]);
$promise = $client->getRequestAuthorizationDetailsAsync([/* ... */]);

Retrieves the authorization details for a specific access denied request. The details include the request context, the evaluations performed, and the policies that were evaluated.

Use this operation to understand why a request was denied. Supported services include an authorization ID in the access denied error message. Pass that ID to this operation to retrieve the details.

Authorization details are available for at least 24 hours after the denial.

To use this operation, you must have the iam:GetRequestAuthorizationDetails permission.

Parameter Syntax

$result = $client->getRequestAuthorizationDetails([
    'authorizationId' => '<string>', // REQUIRED
    'nextToken' => '<string>',
]);

Parameter Details

Members
authorizationId
Required: Yes
Type: string

The authorization ID received in the access denied error message. This ID identifies the specific request to retrieve details for.

nextToken
Type: string

The pagination token from a previous call, used to retrieve the next page of evaluations. Omit this value on the first call.

Result Syntax

[
    'evaluations' => [
        [
            'action' => '<string>',
            'context' => [
                '<String>' => [
                ],
                // ...
            ],
            'evaluatedEffect' => 'ALLOW|EXPLICIT_DENY|IMPLICIT_DENY',
            'matchedPolicies' => [
                [
                    'matchedStatements' => [
                        [
                            'evaluatedEffect' => 'ALLOW|DENY',
                            'sid' => '<string>',
                        ],
                        // ...
                    ],
                    'uri' => '<string>',
                ],
                // ...
            ],
            'resource' => '<string>',
        ],
        // ...
    ],
    'nextToken' => '<string>',
    'policies' => [
        [
            'attachedTo' => [
                [
                    'arn' => '<string>',
                ],
                // ...
            ],
            'inline' => true || false,
            'type' => 'IDENTITY_BASED_POLICY|RESOURCE_BASED_POLICY|PERMISSIONS_BOUNDARY|SESSION_POLICY|SERVICE_CONTROL_POLICY|RESOURCE_CONTROL_POLICY|VPC_ENDPOINT_POLICY',
            'uri' => '<string>',
        ],
        // ...
    ],
    'requestContext' => [
        '<String>' => [
        ],
        // ...
    ],
]

Result Details

Members
evaluations
Required: Yes
Type: Array of Evaluation structures

The list of evaluations for this request. Each evaluation shows how a single action and resource pair was evaluated. This includes the context, the effect, and any policies that matched.

nextToken
Type: string

The pagination token for retrieving the next page of evaluations. This value is absent when there are no more results.

policies
Required: Yes
Type: Array of PolicyInfo structures

The list of policies that were evaluated.

requestContext
Required: Yes
Type: Associative array of custom strings keys (String) to document (null|bool|string|numeric) or an (array|associative array) whose members are all valid documentss

The request context is the set of context keys and values that apply to the entire request and are shared by all evaluations.

Errors

AccessDeniedException:

The caller does not have sufficient access to perform this action.

ResourceNotFoundException:

The requested authorization details do not exist in this region or have expired. Verify that the authorization ID from the access denied error message is correct and the call is made in the region where the denial occurred. Ensure that the calling principal belongs to the same account or organization as the original denied request.

ValidationException:

The request is malformed or is missing one or more required parameters. Check the request parameters and try again.

InternalServerException:

An unexpected error occurred while processing the request. Try again.

Shapes

AccessDeniedException

Description

The caller does not have sufficient access to perform this action.

Members
message
Required: Yes
Type: string

AttachedTo

Description

An entity that a policy is attached to, identified by its ARN.

Members
arn
Type: string

The ARN of the entity that the policy is attached to. The ARN format depends on the policy type:

  • For identity, session, and permissions boundary policies, this is the principal ARN (for example, an IAM role or user ARN).

  • For resource-based policies, this is the resource ARN.

  • For organization control policies (SCPs and RCPs), this is the AWS Organizations ARN of the account, organizational unit, or root.

Document

Members

Evaluation

Description

Represents an individual evaluation for a single action and resource pair. This includes the context, the resulting effect, and any policies that matched.

Members
action
Required: Yes
Type: string

The action evaluated for this request (for example, iam:PassRole).

context
Type: Associative array of custom strings keys (String) to document (null|bool|string|numeric) or an (array|associative array) whose members are all valid documentss

The context keys and values specific to this evaluation. These are applied on top of the request context.

evaluatedEffect
Type: string

The result of the evaluation. Valid values:

  • ALLOW - The action was allowed.

  • EXPLICIT_DENY - The action was explicitly denied by a policy.

  • IMPLICIT_DENY - The action was denied because no policy allowed it.

matchedPolicies
Type: Array of MatchedPolicy structures

The policies that matched during evaluation of this action and resource. An implicit denial produces no matched policies.

resource
Required: Yes
Type: string

The resource that the action targeted. This is typically a resource ARN, but can be a wildcard ARN that matches multiple resources, or empty for actions that are not resource-specific.

InternalServerException

Description

An unexpected error occurred while processing the request. Try again.

Members
message
Required: Yes
Type: string

MatchedPolicy

Description

A policy that matched during evaluation, referenced by URI. The URI corresponds to a policy in the top-level policies list.

Members
matchedStatements
Type: Array of MatchedStatement structures

The statements within the policy that matched during the evaluation.

uri
Required: Yes
Type: string

The URI of the policy. This cross-references an entry in the top-level policies list. The value depends on the policy type:

  • For managed policies, this is the policy ARN.

  • For inline policies, this is an opaque identifier.

MatchedStatement

Description

A statement that matched during evaluation.

Members
evaluatedEffect
Type: string

The evaluated effect of this statement. Valid values:

  • ALLOW - The statement allows the action.

  • DENY - The statement denies the action.

sid
Type: string

The statement ID (Sid). If the statement has no Sid, one is generated for reference.

PolicyInfo

Description

Contains details about a policy evaluated during authorization. Details include the policy type, whether it is inline or managed, a URI that identifies it, and the entities it is attached to.

Members
attachedTo
Type: Array of AttachedTo structures

The entities that the policy is attached to. For identity, session, and resource-based policies, this is typically a single entity. For organization control policies (SCPs and RCPs), it can be multiple entities at different levels of the organization hierarchy.

inline
Type: boolean

Specifies whether this is an inline policy (true) or a managed policy (false).

type
Type: string

The type of policy. Valid values:

  • IDENTITY_BASED_POLICY - An identity-based policy attached to an IAM user, group, or role.

  • PERMISSIONS_BOUNDARY - A permissions boundary for an IAM entity.

  • RESOURCE_BASED_POLICY - A resource-based policy attached to a resource.

  • RESOURCE_CONTROL_POLICY - A resource control policy (RCP) in AWS Organizations.

  • SERVICE_CONTROL_POLICY - A service control policy (SCP) in AWS Organizations.

  • SESSION_POLICY - A session policy passed during role assumption or federation.

  • VPC_ENDPOINT_POLICY - A VPC endpoint policy.

uri
Type: string

A URI that identifies the policy. Use this URI to cross-reference the policy with the matching policies in each evaluation. The value depends on the policy type:

  • For managed policies, this is the policy ARN.

  • For inline policies, which have no ARN, this is an opaque identifier.

ResourceNotFoundException

Description

The requested authorization details do not exist in this region or have expired. Verify that the authorization ID from the access denied error message is correct and the call is made in the region where the denial occurred. Ensure that the calling principal belongs to the same account or organization as the original denied request.

Members
message
Required: Yes
Type: string

ValidationException

Description

The request is malformed or is missing one or more required parameters. Check the request parameters and try again.

Members
message
Required: Yes
Type: string