Class SimulatePrincipalPolicyCommandProtected

Simulate how a set of IAM policies attached to an IAM entity works with a list of API operations and Amazon Web Services resources to determine the policies' effective permissions. The entity can be an IAM user, group, or role. If you specify a user, then the simulation also includes all of the policies that are attached to groups that the user belongs to. You can simulate resources that don't exist in your account.

You can optionally include a list of one or more additional policies specified as strings to include in the simulation. If you want to simulate only policies specified as strings, use SimulateCustomPolicy instead.

You can also optionally include one resource-based policy to be evaluated with each of the resources included in the simulation for IAM users only.

The simulation does not perform the API operations; it only checks the authorization to determine if the simulated policies allow or deny the operations.

Note: This operation discloses information about the permissions granted to other users. If you do not want users to see other user's permissions, then consider allowing them to use SimulateCustomPolicy instead.

Context keys are variables maintained by Amazon Web Services and its services that provide details about the context of an API query request. You can use the Condition element of an IAM policy to evaluate context keys. To get the list of context keys that the policies require for correct simulation, use GetContextKeysForPrincipalPolicy.

If the output is long, you can use the MaxItems and Marker parameters to paginate the results.

The IAM policy simulator evaluates statements in the identity-based policy and the inputs that you provide during simulation. The policy simulator results can differ from your live Amazon Web Services environment. We recommend that you check your policies against your live Amazon Web Services environment after testing using the policy simulator to confirm that you have the desired results. For more information about using the policy simulator, see Testing IAM policies with the IAM policy simulator in the IAM User Guide.

Example

Use a bare-bones client and the command you need to make an API call.

import { IAMClient, SimulatePrincipalPolicyCommand } from "@aws-sdk/client-iam"; // ES Modules import
// const { IAMClient, SimulatePrincipalPolicyCommand } = require("@aws-sdk/client-iam"); // CommonJS import
const client = new IAMClient(config);
const input = { // SimulatePrincipalPolicyRequest
  PolicySourceArn: "STRING_VALUE", // required
  PolicyInputList: [ // SimulationPolicyListType
    "STRING_VALUE",
  ],
  PermissionsBoundaryPolicyInputList: [
    "STRING_VALUE",
  ],
  ActionNames: [ // ActionNameListType // required
    "STRING_VALUE",
  ],
  ResourceArns: [ // ResourceNameListType
    "STRING_VALUE",
  ],
  ResourcePolicy: "STRING_VALUE",
  ResourceOwner: "STRING_VALUE",
  CallerArn: "STRING_VALUE",
  ContextEntries: [ // ContextEntryListType
    { // ContextEntry
      ContextKeyName: "STRING_VALUE",
      ContextKeyValues: [ // ContextKeyValueListType
        "STRING_VALUE",
      ],
      ContextKeyType: "string" || "stringList" || "numeric" || "numericList" || "boolean" || "booleanList" || "ip" || "ipList" || "binary" || "binaryList" || "date" || "dateList",
    },
  ],
  ResourceHandlingOption: "STRING_VALUE",
  MaxItems: Number("int"),
  Marker: "STRING_VALUE",
};
const command = new SimulatePrincipalPolicyCommand(input);
const response = await client.send(command);
// { // SimulatePolicyResponse
//   EvaluationResults: [ // EvaluationResultsListType
//     { // EvaluationResult
//       EvalActionName: "STRING_VALUE", // required
//       EvalResourceName: "STRING_VALUE",
//       EvalDecision: "allowed" || "explicitDeny" || "implicitDeny", // required
//       MatchedStatements: [ // StatementListType
//         { // Statement
//           SourcePolicyId: "STRING_VALUE",
//           SourcePolicyType: "user" || "group" || "role" || "aws-managed" || "user-managed" || "resource" || "none",
//           StartPosition: { // Position
//             Line: Number("int"),
//             Column: Number("int"),
//           },
//           EndPosition: {
//             Line: Number("int"),
//             Column: Number("int"),
//           },
//         },
//       ],
//       MissingContextValues: [ // ContextKeyNamesResultListType
//         "STRING_VALUE",
//       ],
//       OrganizationsDecisionDetail: { // OrganizationsDecisionDetail
//         AllowedByOrganizations: true || false,
//       },
//       PermissionsBoundaryDecisionDetail: { // PermissionsBoundaryDecisionDetail
//         AllowedByPermissionsBoundary: true || false,
//       },
//       EvalDecisionDetails: { // EvalDecisionDetailsType
//         "<keys>": "allowed" || "explicitDeny" || "implicitDeny",
//       },
//       ResourceSpecificResults: [ // ResourceSpecificResultListType
//         { // ResourceSpecificResult
//           EvalResourceName: "STRING_VALUE", // required
//           EvalResourceDecision: "allowed" || "explicitDeny" || "implicitDeny", // required
//           MatchedStatements: [
//             {
//               SourcePolicyId: "STRING_VALUE",
//               SourcePolicyType: "user" || "group" || "role" || "aws-managed" || "user-managed" || "resource" || "none",
//               StartPosition: {
//                 Line: Number("int"),
//                 Column: Number("int"),
//               },
//               EndPosition: {
//                 Line: Number("int"),
//                 Column: Number("int"),
//               },
//             },
//           ],
//           MissingContextValues: [
//             "STRING_VALUE",
//           ],
//           EvalDecisionDetails: {
//             "<keys>": "allowed" || "explicitDeny" || "implicitDeny",
//           },
//           PermissionsBoundaryDecisionDetail: {
//             AllowedByPermissionsBoundary: true || false,
//           },
//         },
//       ],
//     },
//   ],
//   IsTruncated: true || false,
//   Marker: "STRING_VALUE",
// };

Param

SimulatePrincipalPolicyCommandInput

Returns

SimulatePrincipalPolicyCommandOutput

See

• SimulatePrincipalPolicyCommandInput for command's input shape.
• SimulatePrincipalPolicyCommandOutput for command's response shape.
• config for IAMClient's config shape.

Throws

InvalidInputException (client fault)

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

Throws

NoSuchEntityException (client fault)

The request was rejected because it referenced a resource entity that does not exist. The error message describes the resource.

Throws

PolicyEvaluationException (server fault)

The request failed because a provided policy could not be successfully evaluated. An additional detailed message indicates the source of the failure.

Throws

IAMServiceException

Base exception class for all service exceptions from IAM service.