API 連結政策存放區 - Amazon Verified Permissions
運作方式考量事項新增 ABAC

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

API 連結政策存放區

常見的使用案例是使用 Amazon Verified Permissions 授權使用者存取 Amazon API Gateway 上託管APIs API。 Amazon API Gateway 使用 AWS 主控台中的精靈，您可以為在 Amazon Cognito 或任何 OIDC 身分提供者 (IdP) 中管理的使用者建立角色型存取政策，並部署 AWS Lambda 呼叫已驗證許可來評估這些政策的授權方。

若要完成精靈，請在建立新政策存放區時，選擇使用 API Gateway 和身分提供者設定，然後依照步驟進行。

建立 API 連結政策存放區，並佈建您的授權模型和資源以進行授權請求。政策存放區具有將 API Gateway 連線至已驗證許可的身分來源和 Lambda 授權方。建立政策存放區後，您可以根據使用者的群組成員資格來授權 API 請求。例如，Verified Permissions 只能將存取權授予群組成員的使用者Directors。

隨著應用程式的成長，您可以使用 Cedar 政策語言，透過使用者屬性和 OAuth 2.0 範圍來實作精細的授權。例如，Verified Permissions 只能將存取權授予網域 中具有 email 屬性的使用者mycompany.co.uk。

設定 API 的授權模型之後，您剩餘的責任是驗證使用者，並在應用程式中產生 API 請求，並維護您的政策存放區。

若要查看示範，請參閱 Amazon Web Services YouTube 頻道上的 Amazon Verified Permissions - Quick Start Overview 和示範。

主題
重要

您使用 API Gateway 設定和 Verified Permissions 主控台中的身分來源選項建立的政策存放區不適用於立即部署到生產環境。使用初始政策存放區，完成授權模型並將政策存放區資源匯出至 CloudFormation。使用 AWS 雲端開發套件 (CDK)，以程式設計方式將已驗證的許可部署至生產環境。如需詳細資訊，請參閱使用 移至生產環境 AWS CloudFormation。

在連結至 API 和身分來源的政策存放區中，您的應用程式會在向 API 提出請求時，在授權標頭中顯示使用者集區字符。政策存放區的身分來源提供驗證許可的字符驗證。字符會使用 IsAuthorizedWithToken API 在授權請求principal中形成 。Verified Permissions 會針對使用者的群組成員資格建置政策，如身分 (ID) 和存取權杖中的群組宣告所示，例如cognito:groups使用者集區。您的 API 會在 Lambda 授權方中處理您應用程式的權杖，並將其提交至 Verified Permissions 以進行授權決策。當您的 API 從 Lambda 授權方收到授權決策時，它會將請求傳遞到您的資料來源或拒絕請求。

具有 Verified Permissions 的身分來源和 API Gateway 授權的元件

  • 驗證和分組使用者的 Amazon Cognito 使用者集區或 OIDC IdP。使用者的字符會填入群組成員資格，以及 Verified Permissions 在政策存放區中評估的主體或內容。

  • API Gateway REST API。Verified Permissions 會從 API 路徑和 API 方法定義動作，例如 MyAPI::Action::get /photo。

  • 適用於 API 的 Lambda 函數和 Lambda 授權方。Lambda 函數會從使用者集區取得承載字符、請求 Verified Permissions 的授權，並將決策傳回給 API Gateway。使用 API Gateway 和身分來源工作流程設定 會自動為您建立此 Lambda 授權方。

  • Verified Permissions 政策存放區。政策存放區身分來源是您的 Amazon Cognito 使用者集區或 OIDC 提供者群組。政策存放區結構描述會反映 API 的組態，而政策會將使用者群組連結至允許的 API 動作。

  • 使用 IdP 驗證使用者並附加字符至 API 請求的應用程式。

Verified Permissions 如何授權 API 請求

當您建立新的政策存放區並選取使用 API Gateway 和身分來源設定選項時，Verified Permissions 會建立政策存放區結構描述和政策。結構描述和政策會反映 API 動作，以及您想要授權 採取動作的使用者群組。Verified Permissions 也會建立 Lambda 函數和授權方。

