Knowledge Center Monthly Newsletter - March 2025

Stay up to date with the latest from the Knowledge Center. See all new and updated Knowledge Center articles published in the last month and re:Post’s top contributors.

如何在 API Gateway REST API 上將 Amazon Cognito 使用者集區設定為授權者？

3 分的閱讀內容

我想在我的 Amazon API Gateway REST API 上設定一個 Amazon Cognito 使用者集區作為授權者。

簡短說明

有兩種方法可以在 API Gateway REST API 上將 Amazon Cognito 使用者集區設定為授權者：

您可以使用 ID 權杖或存取權杖進行授權。存取權杖可以使用 Amazon Cognito 中的自訂範圍來授權對 API Gateway API 的存取。Lambda 授權者可以驗證 Amazon Cognito 發行的 ID 權杖和存取權杖中的宣告。

如需詳細資訊，請參閱下列主題：

解決方法

先決條件：

建立 COGNITO_USER_POOLS 授權者

如需詳細資訊，請參閱整合 REST API 與 Amazon Cognito 使用者集區。請依照使用 API Gateway 主控台建立 COGNITO\ _USER\ _POOLS 授權者一節中的指示進行。

測試新的 COGNITO_USER_POOLS 授權者

請完成下列步驟：

開啟 API Gateway 主控台。
在新授權者下，選擇測試按鈕。
在測試視窗中，對於授權，輸入來自新 Amazon Cognito 使用者集區的 ID 權杖。
選擇測試。
**注意：**如果 ID 權杖正確，則測試會傳回 200 回應代碼。不正確的 ID 權杖則會傳回 401 回應代碼。

採用 API 方法設定 COGNITO_USER_POOLS 授權者

如需詳細資訊，請參閱整合 REST API 與 Amazon Cognito 使用者集區。請遵循採用各種方法設定 COGNITO_USER_POOLS 授權者一節中的指示。

取得授權權杖

取得授權權杖有三種方法：

使用 AWS Command Line Interface (AWS CLI)。
使用其中一個 AWS SDK。
使用 Postman 應用程式。

**注意：**使用授權碼授予方式來設定 Amazon Cognito 託管的 UI，以便您的應用程式可以針對權杖端點交換程式碼。

如果您使用隱含的授予方式類型，則可以透過回呼網址獲獲得授予方式。回呼網址附加了隱含資料流的存取權杖和 ID 權杖參數。請您務必使用正確的權杖類型。

使用 Amazon Cognito 的託管 UI 取得授權權杖

**注意：**使用授權代碼授予流程時，回應類型參數必須是 "code"。

若要使用授權碼授予流程，請完成下列步驟：

對授權碼授予傳送 GET 請求：

https://example_domain/oauth2/authorize?response_type=code&client_id=example_app_client_id&redirect_uri=example_callback_url

**注意：**以您的使用者集區的網域名稱取代 example_domain。以您的使用者集區的應用程式用戶端 ID 取代 example_app_client_id。以您的回呼網址取代 example_callback_url。包括端點的 identity_provider 參數，以重新導向至聯合身分提供者。如果應用程式用戶端僅針對 Amazon Cognito 使用者集區設定，則下列端點會重新導向至 /login 端點：

https://example_domain/login?response_type=code&client_id=example_app_client_id&redirect_uri=example_callback_url

登入您的使用者集區或聯合身分提供者。使用者介面會重新導向至應用程式用戶端的回呼中所指定的網址。
**重要事項：**重新導向網址包括必須與權杖端點交換以取得有效權杖的授權代碼。
將 POST 請求傳送至 /oauth2/token 端點以交換權杖的授權代碼。如需詳細資訊，請參閱權杖端點。

**範例 POST 請求以交換權杖的授權代碼 **

**注意：**範例 POST 請求使用以下 /oauth2/token 端點：https://example_domain.auth.us-east-1.amazoncognito.com/oauth2/token&

Content-Type='application/x-www-form-urlencoded'&Authorization=Basic ZXhhbXBsZTEyMzQ1Njc4OTA6enl4OTh3N3l2dHNycTY1NHBvMzIx
grant_type=authorization_code&
client_id=example1234567890&
code=AUTHORIZATION_CODE&
redirect_uri=com.myclientapp://myclient/redirect

範例 POST 請求回應

HTTP/1.1 200 OK Content-Type: application/json

{
  "access_token":"abCde1example",
  "id_token":"abCde2example",
  "refresh_token":"abCde3example",
  "token_type":"Bearer",
  "expires_in":3600
}

**注意：**使用隱含授予流程時，回應類型參數必須是 "token"。

若要使用隱含授予流程，請完成下列步驟：

對隱含授予傳送 GET 請求：

