Scopes、M2M 和 APIs搭配資源伺服器 - Amazon Cognito
API 授權Machine-to-machine （M2M） 授權關於範圍關於資源伺服器

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

Scopes、M2M 和 APIs搭配資源伺服器

為使用者集區設定網域後，Amazon Cognito 會自動佈建 2.0 OAuth 授權伺服器和託管 Web UI，其中包含註冊和登入頁面，您的應用程式可以呈現給使用者。如需詳細資訊，請參閱 使用託管 UI 新增應用程式用戶端。您可以選擇希望授權伺服器新增到存取權杖的範圍。範圍授權對資源伺服器和使用者資料的存取權。

資源伺服器是 OAuth 2.0 API 伺服器。為了保護受存取保護的資源，它會驗證來自使用者集區的存取權杖是否包含在其API保護的 中授權所請求方法和路徑的範圍。它會根據權杖簽章驗證發行者、根據權杖過期驗證有效性，以及根據權杖宣告中的範圍驗證存取層級。使用者集區範圍位於存取權杖scope宣告中。如需 Amazon Cognito 存取權杖中宣告的詳細資訊，請參閱 了解存取權杖。

使用 Amazon Cognito ，存取權杖中的範圍可以授權對外部APIs或使用者屬性的存取。您可以向本機使用者、聯合使用者或機器身分發出存取權杖。

API 授權

以下是您可以使用 Amazon Cognito 權杖向 APIs 授權請求的一些方法：

存取權杖

將 Amazon Cognito 授權方新增至RESTAPI方法請求組態時，請將授權範圍新增至授權方組態。透過此組態，您的 API接受Authorization標頭中的存取權杖，並檢閱它們是否有接受的範圍。

ID 權杖

當您將有效的 ID 權杖傳遞給 中的 Amazon Cognito REST 授權方時API，APIGateway 會接受請求並將 ID 權杖內容傳遞給API後端。

Amazon Verified Permissions

在已驗證的許可中，您可以選擇建立 API連結的政策存放區。Verified Permissions 會建立並指派 Lambda 授權方，以處理來自請求Authorization標頭的 ID 或存取權杖。此 Lambda 授權方會將您的權杖傳遞至您的政策存放區，其中 Verified Permissions 會將權杖與政策進行比較，並將允許或拒絕的決定傳回給授權方。

其他 資源

Machine-to-machine （M2M） 授權

Amazon Cognito 支援使用機器身分 存取API資料的應用程式。使用者集區中的機器身分是在應用程式伺服器上執行並連線至遠端 的機密用戶端APIs。其操作無需使用者互動：排程任務、資料串流或資產更新。當這些用戶端使用存取權杖授權其請求時，他們會執行機器以機器 或 M2M 授權。在 M2M 授權中，共用密碼會取代存取控制中的使用者憑證。

API 使用 M2M 授權存取 的應用程式必須具有用戶端 ID 和用戶端秘密。在使用者集區中，您必須建置支援用戶端憑證授予的應用程式用戶端。若要支援用戶端憑證，您的應用程式用戶端必須具有用戶端秘密，且您必須具有使用者集區網域。在此流程中，您的機器身分會直接從 請求存取權杖權杖端點。您只能從用戶端憑證授予的存取權杖中的資源伺服器授權自訂範圍。如需設定應用程式用戶端的詳細資訊，請參閱 使用應用程式用戶端的應用程式特定設定。

來自用戶端憑證授予的存取權杖是您想要允許機器身分向 請求的操作的可驗證陳述式API。若要進一步了解存取權杖如何授權API請求，請繼續閱讀。如需範例應用程式，請參閱以 AWS Amazon Cognito 和 API Gateway 為基礎的機器使用 進行機器授權CDK。

M2M 授權的計費模型與每月作用中使用者 （MAUs） 的計費方式不同。當使用者身分驗證為每位作用中使用者帶來成本時，M2M 計費會反映作用中用戶端憑證應用程式用戶端和權杖請求總磁碟區。如需詳細資訊，請參閱 Amazon Cognito 定價。若要控制 M2M 授權的成本，請最佳化存取權杖的持續時間，以及應用程式提出的權杖請求數量。如需在 M2M 授權中使用API閘道快取減少新權杖請求的方法，管理使用者集區權杖過期和快取請參閱 。

如需最佳化 Amazon Cognito 操作以將成本新增至 AWS 帳單的相關資訊，請參閱 管理成本。

關於範圍

範圍是應用程式可以請求資源的存取層級。在 Amazon Cognito 存取權杖中，範圍是由您使用使用者集區 (具有已知數位簽章的受信任存取權杖發行者) 設定的信任進行備份。使用者集區可以產生具有範圍的存取權杖，以證明您的客戶可以管理部分或全部自己的使用者設定檔，或從後端擷取資料API。Amazon Cognito 使用者集區會發出存取權杖，其中包含使用者集區預留API範圍 、自訂範圍 和 OpenID Connect （OIDC） 範圍 。

使用者集區保留API範圍

