撤銷及核准憑證

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

瞭解權杖撤銷

在某些情況下，應用程式必須明確撤銷或使個別權杖失效。舉例來說，使用者登出已啟用 OAuth 的應用程式時，遭撤銷的權杖就無法再用於授權。權杖遭撤銷後，如果應用程式將該權杖提供給 API Proxy，OAuthV2 政策 (作業為 VerifyAccessToken) 就會拒絕該權杖。

權杖撤銷標準是由 IETF RFC 7009 (OAuth 2.0 權杖撤銷規格) 所定義。

除了撤銷特定權杖，您也可以撤銷用戶端 ID 或整個開發人員應用程式。詳情請參閱「撤銷及核准開發人員應用程式金鑰」。與撤銷個別權杖相比，撤銷用戶端 ID 或開發人員應用程式的影響範圍較廣。撤銷用戶端 ID 或開發人員應用程式後，Apigee 會拒絕與該用戶端 ID 或開發人員應用程式相關聯的所有權杖，且不再為該用戶端 ID 或開發人員應用程式核發新權杖。

撤銷權杖 (存取權杖或更新權杖) 後，您可以在權杖到期前隨時重新核准。重新核准權杖後，Apigee OAuthV2 政策會再次接受該權杖進行授權，直到權杖過期為止。權杖到期時間與權杖的核准或撤銷狀態無關。 如果存取權杖已獲准 (或未遭撤銷) 且未過期，Apigee OAuthV2 政策 (作業為 ValidateAccessToken) 就會接受該權杖。同樣地，如果 Apigee OAuthV2 政策的作業為 RefreshAccessToken，則只有在重新整理權杖獲得核准 (或未遭撤銷) 且未過期時，才會接受該權杖。

您可以使用下列兩項政策撤銷權杖：

OAuthV2 政策可一次撤銷及恢復單一權杖。RevokeOAuthV2 政策更具彈性，可依應用程式 ID 或使用者 ID 一次撤銷多個權杖。本頁面其餘內容說明如何使用 OAuthV2 政策撤銷或恢復先前撤銷的權杖。

撤銷存取和更新權杖

以下是 OAuthV2 政策的設定範例，其中使用 InvalidateToken 作業。在本例中，由於 Token 元素上的 cascade 屬性為 true，Apigee 會撤銷存取權杖和相關聯的更新權杖。

  <OAuthV2 name="InvalidateToken">
    <Operation>InvalidateToken</Operation>
    <Tokens>
      <Token type="accesstoken" cascade="true">request.queryparam.token</Token>
    </Tokens>
  </OAuthV2>

如要進一步瞭解連鎖旗標的運作方式，請參閱下方的「Token 元素的屬性」一節。

<Tokens>/<Token> 元素

找出指定要撤銷權杖的流程變數。舉例來說，如果開發人員應使用名為 access_token 的查詢參數提交撤銷要求，則正確的流程變數為 request.queryparam.access_token。如要在 HTTP 標頭中要求權杖，請將這個值設為 request.header.access_token。

JWT 格式的存取權杖無法撤銷。 此外，您無法使用 OAuthV2 政策，撤銷與 JWT 格式存取權杖相關聯的更新權杖。如果這裡指定的內容變數是指 JWT 存取權杖，或是與 JWT 存取權杖相關聯的更新權杖，就會發生執行階段錯誤。您可以使用 RevokeOAuthV2 政策，撤銷與 JWT 存取權杖相關聯的更新權杖。

屬性

  • type (必要，字串)：變數指定的權杖類型。支援的值為 accesstoken 和 refreshtoken:
    • 如要撤銷存取權杖，請指定類型為 accesstoken。
    • 如要同時撤銷存取權杖和更新權杖，請指定類型 refreshtoken。如果看到類型為 refreshtoken，Apigee 會假設該權杖為更新權杖。如果找到該更新權杖，就會撤銷。如果找不到該重新整理權杖，Apigee 會檢查是否為存取權杖。如果存取權杖存在，就會遭到撤銷。

      注意：如果您將已失效的權杖傳遞至 InvalidateToken 政策，該政策不會傳回錯誤 (您可能會預期會傳回錯誤)。這類作業不會產生任何影響。
  • cascade (選用，布林值，預設值：true) 這個屬性的主要用途是撤銷重新整理權杖，但不撤銷相關聯的存取權杖。請考量下列情況：
    • 只撤銷更新權杖，不要撤銷相關聯的存取權杖。如要這麼做，請將 <Token> 類型設為 refreshtoken，並將層疊設為 false。
    • 撤銷存取權杖和更新權杖。如要這樣做，請將 <Token> 類型設為 accesstoken。串聯的值可以是 true (預設值) 或 false。如果設為 true，存取權杖和更新權杖都會遭到撤銷。如果設為 false，存取權杖就會遭到撤銷，更新權杖也無法使用。詳情請參閱下方附註。
    • 撤銷存取權杖，但不撤銷相關聯的更新權杖。不支援。詳情請參閱下方附註。

注意：基於安全考量，撤銷存取權杖時，系統也會一併撤銷相關聯的重新整理權杖。因此，您無法使用層疊屬性僅撤銷存取權杖。舉例來說，如果將 <Token> 類型設為 accesstoken，並設定 cascade=false，存取權杖就會遭到撤銷 (符合預期)，但相關聯的更新權杖將無法使用。無法用來更新已撤銷的存取權杖。如要只撤銷重新整理權杖，主要使用情境就是使用串聯屬性。在這種情況下，請將 <Token> 類型設為 refreshtoken，並設定 cascade=false。系統會撤銷更新權杖，但相關聯的存取權杖仍有效 (直到過期或遭到撤銷為止)。詳情請參閱這篇 社群論壇討論。

核准存取和更新權杖

使用 ValidateToken 作業「重新核准」已撤銷的權杖。也就是說，套用這項作業後，目標存取或更新權杖的狀態會從「已撤銷」變更為「已核准」。只要權杖尚未過期，您都可以驗證遭撤銷的權杖。

<OAuthV2 name="ValidateToken">
  <Operation>ValidateToken</Operation>
  <Tokens>
    <Token type="refreshtoken" cascade="true">flow.variable</Token>
  </Tokens>
</OAuthV2>

<Tokens>/<Token> 元素

找出指定要驗證權杖的流程變數。舉例來說，如果開發人員應使用名為 access_token 的查詢參數提交驗證要求，正確的流程變數會是 request.queryparam.access_token。如要在 HTTP 標頭中要求權杖，請將這個值設為 request.header.access_token。

屬性

  • type (必要，字串)：變數指定的權杖類型。支援的值為 accesstoken 和 refreshtoken。
  • cascade (選用，布林值)：預設值為 true，會導致驗證作業傳播至相關聯的權杖。因此，如果套用至更新權杖，系統也會驗證相關聯的存取權杖。如果套用至存取權杖，系統也會驗證相關聯的更新權杖。如果將這個值設為 false，則只會驗證指定的存取或更新權杖。