本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# API 連結政策存放區
常見的使用案例是使用 Amazon Verified Permissions 授權使用者存取 Amazon API Gateway 上託管APIs API。 Amazon API Gateway 使用 AWS 主控台中的精靈，您可以為在 [Amazon Cognito](https://aws.amazon.com/cognito) 或任何 OIDC 身分提供者 (IdP) 中管理的使用者建立角色型存取政策，並部署 AWS Lambda 呼叫已驗證許可來評估這些政策的授權方。
若要完成精靈，請在[建立新政策存放](policy-stores-create.md)區時，選擇**使用 API 閘道 和身分提供者設定**，然後依照步驟進行。
建立 API 連結政策存放區，並佈建授權模型和資源以用於授權請求。政策存放區具有連線至 API 閘道 已驗證許可的身分來源和 Lambda 授權方。建立政策存放區後，您可以根據使用者的群組成員資格來授權 API 請求。例如，Verified Permissions 只能將存取權授予群組成員的使用者`Directors`。
隨著應用程式的成長，您可以使用 [Cedar 政策語言](https://docs.cedarpolicy.com/)，透過使用者屬性和 OAuth 2.0 範圍來實作精細的授權。例如，Verified Permissions 只能將存取權授予網域 中具有 `email` 屬性的使用者`mycompany.co.uk`。
設定 API 的授權模型之後，您剩餘的責任是驗證使用者，並在應用程式中產生 API 請求，並維護您的政策存放區。
若要查看示範，請參閱 *Amazon Web Services YouTube 頻道*上的 [Amazon Verified Permissions - Quick Start Overview 和示範](https://www.youtube.com/watch?v=OBrSrzfuWhQ)。
**Topics**
+ [Verified Permissions 如何授權 API 請求](#policy-stores-api-userpool-how-it-works)
+ [API 連結政策存放區的考量事項](#policy-stores-api-userpool-considerations)
+ [新增屬性型存取控制 (ABAC)](#policy-stores-api-userpool-abac)
+ [使用 移至生產環境 AWS CloudFormation](policy-stores-api-userpool-considerations-production.md)
+ [疑難排解 API 連結政策存放區](policy-stores-api-userpool-considerations-troubleshooting.md)
**重要**
您在 Verified Permissions 主控台中使用**設定 API 閘道 和身分來源**選項建立的政策存放區不適用於立即部署到生產環境。使用初始政策存放區，完成授權模型並將政策存放區資源匯出至 CloudFormation。使用 以程式設計方式將已驗證的許可部署至生產環境[AWS Cloud Development Kit (AWS CDK)](https://aws.amazon.com/cdk)。如需詳細資訊，請參閱[使用 移至生產環境 AWS CloudFormation](policy-stores-api-userpool-considerations-production.md)。
在連結至 API 和身分來源的政策存放區中，您的應用程式會在向 API 提出請求時，在授權標頭中顯示使用者集區字符。政策存放區的身分來源提供驗證許可的字符驗證。字符會使用 [IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html) API 在授權請求`principal`中形成 。Verified Permissions 會針對使用者的群組成員資格建立政策，如身分 (ID) 和存取權杖中的群組宣告所示，例如`cognito:groups`使用者集區。您的 API 會在 Lambda 授權方中處理您應用程式的權杖，並將其提交至 Verified Permissions 以進行授權決策。當您的 API 從 Lambda 授權方收到授權決策時，它會將請求傳遞到您的資料來源或拒絕請求。
**使用 Verified Permissions 進行身分來源和 API 閘道 授權的元件**
+ 驗證和分組[Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html)使用者的使用者集區或 OIDC IdP。使用者的字符會填入群組成員資格，以及 Verified Permissions 在政策存放區中評估的主體或內容。
+ [API 閘道](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html) REST API。Verified Permissions 會從 API 路徑和 API 方法定義動作，例如 `MyAPI::Action::get /photo`。
+ 適用於 API 的 Lambda 函數和 [Lambda 授權方](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)。Lambda 函數會從使用者集區取得承載字符、向 Verified Permissions 請求授權，並將決策傳回給 API 閘道。**使用 API 閘道 和身分來源工作流程設定** 會自動為您建立此 Lambda 授權方。
+ Verified Permissions 政策存放區。政策存放區身分來源是您的 Amazon Cognito 使用者集區或 OIDC 提供者群組。政策存放區結構描述會反映 API 的組態，而政策會將使用者群組連結至允許的 API 動作。
+ 使用 IdP 驗證使用者並附加字符至 API 請求的應用程式。
## Verified Permissions 如何授權 API 請求
當您建立新的政策存放區並選取**使用 API 閘道 和身分來源設定**選項時，Verified Permissions 會建立政策存放區結構描述和政策。結構描述和政策會反映 API 動作，以及您想要授權 採取動作的使用者群組。Verified Permissions 也會建立 Lambda 函數和[授權方](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)。
1. 您的使用者透過 Amazon Cognito 或其他 OIDC IdP 使用您的應用程式登入。IdP 會發出 ID 和存取字符與使用者的資訊。
1. 您的應用程式會存放 JWTs。如需詳細資訊，請參閱《 *Amazon Cognito 開發人員指南*》中的[搭配使用者集區使用字符](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html)。
1. 您的使用者請求您的應用程式必須從外部 API 擷取的資料。
1. 您的應用程式向其中的 REST API 請求資料 API 閘道。它會將 ID 或存取權杖附加為請求標頭。
1. 如果您的 API 具有授權決策的快取，則會傳回先前的回應。如果停用快取或 API 目前沒有快取， API 閘道 會將請求參數傳遞給[字符型 Lambda 授權方](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)。
1. Lambda 函數會使用 [IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html) API 將授權請求傳送至 Verified Permissions 政策存放區。Lambda 函數會傳遞授權決策的元素：
1. 使用者字符做為委託人。
1. API 方法與 API 路徑結合，例如 `GetPhoto`作為 動作。
1. 資源`Application`的術語。
1. Verified Permissions 會驗證權杖。如需如何驗證 Amazon Cognito 字符的詳細資訊，請參閱《 *Amazon Cognito 開發人員指南*》中的[使用 Amazon 驗證許可進行授權](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-authorization-with-avp.html)。
1. Verified Permissions 會根據政策存放區中的政策評估授權請求，並傳回授權決策。
1. Lambda 授權方會傳回 `Allow`或 `Deny`回應 API 閘道。
1. API 會傳回資料或`ACCESS_DENIED`回應給您的應用程式。您的應用程式會處理並顯示 API 請求的結果。
## API 連結政策存放區的考量事項
當您在 Verified Permissions 主控台中建置 API 連結政策存放區時，您正在為最終生產部署建立測試。移至生產環境之前，請為您的 API 和使用者集區建立固定組態。請考慮下列因素：
**API 閘道 快取回應**
在 API 連結政策存放區中，Verified Permissions 會建立**授權快取** TTL 為 120 秒的 Lambda 授權方。您可以調整此值或關閉授權方中的快取。在啟用快取的 授權方中，您的授權方每次都會傳回相同的回應，直到 TTL 過期為止。這可以將使用者集區字符的有效生命週期延長至等於所請求階段快取 TTL 的持續時間。
**Amazon Cognito 群組可以重複使用**
Amazon Verified Permissions 會從使用者 ID 或存取權杖中的`cognito:groups`宣告，判斷使用者集區使用者的群組成員資格。此宣告的值是使用者所屬之使用者集區群組的易記名稱陣列。您無法將使用者集區群組與唯一識別符建立關聯。
您刪除的使用者集區群組，並以與相同群組相同的名稱重新建立到您的政策存放區。當您從使用者集區刪除群組時，請從您的政策存放區刪除群組的所有參考。
**API 衍生的命名空間和結構描述是point-in-time**
Verified Permissions 會在*某個時間點*擷取您的 API：它只會在您建立政策存放區時查詢您的 API。當 API 的結構描述或名稱變更時，您必須更新政策存放區和 Lambda 授權方，或建立新的 API 連結政策存放區。Verified Permissions 會從 API 的名稱衍生政策存放區[命名空間](https://docs.cedarpolicy.com/schema/schema.html#schema-namespace)。
**Lambda 函數沒有 VPC 組態**
Verified Permissions 為您的 API 授權方建立的 Lambda 函數會在預設 VPC 中啟動。預設情況下。限制網路存取私有 VPCs APIs 無法與授權使用 Verified Permissions 存取請求的 Lambda 函數通訊。
**Verified Permissions 在 CloudFormation 中部署授權方資源**
若要建立 API 連結政策存放區，您必須登入 Verified Permissions 主控台的高權限 AWS 主體。此使用者部署的 CloudFormation 堆疊可跨數個 建立資源 AWS 服務。此主體必須具有在 Verified Permissions、 IAM Lambda 和 中新增和修改資源的許可 API 閘道。根據最佳實務，請勿與組織中的其他管理員共用這些登入資料。
[使用 移至生產環境 AWS CloudFormation](policy-stores-api-userpool-considerations-production.md) 如需 Verified Permissions 建立的資源概觀，請參閱 。
## 新增屬性型存取控制 (ABAC)
具有 IdP 的典型身分驗證工作階段會傳回 ID 和存取權杖。您可以在應用程式請求中將這些字符類型做為承載字符傳遞至您的 API。視您在建立政策存放區時的選擇而定，已驗證許可預期兩種字符類型之一。這兩種類型都包含有關使用者群組成員資格的資訊。如需 中字符類型的詳細資訊 Amazon Cognito，請參閱《 *Amazon Cognito 開發人員指南*》中的[搭配使用者集區使用字符](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html)。
建立政策存放區之後，您可以新增和延伸政策。例如，您可以在將新群組新增至使用者集區時，將新群組新增至政策。由於您的政策存放區已了解您的使用者集區在字符中呈現群組的方式，因此您可以針對具有新政策的任何新群組，允許一組動作。
您可能也想要根據使用者屬性，將政策評估的群組型模型擴展為更精確的模型。使用者集區字符包含其他使用者資訊，有助於授權決策。
**ID 字符**
ID 字符代表使用者的屬性，並具有高層級的精細存取控制。若要評估電子郵件地址、電話號碼或自訂屬性，例如部門和經理，請評估 ID 字符。
**存取權杖**
存取字符代表具有 OAuth 2.0 範圍的使用者許可。若要新增授權層或設定其他資源的請求，請評估存取權杖。例如，您可以驗證使用者是否在適當的群組中，*並*具有像一般授權存取 API `PetStore.read` 的範圍。使用者集區可以將自訂範圍新增至具有[資源伺服器的](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html)權杖，並在[執行時間使用權杖自訂](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html#user-pool-lambda-pre-token-generation-accesstoken)。
如需在 ID 和存取[Amazon Cognito 字符中處理宣告的範例政策，請參閱將字符映射至結構](cognito-map-token-to-schema.md)描述和將 [OIDC 字符映射至結構](oidc-map-token-to-schema.md)描述。