Grant IAM permissions for CloudFormation Hooks
By default, a brand new user in your AWS account doesn't have permission to manage Hooks using the AWS Management Console, AWS Command Line Interface (AWS CLI), or AWS API. To grant users permission, an IAM administrator can create IAM policies. The administrator can then add the IAM policies to roles, and users can assume the roles.
Use the policy examples in this topic to create your own custom IAM policies to give users permissions to work with Hooks.
To learn how to create an IAM identity-based policy using these example JSON policy documents, see Define custom IAM permissions with customer managed policies in the IAM User Guide.
This topic covers the permissions that are needed to do the following:
-
Manage Hooks – Create, modify, and disable Hooks in your account.
-
Publish Hooks publicly – Register, test, and publish your custom Hooks to make them available publicly in the CloudFormation registry.
-
View invocation results – Access and query the results of Hook invocations in your account.
-
View details for an invocation result – Access detailed information and remediation guidance for a specific Hook invocation result in your account.
As you create your IAM policies, you can find documentation for all of the actions,
resources, and condition keys associated with the cloudformation service prefix
in the Actions,
resources, and condition keys for AWS CloudFormation section of the
Service Authorization Reference.
Topics
Allow a user to manage Hooks
If you need to allow users to manage extensions, including Hooks, without the ability to make them public in the CloudFormation registry, you can use the following example IAM policy.
Important
The ActivateType and SetTypeConfiguration API calls work
together to create Hooks in your account. When you grant a user permission to
call the SetTypeConfiguration API, you automatically grant them the
ability to modify and disable existing Hooks. You can't use resource-level
permissions to restrict access to this API call. Therefore, ensure that you grant
this permission only to authorized users in your account.
Users who manage Hooks might need some related permissions, for example:
-
To view proactive controls from the Control Catalog in the CloudFormation console, the user must have the
controlcatalog:ListControlspermission in an IAM policy. -
To register custom Hooks as private extensions in the CloudFormation registry, the user must have the
cloudformation:RegisterTypepermission in an IAM policy.
Allow a user to publish custom Hooks publicly
The following example IAM policy focuses specifically on publishing capabilities. Use this policy if you need to allow users to make extensions, including Hooks, available publicly in the CloudFormation registry.
Important
Publishing Hooks publicly makes them available to other AWS accounts. Ensure that only authorized users have these permissions and that published extensions meet your organization's quality and security standards.
Allow a user to view Hook invocation results
The IAM permissions needed to view Hook invocation results change depending on the type of information being requested.
List Hook invocation results
To list Hook invocation results, users need different permissions depending on the API request being made.
-
To grant permissions to request all Hook results, results for a specific Hook, or results for a specific Hook and invocation status, you must grant access to the
cloudformation:ListAllHookResultsaction. -
To grant permissions to request results by specifying a Hook target, you must grant access to the
cloudformation:ListHookResultsaction. This permission allows the API caller to specify theTargetTypeandTargetIdparameters when callingListHookResults.
The following shows an example of a basic permissions policy for listing Hook invocation results. IAM identities (users or roles) with this policy have permission to request all invocation results using all available parameter combinations.
Control which change sets can be specified
The following example IAM policy grants permissions to the
cloudformation:ListHookResults action to request results by
specifying the target of the Hook. However, it also denies the action
if the target is a change set named example-changeset.
Control which Hooks can be specified
The following example IAM policy grants permissions to the
cloudformation:ListAllHookResults action to request invocation
results only when the Hook's ARN is provided in the request. It denies
the action for a specified Hook ARN.
Allow a user to view detailed Hook invocation results
To grant permissions to view the detailed results of a specific Hook
invocation, you must grant access to the cloudformation:GetHookResult
action. This permission allows users to retrieve detailed information and remediation
guidance for a specific Hook invocation result. For more information, see
GetHookResult in the AWS CloudFormation API Reference.
The following example IAM policy grants permissions to the
cloudformation:GetHookResult action.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cloudformation:GetHookResult" ], "Resource": "*" } ] }
Note
You can configure Hooks to encrypt detailed invocation results stored in the cloud with your own AWS KMS keys. For information about how to set up the key policy and IAM permissions that you need when you use a customer managed key for encryption, see AWS KMS key policy and permissions for encrypting AWS CloudFormation Hooks results at rest.