此aws.cognito.signin.user.admin範圍會為 Amazon Cognito 使用者集區 中的目前使用者授權自助操作API。它授權存取權杖的持有人使用 和 UpdateUserAttributesAPI操作來查詢GetUser和更新有關承載者的所有資訊。當您使用 Amazon Cognito 使用者集區 來驗證使用者時API，這是您在存取權杖中收到的唯一範圍。這也是您讀取和寫入授權應用程式用戶端，用以讀取和寫入的使用者屬性所需的唯一範圍。您也可以在向 授權端點 提出的請求中請求此範圍。僅此範圍不足以向 userInfo 端點 請求使用者屬性。對於同時授權使用者集區API和使用者的userInfo請求的存取權杖，您必須同時請求 範圍openid和 /oauth2/authorize請求aws.cognito.signin.user.admin。

自訂範圍

自訂範圍會將請求授權給APIs資源伺服器保護的外部。您可以使用其他類型的範圍請求自訂範圍。您可以在此頁面中尋找有關自訂範圍的詳細資訊。

OpenID Connect （OIDC） 範圍

當您使用使用者集區授權伺服器驗證使用者時，包括使用託管 UI 時，您必須請求範圍。您可以在 Amazon Cognito 授權伺服器中驗證使用者集區本機使用者和第三方聯合身分使用者。OIDC 範圍授權您的應用程式從使用者集區的 讀取userInfo 端點使用者資訊。您從userInfo端點查詢使用者屬性的OAuth模型，可以針對使用者屬性的大量請求最佳化您的應用程式。userInfo 端點會傳回由存取權杖中的範圍決定的許可層級的屬性。您可以授權應用程式用戶端發行具有下列OIDC範圍的存取權杖。

openid

OpenID Connect （OIDC） 查詢的最小範圍。授權 ID 權杖、唯一識別符宣告 sub，以及請求其他範圍的能力。

注意

當您請求 openid 範圍而沒有其他人時，您的使用者集區 ID 權杖和 userInfo 回應包含您的應用程式用戶端可以讀取的所有使用者屬性的宣告。當您請求 openid 和其他OIDC範圍profile，例如 email、 和 時phone，ID 字符和userInfo回應的內容僅限於其他範圍的限制。

例如，使用參數 scope=openid+email 向 授權端點 發出請求會傳回包含 sub、email 和 email_verified 的 ID 權杖。此請求的存取權杖傳回與 userInfo 端點 相同的屬性。具有參數 scope=openid 的請求傳回返回 ID 權杖和從 userInfo 中的所有用戶端可讀屬性。

profile

授權應用程式用戶端可讀取的所有使用者屬性。

email

授權使用者屬性 email 與 email_verified。如果已明確設定值，Amazon Cognito 會傳回 email_verified。

phone

授權使用者屬性 phone_number 與 phone_number_verified。

關於資源伺服器

資源伺服器API可能會授予資料庫中資訊的存取權，或控制您的 IT 資源。Amazon Cognito 存取權杖可以授權對支援 2.0 OAuth APIs的 的存取權。Amazon API Gateway RESTAPIs內建支援使用 Amazon Cognito 存取權杖進行授權。 https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-integrate-with-cognito.html您的應用程式會將API通話中的存取權杖傳遞給資源伺服器。資源伺服器會檢查存取字符，以判斷是否應授予存取權。

Amazon Cognito 未來可能會對使用者集區存取權杖的架構進行更新。如果您的應用程式在將存取權杖傳遞至 之前分析其內容API，您必須設計程式碼以接受結構描述的更新。

自訂範圍由您定義，並擴充使用者集區的授權功能，以納入與查詢和修改使用者及其屬性無關的用途。例如，如果您有用於照片的資源伺服器，它可能會定義兩個範圍：photos.read 用於照片的讀取存取權，photos.write 用於寫入/刪除存取權。您可以設定 API以接受存取權杖以進行授權，並授予HTTP GET請求以 scope 存取權杖photos.read，以及HTTP POST請求以 存取權杖photos.write。這些都是自訂範圍。

注意

您的資源伺服器在處理字符內的任何宣告之前，必須先驗證存取字符簽章和過期日期。如需有關驗證權杖的詳細資訊，請參閱 驗證 JSON Web 權杖。如需在 Amazon API Gateway 中驗證和使用使用者集區權杖的詳細資訊，請參閱 部落格 將 Amazon Cognito 使用者集區與 API Gateway 整合。API Gateway 是檢查存取權杖和保護 資源的好選項。如需 API Gateway Lambda 授權方的詳細資訊，請參閱使用 API Gateway Lambda 授權方。

概觀

透過 Amazon Cognito ，您可以建立 OAuth 2.0 資源伺服器，並將自訂範圍與它們建立關聯。存取權杖中的自訂範圍會授權 中的特定動作API。您可以授權讓使用者集區中的任何應用程式用戶端從任一部資源伺服器發出自訂範圍。將您的自訂範圍與應用程式用戶端建立關聯，並從 請求 OAuth 2.0 授權碼授予、隱含授予和用戶端憑證授予中的這些範圍。 權杖端點Amazon Cognito 會在存取權杖中將自訂範圍新增至 scope 宣告中。用戶端可以對其資源伺服器使用存取字符，資源伺服器會根據存在於字符中的範圍來制定授權決策。如需存取字符範圍的詳細資訊，請參閱將字符用於使用者集區。

