github.com/pulumi/pulumi-aws/sdk/v6@v6.32.0/go/aws/iam/getPrincipalPolicySimulation.go

// Code generated by the Pulumi Terraform Bridge (tfgen) Tool DO NOT EDIT.
// *** WARNING: Do not edit by hand unless you're certain you know what you are doing! ***

package iam

import (
	"context"
	"reflect"

	"github.com/pulumi/pulumi-aws/sdk/v6/go/aws/internal"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

// Runs a simulation of the IAM policies of a particular principal against a given hypothetical request.
//
// You can use this data source in conjunction with
// Preconditions and Postconditions so that your configuration can test either whether it should have sufficient access to do its own work, or whether policies your configuration declares itself are sufficient for their intended use elsewhere.
//
// > **Note:** Correctly using this data source requires familiarity with various details of AWS Identity and Access Management, and how various AWS services integrate with it. For general information on the AWS IAM policy simulator, see [Testing IAM policies with the IAM policy simulator](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_testing-policies.html). This data source wraps the `iam:SimulatePrincipalPolicy` API action described on that page.
//
// ## Example Usage
//
// ### Self Access-checking Example
//
// The following example raises an error if the credentials passed to the AWS provider do not have access to perform the three actions `s3:GetObject`, `s3:PutObject`, and `s3:DeleteObject` on the S3 bucket with the given ARN.
//
// <!--Start PulumiCodeChooser -->
// ```go
// package main
//
// import (
//
//	"github.com/pulumi/pulumi-aws/sdk/v6/go/aws"
//	"github.com/pulumi/pulumi-aws/sdk/v6/go/aws/iam"
//	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
//
// )
//
//	func main() {
//		pulumi.Run(func(ctx *pulumi.Context) error {
//			current, err := aws.GetCallerIdentity(ctx, nil, nil)
//			if err != nil {
//				return err
//			}
//			_, err = iam.LookupPrincipalPolicySimulation(ctx, &iam.LookupPrincipalPolicySimulationArgs{
//				ActionNames: []string{
//					"s3:GetObject",
//					"s3:PutObject",
//					"s3:DeleteObject",
//				},
//				PolicySourceArn: current.Arn,
//				ResourceArns: []string{
//					"arn:aws:s3:::my-test-bucket",
//				},
//			}, nil)
//			if err != nil {
//				return err
//			}
//			return nil
//		})
//	}
//
// ```
// <!--End PulumiCodeChooser -->
//
// If you intend to use this data source to quickly raise an error when the given credentials are insufficient then you must use `dependsOn` inside any resource which would require those credentials, to ensure that the policy check will run first:
//
// <!--Start PulumiCodeChooser -->
// ```go
// package main
//
// import (
//
//	"github.com/pulumi/pulumi-aws/sdk/v6/go/aws/s3"
//	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
//
// )
//
//	func main() {
//		pulumi.Run(func(ctx *pulumi.Context) error {
//			_, err := s3.NewBucketObject(ctx, "example", &s3.BucketObjectArgs{
//				Bucket: pulumi.Any("my-test-bucket"),
//			}, pulumi.DependsOn([]pulumi.Resource{
//				s3ObjectAccess,
//			}))
//			if err != nil {
//				return err
//			}
//			return nil
//		})
//	}
//
// ```
// <!--End PulumiCodeChooser -->
//
// ### Testing the Effect of a Declared Policy
//
// The following example declares an S3 bucket and a user that should have access to the bucket, and then uses `iam.getPrincipalPolicySimulation` to verify that the user does indeed have access to perform needed operations against the bucket.
//
// <!--Start PulumiCodeChooser -->
// ```go
// package main
//
// import (
//
//	"encoding/json"
//	"fmt"
//
//	"github.com/pulumi/pulumi-aws/sdk/v6/go/aws"
//	"github.com/pulumi/pulumi-aws/sdk/v6/go/aws/iam"
//	"github.com/pulumi/pulumi-aws/sdk/v6/go/aws/s3"
//	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
//
// )
//
//	func main() {
//		pulumi.Run(func(ctx *pulumi.Context) error {
//			current, err := aws.GetCallerIdentity(ctx, nil, nil)
//			if err != nil {
//				return err
//			}
//			example, err := iam.NewUser(ctx, "example", &iam.UserArgs{
//				Name: pulumi.String("example"),
//			})
//			if err != nil {
//				return err
//			}
//			exampleBucketV2, err := s3.NewBucketV2(ctx, "example", &s3.BucketV2Args{
//				Bucket: pulumi.String("my-test-bucket"),
//			})
//			if err != nil {
//				return err
//			}
//			_, err = iam.NewUserPolicy(ctx, "s3_access", &iam.UserPolicyArgs{
//				Name: pulumi.String("example_s3_access"),
//				User: example.Name,
//				Policy: exampleBucketV2.Arn.ApplyT(func(arn string) (pulumi.String, error) {
//					var _zero pulumi.String
//					tmpJSON0, err := json.Marshal(map[string]interface{}{
//						"Version": "2012-10-17",
//						"Statement": []map[string]interface{}{
//							map[string]interface{}{
//								"Action":   "s3:GetObject",
//								"Effect":   "Allow",
//								"Resource": arn,
//							},
//						},
//					})
//					if err != nil {
//						return _zero, err
//					}
//					json0 := string(tmpJSON0)
//					return pulumi.String(json0), nil
//				}).(pulumi.StringOutput),
//			})
//			if err != nil {
//				return err
//			}
//			accountAccess, err := s3.NewBucketPolicy(ctx, "account_access", &s3.BucketPolicyArgs{
//				Bucket: exampleBucketV2.Bucket,
//				Policy: pulumi.All(exampleBucketV2.Arn, exampleBucketV2.Arn).ApplyT(func(_args []interface{}) (string, error) {
//					exampleBucketV2Arn := _args[0].(string)
//					exampleBucketV2Arn1 := _args[1].(string)
//					var _zero string
//					tmpJSON1, err := json.Marshal(map[string]interface{}{
//						"Version": "2012-10-17",
//						"Statement": []map[string]interface{}{
//							map[string]interface{}{
//								"Action": "s3:*",
//								"Effect": "Allow",
//								"Principal": map[string]interface{}{
//									"AWS": current.AccountId,
//								},
//								"Resource": []string{
//									exampleBucketV2Arn,
//									fmt.Sprintf("%v/*", exampleBucketV2Arn1),
//								},
//							},
//						},
//					})
//					if err != nil {
//						return _zero, err
//					}
//					json1 := string(tmpJSON1)
//					return json1, nil
//				}).(pulumi.StringOutput),
//			})
//			if err != nil {
//				return err
//			}
//			_ = iam.LookupPrincipalPolicySimulationOutput(ctx, iam.GetPrincipalPolicySimulationOutputArgs{
//				ActionNames: pulumi.StringArray{
//					pulumi.String("s3:GetObject"),
//				},
//				PolicySourceArn: example.Arn,
//				ResourceArns: pulumi.StringArray{
//					exampleBucketV2.Arn,
//				},
//				ResourcePolicyJson: accountAccess.Policy,
//			}, nil)
//			return nil
//		})
//	}
//
// ```
// <!--End PulumiCodeChooser -->
//
// When using `iam.getPrincipalPolicySimulation` to test the effect of a policy declared elsewhere in the same configuration, it's important to use `dependsOn` to make sure that the needed policy has been fully created or updated before running the simulation.
func LookupPrincipalPolicySimulation(ctx *pulumi.Context, args *LookupPrincipalPolicySimulationArgs, opts ...pulumi.InvokeOption) (*LookupPrincipalPolicySimulationResult, error) {
	opts = internal.PkgInvokeDefaultOpts(opts)
	var rv LookupPrincipalPolicySimulationResult
	err := ctx.Invoke("aws:iam/getPrincipalPolicySimulation:getPrincipalPolicySimulation", args, &rv, opts...)
	if err != nil {
		return nil, err
	}
	return &rv, nil
}

// A collection of arguments for invoking getPrincipalPolicySimulation.
type LookupPrincipalPolicySimulationArgs struct {
	// A set of IAM action names to run simulations for. Each entry in this set adds an additional hypothetical request to the simulation.
	//
	// Action names consist of a service prefix and an action verb separated by a colon, such as `s3:GetObject`. Refer to [Actions, resources, and condition keys for AWS services](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html) to see the full set of possible IAM action names across all AWS services.
	ActionNames []string `pulumi:"actionNames"`
	// A set of additional principal policy documents to include in the simulation. The simulator will behave as if each of these policies were associated with the object specified in `policySourceArn`, allowing you to test the effect of hypothetical policies not yet created.
	AdditionalPoliciesJsons []string `pulumi:"additionalPoliciesJsons"`
	// The ARN of an user that will appear as the "caller" of the simulated requests. If you do not specify `callerArn` then the simulation will use the `policySourceArn` instead, if it contains a user ARN.
	CallerArn *string `pulumi:"callerArn"`
	// Each `context` block defines an entry in the table of additional context keys in the simulated request.
	//
	// IAM uses context keys for both custom conditions and for interpolating dynamic request-specific values into policy values. If you use policies that include those features then you will need to provide suitable example values for those keys to achieve a realistic simulation.
	Contexts []GetPrincipalPolicySimulationContext `pulumi:"contexts"`
	// A set of [permissions boundary policy documents](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) to include in the simulation.
	PermissionsBoundaryPoliciesJsons []string `pulumi:"permissionsBoundaryPoliciesJsons"`
	// The [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) of the IAM user, group, or role whose policies will be included in the simulation.
	//
	// You must closely match the form of the real service request you are simulating in order to achieve a realistic result. You can use the following additional arguments to specify other characteristics of the simulated requests:
	PolicySourceArn string `pulumi:"policySourceArn"`
	// A set of ARNs of resources to include in the simulation.
	//
	// This argument is important for actions that have either required or optional resource types listed in [Actions, resources, and condition keys for AWS services](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html), and you must provide ARNs that identify AWS objects of the appropriate types for the chosen actions.
	//
	// The policy simulator only automatically loads policies associated with the `policySourceArn`, so if your given resources have their own resource-level policy then you'll also need to provide that explicitly using the `resourcePolicyJson` argument to achieve a realistic simulation.
	ResourceArns []string `pulumi:"resourceArns"`
	// Specifies a special simulation type to run. Some EC2 actions require special simulation behaviors and a particular set of resource ARNs to achieve a realistic result.
	//
	// For more details, see the `ResourceHandlingOption` request parameter for [the underlying `iam:SimulatePrincipalPolicy` action](https://docs.aws.amazon.com/IAM/latest/APIReference/API_SimulatePrincipalPolicy.html).
	ResourceHandlingOption *string `pulumi:"resourceHandlingOption"`
	// An AWS account ID to use for any resource ARN in `resourceArns` that doesn't include its own AWS account ID. If unspecified, the simulator will use the account ID from the `callerArn` argument as a placeholder.
	ResourceOwnerAccountId *string `pulumi:"resourceOwnerAccountId"`
	// An IAM policy document representing the resource-level policy of all of the resources specified in `resourceArns`.
	//
	// The policy simulator cannot automatically load policies that are associated with individual resources, as described in the documentation for `resourceArns` above.
	ResourcePolicyJson *string `pulumi:"resourcePolicyJson"`
}

// A collection of values returned by getPrincipalPolicySimulation.
type LookupPrincipalPolicySimulationResult struct {
	ActionNames             []string `pulumi:"actionNames"`
	AdditionalPoliciesJsons []string `pulumi:"additionalPoliciesJsons"`
	// `true` if all of the simulation results have decision "allowed", or `false` otherwise.
	AllAllowed                       bool                                  `pulumi:"allAllowed"`
	CallerArn                        *string                               `pulumi:"callerArn"`
	Contexts                         []GetPrincipalPolicySimulationContext `pulumi:"contexts"`
	Id                               string                                `pulumi:"id"`
	PermissionsBoundaryPoliciesJsons []string                              `pulumi:"permissionsBoundaryPoliciesJsons"`
	PolicySourceArn                  string                                `pulumi:"policySourceArn"`
	ResourceArns                     []string                              `pulumi:"resourceArns"`
	ResourceHandlingOption           *string                               `pulumi:"resourceHandlingOption"`
	ResourceOwnerAccountId           *string                               `pulumi:"resourceOwnerAccountId"`
	ResourcePolicyJson               *string                               `pulumi:"resourcePolicyJson"`
	// A set of result objects, one for each of the simulated requests, with the following nested attributes:
	Results []GetPrincipalPolicySimulationResult `pulumi:"results"`
}

func LookupPrincipalPolicySimulationOutput(ctx *pulumi.Context, args LookupPrincipalPolicySimulationOutputArgs, opts ...pulumi.InvokeOption) LookupPrincipalPolicySimulationResultOutput {
	return pulumi.ToOutputWithContext(context.Background(), args).
		ApplyT(func(v interface{}) (LookupPrincipalPolicySimulationResult, error) {
			args := v.(LookupPrincipalPolicySimulationArgs)
			r, err := LookupPrincipalPolicySimulation(ctx, &args, opts...)
			var s LookupPrincipalPolicySimulationResult
			if r != nil {
				s = *r
			}
			return s, err
		}).(LookupPrincipalPolicySimulationResultOutput)
}

// A collection of arguments for invoking getPrincipalPolicySimulation.
type LookupPrincipalPolicySimulationOutputArgs struct {
	// A set of IAM action names to run simulations for. Each entry in this set adds an additional hypothetical request to the simulation.
	//
	// Action names consist of a service prefix and an action verb separated by a colon, such as `s3:GetObject`. Refer to [Actions, resources, and condition keys for AWS services](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html) to see the full set of possible IAM action names across all AWS services.
	ActionNames pulumi.StringArrayInput `pulumi:"actionNames"`
	// A set of additional principal policy documents to include in the simulation. The simulator will behave as if each of these policies were associated with the object specified in `policySourceArn`, allowing you to test the effect of hypothetical policies not yet created.
	AdditionalPoliciesJsons pulumi.StringArrayInput `pulumi:"additionalPoliciesJsons"`
	// The ARN of an user that will appear as the "caller" of the simulated requests. If you do not specify `callerArn` then the simulation will use the `policySourceArn` instead, if it contains a user ARN.
	CallerArn pulumi.StringPtrInput `pulumi:"callerArn"`
	// Each `context` block defines an entry in the table of additional context keys in the simulated request.
	//
	// IAM uses context keys for both custom conditions and for interpolating dynamic request-specific values into policy values. If you use policies that include those features then you will need to provide suitable example values for those keys to achieve a realistic simulation.
	Contexts GetPrincipalPolicySimulationContextArrayInput `pulumi:"contexts"`
	// A set of [permissions boundary policy documents](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) to include in the simulation.
	PermissionsBoundaryPoliciesJsons pulumi.StringArrayInput `pulumi:"permissionsBoundaryPoliciesJsons"`
	// The [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) of the IAM user, group, or role whose policies will be included in the simulation.
	//
	// You must closely match the form of the real service request you are simulating in order to achieve a realistic result. You can use the following additional arguments to specify other characteristics of the simulated requests:
	PolicySourceArn pulumi.StringInput `pulumi:"policySourceArn"`
	// A set of ARNs of resources to include in the simulation.
	//
	// This argument is important for actions that have either required or optional resource types listed in [Actions, resources, and condition keys for AWS services](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html), and you must provide ARNs that identify AWS objects of the appropriate types for the chosen actions.
	//
	// The policy simulator only automatically loads policies associated with the `policySourceArn`, so if your given resources have their own resource-level policy then you'll also need to provide that explicitly using the `resourcePolicyJson` argument to achieve a realistic simulation.
	ResourceArns pulumi.StringArrayInput `pulumi:"resourceArns"`
	// Specifies a special simulation type to run. Some EC2 actions require special simulation behaviors and a particular set of resource ARNs to achieve a realistic result.
	//
	// For more details, see the `ResourceHandlingOption` request parameter for [the underlying `iam:SimulatePrincipalPolicy` action](https://docs.aws.amazon.com/IAM/latest/APIReference/API_SimulatePrincipalPolicy.html).
	ResourceHandlingOption pulumi.StringPtrInput `pulumi:"resourceHandlingOption"`
	// An AWS account ID to use for any resource ARN in `resourceArns` that doesn't include its own AWS account ID. If unspecified, the simulator will use the account ID from the `callerArn` argument as a placeholder.
	ResourceOwnerAccountId pulumi.StringPtrInput `pulumi:"resourceOwnerAccountId"`
	// An IAM policy document representing the resource-level policy of all of the resources specified in `resourceArns`.
	//
	// The policy simulator cannot automatically load policies that are associated with individual resources, as described in the documentation for `resourceArns` above.
	ResourcePolicyJson pulumi.StringPtrInput `pulumi:"resourcePolicyJson"`
}

func (LookupPrincipalPolicySimulationOutputArgs) ElementType() reflect.Type {
	return reflect.TypeOf((*LookupPrincipalPolicySimulationArgs)(nil)).Elem()
}

// A collection of values returned by getPrincipalPolicySimulation.
type LookupPrincipalPolicySimulationResultOutput struct{ *pulumi.OutputState }

func (LookupPrincipalPolicySimulationResultOutput) ElementType() reflect.Type {
	return reflect.TypeOf((*LookupPrincipalPolicySimulationResult)(nil)).Elem()
}

func (o LookupPrincipalPolicySimulationResultOutput) ToLookupPrincipalPolicySimulationResultOutput() LookupPrincipalPolicySimulationResultOutput {
	return o
}

func (o LookupPrincipalPolicySimulationResultOutput) ToLookupPrincipalPolicySimulationResultOutputWithContext(ctx context.Context) LookupPrincipalPolicySimulationResultOutput {
	return o
}

func (o LookupPrincipalPolicySimulationResultOutput) ActionNames() pulumi.StringArrayOutput {
	return o.ApplyT(func(v LookupPrincipalPolicySimulationResult) []string { return v.ActionNames }).(pulumi.StringArrayOutput)
}

func (o LookupPrincipalPolicySimulationResultOutput) AdditionalPoliciesJsons() pulumi.StringArrayOutput {
	return o.ApplyT(func(v LookupPrincipalPolicySimulationResult) []string { return v.AdditionalPoliciesJsons }).(pulumi.StringArrayOutput)
}

// `true` if all of the simulation results have decision "allowed", or `false` otherwise.
func (o LookupPrincipalPolicySimulationResultOutput) AllAllowed() pulumi.BoolOutput {
	return o.ApplyT(func(v LookupPrincipalPolicySimulationResult) bool { return v.AllAllowed }).(pulumi.BoolOutput)
}

func (o LookupPrincipalPolicySimulationResultOutput) CallerArn() pulumi.StringPtrOutput {
	return o.ApplyT(func(v LookupPrincipalPolicySimulationResult) *string { return v.CallerArn }).(pulumi.StringPtrOutput)
}

func (o LookupPrincipalPolicySimulationResultOutput) Contexts() GetPrincipalPolicySimulationContextArrayOutput {
	return o.ApplyT(func(v LookupPrincipalPolicySimulationResult) []GetPrincipalPolicySimulationContext { return v.Contexts }).(GetPrincipalPolicySimulationContextArrayOutput)
}

func (o LookupPrincipalPolicySimulationResultOutput) Id() pulumi.StringOutput {
	return o.ApplyT(func(v LookupPrincipalPolicySimulationResult) string { return v.Id }).(pulumi.StringOutput)
}

func (o LookupPrincipalPolicySimulationResultOutput) PermissionsBoundaryPoliciesJsons() pulumi.StringArrayOutput {
	return o.ApplyT(func(v LookupPrincipalPolicySimulationResult) []string { return v.PermissionsBoundaryPoliciesJsons }).(pulumi.StringArrayOutput)
}

func (o LookupPrincipalPolicySimulationResultOutput) PolicySourceArn() pulumi.StringOutput {
	return o.ApplyT(func(v LookupPrincipalPolicySimulationResult) string { return v.PolicySourceArn }).(pulumi.StringOutput)
}

func (o LookupPrincipalPolicySimulationResultOutput) ResourceArns() pulumi.StringArrayOutput {
	return o.ApplyT(func(v LookupPrincipalPolicySimulationResult) []string { return v.ResourceArns }).(pulumi.StringArrayOutput)
}

func (o LookupPrincipalPolicySimulationResultOutput) ResourceHandlingOption() pulumi.StringPtrOutput {
	return o.ApplyT(func(v LookupPrincipalPolicySimulationResult) *string { return v.ResourceHandlingOption }).(pulumi.StringPtrOutput)
}

func (o LookupPrincipalPolicySimulationResultOutput) ResourceOwnerAccountId() pulumi.StringPtrOutput {
	return o.ApplyT(func(v LookupPrincipalPolicySimulationResult) *string { return v.ResourceOwnerAccountId }).(pulumi.StringPtrOutput)
}

func (o LookupPrincipalPolicySimulationResultOutput) ResourcePolicyJson() pulumi.StringPtrOutput {
	return o.ApplyT(func(v LookupPrincipalPolicySimulationResult) *string { return v.ResourcePolicyJson }).(pulumi.StringPtrOutput)
}

// A set of result objects, one for each of the simulated requests, with the following nested attributes:
func (o LookupPrincipalPolicySimulationResultOutput) Results() GetPrincipalPolicySimulationResultArrayOutput {
	return o.ApplyT(func(v LookupPrincipalPolicySimulationResult) []GetPrincipalPolicySimulationResult { return v.Results }).(GetPrincipalPolicySimulationResultArrayOutput)
}

func init() {
	pulumi.RegisterOutputType(LookupPrincipalPolicySimulationResultOutput{})
}