本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 IAM 許可權控制 REST API 的存取 透過控制對下列兩個 API Gateway 元件程序的存取，您可以使用 [IAM 許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html)控制對 Amazon API Gateway API 的存取： + 若要在 API Gateway 中建立、部署及管理 API，您必須授予 API 開發人員許可來執行 API Gateway 之 API 管理元件支援的必要動作。 + 若要呼叫已部署的 API 或重新整理 API 快取，您必須授予 API 發起人許可來執行 API Gateway 的 API 執行元件支援的必要 IAM 動作。 這兩個處理的存取控制需要不同的許可模型，以下將進行說明。 ## 建立與管理 API 的 API Gateway 許可模型 若要讓 API 開發人員在 API Gateway 中建立及管理 API，您必須[建立 IAM 許可政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)，允許指定的 API 開發人員建立、更新、部署、檢視或刪除必要的 [API 實體](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)。您會將許可政策附加到使用者、角色或群組。 若要提供存取權，請新增權限至您的使用者、群組或角色： + 中的使用者和群組 AWS IAM Identity Center： 建立權限合集。請按照《*AWS IAM Identity Center 使用者指南*》中的[建立權限合集](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html)說明進行操作。 + 透過身分提供者在 IAM 中管理的使用者： 建立聯合身分的角色。遵循《*IAM 使用者指南*》的[為第三方身分提供者 (聯合) 建立角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html)中的指示。 + IAM 使用者： + 建立您的使用者可擔任的角色。請按照《*IAM 使用者指南*》的[為 IAM 使用者建立角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html)中的指示。 + (不建議) 將政策直接附加至使用者，或將使用者新增至使用者群組。請遵循《*IAM 使用者指南*》的[新增許可到使用者 (主控台)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) 中的指示。 如需如何使用此許可模型的詳細資訊，請參閱「[API Gateway 身分類型政策](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies)」。 ## 用於呼叫 API 的 API Gateway 許可模型 若要讓 API 發起人呼叫 API 或重新整理其快取，您必須建立 IAM 政策，允許已啟用使用者身分驗證的指定 API 發起人呼叫 API 方法。API 開發人員可將方法的 `authorizationType` 屬性設定為 `AWS_IAM`，以要求發起人提交使用者的憑證以進行身份驗證。API Gateway 支援第 4a 版簽署程序 (SigV4a) 和第 4 版簽署程序 (SigV4) 來驗證使用者的憑證。如需詳細資訊，請參閱 [AWS 第 4 版簽署程序](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)。然後您可以將政策連接至使用者、角色或群組。 在此 IAM 許可政策陳述式中，IAM `Resource` 元素包含指定 HTTP 動詞與 API Gateway [資源路徑](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)所識別的已部署 API 方法清單。IAM `Action` 元素包含必要的 API Gateway API 執行動作。這些動作包含 `execute-api:Invoke` 或 `execute-api:InvalidateCache`，其中 `execute-api` 指定 API Gateway 的基礎 API 執行元件。 如需如何使用此許可模型的詳細資訊，請參閱「[控制對 API 的呼叫存取權](api-gateway-control-access-using-iam-policies-to-invoke-api.md)」。 當 API 在後端與 AWS 服務 （例如， AWS Lambda) 整合時，API Gateway 也必須具有代表 API 發起人存取整合 AWS 資源 （例如，叫用 Lambda 函數） 的許可。若要授予這些許可，請建立**適用於 API Gateway 的AWS 服務**類型的 IAM 角色。當您在 IAM 管理主控台建立此角色時，所產生的角色會包含下列 IAM 信任政策，其中宣告 API Gateway 是允許擔任該角色的受信任實體： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ 如果您藉由呼叫 [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) 的 CLI 命令或是藉由對應的軟體開發套件方法來建立 IAM 角色，則您必須將 `assume-role-policy-document` 的輸入參數提供給上述政策。請勿嘗試直接在 IAM 管理主控台或 calling AWS CLI [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) 命令或對應的 SDK 方法中建立此類政策。 若要讓 API Gateway 呼叫整合 AWS 服務，您還必須將 連接到此角色，以呼叫整合 AWS 服務的合適 IAM 許可政策。例如，若要呼叫 Lambda 函數，您必須在 IAM 角色中納入下列 IAM 許可政策： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "*" } ] } ``` ------ 請注意，Lambda 支援合併信任與許可政策的資源類型存取政策。使用 API Gateway 主控台整合 API 與 Lambda 函數時，不會要求您明確設定此 IAM 角色，因為主控台會在您的同意下，為您設定 Lambda 函數的資源型許可。 **注意** 若要對 AWS 服務制定存取控制，您可以使用以發起人為基礎的許可模型，其中許可政策直接連接到發起人的使用者或群組，或以角色為基礎的許可模型，其中許可政策連接到 API Gateway 可以擔任的 IAM 角色。這兩個模型的許可政策可能有所不同。例如，發起人類型政策會封鎖存取，而角色類型政策則會允許存取。您可以利用此功能，要求使用者只能透過 API Gateway API 存取 AWS 服務。 # 控制對 API 的呼叫存取權 在本節中，您會了解使用 IAM 許可控制 API 存取權的許可模型。啟用 IAM 授權時，用戶端必須使用 Signature 第 4a 版 (SigV4a) 和 Signature 第 4 版 (SigV4) 以 AWS 登入資料簽署其請求。如需詳細資訊，請參閱 [AWS 第 4 版簽署程序](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)。 在此區段中，我們會展示範本 IAM 政策聲明和政策聲明參考。政策聲明參考包括與 API 執行服務相關之 `Action` 與 `Resource` 欄位的格式。使用這些參考來建立您的 IAM 政策聲明。建立 IAM 政策聲明時，您可能需要考慮 API Gateway 資源政策影響授權工作流程的方式。如需詳細資訊，請參閱[API Gateway 資源政策如何影響授權工作流程](apigateway-authorization-flow.md)。 處理私有 API 時，您應結合使用 API Gateway 資源政策與 VPC 端點政策。如需詳細資訊，請參閱下列主題： + [使用 API Gateway 資源政策來控制對 REST API 的存取](apigateway-resource-policies.md) + [在 API Gateway 中使用私有 API 的 VPC 端點政策](apigateway-vpc-endpoint-policies.md) ## 控制誰可以使用 IAM 政策呼叫 API Gateway API 方法 若要控制誰可以或無法使用 IAM 許可呼叫已部署的 API，請以必要的許可建立 IAM 政策文件。這類政策文件的範本如下所示。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Permission", "Action": [ "execute-api:Execution-operation" ], "Resource": [ "arn:aws:execute-api:region:123456789012:api-id/stage/METHOD_HTTP_VERB/Resource-path" ] } ] } ``` ------ 在本例中，`Permission` 將根據您要授予或撤銷內含許可，取代為 `Allow` 或 `Deny`。`Execution-operation`​ 將取代為 API 執行服務支援的操作。`METHOD_HTTP_VERB`​ 代表指定資源支援的 HTTP 動詞。`Resource-path` 是支援上述 `METHOD_HTTP_VERB` 之已部署 API `[Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)` 執行個體的 URL 路徑預留位置。如需詳細資訊，請參閱[在 API Gateway 中執行 API 之 IAM 政策的陳述式參考](#api-gateway-calling-api-permissions)。 **注意** 若要讓 IAM 政策生效，您必須將方法的 `[authorizationType](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType)` 屬性設定為 `AWS_IAM`，以啟用 API 方法上的 IAM 身分驗證。不這樣做會使這些 API 方法可供公開存取。 例如，若要授予使用者檢視指定 API 所公開之寵物清單的許可，但拒絕使用者將寵物新增至清單的許可，您可以在 IAM 政策中包含下列陳述式： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/*/GET/pets" ] }, { "Effect": "Deny", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/*/POST/pets" ] } ] } ``` ------ 若要授予使用者許可，讓他們可以檢視設定為 `GET /pets/{petId}` 之 API 所公開的特定寵物，您可以在 IAM 政策中包含以下陳述式： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111122223333:api-id/*/GET/pets/a1b2" ] } ] } ``` ------ ## 在 API Gateway 中執行 API 之 IAM 政策的陳述式參考 下列資訊說明執行 API 的存取許可之 IAM 政策陳述式的動作與資源格式。 ### 在 API Gateway 中執行 API 之許可的動作格式 API 執行 `Action` 表達式具有下列一般格式： ``` execute-api:action ``` 其中 *action* 是可用的 API 執行動作： + **\$1**，表示下列所有動作。 + **Invoke**，在用戶端請求下用來呼叫 API。 + **InvalidateCache**，在用戶端請求下用來使 API 快取失效。 ### 在 API Gateway 中執行 API 之許可的資源格式 API 執行 `Resource` 表達式具有下列一般格式： ``` arn:aws:execute-api:region:account-id:api-id/stage-name/HTTP-VERB/resource-path-specifier ``` 其中： + *region* 是對應至 方法之已部署 API AWS 的區域 （例如 **us-east-1**或**\$1**所有 AWS 區域的 )。 + *account-id* 是 REST API 擁有者的 12 位數 AWS 帳戶 ID。 + *api-id* 是 API Gateway 分配給該方法之 API 的標識符。 + *stage-name* 是與方法相關聯的階段名稱。 + *HTTP-VERB* 是方法的 HTTP 動詞。它可以是下列其中一項：GET、POST、PUT、DELETE、PATCH。 + *resource-path-specifier* 是所需方法的路徑 **注意** 如果您指定萬用字元 (`*`)，則 `Resource` 表達式會將萬用字元套用至表達式的其餘部分。 一些範例資源表達式包括： + **arn:aws:execute-api:\$1:\$1:\$1** 用於任何階段中的任何資源路徑， 用於任何 AWS 區域中的任何 API。 + **arn:aws:execute-api:us-east-1:\$1:\$1** 對於任何階段中的任何資源路徑，對於 AWS 區域中的任何 API`us-east-1`。 + **arn:aws:execute-api:us-east-1:\$1:*api-id*/\$1** 對於任何階段中的任何資源路徑，對於 us-east-1 AWS 區域中識別符為 *api-id* 的 API。 + **arn:aws:execute-api:us-east-1:\$1:*api-id*/`test`/\$1**，表示 us-east-1 的 AWS 區域中識別符為 *api-id* 之 API `test` 階段的任何資源路徑。 如需詳細資訊，請參閱 [API Gateway Amazon Resource Name (ARN) 參考資料](arn-format-reference.md)。 # API 執行許可的 IAM 政策範例 如需許可模型與其他背景資訊，請參閱「[控制對 API 的呼叫存取權](api-gateway-control-access-using-iam-policies-to-invoke-api.md)」。 下列政策聲明會授予使用者許可，以呼叫識別符為 `a123456789` 之 API 的 `test` 階段中沿著 `mydemoresource` 路徑的任何 POST 方法 (假設對應的 API 已部署至 us-east-1 的 AWS 區域)： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:*:a123456789/test/POST/my-demo-resource-path/*" ] } ] } ``` ------ 下列範例政策陳述式會提供使用者許可，在已部署識別符為 `petstorewalkthrough/pets` 之 API 的 `a123456789` 區域中，呼叫對應 API 之任何階段中資源路徑 AWS 上的任何方法： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:*:*:a123456789/*/*/petstorewalkthrough/pets" ] } ] } ``` ------