使用 JWT OAuth 權杖

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

查看 Apigee Edge 說明文件。

本主題說明如何使用 OAuthV2 政策產生、驗證及重新整理 JWT 存取權杖。

簡介

OAuthV2 政策可透過 JWT 作業，產生、驗證及重新整理符合 IETF RFC 9068 標準的存取權杖。這項標準說明如何以 JWT 格式核發存取權杖。JWT 通常用於在已連線的應用程式之間共用聲明或判斷。以 JWT 格式核發 OAuthV2 存取權杖，可做為核發不透明存取權杖的替代方案。

如果設定為 JWT，OAuthV2 政策會產生並傳回 Base64 編碼的 JWT，其中包含以半形句號分隔的標頭、酬載和簽章。例如：

圖 1：JWT 序列化格式，由標頭、酬載和簽章組成，並以半形句號分隔。

這些元素的編碼內容取決於 OAuthV2 政策的設定方式。在政策中，您可以指定簽署演算法和主體/名稱等酬載元素。舉例來說，標頭可能會解碼為 {"alg":"HS256","typ":"at+JWT"}，而酬載可能會解碼為：{"sub":"ABC1234567","iat":1516239022}。

標頭會指定 typ 憑證附加資訊 (一律為 "at+JWT) 和 alg 憑證附加資訊，指出用於簽署 JWT 的演算法。Apigee 支援 RSA 和 HMAC 演算法：RS(256,384,512) 和 HS(256,384,512)。

酬載

酬載包含實體的聲明。部分聲明必須在政策設定中提供，其他聲明則由 Apigee 執行階段自動產生。這項政策支援下列聲明：

著作權聲明 說明 提供者
iss 權杖核發者。這個值的設定方式如下：(http|https)://{domain-name-for-proxy}/{proxy-basePath}。例如：https://api.mycompany.com/auth/v2。 Apigee
sub 用戶端 ID 或資源擁有者 ID (適用於密碼或授權授予類型)。如果要求中提供 appEndUserId 參數，系統會將該值做為資源擁有者 ID。您可以使用 OAuthV2 政策的 <AppEndUser> 元素，控管這個值的設定位置。 API 開發人員
jti 專屬 ID，以 UUID 支援的隨機字串表示，用於專屬識別權杖。 Apigee
exp 到期時間，也就是系統將權杖視為無效的時間。這個值以 Epoch 時間 (以秒為單位) 表示。 Apigee
iat 簽發時間，也就是權杖的建立時間。這個值以 Epoch 時間 (以秒為單位) 表示。 Apigee
client_id 用戶端應用程式的專屬 ID。 API 開發人員
scope 指派給權杖的 OAuth 範圍。另請參閱「使用 OAuth 範圍」。 API 開發人員

簽名

簽章是使用編碼標頭、酬載、密碼/私密金鑰和演算法產生。 簽章用於確保權杖內容未遭竄改。

如要進一步瞭解 JWT 格式的 OAuth 2.0 存取權杖，請參閱 IETF RFC 9068：OAuth 2.0 存取權杖的 JSON Web Token (JWT) 設定檔。

先決條件

本文假設您瞭解如何使用 OAuthV2 政策產生及驗證 OAuthV2 存取權杖。無論您是使用 JWT 作業，還是建立不透明字串權杖的傳統作業，OAuthV2 政策的基本用法都相同。您可以使用 JWT 存取權杖，搭配所有支援的 OAuthV2 授權類型。請參閱 OAuth 2.0 簡介。

生成中

使用 GenerateJWTAccessToken 和 GenerateJWTAccessTokenImplicitGrant 作業，透過 OAuthV2 政策產生 JWT 存取權杖。這些作業與政策的傳統 GenerateAccessToken 和 GenerateAccessTokenImplicitGrant 作業類似。主要差異在於 JWT 作業會傳回 JWT 格式的存取權杖，而非不透明的字串權杖。另請參閱「取得 OAuth 2.0 權杖」。

下列範例說明如何在 OAuthV2 政策中使用這些作業。範例使用 client_credentials 授權類型，但您可以使用任何支援的授權類型執行這些作業。

產生以 HMAC 演算法簽署的 JWT 格式權杖

使用其中一個 HMAC (HS256/HS384/HS512) 演算法指定 <Algorithm> 元素。同時提供 <SecretKey>。 下列範例顯示設定的政策，可使用指定的密鑰，以 HS512 演算法產生已簽署的 JWT。

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

產生以 RSA 演算法簽署的 JWT 格式符記

在 <Algorithm> 元素中指定其中一個 RSA 演算法 (RS256/RS384/RS512 其中之一)，並在 <PrivateKey> 元素中提供私密金鑰。下列範例顯示設定的政策，可使用 RS256 演算法，產生以 RSA 私密金鑰簽署的 JWT。

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

使用隱含授權類型產生 JWT 格式的權杖

GenerateJWTAccessTokenImplicitGrant 作業會使用隱含授權類型產生 JWT 存取權杖。系統會自動為權杖提供隱含授權類型，因此不需要 <SupportedGrantTypes> 元素。由於這是 JWT，因此必須提供 <Algorithm> 元素。以下範例顯示 RS256 演算法的用法。因此，<PrivateKey> 元素為必要元素。另請參閱「使用隱含授權類型」。

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessTokenImplicitGrant</Operation>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

驗證中

使用 VerifyJWTAccessToken operation，透過 OAuthV2 政策驗證 JWT 存取權杖。這項作業與 VerifyAccessToken 作業類似，但 VerifyJWTAccessToken 適用於 JWT 格式的權杖，而 VerifyAccessToken 適用於不透明權杖。

驗證以 HMAC 演算法簽署的 JWT 存取權杖

以下範例說明如何設定 OAuthV2 政策，驗證以 HS512 演算法簽署的 JWT 權杖。使用 HMAC 演算法搭配 VerifyJWTAccessToken 作業時，政策設定必須使用 <SecretKey> 元素，指定用於簽署 JWT 的私密金鑰。

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
</OAuthV2>

驗證以 RSA 演算法簽署的 JWT 存取權杖

以下範例說明如何設定 OAuthV2 政策，驗證以 RS512 演算法簽署的 JWT 權杖。使用 RSA 演算法搭配 VerifyJWTAccessToken 作業時，政策設定必須使用 <PublicKey> 元素，指定與用於簽署 JWT 的私密金鑰對應的公開金鑰。

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>RS512</Algorithm>
  <PublicKey>
    <Value ref="propertyset.non-secrets.rsa-publickey-1"/>
  </PublicKey>
</OAuthV2>

正在重新整理

使用 RefreshJWTAccessToken operation 重新整理 JWT 存取權杖。 這項作業與傳統的政策 RefreshAccessToken 作業類似。另請參閱「重新整理存取權杖」。

重新整理以 HMAC 簽署的存取權杖

下列政策範例說明如何設定 OAuthV2 政策，以重新整理使用 HMAC 演算法簽署的 JWT 權杖。在此情況下，<SecretKey> 和 <Algorithm> 元素為必填欄位。

重新整理作業的回應與新產生的權杖回覆類似。重新整理作業會產生新的 JWT 權杖，並更新到期時間，其他聲明則維持不變。

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>HS512</Algorithm>
    <SecretKey>
      <Value ref="private.mysecretkey"/>
    </SecretKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

重新整理以 RSA 簽署的 JWT 存取權杖

下列政策範例說明如何設定 OAuthV2 政策，以重新整理使用 RSA 演算法簽署的 JWT 權杖。另請參閱「重新整理存取權杖」。 

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>RS256</Algorithm>
    <PrivateKey>
      <Value ref="private.rsa-privatekey-1"/>
    </PrivateKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

權杖回應範例

無論是產生或重新整理作業，回應主體看起來都會類似下列範例。請注意，access_token 會以序列化 JWT 表示，而更新權杖是傳統的不透明權杖。

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K0pXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "developer.email": "developer@example.org",
  "token_type": "Bearer",
  "issued_at": "1658352381404",
  "expires_in": 1799,
  "refresh_token": "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "refresh_token_issued_at": "1658352381404",
  "refresh_token_expires_in": 86399,
  "refresh_token_status": "Approved",
  "refresh_count": "0",
  "organization_name": "cerruti",
  "api_product_list_json": [ "TestingProduct" ]
}

