本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 範圍、M2M 和資源伺服器 在使用者集區的網域設定完成後，Amazon Cognito 會自動佈建一個 OAuth 2.0 授權伺服器和託管 Web UI，包含您的應用程式可以呈現給使用者的註冊和登入頁面。如需更多資訊，請參閱[使用者集區受管登入](cognito-user-pools-managed-login.md)。您可以選擇希望授權伺服器新增到存取權杖的範圍。範圍授權對資源伺服器和使用者資料的存取權。 *資源伺服器*是 OAuth 2.0 API 伺服器。為了保護受存取保護的資源，它會驗證來自使用者集區的存取權杖是否包含授權其保護的 API 中請求方法和路徑範圍。它會根據權杖簽章驗證發行者、根據權杖過期驗證有效性，以及根據權杖宣告中的範圍驗證存取層級。使用者集區範圍位於存取權杖`scope`宣告中。如需 Amazon Cognito 存取權杖中宣告的詳細資訊，請參閱 [了解存取權杖](amazon-cognito-user-pools-using-the-access-token.md)。 使用 Amazon Cognito，存取字符中的範圍可以授權存取外部 APIs或使用者屬性。您可以向本機使用者、聯合身分使用者或機器身分發出存取權杖。 **Topics** + [API 授權](#cognito-user-pools-define-resource-servers-about-api-authz) + [Machine-to-machine(M2M) 授權](#cognito-user-pools-define-resource-servers-about-m2m) + [關於範圍](#cognito-user-pools-define-resource-servers-about-scopes) + [關於資源伺服器](#cognito-user-pools-define-resource-servers-about-resource-servers) + [資源繫結](#cognito-user-pools-resource-binding) ## API 授權 以下是您可以使用 Amazon Cognito 權杖授權 APIs 請求的一些方式： **存取權杖** 將 Amazon Cognito 授權方新增至 REST API 方法請求組態時，請將**授權範圍**新增至授權方組態。透過此組態，您的 API 接受 `Authorization`標頭中的存取字符，並檢閱它們是否有接受的範圍。 **ID 權杖** 當您將有效的 ID 字符傳遞至 REST API 中的 Amazon Cognito 授權方時，API Gateway 會接受請求並將 ID 字符內容傳遞至 API 後端。 **Amazon Verified Permissions** 在 Verified Permissions 中，您可以選擇建立 [API 連結政策存放區](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/policy-stores_api-userpool.html)。Verified Permissions 會建立並指派 Lambda 授權方，以處理來自請求`Authorization`標頭的 ID 或存取權杖。此 Lambda 授權方會將權杖傳遞至您的政策存放區，其中 Verified Permissions 會將權杖與政策進行比較，並將允許或拒絕決策傳回給授權方。 **其他資源** + [在 API Gateway 中控制和管理對 REST API 的存取](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-control-access-to-api.html) + [使用 Amazon Verified Permissions 進行授權](amazon-cognito-authorization-with-avp.md) ## Machine-to-machine(M2M) 授權 Amazon Cognito 支援使用*機器身分*存取 API 資料的應用程式。使用者集區中的機器身分是在應用程式伺服器上執行並連線至遠端 APIs[機密用戶端](user-pool-settings-client-apps.md#user-pool-settings-client-app-client-types)。它們的操作在沒有使用者互動的情況下進行：排程任務、資料串流或資產更新。當這些用戶端使用存取字符授權其請求時，他們會執行*機器到機器*或 M2M 授權。在 M2M 授權中，共用秘密會取代存取控制中的使用者登入資料。 使用 M2M 授權存取 API 的應用程式必須具有用戶端 ID 和用戶端秘密。在您的使用者集區中，您必須建置支援用戶端憑證授予的應用程式用戶端。若要支援用戶端登入資料，您的應用程式用戶端必須擁有用戶端秘密，而且您必須擁有使用者集區網域。在此流程中，您的機器身分會直接從 請求存取字符[權杖端點](token-endpoint.md)。您只能在用戶端憑證授予的存取權杖中，從[資源伺服器](#cognito-user-pools-define-resource-servers-about-resource-servers)授權自訂範圍。如需設定應用程式用戶端的詳細資訊，請參閱 [使用應用程式用戶端的應用程式特定設定](user-pool-settings-client-apps.md)。 來自用戶端憑證授予的存取字符是您想要允許機器身分從 API 請求的操作的可驗證陳述式。若要進一步了解存取權杖如何授權 API 請求，請繼續閱讀。如需範例應用程式，請參閱 [Amazon Cognito 和 API Gateway 型機器，以使用 AWS CDK 進行機器授權](https://github.com/aws-samples/amazon-cognito-and-api-gateway-based-machine-to-machine-authorization-using-aws-cdk)。 M2M 授權的計費模式與每月作用中使用者 (MAUs的計費方式不同。當使用者身分驗證為每位作用中使用者帶來成本時，M2M 帳單會反映作用中的用戶端登入資料應用程式用戶端和字符請求總量。如需詳細資訊，請參閱 [Amazon Cognito 定價](https://aws.amazon.com/cognito/pricing)。若要控制 M2M 授權的成本，請最佳化存取字符的持續時間，以及應用程式提出的字符請求數量。如需在 M2M 授權中使用 API Gateway 快取來減少新權杖請求[管理使用者集區字符過期和快取](amazon-cognito-user-pools-using-tokens-caching-tokens.md)的方法，請參閱 。 如需最佳化 Amazon Cognito 操作以為您的 AWS 帳單增加成本的相關資訊，請參閱 [管理成本](tracking-cost.md#tracking-cost-managing)。 **machine-to-machine(M2M) 用戶端登入資料的用戶端中繼資料** 您可以在 M2M 請求中傳遞[用戶端中繼資料](cognito-user-pools-working-with-lambda-triggers.md#working-with-lambda-trigger-client-metadata)。用戶端中繼資料是來自使用者或應用程式環境的其他資訊，有助於 的結果[產生權杖前 Lambda 觸發程序](user-pool-lambda-pre-token-generation.md)。在使用者主體的身分驗證操作中，您可以將用戶端中繼資料傳遞至 [AdminRespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminRespondToAuthChallenge.html) 和 [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html) API 請求內文中的權杖產生前觸發器。由於應用程式會透過對 的直接請求，為 M2M 執行產生存取字符的流程[權杖端點](token-endpoint.md)，因此具有不同的模型。在用戶端登入資料的字符請求 POST 內文中，將具有用戶端中繼資料物件 URL 編碼 (`x-www-form-urlencoded`) 的 `aws_client_metadata` 參數傳遞至字串。如需請求範例，請參閱 [具有基本授權的用戶端憑證具有 POST 內文授權的用戶端憑證](token-endpoint.md#exchanging-client-credentials-for-an-access-token-in-request-body)。以下是傳遞鍵/值對 的範例參數`{"environment": "dev", "language": "en-US"}`。 ``` aws_client_metadata=%7B%22environment%22%3A%20%22dev%22,%20%22language%22%3A%20%22en-US%22%7D ``` ## 關於範圍 *範圍*是應用程式可以請求資源的存取層級。在 Amazon Cognito 存取權杖中，範圍是由您使用使用者集區 (具有已知數位簽章的受信任存取權杖發行者) 設定的信任進行備份。使用者集區可以產生具有範圍的存取權杖，這些範圍可以證明您的客戶端可以管理自己部分或全部使用者設定檔，或從後端 API 擷取資料。Amazon Cognito 使用者集區會發出存取權杖*，其中包含使用者集區預留 API 範圍*、*自訂範圍*和 *OpenID Connect (OIDC) 範圍*。 **使用者集區保留的 API 範圍** 此`aws.cognito.signin.user.admin`範圍授權 Amazon Cognito 使用者集區 API 中目前使用者的自助式操作。它授權存取字符的持有人使用 [GetUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html) 和 [UpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserAttributes.html) API 操作來查詢和更新承載的所有資訊。在您使用 Amazon Cognito 使用者集區 API 驗證使用者時，這是您在存取權杖中收到的唯一範圍。這也是您讀取和寫入授權應用程式用戶端，用以讀取和寫入的使用者屬性所需的唯一範圍。您也可以在向 [授權端點](authorization-endpoint.md) 提出的請求中請求此範圍。僅此範圍不足以向 [userInfo 端點](userinfo-endpoint.md) 請求使用者屬性。對於為您的使用者授權使用者集區 API *和* `userInfo` 請求的存取權杖，您必須在 `/oauth2/authorize` 請求中同時請求範圍 `openid` 和 `aws.cognito.signin.user.admin`。 **自訂範圍** 自訂範圍授權對資源伺服器保護的外部 API 的請求。您可以使用其他類型的範圍請求自訂範圍。您可以在此頁面中尋找有關自訂範圍的詳細資訊。 **OpenID Connect (OIDC) 範圍** 當您使用使用者集區授權伺服器驗證使用者時，包括使用受管登入時，您必須請求範圍。您可以在 Amazon Cognito 授權伺服器中驗證使用者集區本機使用者和第三方聯合身分使用者。OIDC 範圍授權您的應用程式從使用者集[userInfo 端點](userinfo-endpoint.md)區的 讀取使用者資訊。您可以從 `userInfo` 端點查詢使用者屬性的 OAuth 模型，可針對大量使用者屬性要求最佳化您的應用程式。`userInfo` 端點會傳回由存取權杖中的範圍決定的許可層級的屬性。您可以授權應用程式用戶端發行具有下列 OIDC 範圍的存取權杖。 openid OpenID Connect (OIDC) 查詢的最小範圍。授權 ID 權杖、唯一識別符宣告 `sub`，以及請求其他範圍的能力。 當您請求 `openid` 範圍而沒有其他人時，您的使用者集區 ID 權杖和 `userInfo` 回應包含您的應用程式用戶端可以讀取的所有使用者屬性的宣告。當您請求 `openid` 和其他 OIDC 範圍`email`，例如 `profile`、 和 `phone`時，ID 字符和 [userInfo](userinfo-endpoint.md#userinfo-endpoint.title) 回應的內容僅限於其他範圍的限制。 例如，使用參數 `scope=openid+email` 向 [授權端點](authorization-endpoint.md) 發出請求會傳回包含 `sub`、`email` 和 `email_verified` 的 ID 權杖。此請求的存取權杖傳回與 [userInfo 端點](userinfo-endpoint.md) 相同的屬性。具有參數 `scope=openid` 的請求傳回返回 ID 權杖和從 `userInfo` 中的所有用戶端可讀屬性。 profile 授權應用程式用戶端可讀取的所有使用者屬性。 email 授權使用者屬性 `email` 與 `email_verified`。如果已明確設定值，Amazon Cognito 會傳回 `email_verified`。 phone 授權使用者屬性 `phone_number` 與 `phone_number_verified`。 ## 關於資源伺服器 資源伺服器 API 可能會授與資料庫中資訊的存取權，或授與控制您的 IT 資源。Amazon Cognito 存取字符可以授權對支援 OAuth 2.0 之 API 的存取。Amazon API Gateway REST API 具有使用 Amazon Cognito 存取字符進行授權的[內建支援](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-integrate-with-cognito.html)。您的應用程式會在 API 呼叫中傳遞存取字符至資源伺服器。資源伺服器會檢查存取字符，以判斷是否應授予存取權。 Amazon Cognito 未來可能會對使用者集區存取權杖的架構進行更新。如果您的應用程式在將存取權杖傳遞給 API 之前分析過存取權杖內容，則必須設計程式碼以接受結構描述的更新。 自訂範圍由您定義，並擴充使用者集區的授權功能，以納入與查詢和修改使用者及其屬性無關的用途。例如，如果您有用於照片的資源伺服器，它可能會定義兩個範圍：`photos.read` 用於照片的讀取存取權，`photos.write` 用於寫入/刪除存取權。您可以設定 API 接受存取權杖以進行授權，並在 `scope` 宣告中對存取權杖的 `HTTP GET` 請求授予 `photos.read`，以及對權杖的 `HTTP POST` 請求授予 `photos.write`。這些都是*自訂範圍*。 **注意** 您的資源伺服器在處理字符內的任何宣告之前，必須先驗證存取字符簽章和過期日期。如需有關驗證權杖的詳細資訊，請參閱 [驗證 JSON Web 字符](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md)。如需有關驗證及使用 Amazon API Gateway 中使用者集區權杖的詳細資訊，請參閱[將 Amazon Cognito 使用者集區與 API Gateway 整合](https://aws.amazon.com/blogs/mobile/integrating-amazon-cognito-user-pools-with-api-gateway/)部落格文章。API Gateway 是檢查存取權杖及保護資源的理想選項。如需 API Gateway Lambda 授權方的詳細資訊，請參閱[使用 API Gateway Lambda 授權方](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)。 **概觀** 您可以使用 Amazon Cognito 建立 OAuth2.0 **資源伺服器**，並將**自訂範圍**與這些伺服器建立關聯。存取權杖中的自訂範圍會授權您 API 中的特定動作。您可以授權讓使用者集區中的任何應用程式用戶端從任一部資源伺服器發出自訂範圍。將您的自訂範圍與應用程式用戶端建立關聯，並且在 OAuth2.0 授權碼授予、隱含授予和用戶端憑證授予中向 [權杖端點](token-endpoint.md) 請求這些範圍。Amazon Cognito 會在存取權杖中將自訂範圍新增至 `scope` 宣告中。用戶端可以對其資源伺服器使用存取字符，資源伺服器會根據存在於字符中的範圍來制定授權決策。如需存取字符範圍的詳細資訊，請參閱[將字符用於使用者集區](amazon-cognito-user-pools-using-tokens-with-identity-providers.md)。 ![\[資源伺服器流程的概觀。用戶端請求具有自訂範圍的授予，使用者集區傳回具有自訂範圍的存取字符，而用戶端向 API 提供存取字符。\]](http://docs.aws.amazon.com/zh_tw/cognito/latest/developerguide/images/resource-servers.png) 若要取得具有自訂範圍的存取權杖，您的應用程式必須向 [權杖端點](token-endpoint.md) 提出請求，兌換授權碼或請求用戶端憑證授予。在受管登入中，您也可以從隱含授予請求存取字符中的自訂範圍。 **注意** 由於其設計是作為 IdP 與使用者集區進行人為互動驗證，因此 [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) 和 [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) 請求只會在存取權杖中產生一個具有單一值 `aws.cognito.signin.user.admin` 的 `scope` 宣告。 **管理資源伺服器和自訂範圍** 建立資源伺服器時，您必須提供資源伺服器名稱和資源伺服器識別符。您必須為您在資源伺服器中建立的每個範圍，提供範圍名稱和描述。 + **資源伺服器名稱**：資源伺服器的易記名稱，例如 `Solar system object tracker` 或 `Photo API`。 + **資源伺服器識別碼**：資源伺服器的唯一識別碼。識別符 (例如 `solar-system-data`) 是您想要與 API 建立關聯的任何名稱。您可以設定較長的識別符 (例如 `https://solar-system-data-api.example.com`)，更直接地引用 API URI 路徑，但較長的權杖字串會增加存取權杖的大小。 + **範圍名稱**：您想要在 `scope` 宣告中包含的值。例如 `sunproximity.read`。 + **描述**：易懂的範圍描述。例如 `Check current proximity to sun`。 Amazon Cognito 可針對任何使用者在存取權杖中包含自訂範圍，無論這些使用者是您的使用者集區本機使用者還是與第三方身分提供者聯合的使用者。您可以使用包含受管登入的 OAuth 2.0 授權伺服器，在身分驗證流程期間選擇使用者存取字符的範圍。您的使用者身分驗證必須從 [授權端點](authorization-endpoint.md) 開始，並以 `scope` 作為請求參數之一。以下是資源伺服器的建議格式。對於識別符，請使用 API 易記名稱。對於自訂範圍，請使用他們授權的動作。 ``` resourceServerIdentifier/scopeName ``` 例如，您在古柏帶 (Kuiper belt) 中發現了一顆新的小行星，並且想要透過 `solar-system-data` API 進行註冊。授權寫入操作到小行星資料庫的範圍是 `asteroids.add`。當您請求授權您註冊發現的存取權杖時，請將 `scope` HTTPS 請求參數格式化為 `scope=solar-system-data/asteroids.add`。 從資源伺服器刪除範圍並不會刪除其與所有用戶端的關聯。而是會將範圍標記為*非作用中*。Amazon Cognito 不會新增非作用中範圍至存取權杖，但如果您的應用程式提出請求，則會正常繼續進行。如果您稍後再次將範圍新增至資源伺服器，則 Amazon Cognito 會再次將其寫入存取權杖。如果您請求的範圍尚未與您的應用程式用戶端建立關聯，則無論您是否將該範圍從使用者集區資源伺服器中刪除，驗證都會失敗。 您可以使用 AWS 管理主控台、 API 或 CLI 來定義使用者集區的資源伺服器和範圍。 ### 為您的使用者集區定義資源伺服器 (AWS 管理主控台) 您可以使用 AWS 管理主控台 為您的使用者集區定義資源伺服器。 **定義資源伺服器** 1. 登入 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)。 1. 在導覽窗格中，選擇 **User Pools** (使用者集區)，然後選擇您要編輯的使用者集區。 1. 選擇**品牌**下的**網域**功能表，並尋找**資源伺服器**。 1. 選擇 **Create a resource server** (建立資源伺服器)。 1. 輸入 **Resource server name** (資源伺服器名稱)。例如 `Photo Server`。 1. 輸入 **Resource server identifier** (資源伺服器識別符)。例如 `com.example.photos`。 1. 輸入資源的 **Custom scopes** (自訂範圍)，例如 `read` 和 `write`。 1. 為每個 **Scope name** (範圍名稱) 輸入 **Description** (描述)，例如 `view your photos` 和 `update your photos`。 1. 選擇**建立**。 您可以在**資源伺服器**下的**網域**選單中，在自訂範圍欄中檢閱**您的自訂範圍**。您可以從應用程式下的應用程式用戶端選單，為**應用程式****用戶端**啟用自訂範圍。選取應用程式用戶端，尋找**登入頁面**，然後選擇**編輯**。新增 **Custom scopes** (自訂範圍)，然後選擇 **Save changes** (儲存變更)。 ### 為您的使用者集區 (AWS CLI 和 AWS API) 定義資源伺服器 使用下列命令為您的使用者集區指定資源伺服器設定。 **建立資源伺服器** + AWS CLI: `aws cognito-idp create-resource-server` + AWS API：[CreateResourceServer](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateResourceServer.html) **取得資源伺服器設定的相關資訊** + AWS CLI: `aws cognito-idp describe-resource-server` + AWS API：[DescribeResourceServer](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeResourceServer.html) **為您的使用者集區列出所有資源伺服器的相關資訊** + AWS CLI: `aws cognito-idp list-resource-servers` + AWS API：[ListResourceServers](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListResourceServers.html) **刪除資源伺服器** + AWS CLI: `aws cognito-idp delete-resource-server` + AWS API：[DeleteResourceServer](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DeleteResourceServer.html) **更新資源伺服器的設定** + AWS CLI: `aws cognito-idp update-resource-server` + AWS API：[UpdateResourceServer](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateResourceServer.html) ## 資源繫結 透過資源繫結，也稱為資源指標，您可以從使用者集區授權伺服器請求 API 特定的授予。資源繫結是 RFC 8707 中定義的 OAuth 2.0 擴充功能，可讓用戶端明確指定想要在授權請求期間存取的資源伺服器。 [https://www.rfc-editor.org/rfc/rfc8707.html](https://www.rfc-editor.org/rfc/rfc8707.html)透過資源繫結，您的 API 組態可以拒絕存取並非專門用於它們的字符。 **注意** 您只能將存取權杖繫結至使用者的資源。您無法請求具有 client-credentials M2M 授權的資源繫結。 當您搭配 Amazon Cognito 使用者集區使用資源繫結時，用戶端可以在對使用者集區授權伺服器的身分驗證請求中包含 `resource` 參數。您的使用者集區會驗證所請求資源的值是否為 URL，遵循與[應用程式用戶端](user-pool-settings-client-apps.md#cognito-user-pools-app-idp-settings-about)回呼 URLs 相同的結構描述規則：`https://`、`http://``localhost`僅限 ，或自訂結構描述，例如 `myapp://`。Amazon Cognito 會將請求的 URI 設定為[存取字符](amazon-cognito-user-pools-using-the-access-token.md)`aud`宣告中的對象。如果請求的資源是使用者集區資源伺服器，資源伺服器識別符必須是 URL 格式。您可以為每個身分驗證請求請求一個資源。 此功能僅適用於使用使用者集區 OAuth 2.0 授權伺服器的[受管登入身分驗證](authentication-flows-selection-managedlogin.md)。您可以從 請求隱含和授權碼授予中的資源繫結[授權端點](authorization-endpoint.md)。來自 的權杖重新整理授權會[權杖端點](token-endpoint.md)繼承原始請求的`aud`宣告。它目前不適用於 [SDK 身分驗證模型](authentication-flows-selection-sdk.md)。 **使用 Amazon Cognito 使用者集區實作資源繫結** 1. 使用唯一識別符設定使用者集區中的一或多個資源伺服器。 1. 在您向 提出的授權請求中`/oauth2/authorize`，請求授權碼或隱含授予，並包含 `resource` 參數。的值`resource`必須是 URL 格式的資源伺服器識別符或 URL。例如 `&resource=https://solar-system-data-api.example.com`。 1. 授權伺服器會驗證資源請求、完成身分驗證，並將存取權杖`aud`宣告設定為請求的資源 URL。 1. 為了驗證權杖是否特別為其發出，使用使用者存取權杖的資源會檢查`aud`宣告。