使用資源伺服器進行範圍、M2M 和 API 授權 - Amazon Cognito
M achine-to-machine (M2M) 授權關於範圍關於資源伺服器

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

使用資源伺服器進行範圍、M2M 和 API 授權

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

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

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

M achine-to-machine (M2M) 授權

Amazon Cognito 支援使用機器身分存取 API 資料的應用程式。使用者集區中的機器身分識別是在應用程式伺服器上執行並連線至遠端 API 的機密用戶端。他們的操作在沒有用戶互動的情況下進行：計劃任務，數據流或資產更新。當這些客戶端使用訪問令牌授權其請求時，它們會執行機器對機器或 M2M 授權。在 M2M 授權中，共用密碼會取代存取控制中的使用者認證。

使用 M2M 授權存取 API 的應用程式必須具有用戶端 ID 和用戶端密碼。在您的使用者集區中，您必須建置支援用戶端認證授與的應用程式用戶端。要支持客戶端憑據，您的應用程序客戶端必須具有客戶端密鑰，並且您必須具有用戶池域。在此流程中，您的機器身分會直接從權杖端點. 您可以在用戶端認證授與的存取權杖中，僅授權來自資源伺服器的自訂範圍。如需設定應用程式用戶端的詳細資訊，請參閱使用者集區應用程式用戶端。

來自客戶端憑據授予的訪問令牌是您希望允許您的機器身份從 API 請求的操作的可驗證聲明。要了解有關訪問令牌如何授權 API 請求的更多信息，請繼續閱讀。如需範例應用程式，請參閱使用 AWS CDK 的 Amazon Cognito 和 API Gateway 式機器對機器授權。

M2M 授權的計費模式與每月活躍用戶（MAU）計費方式不同。如果用戶身份驗證承擔每個活躍用戶的費用，M2M 計費反映了活動客戶端憑據應用程序客戶端和令牌請求總量。如需詳細資訊，請參閱 Amazon Cognito 定價。為了控制 M2M 授權的成本，請優化訪問令牌的持續時間和應用程序發出的令牌請求數量。有關使用 API Gateway 緩存來減少 M2M 授權中對新令牌的請求的方法，請參快取權杖閱。

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

關於範圍

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

使用者集區保留的 API 範圍

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

自訂範圍

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

標準範圍

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

openid

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

注意

當您請求 openid 範圍而沒有其他人時，您的使用者集區 ID 權杖和 userInfo 回應包含您的應用程式用戶端可以讀取的所有使用者屬性的宣告。當您請求 openid 和其他標準範圍 (例如 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 存取字符可以授權對支援 OAuth 2.0 之 API 的存取。Amazon API Gateway REST API 具有使用 Amazon Cognito 存取字符進行授權的內建支援。您的應用程式會在 API 呼叫中傳遞存取字符至資源伺服器。資源伺服器會檢查存取字符，以判斷是否應授予存取權。

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

自訂範圍由您定義，並擴充使用者集區的授權功能，以納入與查詢和修改使用者及其屬性無關的用途。例如，如果您有用於照片的資源伺服器，它可能會定義兩個範圍：photos.read 用於照片的讀取存取權，photos.write 用於寫入/刪除存取權。您可以設定 API 接受存取權杖以進行授權，並在 scope 宣告中對存取權杖的 HTTP GET 請求授予 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 建立 OAuth2.0 資源伺服器，並將自訂範圍與這些伺服器建立關聯。存取權杖中的自訂範圍會授權您 API 中的特定動作。您可以授權讓使用者集區中的任何應用程式用戶端從任一部資源伺服器發出自訂範圍。將您的自訂範圍與應用程式用戶端建立關聯，並且在 OAuth2.0 授權碼授予、隱含授予和用戶端憑證授予中向 權杖端點 請求這些範圍。Amazon Cognito 會在存取權杖中將自訂範圍新增至 scope 宣告中。用戶端可以對其資源伺服器使用存取字符，資源伺服器會根據存在於字符中的範圍來制定授權決策。如需存取字符範圍的詳細資訊，請參閱將字符用於使用者集區。

資源伺服器流程的概觀。用戶端請求具有自訂範圍的授予，使用者集區傳回具有自訂範圍的存取字符，而用戶端向 API 提供存取字符。

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

注意

因為它們是專為使用者集區做為 IdP 的人工互動式驗證而設計，而InitiateAuth且AdminInitiateAuth要求只會在具有單一值的存取權杖中產生scope宣告。aws.cognito.signin.user.admin

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

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

  • 資源伺服器名稱：資源伺服器的易記名稱，例如 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 可針對任何使用者在存取權杖中包含自訂範圍，無論這些使用者是您的使用者集區本機使用者還是與第三方身分提供者聯合的使用者。您可以使用包含託管 UI 的 OAuth 2.0 授權伺服器，在身分驗證流程期間為使用者的存取權杖選擇範圍。您的使用者身分驗證必須從 授權端點 開始，並以 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 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) 定義資源伺服器

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

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