資源伺服器流程的概觀。用戶端請求具有自訂範圍的授予，使用者集區會傳回具有自訂範圍的存取權杖，而用戶端會將存取權杖呈現給 API。

若要取得具有自訂範圍的存取權杖，您的應用程式必須向 權杖端點 提出請求，兌換授權碼或請求用戶端憑證授予。在託管 UI 中，您還可以透過隱含授予在存取字符中請求自訂範圍。

注意

因為它們旨在以使用者集區作為 IdP 進行人工互動身分驗證，InitiateAuth且AdminInitiateAuth請求只會在具有單一值 的存取權杖中產生scope宣告aws.cognito.signin.user.admin。

管理資源伺服器和自訂範圍

建立資源伺服器時，您必須提供資源伺服器名稱和資源伺服器識別符。您必須為您在資源伺服器中建立的每個範圍，提供範圍名稱和描述。

  • 資源伺服器名稱：資源伺服器的易記名稱，例如 Solar system object tracker 或 Photo API。

  • 資源伺服器識別碼：資源伺服器的唯一識別碼。識別符是您想要與 建立關聯的任何名稱API，例如 solar-system-data。您可以設定較長的識別符，例如https://solar-system-data-api.example.com更直接地參考APIURI路徑，但較長的字串會增加存取權杖的大小。

  • 範圍名稱：您想要在 scope 宣告中包含的值。例如：sunproximity.read。

  • 描述：易懂的範圍描述。例如：Check current proximity to sun。

Amazon Cognito 可針對任何使用者在存取權杖中包含自訂範圍，無論這些使用者是您的使用者集區本機使用者還是與第三方身分提供者聯合的使用者。您可以在使用包含託管 UI 的 2.0 OAuth 授權伺服器進行身分驗證流程期間，為使用者的存取權杖選擇範圍。您的使用者身分驗證必須從 授權端點 開始，並以 scope 作為請求參數之一。以下是資源伺服器的建議格式。對於識別符，請使用API易記的名稱。對於自訂範圍，請使用他們授權的動作。

resourceServerIdentifier/scopeName

例如，您已在 Kuiper 皮帶中發現新的小行星，並想要透過 solar-system-data 註冊API。授權寫入操作到小行星資料庫的範圍是 asteroids.add。當您請求會授權您註冊探索的存取權杖時，請將您的scopeHTTPS請求參數格式化為 scope=solar-system-data/asteroids.add。

從資源伺服器刪除範圍並不會刪除其與所有用戶端的關聯。而是會將範圍標記為非作用中。Amazon Cognito 不會新增非作用中範圍至存取權杖，但如果您的應用程式提出請求，則會正常繼續進行。如果您稍後再次將範圍新增至資源伺服器，則 Amazon Cognito 會再次將其寫入存取權杖。如果您請求的範圍尚未與您的應用程式用戶端建立關聯，則無論您是否將該範圍從使用者集區資源伺服器中刪除，驗證都會失敗。

您可以使用 AWS Management Console、 API或 CLI 來定義使用者集區的資源伺服器和範圍。

為您的使用者集區定義資源伺服器 (AWS Management Console)

您可以使用 AWS Management Console 來定義使用者集區的資源伺服器。

定義資源伺服器

  1. 登入 Amazon Cognito 主控台。

  2. 在導覽窗格中，選擇 User Pools (使用者集區)，然後選擇您要編輯的使用者集區。

  3. 選擇 App integration (應用程式整合) 索引標籤，並找到 Resource servers (資源伺服器)。

  4. 選擇 Create a resource server (建立資源伺服器)。

  5. 輸入 Resource server name (資源伺服器名稱)。例如：Photo Server。

  6. 輸入 Resource server identifier (資源伺服器識別符)。例如：com.example.photos。

  7. 輸入資源的 Custom scopes (自訂範圍)，例如 read 和 write。

  8. 為每個 Scope name (範圍名稱) 輸入 Description (描述)，例如 view your photos 和 update your photos。

  9. 選擇 Create (建立)。

可以在 Custom scopes (自訂範圍) 欄，Resource servers (資源伺服器) 下的 App integration (應用程式整合) 中檢閱您的自訂範圍。可以從 App clients (應用程式用戶端) 下的 App integration (應用程式整合) 索引標籤啟用自訂範圍。選取應用程式用戶端，找到 Hosted UI settings (託管 UI 設定)，然後選擇 Edit (編輯)。新增 Custom scopes (自訂範圍)，然後選擇 Save changes (儲存變更)。

為您的使用者集區定義資源伺服器 （AWS CLI 和 AWS API）

使用下列命令為您的使用者集區指定資源伺服器設定。

建立資源伺服器
取得資源伺服器設定的相關資訊
為您的使用者集區列出所有資源伺服器的相關資訊
刪除資源伺服器
更新資源伺服器的設定