本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 授予 CloudFormation Hooks 的 IAM 許可
<a name="grant-iam-permissions-for-hooks"></a>

根據預設，您 中的新使用者 AWS 帳戶 沒有使用 AWS 管理主控台、 AWS Command Line Interface (AWS CLI) 或 AWS API 管理勾點的許可。若要授予使用者許可，IAM 管理員可以建立 IAM 政策。然後，管理員可以將 IAM 政策新增至角色，使用者便能擔任這些角色。

使用本主題中的政策範例來建立您自己的自訂 IAM 政策，以授予使用者使用 Hooks 的許可。

若要了解如何使用這些範例 JSON 政策文件建立 IAM 身分型政策，請參閱《[IAM 使用者指南》中的使用客戶受管政策定義自訂 IAM 許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)。 **

本主題涵蓋執行下列動作所需的許可：
+ **管理勾點** – 在帳戶中建立、修改和停用勾點。
+ **公開發佈勾點** – 註冊、測試和發佈您的自訂勾點，以便在 CloudFormation 登錄檔中公開提供。
+ **檢視調用結果** – 存取和查詢您帳戶中的 Hook 調用結果。
+ **檢視調用結果的詳細資訊** – 存取您帳戶中特定 Hook 調用結果的詳細資訊和修補指導。

建立 IAM 政策時，您可以在`cloudformation`服務*授權參考* 章節的動作、資源和條件索引鍵中找到與服務字首相關聯的所有[動作、資源和條件索引鍵 CloudFormation](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awscloudformation.html)的文件。

**Topics**
+ [允許使用者管理勾點](#iam-permissions-to-manage-hooks)
+ [允許使用者公開發佈自訂勾點](#iam-permissions-for-public-hook-publishing)
+ [允許使用者檢視勾點調用結果](#iam-permissions-to-request-invocation-results)
+ [允許使用者檢視詳細的勾點調用結果](#get-detailed-hook-invocation-results)
+ [AWS KMS 加密靜態 CloudFormation Hooks 結果的金鑰政策和許可](hooks-kms-key-policy.md)

## 允許使用者管理勾點
<a name="iam-permissions-to-manage-hooks"></a>

如果您需要允許使用者管理延伸模組，包括勾點，而不能在 CloudFormation 登錄檔中公開這些延伸模組，您可以使用下列範例 IAM 政策。

**重要**  
`ActivateType` 和 `SetTypeConfiguration` API 呼叫一起運作，在您的 帳戶中建立勾點。當您授予使用者呼叫 `SetTypeConfiguration` API 的許可時，您會自動授予他們修改和停用現有勾點的能力。您無法使用資源層級許可來限制對此 API 呼叫的存取。因此，請確定您僅將此許可授予帳戶中的授權使用者。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:ActivateType",
                "cloudformation:DescribeType",
                "cloudformation:ListTypes",
                "cloudformation:SetTypeConfiguration"
            ],
            "Resource": "*"
        }
    ]
}
```

------

管理勾點的使用者可能需要一些相關的許可，例如：
+ 若要在 CloudFormation 主控台中從 Control Catalog 檢視主動控制，使用者必須擁有 IAM 政策中的 `controlcatalog:ListControls`許可。
+ 若要在 CloudFormation 登錄檔中將自訂勾點註冊為私有延伸，使用者必須在 IAM 政策中擁有 `cloudformation:RegisterType`許可。

## 允許使用者公開發佈自訂勾點
<a name="iam-permissions-for-public-hook-publishing"></a>

下列範例 IAM 政策特別著重於發佈功能。如果您需要允許使用者在 CloudFormation 登錄檔中公開使用延伸項目，包括勾點，請使用此政策。

**重要**  
發佈勾點可公開提供給其他 AWS 帳戶。確保只有授權使用者具有這些許可，且已發佈的延伸符合組織的品質和安全標準。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:DescribePublisher",
                "cloudformation:DescribeTypeRegistration",
                "cloudformation:ListTypes",
                "cloudformation:ListTypeVersions",
                "cloudformation:PublishType",
                "cloudformation:RegisterPublisher",
                "cloudformation:RegisterType",
                "cloudformation:TestType"
            ],
            "Resource": "*"
        }
    ]
}
```

------