https://example_domain/oauth2/authorize?response_type=token&client_id=example_app_client_id&redirect_uri=example_callback_url

https://example_domain/login?response_type=token&client_id=example_app_client_id&redirect_uri=example_callback_url

使用現有使用者的使用者名稱和密碼登入您的使用者集區，或建立新的使用者以進行登入。使用者介面會重新導向至應用程式用戶端的回呼中所指定的網址。
注意：重新導向網址包括 ID 權杖和存取權杖。
重新導向網址範例：

https://www.example.com/#id_token=123456789idtoken123456789&access_token=123456789accesstoken123456789expires_in=3600&token_type=Bearer

使用 AWS CLI 取得授權權杖

**注意：**如果您在執行 AWS CLI 命令時收到錯誤，請參閱對 AWS CLI 錯誤進行疑難排解。此外，請確定您使用的是最新的 AWS CLI 版本。

執行以下 initiate-auth AWS CLI 命令以取得授權權杖：

aws cognito-idp initiate-auth --auth-flow USER_PASSWORD_AUTH --auth-parameters USERNAME=example_user,PASSWORD=example_password --client-id example_app_client_id

重要事項： 將 example_user 取代為您的使用者名稱，example_password 取代為您的密碼，以及 example_app_client_id 取代為您的應用程式用戶端 ID。

範例 initiate-auth AWS CLI 命令回應

{
  "AuthenticationResult": {
    "AccessToken": "abCde1example",
    "IdToken": "abCde2example",
    "RefreshToken": "abCde3example",
    "TokenType": "Bearer",
    "ExpiresIn": 3600
  },
  "ChallengeParameters": {}
}

使用其中一個 AWS SDK 取得授權權杖

如需詳細資訊，請參閱將 Amazon Cognito 驗證和授權與 Web 和行動應用程式整合。

使用 Postman 取得授權權杖

使用 Postman 網站中的 OAuth 2.0 授權模式取得授權權杖。如需詳細資訊，請參閱為什麼在建立 Lambda Authorizer 之後收到 API Gateway「401 未經授權」錯誤？

在 Amazon Cognito 使用者集區中設定 OAuth 2.0 自訂範圍，並在 API Gateway 中驗證範圍

範圍提供應用程式可以要求資源的存取層級。Amazon Cognito 具有內建的 OAuth 範圍，可加以設定以允許應用程式用戶端與使用者集區建立關聯。如需 Amazon Cognito 中內建範圍的詳細資訊，請參閱應用程式用戶端術語。

自訂範圍可以與 OAuth 2.0 資源伺服器建立關聯。如需資源伺服器的詳細資訊，請參閱 OAuth 2.0 範圍和使用資源伺服器的 API 授權。

當您將搭配 API Gateway 使用 Amazon Cognito 時，Amazon Cognito 授權者會驗證請求並確保資源安全。搭配 Amazon Cognito 和 API Gateway 使用自訂範圍，以提供不同層級的 API 資源存取權限。在公開資源以存取權杖範圍時，您還可以獲得更多控制權。

**在使用者集區中設定資源伺服器與 OAuth 2.0 自訂範圍 **

為您的使用者集區定義資源伺服器與自訂範圍。
對於資源伺服器識別符，請提供資源所在之 API Gateway 的 HTTPS 端點。
如有必要，設定使用者集區應用程式用戶端，然後在應用程式用戶端設定中新增自訂範圍。
**注意：**自訂範圍名稱格式採用以下格式： resourceServerIdentifier/scopeName

當用戶端應用程式在 OAuth 2.0 流程中請求自訂範圍時，用戶端應用程式必須請求範圍的完整識別符。例如，如果資源伺服器識別符為 https://myresourceserver.example.com，而範圍名稱是 resources.read，則用戶端應用程式必須在執行階段要求 https://myresourceserver.example.com/resources.read。

驗證 API Gateway 中的 OAuth 2.0 自訂範圍

整合 REST API 與 Amazon Cognito 使用者集區。
在 API Gateway 主控台中，選擇 REST API。
在資源窗格中，選擇方法名稱。
選擇方法請求組態。
從授權下拉式清單中，選擇 Cognito 授權者。這會自動新增一個名稱為 OAuth 範圍的新欄位。
在 OAuth 範圍欄位中，以先前提到的格式輸入自訂範圍的完整識別符。例如，**https://myresourceserver.example.com/resources.read **。
儲存並部署 API。

使用 Postman 或 CURL 測試設定

若要從 Amazon Cognito 授權伺服器取得存取權杖，請使用針對用戶端定義的其中一個 OAuth 2.0 流程。
將收到的存取權杖作為請求的授權標頭傳送至 API Gateway。

如果一切順利，而且 API Gateway 驗證並確認存取權杖和自訂範圍，那麼您將收到 200 OK 回應。