顯示具有 Amazon API Gateway、Amazon Cognito 和 Amazon Verified Permissions 的授權請求流程的圖表。

  1. 您的使用者透過 Amazon Cognito 或其他 OIDC IdP 使用您的應用程式登入。IdP 會發出 ID 和存取字符與使用者的資訊。

  2. 您的應用程式會存放 JWTs。如需詳細資訊，請參閱《Amazon Cognito 開發人員指南》中的搭配使用者集區使用字符。

  3. 您的使用者請求您的應用程式必須從外部 API 擷取的資料。

  4. 您的應用程式會從 API Gateway 中的 REST API 請求資料。它會附加 ID 或存取權杖做為請求標頭。

  5. 如果您的 API 具有授權決策的快取，則會傳回先前的回應。如果停用快取或 API 目前沒有快取，API Gateway 會將請求參數傳遞給字符型 Lambda 授權方。

  6. Lambda 函數會使用 IsAuthorizedWithToken API 將授權請求傳送至 Verified Permissions 政策存放區。Lambda 函數會傳遞授權決策的元素：

    1. 使用者字符作為委託人。

    2. API 方法結合 API 路徑，例如 GetPhoto作為 動作。

    3. 資源Application的術語。

  7. Verified Permissions 會驗證權杖。如需如何驗證 Amazon Cognito 權杖的詳細資訊，請參閱《Amazon Amazon Cognito授權 Amazon 驗證許可。

  8. Verified Permissions 會根據政策存放區中的政策評估授權請求，並傳回授權決策。

  9. Lambda 授權方會將 Allow或 Deny回應傳回 API Gateway。

  10. API 會傳回資料或ACCESS_DENIED回應給您的應用程式。您的應用程式會處理並顯示 API 請求的結果。

API 連結政策存放區的考量事項

當您在 Verified Permissions 主控台中建置 API 連結政策存放區時，您正在為最終生產部署建立測試。移至生產環境之前，請為您的 API 和使用者集區建立固定組態。請考慮下列因素：

API Gateway 快取回應

在 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 的名稱衍生政策存放區命名空間。

Lambda 函數沒有 VPC 組態

Verified Permissions 為您的 API 授權方建立的 Lambda 函數會在預設 VPC 中啟動。預設情況下。限制網路存取私有 VPCs APIs 無法與授權具有 Verified Permissions 存取請求的 Lambda 函數通訊。

Verified Permissions 在 CloudFormation 中部署授權方資源

若要建立 API 連結政策存放區，您必須登入高度特權 AWS 委託人至 Verified Permissions 主控台。此使用者部署的 AWS CloudFormation 堆疊可跨數個 建立資源 AWS 服務。此主體必須具有在 Verified Permissions IAM、Lambda 和 API Gateway 中新增和修改資源的許可。根據最佳實務，請勿與組織中的其他管理員共用這些登入資料。

使用 移至生產環境 AWS CloudFormation 如需 Verified Permissions 建立的資源概觀，請參閱 。

新增屬性型存取控制 (ABAC)

具有 IdP 的典型身分驗證工作階段會傳回 ID 和存取權杖。您可以在應用程式請求中將這些字符類型做為承載字符傳遞至您的 API。視您在建立政策存放區時的選擇而定，驗證許可預期兩種字符類型之一。這兩種類型都包含有關使用者群組成員資格的資訊。如需 Amazon Cognito 中字符類型的詳細資訊，請參閱《Amazon Cognito 開發人員指南》中的搭配使用者集區使用字符。

建立政策存放區之後，您可以新增和延伸政策。例如，您可以在將新群組新增至使用者集區時，將新群組新增至政策。由於您的政策存放區已了解您的使用者集區在字符中呈現群組的方式，因此您可以針對具有新政策的任何新群組允許一組動作。

您也可以根據使用者屬性，將政策評估的群組型模型擴展為更精確的模型。使用者集區字符包含其他使用者資訊，有助於授權決策。

ID 字符

ID 字符代表使用者的屬性，並具有高層級的精細存取控制。若要評估電子郵件地址、電話號碼或自訂屬性，例如部門和經理，請評估 ID 字符。

存取權杖

存取字符代表具有 OAuth 2.0 範圍的使用者許可。若要新增授權層或設定其他資源的請求，請評估存取權杖。例如，您可以驗證使用者是否在適當的群組中，並具有像一般授權存取 API PetStore.read 的範圍。使用者集區可以將自訂範圍新增至具有資源伺服器的權杖，並在執行時間使用權杖自訂。

請參閱將 Amazon Cognito 權杖映射至結構描述，以及將 OIDC 權杖映射至結構描述，以取得在 ID 和存取權杖中處理宣告的政策範例。