## 允許使用者檢視勾點調用結果
<a name="iam-permissions-to-request-invocation-results"></a>

檢視勾點調用結果所需的 IAM 許可會根據請求的資訊類型而變更。

### 列出勾點調用結果
<a name="list-hook-invocation-results"></a>

若要列出勾點調用結果，使用者需要不同的許可，具體取決於提出的 API 請求。
+ 若要授予請求所有勾點結果、特定勾點結果或特定勾點和調用狀態結果的許可，您必須授予 `cloudformation:ListAllHookResults` 動作的存取權。
+ 若要透過指定勾點目標授予請求結果的許可，您必須授予 `cloudformation:ListHookResults` 動作的存取權。此許可允許 API 呼叫者在呼叫 時指定 `TargetType`和 `TargetId` 參數`ListHookResults`。

以下顯示列出勾點調用結果的基本許可政策範例。具有此政策的 IAM 身分 （使用者或角色） 具有使用所有可用參數組合來請求所有調用結果的許可。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:ListAllHookResults",
                "cloudformation:ListHookResults"
            ],
            "Resource": "*"
        }
    ]
}
```

------

#### 控制可以指定哪些變更集
<a name="control-which-change-sets"></a>

下列範例 IAM 政策會指定 勾點的目標，授予 `cloudformation:ListHookResults` 動作請求結果的許可。不過，如果目標是名為 的變更集，也會拒絕該動作`example-changeset`。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:ListHookResults"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Deny",
            "Action": [
                "cloudformation:ListHookResults"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "cloudformation:ChangeSetName": "example-changeset"
                }
            }
        }
    ]
}
```

------

#### 控制可以指定哪些勾點
<a name="control-which-hooks"></a>

下列範例 IAM 政策授予 `cloudformation:ListAllHookResults` 動作的許可，僅在請求中提供 Hook 的 ARN 時請求調用結果。它會拒絕指定 Hook ARN 的動作。

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:ListAllHookResults"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Deny",
            "Action": [
                "cloudformation:ListAllHookResults"
            ],
            "Resource": "*",
            "Condition": {
                "Null": {
                    "cloudformation:TypeArn": "true"
                }
            }
        },
        {
            "Effect": "Deny",
            "Action": [
                "cloudformation:ListAllHookResults"
            ],
            "Resource": "*",
            "Condition": {
                "ArnEquals": {
                    "cloudformation:TypeArn": "arn:aws:cloudformation:us-east-1:123456789012:type/hook/MyCompany-MyHook"
                }
            }
        }
    ]
}
```

------

## 允許使用者檢視詳細的勾點調用結果
<a name="get-detailed-hook-invocation-results"></a>

若要授予許可來檢視特定 Hook 調用的詳細結果，您必須授予 `cloudformation:GetHookResult` 動作的存取權。此許可允許使用者擷取特定 Hook 調用結果的詳細資訊和修補指導。如需詳細資訊，請參閱《 *AWS CloudFormation API 參考*》中的 [GetHookResult](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_GetHookResult.html)。

下列範例 IAM 政策授予 `cloudformation:GetHookResult`動作的許可。

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
       "Action": [
         "cloudformation:GetHookResult"
      ],
      "Resource": "*"
    }
  ]
}
```

------

**注意**  
您可以設定勾點，使用您自己的 AWS KMS 金鑰加密存放在雲端中的詳細調用結果。如需有關如何在使用客戶受管金鑰進行加密時設定金鑰政策和所需的 IAM 許可的資訊，請參閱 [AWS KMS 加密靜態 CloudFormation Hooks 結果的金鑰政策和許可](hooks-kms-key-policy.md)。

# AWS KMS 加密靜態 CloudFormation Hooks 結果的金鑰政策和許可
<a name="hooks-kms-key-policy"></a>

本主題說明如何設定當您指定客戶受管金鑰來加密可從 [GetHookResult](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_GetHookResult.html) API 取得的 Hooks 註釋資料時所需的 AWS KMS 金鑰政策和許可。

**注意**  
CloudFormation 勾點不需要額外的授權，即可使用預設值 AWS 擁有的金鑰 來加密帳戶中的註釋資料。

