驗證 JSON Web 權杖 - Amazon Cognito

驗證 JSON Web 權杖

這些步驟描述有關驗證使用者集區 JSON web 權杖 (JWT)。

先決條件

您的程式庫、軟體開發套件或軟體架構可能已處理本節的任務。例如,Amazon Cognito 開發套件在用戶端提供使用者集區的權杖處理和管理。同樣地,如果符合兩項條件:需有有效 (未過期) 重新整理權杖,而且 ID 權杖和存取權杖的有效時間須至少還剩餘 5 分鐘,適用於 iOS 的 Mobile SDK 和適用於 Android 的 Mobile SDK 就會自動重新整理您的 ID 權杖和存取權杖。如需 JavaScript、Android 和 iOS 適用的軟體開發套件 (SDK) 和範本程式碼,請參閱 Amazon Cognito 使用者集區 SDK

許多程式庫可用於解碼和驗證 JSON Web 權杖 (JWT)。如果您必須手動處理權杖以進行伺服器端 API 處理,又或者您使用的是其他程式設計語言,那麼這些程式庫就很實用。請參閱可搭配 JWT 權杖使用的 OpenID Foundation 程式庫清單

步驟 1:確認 JWT 的結構

JSON Web Token (JWT) 包含三個部分:

  1. 標頭

  2. 酬載

  3. 簽章

11111111111.22222222222.33333333333

這些節會編碼為 base64url 字串,並以點 (.) 字元區隔。如果您的 JWT 不符合這個結構,請將其視為無效,並且拒絕接受。

步驟 2:驗證 JWT 簽章

JWT 簽章是標頭和酬載的雜湊組合。Amazon Cognito 會為每個使用者集區產生兩組 RSA 加密金鑰對。其中一個私有金鑰是用來簽署權杖。

驗證 JWT 權杖的簽章

  1. 解碼 ID 權杖。

    您可以使用 AWS Lambda 來解碼使用者集區 JWT。如需詳細資訊,請參閱使用 AWS Lambda 解碼及驗證 Amazon Cognito JWT 權杖

    OpenID Foundation 也會提供可搭配 JWT 權杖使用的程式庫清單

  2. 比較本機金鑰 ID (kid) 與公有 kid。

    1. 下載並存放對應至您的使用者集區的公開 JSON Web Key (JWK)。JSON Web Key Set (JWKS) 中會提供這個金鑰。針對您的環境構建以下 URL 即可找到它:

      https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/jwks.json

      如需 JWK 和 JWK 集的詳細資訊,請參閱 JSON Web 金鑰 (JWK)

      注意

      為您的使用者集區下載和存放 JWK 是一次性步驟,之後 Web API 操作才能處理權杖。完成後,您可以在每次搭配 Web API 操作使用 ID 權杖或存取權杖時,執行下列步驟。

      這是範本 jwks.json 檔案:

      { "keys": [{ "kid": "1234example=", "alg": "RS256", "kty": "RSA", "e": "AQAB", "n": "1234567890", "use": "sig" }, { "kid": "5678example=", "alg": "RS256", "kty": "RSA", "e": "AQAB", "n": "987654321", "use": "sig" }] }
      金鑰 ID (kid)

      kid 是指出在保護權杖之 JSON Web Signature (JWS) 安全時所使用金鑰的提示。

      演算法 (alg)

      alg 標頭參數代表用來保護 ID 權杖安全的加密演算法。使用者集區是使用 RS256 演算法,即採用 SHA-256 的 RSA 簽章。如需 RSA 的詳細資訊,請參閱 RSA 加密法

      金鑰類型 (kty)

      kty 參數會識別搭配金鑰 (本範例中的金鑰為 "RSA") 的加密演算法系列。

      RSA 指數 (e)

      這個 e 參數包含 RSA 公開金鑰的指數值。它以 Base64urlUInt 編碼值表示。

      RSA 模數 (n)

      這個 n 參數包含 RSA 公開金鑰的模數值。它以 Base64urlUInt 編碼值表示。

      用途 (use)

      這個 use 參數描述公開金鑰的用途。在這個範例中,usesig 代表簽章。

    2. 搜尋符合您的 JWT 中 kidkid 的公有 JSON Web 金鑰。

  3. 使用 JWT 程式庫,例如 GitHub 上的 aws-jwt-verify 程式庫,將發行者的簽章與權杖中的簽章進行比較。發行者簽章衍生自 kid 的公有金鑰 (RSA 模數 "n"),格式時與權杖 kid 相符的 jwks.json。您可能需要先將 JWK 轉換成 PEM 格式。以下範例處理了 JWT 和 JWK,並且使用 Node.js 程式庫、jsonwebtoken 來驗證 JWT 簽章:

    Node.js
    var jwt = require('jsonwebtoken'); var jwkToPem = require('jwk-to-pem'); var pem = jwkToPem(jwk); jwt.verify(token, pem, { algorithms: ['RS256'] }, function(err, decodedToken) { });

步驟 3:驗證宣告

驗證 JWT 宣告

  1. 確認權杖未過期。

  2. 在 ID 權杖中的 aud 宣告和在存取權杖中的 client_id 宣告應符合在 Amazon Cognito 使用者集區建立的應用程式用戶端 ID。

  3. 發行者 (iss) 宣告應該符合您的使用者集區。例如,在 us-east-1 區域中建立的使用者集區會有以下 iss 值:

    https://cognito-idp.us-east-1.amazonaws.com/<userpoolID>.

  4. 檢查 token_use宣告。

    • 如果您在 Web API 操作中只接受存取權杖,其值必須是 access

    • 如果您只使用 ID 權杖,其值必須是 id

    • 如果是同時使用 ID 權杖和存取權杖,token_use 宣告必須是 idaccess

您現在可以信任權杖內部的宣告。