本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Amazon Verified Permissions 進行授權
[Amazon Verified Permissions](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/what-is-avp.html) 是一項授權服務，適用於您建置的應用程式。當您新增 Amazon Cognito 使用者集區做為身分來源時，您的應用程式就可以將使用者集區存取權或身分 (ID) 權杖傳遞給 Verified Permissions 以決定允許或拒絕。Verified Permissions 會根據您使用 [Cedar 政策語言](https://docs.cedarpolicy.com/)撰寫的政策來考量您使用者的屬性和請求內容。請求內容可包括所請求文件、影像或其他資源的識別符，以及您的使用者想要對資源執行的動作。
您的應用程式可以在 [IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html) 或 [BatchIsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_BatchIsAuthorizedWithToken.html) API 請求中提供使用者的身分或存取權杖給已驗證的許可。這些 API 操作接受您的使用者做為 `Resource`，`Principal`並對他們想要存取`Action`的 做出授權決策。其他自訂`Context`可以有助於詳細的存取決策。
當您的應用程式在 `IsAuthorizedWithToken` API 請求中顯示權杖時，Verified Permissions 就會執行以下驗證。
1. 您的使用者集區是針對所請求的政策存放區設定的 Verified Permissions [身分來源](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/identity-providers.html)。
1. `client_id` 或 `aud` 宣告分別位在您的存取或身分權杖中，兩者之一會符合您提供給 Verified Permissions 的使用者集區應用程式用戶端 ID。若要驗證此宣告，您必須在您的 Verified Permissions 身分來源中[設定用戶端 ID 驗證](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/cognito-validation.html)。
1. 您的權杖未過期。
1. 權杖中的`token_use`宣告值與您傳遞給 的參數相符`IsAuthorizedWithToken`。`access` 如果您將其傳遞至 `accessToken` 參數，且`id`您將其傳遞至 `identityToken` 參數，則`token_use`宣告必須是 。
1. 權杖中的簽名來自您的使用者集區已發布的 JSON Web 金鑰 (JWK)。您可以在 `https://cognito-idp.Region.amazonaws.com/your user pool ID/.well-known/jwks.json` 檢視您的 JWK。
**撤銷的權杖和刪除的使用者**
Verified Permissions 只會驗證從您的身分來源得知的資訊，以及您使用者的權杖到期時間資訊。Verified Permissions 不會檢查權杖是否撤銷或使用者是否存在。即使您撤銷了使用者的權杖，或是從使用者集區刪除了使用者的設定檔，在權杖過期之前，Verified Permissions 仍會將該權杖視為有效。
**政策評估**
將您的使用者集區設定為[政策存放區](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/terminology.html#term-policy-store)的[身分來源](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/identity-providers.html)。設定讓您的應用程式在請求中提交使用者的權杖給 Verified Permissions。Verified Permissions 會針對每個請求，將權杖中的宣告與政策進行比較。Verified Permissions 政策就像 AWS 中的 IAM 政策。它會宣告*主體*、*資源*和*動作*。如果 Verified Permissions 符合允許的動作且不符合明確`Deny`動作，`Allow`則會使用 回應您的請求；否則，它會使用 回應`Deny`。如需詳細資訊，請參閱*《Amazon Verified Permissions User Guide》*中的 [Amazon Verified Permissions policies](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policies.html)。
**自訂權杖**
若要變更、新增和移除您要呈現給 Verified Permissions 的使用者宣告，請使用 自訂存取和身分字符中的內容[產生權杖前 Lambda 觸發程序](user-pool-lambda-pre-token-generation.md)。使用權杖產生前觸發程序，您就可以新增和修改權杖中的宣告。例如，您可以查詢資料庫中的其他使用者屬性，並將這些屬性編碼到您的 ID 權杖中。
**注意**
由於 Verified Permissions 處理宣告的方式，請勿在您的權杖產生前函數中新增名為 `cognito`、`dev` 或 `custom` 的宣告。若您不是採用冒號分隔格式 (如 `cognito:username`) 顯示這些保留的宣告字首，而是採用完整宣告名稱，那麼您的授權請求便會失敗。
**其他資源**
+ [將 Amazon Cognito 權杖映射至已驗證的許可結構描述](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/identity-sources_map-token-to-schema.html)
+ [使用 Amazon Verified Permissions 和 Amazon Cognito 授權 API Gateway APIs ](https://aws.amazon.com/blogs/security/authorize-api-gateway-apis-using-amazon-verified-permissions-and-amazon-cognito/)
+ [研討會：使用 Amazon Cognito 和驗證許可進行身分驗證和授權](https://catalog.workshops.aws/app-auth)
## 具有已驗證許可的 API 授權
您的 ID 或存取權杖可以授權請求使用 Verified Permissions 後端 Amazon API Gateway REST APIs。您可以使用使用者集區和 API 的立即連結來建立[政策存放](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policy-stores.html)區。[使用設定 API Gateway 和身分來源](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policy-stores_create.html)啟動選項，Verified Permissions 會將使用者集區身分來源新增至政策存放區，並將 Lambda 授權方新增至 API。當您的應用程式將使用者集區承載符記傳遞至 API 時，Lambda 授權方會叫用驗證許可。授權方以委託人身分傳遞權杖，並以請求路徑和方法做為動作傳遞權杖。
下圖說明具有已驗證許可的 API Gateway API 的授權流程。如需詳細資訊，請參閱《Amazon Verified Permissions 使用者指南》中的 [API 連結政策存放](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policy-stores_api-userpool.html)區。
![\[說明使用 Amazon Verified Permissions 進行 API 授權流程的圖表。應用程式向 Amazon API Gateway API 提出請求。API 會叫用 Lambda 授權方。授權方向 Verified Permissions 提出 API 請求。Verified Permissions 會檢查字符有效性並傳回授權決策。\]](http://docs.aws.amazon.com/zh_tw/cognito/latest/developerguide/images/amazon-cognito-avp-use-case.png)
Verified Permissions 會圍繞[使用者集區群組](cognito-user-pools-user-groups.md)建立 API 授權。由於 ID 和存取權杖都包含`cognito:groups`宣告，因此您的政策存放區可以在各種應用程式內容中管理 APIs 的角色型存取控制 (RBAC)。
### 選擇政策存放區設定
在政策存放區上設定身分來源時，您必須選擇是否要處理存取或 ID 字符。此決策對政策引擎的運作方式至關重要。ID 字符包含使用者屬性。存取字符包含使用者存取控制資訊：[OAuth 範圍](cognito-user-pools-define-resource-servers.md)。雖然這兩種字符類型都有群組成員資訊，但我們通常建議使用 Verified Permissions 政策存放區的 RBAC 存取字符。存取權杖會新增 群組成員資格，其範圍有助於授權決策。存取字符中的宣告會成為授權請求中的[內容](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/context.html)。
當您將使用者集區設定為身分來源時，也必須設定使用者和群組實體類型。實體類型是您可以在 Verified Permissions 政策中參考的主體、動作和資源識別符。政策存放區中的實體可以有*成員*關係，其中一個實體可以是*父*實體的成員。透過 成員資格，您可以參考委託人群組、動作群組和資源群組。如果是使用者集區群組，您指定的使用者實體類型必須是群組實體類型的成員。當您設定 [API 連結政策存放](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policy-stores_api-userpool.html)區或遵循 Verified Permissions 主控台中的**引導設定**時，您的政策存放區會自動具有此父成員關係。
ID 字符可以結合 RBAC 與屬性型存取控制 (ABAC)。建立 [API 連結政策存放區](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policy-stores_api-userpool.html)之後，您可以使用[使用者屬性](#amazon-cognito-authorization-with-avp-example-policy)*和*群組成員資格來增強政策。ID 字符中的屬性宣告會成為授權請求中的[主體屬性](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policies_examples-abac.html)。您的政策可以根據委託人屬性進行授權決策。
您也可以設定政策存放區，以接受權杖，其中包含符合您所提供可接受應用程式用戶端清單的 `aud`或 `client_id`宣告。
### 角色型 API 授權的範例政策
下列範例政策是透過為 [PetStore](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-api-from-example.html) 範例 REST API 設定 Verified Permissions 政策存放區所建立。
```
permit(
principal in PetStore::UserGroup::"us-east-1_EXAMPLE|MyGroup",
action in [ PetStore::Action::"get /pets", PetStore::Action::"get /pets/{petId}" ],
resource
);
```
Verified Permissions 會在下列情況下，從您的應用程式將`Allow`決策傳回給授權請求：
1. 您的應用程式已將 `Authorization`標頭中的 ID 或存取權杖做為承載權杖傳遞。
1. 您的應用程式已使用包含字串 的`cognito:groups`宣告傳遞權杖`MyGroup`。
1. 例如，您的應用程式向 `https://myapi.example.com/pets`或 提出`HTTP GET`請求`https://myapi.example.com/pets/scrappy`。
## Amazon Cognito 使用者的政策範例
您的使用者集區也可以在 API 請求以外的條件下產生驗證許可的授權請求。您可以將應用程式中的任何存取控制決策提交到您的政策存放區。例如，您可以在任何請求傳輸網路之前，使用屬性型存取控制來補充 Amazon DynamoDB 或 Amazon S3 安全性，以減少配額使用。
以下範例使用 [Cedar 政策語言](https://docs.cedarpolicy.com/)，允許透過某一個使用者集區應用程式用戶端進行驗證的財務使用者讀取和寫入 `example_image.png`。John 是您的應用程式中的使用者，他從您的應用程式用戶端收到 ID 權杖，並在 GET 請求中將該權杖傳遞至需要授權的 URL `https://example.com/images/example_image.png`。John 的 ID 權杖內有您的使用者集區應用程式用戶端 ID `1234567890example` 的 `aud` 宣告。您的權杖產生前 Lambda 函數還針對 John 插入了一個值為 `Finance1234` 的新宣告 `costCenter`。
```
permit (
principal,
actions in [ExampleCorp::Action::"readFile", "writeFile"],
resource == ExampleCorp::Photo::"example_image.png"
)
when {
principal.aud == "1234567890example" &&
principal.custom.costCenter like "Finance*"
};
```
以下請求內文會產生 `Allow` 回應。
```
{
"accesstoken": "[John's ID token]",
"action": {
"actionId": "readFile",
"actionType": "Action"
},
"resource": {
"entityId": "example_image.png",
"entityType": "Photo"
}
}
```
若您想要在 Verified Permissions 政策中指定主體，請使用下列格式：
```
permit (
principal == [Namespace]::[Entity]::"[user pool ID]|[user sub]",
action,
resource
);
```
以下是使用者集區中 ID `us-east-1_Example`為 且 ID 為 或使用者 ID 為 之使用者的範例委託人`973db890-092c-49e4-a9d0-912a4c0a20c7`。
```
principal == ExampleCorp::User::"us-east-1_Example|973db890-092c-49e4-a9d0-912a4c0a20c7",
```
當您想要在 Verified Permissions 政策中指定使用者群組時，請使用下列格式：
```
permit (
principal in [Namespace]::[Group Entity]::"[Group name]",
action,
resource
);
```
**屬性型存取控制**
為您的應用程式使用 Verified Permissions 的授權，以及[憑證的 Amazon Cognito 身分集區存取控制功能的屬性](https://docs.aws.amazon.com/cognito/latest/developerguide/attributes-for-access-control.html) AWS ，都是以屬性為基礎的存取控制 (ABAC) 形式。 Amazon Cognito 以下是 Verified Permissions 與 Amazon Cognito ABAC 的比較。在 ABAC 中，系統會檢查實體的屬性，並從您定義的條件做出授權決策。
| 服務 | 流程 | 結果 |
| --- |--- |--- |
| Amazon Verified Permissions | Returns an 允許 or 拒絕 decision from analysis of a user pool JWT. | Access to application resources succeeds or fails based on Cedar policy evaluation. |
| Amazon Cognito identity pools (attributes for access control) | Assigns [工作階段標籤](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html) to your user based on their attributes. IAM policy conditions can check tags 允許 or 拒絕 user access to AWS 服務. | A tagged session with temporary AWS credentials for an IAM role. |