**Topics**
+ [概觀](#hooks-kms-overview)
+ [使用加密內容控制對客戶受管金鑰的存取](#hooks-encryption-context-security)
+ [客戶受管 KMS 金鑰政策](#hooks-policy-example-cmk-access)
+ [`SetTypeConfiguration` API 的 KMS 許可](#hooks-policy-example-settypeconfiguration-permissions)
+ [`GetHookResult` API 的 KMS 許可](#hooks-policy-example-gethookresult-permissions)

## 概觀
<a name="hooks-kms-overview"></a>

下列項目 AWS KMS keys 可用於加密 Hook 註釋資料：
+ [AWS 擁有的金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-owned-cmk) – 根據預設，CloudFormation 會使用 AWS 擁有的金鑰 來加密資料。您無法檢視、管理或使用 AWS 擁有的金鑰或稽核其使用方式。不過，您不需要執行明確的組態來保護用來加密資料的金鑰。 AWS 擁有的金鑰 是免費的 （無需每月費用或使用費）。除非您需要稽核或控制保護註釋資料的加密金鑰，否則 AWS 擁有的金鑰 是不錯的選擇。
+ [客戶受管金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) – CloudFormation 支援使用您建立、擁有和管理的對稱客戶受管金鑰，在現有的 上新增第二層加密 AWS 擁有的金鑰。需支付 AWS KMS 費用。如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》**中的[建立金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)。若要管理您的金鑰，請在 AWS Key Management Service [AWS KMS 主控台](https://console.aws.amazon.com/kms) AWS CLI、 或 AWS KMS API 中使用 (AWS KMS)。如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》[https://docs.aws.amazon.com/kms/latest/developerguide/](https://docs.aws.amazon.com/kms/latest/developerguide/)。

您可以在建立和更新勾點時設定客戶受管金鑰。當您提供客戶受管金鑰時，CloudFormation 會使用此金鑰在儲存註釋資料之前對其進行加密。當註釋資料稍後在 `GetHookResult` API 操作期間存取時，CloudFormation 會自動將其解密。如需設定 Hooks 加密金鑰的相關資訊，請參閱 [勾點組態結構描述語法參考](hook-configuration-schema.md)。

**重要**  
請注意，指定客戶受管金鑰`KmsKeyId`的選項目前只有在您使用 AWS CLI 來設定勾點時才能使用。

## 使用加密內容控制對客戶受管金鑰的存取
<a name="hooks-encryption-context-security"></a>

CloudFormation Hooks 會自動在每個註釋儲存和擷取操作中包含加密內容。這可讓您在金鑰政策中設定加密內容條件，以確保金鑰只能用於特定勾點：
+ `kms:EncryptionContext:aws:cloudformation:hooks:service` – 確保金鑰僅供 CloudFormation Hooks 服務使用。
+ `kms:EncryptionContext:aws:cloudformation:account-id` – 透過比對您的 AWS 帳戶 ID 來防止跨帳戶金鑰使用。
+ `kms:EncryptionContext:aws:cloudformation:arn` – 使用 ARN 模式限制特定勾點的使用。

這些條件透過密碼編譯方式將加密的資料繫結至特定 Hook 內容，提供額外的保護，避免混淆代理人攻擊。

## 客戶受管 KMS 金鑰政策
<a name="hooks-policy-example-cmk-access"></a>

建立客戶受管金鑰時，您必須定義其金鑰政策，以允許 CloudFormation Hooks 服務執行 AWS KMS 操作。若要使用下列金鑰政策，請將*預留位置值*取代為您自己的資訊。

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "EnableIAMUserDescribeKey",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/ExampleRole"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "cloudformation.us-east-1.amazonaws.com"
        }
      }
    },
    {
      "Sid": "EnableIAMUserGenerateDataKey",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/ExampleRole"
      },
      "Action": "kms:GenerateDataKey",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "cloudformation.us-east-1.amazonaws.com",
          "kms:EncryptionContext:aws:cloudformation:hooks:service": "hooks.cloudformation.amazonaws.com",
          "kms:EncryptionContext:aws:cloudformation:123456789012": "123456789012"
        },
        "ArnLike": {
          "kms:EncryptionContext:aws:cloudformation:arn": "arn:aws:cloudformation:*:123456789012:hook/*"
        }
      }
    },
    {
      "Sid": "EnableIAMUserDecrypt",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/ExampleRole"
      },
      "Action": "kms:Decrypt",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "cloudformation.us-east-1.amazonaws.com"
        }
      }
    },
    {
      "Sid": "AllowHooksServiceDescribeKey",
      "Effect": "Allow",
      "Principal": {
        "Service": "hooks.cloudformation.amazonaws.com"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:cloudformation:*:123456789012:hook/*"
        }
      }
    },
    {
      "Sid": "AllowHooksService",
      "Effect": "Allow",
      "Principal": {
        "Service": "hooks.cloudformation.amazonaws.com"
      },
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012",
          "kms:EncryptionContext:aws:cloudformation:hooks:service": "hooks.cloudformation.amazonaws.com",
          "kms:EncryptionContext:aws:cloudformation:123456789012": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:cloudformation:*:123456789012:hook/*",
          "kms:EncryptionContext:aws:cloudformation:arn": "arn:aws:cloudformation:*:123456789012:hook/*"
        }
      }
    }
  ]
}
```

------

此政策會將許可授予 IAM 角色 （前三個陳述式） 和 CloudFormation Hooks 服務 （最後兩個陳述式）。`kms:ViaService` 條件金鑰可確保 KMS 金鑰只能透過 CloudFormation 使用，防止直接 KMS API 呼叫。金鑰操作包括：
+ `kms:DescribeKey` – 驗證金鑰屬性和中繼資料。此操作位於不同的陳述式中，因為它無法與加密內容條件搭配使用。
+ `kms:GenerateDataKey` – 產生資料加密金鑰，以在儲存前加密註釋。此操作包含範圍存取控制的加密內容條件。
+ `kms:Decrypt` – 解密先前加密的註釋資料。對於 IAM 角色，這包含 `kms:ViaService`條件。對於服務主體，這包含加密內容條件。

`aws:SourceAccount` 和 `aws:SourceArn`條件索引鍵提供主要保護，防止混淆代理人攻擊。加密內容條件提供額外的驗證層。如需詳細資訊，請參閱《 *AWS Key Management Service 開發人員指南*》中的[使用 aws:SourceArn或 aws:SourceAccount條件金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/least-privilege.html#least-privilege-source-arn)。

**重要**  
勾點執行角色不需要 AWS KMS 許可。CloudFormation Hooks 服務主體會執行所有 AWS KMS 操作。

## `SetTypeConfiguration` API 的 KMS 許可
<a name="hooks-policy-example-settypeconfiguration-permissions"></a>

在 [SetTypeConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SetTypeConfiguration.html) API 呼叫期間，CloudFormation 會驗證使用者使用指定 AWS KMS 金鑰加密註釋資料的許可。將下列 IAM 政策新增至將使用 `SetTypeConfiguration` API 設定加密的使用者或角色。使用您的資訊取代*預留位置的值*。

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cloudformation:SetTypeConfiguration",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "kms:DescribeKey",
      "Resource": "arn:aws:kms:us-east-1:123456789012:key/abc-123"
    },
    {
      "Effect": "Allow",
      "Action": "kms:GenerateDataKey",
      "Resource": "arn:aws:kms:us-east-1:123456789012:key/abc-123",
      "Condition": {
        "StringEquals": {
          "kms:EncryptionContext:aws:cloudformation:hooks:service": "hooks.cloudformation.amazonaws.com",
          "kms:EncryptionContext:aws:cloudformation:123456789012": "123456789012"
        },
        "ArnLike": {
          "kms:EncryptionContext:aws:cloudformation:arn": "arn:aws:cloudformation:*:123456789012:hook/*"
        }
      }
    }
  ]
}
```

------

## `GetHookResult` API 的 KMS 許可
<a name="hooks-policy-example-gethookresult-permissions"></a>

若要呼叫使用客戶受管金鑰的 [GetHookResult](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_GetHookResult.html) for Hooks，使用者必須擁有該金鑰的`kms:Decrypt`許可。將下列 IAM 政策新增至將呼叫 的使用者或角色`GetHookResult`。`arn:aws:kms:us-east-1:123456789012:key/abc-123` 使用客戶受管金鑰的 ARN 取代 。

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cloudformation:GetHookResult",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "arn:aws:kms:us-east-1:123456789012:key/abc-123"
    }
  ]
}
```

------