必要政策元素摘要

下表說明上述範例中使用的 JWT 專屬元素：

元素 類型 附註
演算法 靜態值 指定用來簽署權杖的演算法。
SecretKey 參照值 提供用於以 HMAC 演算法 (HS 256/384/512) 驗證或簽署權杖的密鑰。
PrivateKey 參照值 提供用於產生權杖的私密金鑰。僅在演算法為 RSA 演算法時使用：RS (256/384/512)。
PublicKey 參照值 提供用於驗證權杖的公開金鑰。僅在演算法為 RSA 演算法時使用：RS (256/384/512)。

不支援的政策元素

JWT 權杖設定不支援下列 OAuthV2 政策元素：

元素 附註
ExternalAuthorization 產生 JWT 存取權杖時，OAuthV2 政策會驗證用戶端 ID 和密鑰。
ExternalAccessToken 產生 JWT 存取權杖時，權杖會由 Apigee 簽署，且憑證附加資訊會由 Apigee 預設提供，或透過政策設定提供。這項政策支援 ExternalRefreshToken，有助於遷移用途。
RFCCompliantRequestResponse 根據預設，系統會產生及更新符合 RFC 規範的 JWT 存取權杖。

使用須知

  • 系統不支援加密的 JWT。
  • 除了 JWT 存取權杖，政策回應也包含不透明的重新整理權杖 (適用於支援重新整理權杖的授權類型)。只有密碼和授權碼授權類型支援更新權杖。
  • 在傳送至含有 OAuthV2 政策的 Proxy 的要求中，加入 Authorization 標頭。
  • 您無法撤銷 JWT 存取權杖。產生的 JWT 權杖在到期前都有效。 您可以撤銷與 JWT 存取權杖相關聯的更新權杖。
  • 存取權杖的產生、驗證和重新整理作業必須由 Apigee 處理。雖然有權存取公開或私密金鑰的外部應用程式或閘道可以解碼 JWT 的內容，但外部應用程式沒有 client_id 聲明所識別的 API 產品相關資訊，因此無法在 API Proxy 授權中扮演任何角色。