OAuthV2 政策

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

查看 Apigee Edge 說明文件。

政策圖示

結果

OAuthV2 是一項多面向的政策，可執行 OAuth 2.0 授權類型作業。這是用來在 Apigee 上設定 OAuth 2.0 端點的主要政策。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

如要進一步瞭解 Apigee 的 OAuth，請參閱 OAuth 首頁。並提供資源、範例、影片等內容的連結。

範例

VerifyAccessToken

VerifyAccessToken

這項 OAuthV2 政策設定 (搭配 VerifyAccessToken 作業) 會驗證提交給 Apigee 的存取權杖是否有效。觸發這項政策作業時，Apigee 會在要求中尋找有效的存取權杖。如果存取權杖有效，系統就會允許要求繼續進行。如果無效，系統會停止所有處理作業，並在回應中傳回錯誤。

<OAuthV2 name="OAuthV2-Verify-Access-Token">
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

用戶端應用程式必須傳送附有權杖的要求。例如，使用 curl 時可能如下所示：

$ curl https://API_ENDPOINT/weather/forecastrss?w=12797282 \
  -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"

其中 API_ENDPOINT 是用於存取 API 的網域，已在 Apigee 系統中設定。

根據預設，OAuthV2 政策會從 Authorization 標頭擷取存取權杖，並移除 Bearer 前置字元。您可以使用 AccessToken 設定元素變更這項預設行為。

GenerateAccessToken

產生存取權杖

如需範例，瞭解如何為每個支援的授權類型要求存取權杖，請參閱「取得 OAuth 2.0 權杖」。本主題包含這些作業的範例：

GenerateAuthorizationCode

產生授權碼

如需要求授權碼的範例，請參閱「要求授權碼」。

RefreshAccessToken

重新整理存取權杖

如需使用更新權杖要求存取權杖的範例，請參閱「更新存取權杖」。

JWT 存取權杖

JWT 存取權杖

如需產生、驗證及更新 JWT 存取權杖的範例，請參閱「使用 JWT 存取權杖」。

回覆流程權杖

在回應流程中產生存取權杖

有時您可能需要在回應流程中產生存取權杖。舉例來說，您可能會在後端服務中完成某些自訂驗證後，執行這項操作。在本範例中，用途需要存取權杖和更新權杖，因此排除隱含授權類型。在本例中，我們會使用密碼授權類型產生權杖。如您所見，要讓這項功能正常運作，訣竅是傳遞含有 JavaScript 政策的 Authorization 要求標頭。

首先，請看以下範例政策：

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

如果您將這項政策放在回應流程中，即使政策中指定了正確的登入參數，系統仍會失敗並顯示 401 UnAuthorized 錯誤。如要解決這個問題，請設定授權要求標頭。

Authorization 標頭必須包含 Basic 存取配置，以及 Base64 編碼的 client_id:client_secret。

您可以在 OAuthV2 政策之前加入 JavaScript 政策，藉此新增這個標頭，如下所示。「local_clientid」和「local_secret」環境變數必須事先設定，且可在流程中使用：

var clientId = context.getVariable("local_clientid");
var clientSecret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+ CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(clientId + ':' + clientSecret)));

另請參閱編碼基本驗證憑證。

元素參考資料

政策參考資料說明 OAuthV2 政策的元素和屬性。

以下顯示的範例政策只是其中一種設定。這個範例顯示為 GenerateAccessToken 作業設定的 OAuthV2 原則。包括必要和選用元素。詳情請參閱本節中的元素說明。

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

<OAuthV2> 屬性

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

下表說明所有政策父項元素的共同屬性：

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。

您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。

 不適用 必填
continueOnError

將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。

將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：

 false 選用
enabled

設為 true 即可強制執行政策。

設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。

 是 選用
async

此屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素，系統會使用政策的 name 屬性值。
存在必要性 選用
類型 字串

<AccessToken> 元素

<AccessToken>request.header.access_token</AccessToken>

根據預設，當 Operation 為 VerifyAccessToken 時，這項政策會預期存取權杖以持有人權杖的形式，在 Authorization 標頭中傳送；也就是說，權杖會以「Bearer」為前置字元，後面加上一個空白字元。您可以使用這個元素變更預設值，並指定包含要驗證存取權杖的變數名稱。使用這個元素時，政策預設不會在變數內容中尋找前置字元。如要指定政策應尋找前置字串，請一併使用 AccessTokenPrefix 元素。

範例：

  • 政策設定如下：

      <OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header">
      <Operation>VerifyAccessToken</Operation>
      <AccessToken>request.header.access_token</AccessToken>
  </OAuthV2>

    如要使用 curl 傳遞權杖，可以採用下列做法：

      curl https://API_ENDPOINT/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

  • 政策設定如下：

      <OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam">
      <Operation>VerifyAccessToken</Operation>
      <AccessToken>request.queryparam.token</AccessToken>
  </OAuthV2>

    如要使用 curl 傳遞權杖，可以採用下列做法：

      curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"

其中 API_ENDPOINT 是用於存取 API 的網域，已在 Apigee 系統中設定。

預設

不適用

外觀狀態

選用
類型 字串
有效值

任何變數名稱
搭配作業使用
  • VerifyAccessToken

<AccessTokenPrefix> 元素

<AccessTokenPrefix>Prefix</AccessTokenPrefix>

根據預設，當 Operation 為 VerifyAccessToken 時，這項政策會預期存取權杖以持有人權杖的形式，在 Authorization 標頭中傳送；也就是說，權杖會以「Bearer」為前置字元，後面加上一個空白字元。如果您使用 AccessToken 元素為傳入的存取權杖指定其他位置，也可以使用這個元素 (AccessTokenPrefix) 指定其他非標準前置字元。

舉例來說，如果您指定：

<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header">
    <Operation>VerifyAccessToken</Operation>
    <AccessToken>request.header.token</AccessToken>
    <AccessTokenPrefix>KEY</AccessTokenPrefix>
</OAuthV2>

然後，這項政策會從 token 要求標頭中擷取傳入的存取權杖，方法如下：如果標頭開頭為「KEY」一字，後面接著一個半形空格，政策就會移除該前置字串和半形空格，並將剩餘值解讀為存取權杖。如果標頭中沒有指定的前置字串，政策就會擲回錯誤。

如果您指定 AccessToken 元素，但未指定 AccessTokenPrefix 元素，政策會將 AccessToken 元素中指定的變數值解讀為存取權杖。

只有同時使用 AccessToken 元素時，這個元素才會生效。

預設

-none-

外觀狀態

選用
類型 字串
有效值

任何字串
搭配作業使用
  • VerifyAccessToken

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

指定用來簽署 JWT 存取權杖的加密演算法。RSA (RS*) 演算法採用公開/私密金鑰組，而 HMAC (HS*) 演算法則採用共用密鑰。GenerateJWTAccessToken、VerifyJWTAccessToken 和 RefreshJWTAccessToken 作業都需要這個元素。

預設 不適用
外觀狀態 使用 GenerateJWTAccessToken、VerifyJWTAccessToken 和 RefreshJWTAccessToken 作業時，此為必填屬性。
類型 字串
有效值 HS256、HS384、HS512、RS256、RS384、RS512

<AppEndUser> 元素

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

如果必須將應用程式使用者 ID 傳送至授權伺服器，您可以使用這個元素指定 Apigee 應從何處尋找使用者 ID。舉例來說，這類資料可以做為查詢參數或在 HTTP 標頭中傳送。

舉例來說，request.queryparam.app_enduser 表示 AppEndUser 應以查詢參數的形式存在，例如 ?app_enduser=ntesla@theramin.com。如要在 HTTP 標頭中要求 AppEndUser，請將這個值設為 request.header.app_enduser。

提供這項設定後，您就能在存取權杖中加入應用程式使用者 ID。如果您想依使用者 ID 擷取或撤銷 OAuth 2.0 存取權杖，這項功能就非常實用。詳情請參閱「 根據使用者 ID、應用程式 ID 或兩者，啟用 OAuth 2.0 存取權杖的擷取和撤銷功能」。

預設

不適用

外觀狀態

選用
類型 字串
有效值

政策在執行階段可存取的任何流程變數。
搭配授權類型使用
  • authorization_code
  • 隱含
  • 密碼
  • client_credentials

<Attributes/Attribute>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

使用這個元素，在存取權杖或授權碼中新增自訂屬性。舉例來說，您可能會想在存取權杖中嵌入使用者 ID 或工作階段 ID，以便在執行階段擷取及檢查。

這個元素可讓您在流程變數或常值字串中指定值。如果同時指定變數和字串，系統會使用流程變數中指定的值。如果無法解析變數，則字串為預設值。

如要進一步瞭解如何使用這個元素，請參閱「自訂權杖和授權碼」。

在回應中顯示或隱藏自訂屬性

請注意，如果將這項政策的 GenerateResponse 元素設為 true，回應中會傳回權杖的完整 JSON 表示法，包括您設定的任何自訂屬性。在某些情況下，您可能會想在回應中隱藏部分或所有自訂屬性，讓用戶端應用程式無法看到這些屬性。

根據預設，自訂屬性會顯示在回應中。如要隱藏這些按鈕，請將 display 參數設為 false。例如：

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

display 屬性的值不會保留。假設您產生含有自訂屬性的存取權杖，並想在產生的回應中隱藏這些屬性，設定 display=false 即可達成這個目標。不過，如果之後使用更新權杖產生新的存取權杖，更新權杖回應中就會顯示存取權杖的原始自訂屬性。這是因為 Apigee 不會記得 display 屬性最初是在產生存取權杖政策中設為 false，自訂屬性只是存取權杖中繼資料的一部分。

如果您在授權碼中加入自訂屬性，也會看到相同行為：使用該授權碼產生存取權杖時，這些自訂屬性會顯示在存取權杖回應中。同樣地，這可能不是您預期的行為。

如要在這些情況下隱藏自訂屬性，請選擇下列做法：

  • 在更新權杖政策中明確重設自訂屬性，並將顯示設定設為 false。在這種情況下，您可能需要使用 GetOAuthV2Info 政策，從原始存取權杖擷取原始自訂值。
  • 使用後續處理 JavaScript 政策，手動擷取您不想在回應中看到的任何自訂屬性。

另請參閱「自訂憑證和授權碼」。

預設

N/A

外觀狀態

選用
有效值
  • name - 屬性名稱
  • ref - 屬性的值。可來自流程變數。
  • display - (選填) 可指定自訂屬性是否顯示在回應中。如果 true，自訂屬性會顯示在回應中 (如果 GenerateResponse 也已啟用)。如果是 false，回應中就不會包含自訂屬性。預設值為 true。 請參閱「在回應中顯示或隱藏自訂屬性」。
搭配授權類型使用
  • authorization_code
  • 隱含
  • 密碼
  • client_credentials
  • refresh_token
  • 也可搭配 GenerateAuthorizationCode 作業使用。

<CacheExpiryInSeconds> 元素

<CacheExpiryInSeconds ref="propertyset.settings.token-ttl">60</CacheExpiryInSeconds>

這個元素只能搭配 VerifyAccessToken 作業使用。這項屬性會指定特定政策執行作業的存取權權杖快取存留時間 (TTL)。Apigee 首次驗證 OAuth 2 存取權杖時，必須從永久儲存空間擷取存取權杖。這項作業相對昂貴，因此 Apigee 會快取權杖查詢結果，包括權杖狀態、權杖適用的產品清單，以及附加至權杖的任何自訂屬性。在存留時間到期前，後續對 OAuthV2/VerifyAccessToken 的呼叫都會讀取記憶體內快取的結果，這表示權杖驗證速度會快上許多。

存取權杖快取的預設存留時間為 180 秒。這個元素可讓您縮短 TTL，以正確性換取效能。如果偶爾會撤銷權杖，且希望縮短 Apigee 繼續將撤銷的權杖視為有效的時間範圍，那麼這種做法就很有意義。

支援的範圍為 1 到 180 秒。您可以提供流程變數和預設值。如果您提供流程變數，且該變數含有數值，系統會優先採用該變數，而非指定的預設值。

預設

 不適用

如果省略這個元素，快取存取權杖的預設到期時間為 180 秒。

外觀狀態

 選用

類型

 整數

有效值

 任何正整數，不得為零。以秒為單位指定有效期限。
搭配作業使用
  • VerifyAccessToken

屬性

下表說明 <CacheExpiryInSeconds> 元素的屬性

屬性 說明 預設 存在必要性
ref

流程變數的參照，其中包含以秒為單位的快取到期值。

如果提供流程變數值，系統會優先採用該值，而非指定的預設值。

 不適用 選用

<ClientId> 元素

<ClientId>request.formparam.client_id</ClientId>

在某些情況下，用戶端應用程式必須將用戶端 ID 傳送至授權伺服器。這個元素指定 Apigee 應在流程變數 request.formparam.client_id 中尋找用戶端 ID。不支援將 ClientId 設為任何其他變數。另請參閱「取得 OAuth 2.0 權杖」。

預設

request.formparam.client_id (x-www-form-urlencoded，且在要求內文中指定)

外觀狀態

選用
類型 字串
有效值 流程變數：request.formparam.client_id
搭配授權類型使用
  • authorization_code
  • 密碼
  • 隱含
  • client_credentials

也可搭配 GenerateAuthorizationCode 作業使用。

<Code> 元素

<Code>request.queryparam.code</Code>

在授權授予類型流程中，用戶端必須向授權伺服器 (Apigee) 提交授權碼。這個元素可讓您指定 Apigee 應在何處尋找授權碼。舉例來說，可以做為查詢參數、HTTP 標頭或表單參數 (預設) 傳送。

變數 request.queryparam.auth_code 表示授權碼應以查詢參數的形式存在，例如 ?auth_code=AfGlvs9。如要在 HTTP 標頭中要求授權碼，請將這個值設為 request.header.auth_code。另請參閱「取得 OAuth 2.0 權杖」。

預設

request.formparam.code (x-www-form-urlencoded，且在要求內文中指定)

外觀狀態

選用
類型 字串
有效值 政策在執行階段可存取的任何流程變數
搭配授權類型使用 authorization_code

<ExpiresIn> 元素

<ExpiresIn>10000</ExpiresIn>

強制執行存取權杖和授權碼的到期時間 (以毫秒為單位)。(如果是重新整理權杖，請使用 <RefreshTokenExpiresIn>。) 到期時間值是系統產生的值加上 <ExpiresIn> 值。如未指定 <ExpiresIn>，系統會套用在系統層級設定的預設值。

您也可以在執行階段設定到期時間，方法是使用硬式編碼的預設值，或是參照流程變數。舉例來說，您可以將權杖到期值儲存在鍵值對應中、擷取該值、指派給變數，並在政策中參照該變數。例如：kvm.oauth.expires_in。

Apigee 會在存取實體後，將下列實體保留在快取中至少 180 秒。

  • OAuth 存取權杖。也就是說，OAuth v2 政策中的 ExpiresIn 元素無法在 180 秒內使存取權杖過期。
  • 金鑰管理服務 (KMS) 實體 (應用程式、開發人員、API 產品)。
  • OAuth 權杖和 KMS 實體的自訂屬性。

下列詩節也會指定流程變數和預設值。請注意，流程變數值優先於指定的預設值。

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Apigee 不支援在權杖建立後強制過期。如需強制權杖到期 (例如根據條件)，請參閱 這篇 Apigee 社群貼文，瞭解可能的解決方案。

根據預設，過期的存取權杖會在過期後 3 天，自動從 Apigee 系統中清除。另請參閱「清除存取權權杖」

預設

如未指定，系統會套用在系統層級設定的預設值。

外觀狀態

選用
類型 整數
有效值

任何正整數，不得為零。以毫秒為單位指定到期時間。雖然這個元素的值是以毫秒為單位，但權杖 expires_in 屬性和 expires_in 流程變數中設定的值是以秒為單位。
搭配授權類型使用
  • authorization_code
  • 隱含
  • 密碼
  • client_credentials
  • refresh_token

也用於 GenerateAuthorizationCode 作業。

<ExternalAccessToken> 元素

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

告知 Apigee 要從何處尋找外部存取權杖 (非由 Apigee 產生的存取權杖)。

變數 request.queryparam.external_access_token 表示外部存取權杖應以查詢參數的形式存在，例如 ?external_access_token=12345678。如要在 HTTP 標頭中要求外部存取權杖，請將這個值設為 request.header.external_access_token。另請參閱「使用第三方 OAuth 權杖」。

<ExternalAuthorization> 元素

<ExternalAuthorization>true</ExternalAuthorization>

如果這個元素為 false 或不存在，Apigee 會正常根據 Apigee 授權儲存區驗證 client_id 和 client_secret。如要使用第三方 OAuth 權杖，請使用這個元素。如要瞭解如何使用這個元素，請參閱「使用第三方 OAuth 權杖」。

預設

false

外觀狀態

選用
類型 布林值
有效值 true 或 false
搭配授權類型使用
  • authorization_code
  • 密碼
  • client_credentials

<ExternalAuthorizationCode> 元素

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

告知 Apigee 外部授權碼 (非由 Apigee 產生的授權碼) 的位置。

變數 request.queryparam.external_auth_code 表示外部授權碼應以查詢參數的形式存在，例如 ?external_auth_code=12345678。如要在 HTTP 標頭中要求外部授權碼，請將這個值設為 request.header.external_auth_code。另請參閱「使用第三方 OAuth 權杖」。

<ExternalRefreshToken> 元素

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

告知 Apigee 在何處尋找外部更新權杖 (非由 Apigee 產生的更新權杖)。

變數 request.queryparam.external_refresh_token 表示外部重新整理權杖應以查詢參數的形式存在，例如 ?external_refresh_token=12345678。如要在 HTTP 標頭中要求外部重新整理權杖，請將這個值設為 request.header.external_refresh_token。另請參閱「使用第三方 OAuth 權杖」。

<GenerateResponse> 元素

<GenerateResponse enabled='true'/>

如果設為 true 或省略 enabled 屬性，政策就會產生並傳回回應。舉例來說，如果是 GenerateAccessToken，回應可能如下所示：

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

如果設為 false 或省略 <GenerateResponse> 元素，系統就不會傳送任何回應。而是會填入與政策函式相關的一組流程變數值。舉例來說，系統會以新產生的授權碼填入名為 oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code 的流程變數。請注意，回應中的 expires_in 會以秒為單位。

預設

是

外觀狀態

選用
類型 字串
有效值 true 或 false
搭配授權類型使用
  • 隱含
  • 密碼
  • client_credentials
  • refresh_token
  • 也可搭配 GenerateAuthorizationCode 作業使用。

<GenerateErrorResponse> 元素

<GenerateErrorResponse enabled='true'/>

如果設為 true，且 ContinueOnError 屬性設為 true，政策就會產生並傳回回應。如果 false (預設值)，系統不會傳送任何回應。而是會填入與政策函式相關的一組流程變數值。

預設

false

外觀狀態

選用
類型 字串
有效值 true 或 false
搭配授權類型使用
  • 隱含
  • 密碼
  • client_credentials
  • refresh_token
  • 也可搭配 GenerateAuthorizationCode 作業使用。

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

告知政策要在要求中傳遞授權類型參數。根據 OAuth 2.0 規格，要求存取權杖和授權碼時，必須提供授權類型。變數可以是標頭、查詢參數或表單參數 (預設)。

舉例來說，request.queryparam.grant_type 表示密碼應以查詢參數的形式呈現，例如 ?grant_type=password。 如要在 HTTP 標頭中要求授權類型，請將這個值設為 request.header.grant_type。另請參閱「取得 OAuth 2.0 權杖」。

預設

request.formparam.grant_type (x-www-form-urlencoded，且在要求主體中指定)

外觀狀態

選用
類型 字串
有效值 如上所述的變數。
搭配授權類型使用
  • authorization_code
  • 密碼
  • 隱含
  • client_credentials
  • refresh_token

<Operation> 元素

<Operation>GenerateAuthorizationCode</Operation>

政策執行的 OAuth 2.0 作業。

預設

如未指定 <Operation>，Apigee 會查看 <SupportedGrantTypes> 清單。只有這些授權類型的作業才會成功。換句話說，如果您在 <SupportedGrantTypes> 清單中指定 <GrantType>，可以省略 <Operation>。如果未指定 <Operation> 或 <SupportedGrantTypes>，預設授權類型為 authorization_code。也就是說，authorization_code 授權類型要求會成功，但其他要求都會失敗。

外觀狀態

選用
類型 字串
有效值
  • GenerateAccessToken - 產生存取權杖。另請參閱「取得 OAuth 2.0 權杖」。
  • GenerateAccessTokenImplicitGrant - 產生隱含授權類型的存取權杖。另請參閱「取得 OAuth 2.0 權杖」。
  • GenerateAuthorizationCode - 生成驗證碼。使用授權碼授權類型。另請參閱「取得 OAuth 2.0 權杖」。
  • RefreshAccessToken - 使用更新權杖換取新的存取權杖。 另請參閱「取得 OAuth 2.0 權杖」。
  • VerifyAccessToken - 驗證要求中傳送的存取權杖是否有效。請參閱上方的 VerifyAccessToken 範例和「驗證存取權杖」。
  • InvalidateToken - 撤銷存取權杖。權杖遭撤銷後，用戶端就無法使用該權杖呼叫受保護的 API。另請參閱核准及撤銷存取權杖。
  • ValidateToken - 恢復或「核准」先前撤銷的存取權杖。另請參閱核准及撤銷存取權杖。

其他 JWT 存取權杖作業

如果您偏好使用 JWT 存取權杖，而非不透明的字串權杖，也可以使用下列作業產生及驗證 JWT 權杖。詳情請參閱「使用 JWT OAuth 權杖作業」：

  • GenerateJWTAccessToken - 使用已簽署的 JWT 產生存取權杖。 請參閱「產生 JWT 存取權杖」。
  • GenerateJWTAccessTokenImplicitGrant - 針對隱含授權類型，使用已簽署的 JWT 產生存取權杖。 請參閱「產生 JWT 存取權杖」。
  • VerifyJWTAccessToken - 驗證已簽署的 JWT 存取權杖。 另請參閱「驗證 JWT 存取權杖」。
  • RefreshJWTAccessToken：使用更新權杖換取新的 JWT 存取權杖。 另請參閱「重新整理 JWT 存取權杖」。

<PassWord> 元素

<PassWord>request.queryparam.password</PassWord>

這個元素只能搭配 密碼授權類型使用。使用密碼授權類型時，必須向 OAuthV2 政策提供使用者憑證 (密碼和使用者名稱)。<PassWord> 和 <UserName> 元素用於指定變數，Apigee 可在其中找到這些值。如未指定這些元素，政策會預期在名為 username 和 password 的表單參數中找到值 (預設)。如果找不到值，政策就會擲回錯誤。您可以使用 <PassWord> 和 <UserName> 元素，參照任何含有憑證的流程變數。

舉例來說，您可以使用查詢參數在權杖要求中傳遞密碼，並將 <PassWord>request.queryparam.password</PassWord> 元素設定如下：<PassWord>request.queryparam.password</PassWord>. 如要在 HTTP 標頭中要求密碼，請將這個值設為 request.header.password。

OAuthV2 政策不會對這些憑證值執行任何其他操作，Apigee 只是驗證這些值是否存在。API 開發人員必須先擷取要求值並傳送至身分識別供應商，然後才能執行權杖產生政策。

另請參閱「取得 OAuth 2.0 權杖」。

預設

request.formparam.password (x-www-form-urlencoded，且在要求內文中指定)

外觀狀態

選用
類型 字串
有效值 政策在執行階段可用的任何流程變數。
搭配授權類型使用 密碼

<PrivateKey>/<Value>

<PrivateKey>
  <Value ref="variable-name-here"/>
</PrivateKey>

提供用來以 RSA 演算法驗證或簽署 JWT 格式存取權杖的私密金鑰。 使用 ref 屬性在流程變數中傳遞金鑰。 只有在 Algorithm 元素值為 RS256、RS384 或 RS512 時才使用。詳情請參閱「使用 JWT OAuth 權杖作業」。

預設 不適用
外觀狀態 如果 Algorithm 元素值為 HS256、HS384 或 HS512，則為必要欄位。
類型 字串
有效值 包含字串的流程變數，代表 PEM 編碼的 RSA 私密金鑰值。

<PublicKey>/<Value>

<PublicKey>
   <Value ref="variable-name-here"/>
</PublicKey>

指定公開金鑰或公開憑證，用於驗證以 RSA 演算法簽署的 JWT 格式存取權權杖簽章。使用 ref 屬性在流程變數中傳遞金鑰/憑證。只有在 Algorithm 元素值為 RS256、RS384 或 RS512 時才使用。

預設 不適用
外觀狀態 如要驗證以 RSA 演算法簽署的 JWT，您必須使用 Certificate、JWKS 或 Value 元素。
類型 字串
有效值 流程變數或字串。

<RedirectUri> 元素

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

指定 Apigee 應在要求中尋找 redirect_uri 參數的位置。

關於重新導向 URI

重新導向 URI 會搭配授權碼和隱含授權類型使用。重新導向 URI 會告知授權伺服器 (Apigee) 要將授權碼 (適用於授權碼授權類型) 或存取權杖 (適用於隱含授權類型) 傳送至何處。請務必瞭解這個參數的必要性、選用性，以及使用方式：

  • (必要) 如果回呼網址已向與要求用戶端金鑰相關聯的開發人員應用程式註冊，且要求中含有 redirect_uri，則兩者必須完全相符。如果兩者不相符，系統會傳回錯誤。如要瞭解如何在 Apigee 註冊開發人員應用程式及指定回呼網址，請參閱「註冊應用程式及管理 API 金鑰」。

  • (選用) 如果已註冊回呼網址，且要求中缺少 redirect_uri，Apigee 會重新導向至已註冊的回呼網址。
  • (必要) 如果未註冊回呼網址，則必須提供 redirect_uri。請注意，在這種情況下，Apigee 會接受「任何」網址。這個案例可能會造成安全問題， 因此只能搭配信任的用戶端應用程式使用。如果用戶端應用程式不受信任，最佳做法是一律要求註冊回呼網址。

您可以在查詢參數或標頭中傳送這個參數。變數 request.queryparam.redirect_uri 表示 RedirectUri 應以查詢參數的形式存在，例如 ?redirect_uri=login.myapp.com。如要在 HTTP 標頭中要求 RedirectUri，請將這個值設為 request.header.redirect_uri。另請參閱「取得 OAuth 2.0 權杖」。

預設

request.formparam.redirect_uri (x-www-form-urlencoded，且在要求主體中指定)

外觀狀態

選用
類型 字串
有效值 可在執行階段存取政策中的任何流程變數
搭配授權類型使用
  • authorization_code
  • 隱含

也用於 GenerateAuthorizationCode 作業。

<RefreshToken> 元素

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

使用更新權杖要求存取權杖時，您必須在要求中提供更新權杖。這個元素可讓您指定 Apigee 應在何處尋找更新權杖。舉例來說，可以做為查詢參數、HTTP 標頭或表單參數 (預設) 傳送。

變數 request.queryparam.refreshtoken 表示重新整理符記應以查詢參數的形式存在，例如 ?refresh_token=login.myapp.com。如要在 HTTP 標頭中要求 RefreshToken，請將這個值設為 request.header.refresh_token。另請參閱「取得 OAuth 2.0 權杖」。

預設

request.formparam.refresh_token (x-www-form-urlencoded，且在要求內文中指定)

外觀狀態

選用
類型 字串
有效值 可在執行階段存取政策中的任何流程變數
搭配授權類型使用
  • refresh_token

<RefreshTokenExpiresIn> 元素

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

強制設定重新整理權杖的到期時間 (以毫秒為單位)。到期時間值為系統產生的值加上 <RefreshTokenExpiresIn> 值。如未指定 <RefreshTokenExpiresIn>，系統會套用預設值。

您也可以在執行階段設定到期時間，方法是使用硬式編碼的預設值，或是參照流程變數。舉例來說，您可以將權杖到期值儲存在鍵值對應中、擷取該值、指派給變數，並在政策中參照該變數。例如：kvm.oauth.expires_in。

下列詩節也會指定流程變數和預設值。請注意，流程變數值優先於指定的預設值。

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    86400000 <!--value in milliseconds-->
</RefreshTokenExpiresIn>

預設

2592000000 毫秒 (30 天) (2023 年 5 月 31 日生效)

外觀狀態

選用
類型 整數
有效值

任何正整數，不得為零。指定到期時間 (以毫秒為單位)。
搭配授權類型使用
  • authorization_code
  • 密碼
  • refresh_token

<ResponseType> 元素

<ResponseType>request.queryparam.response_type</ResponseType>

這個元素會告知 Apigee 用戶端應用程式要求的授權類型。這項參數只會用於授權碼和隱含授權類型流程。

根據預設，Apigee 會在 response_type 查詢參數中尋找回應類型值。如要覆寫這項預設行為，請使用 <ResponseType> 元素設定含有回應類型值的流程變數。舉例來說，如果您將這個元素設為 request.header.response_type，Apigee 會在要求標頭中尋找要傳遞的回應類型。另請參閱「取得 OAuth 2.0 權杖」。

預設

request.formparam.response_type (x-www-form-urlencoded，且在要求主體中指定)

外觀狀態

(選用步驟) 如要覆寫預設行為，請使用這個元素。
類型 字串
有效值 code (適用於授權碼授權類型) 或 token (適用於隱含授權類型)
搭配授權類型使用
  • 隱含
  • 也用於 GenerateAuthorizationCode 作業。

<ReuseRefreshToken> 元素

<ReuseRefreshToken>true</ReuseRefreshToken>

設為 true 時，系統會重複使用現有的更新權杖，直到權杖過期為止。如果 false，當您提供有效的更新權杖時，Apigee 會核發新的更新權杖。

預設

false

外觀狀態

選用
類型 布林值
有效值

true或false
搭配授權類型使用
  • refresh_token

<RFCCompliantRequestResponse> 元素

<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>

當 true 時，這項政策會遵守 RFC6749 標準，並啟用下列相容行為：

  • 為遵守 RFC2616 (超文字傳輸通訊協定 - HTTP/1.1)，錯誤和非錯誤回應都會包含 HTTP Cache-Control 回應標頭欄位，且任何含有權杖、憑證或其他私密資訊的回應，以及 Pragma 回應標頭欄位的值都會是 no-store，Pragma 回應標頭欄位的值則會是 no-cache。
  • expires_in 屬性為英數字元格式。為求一致性，refresh_token_expires_in 也會是英數字元。
  • 產生權杖的 OAuthV2 回應會包含符合 RFC 的 Bearer 標頭欄位，而非 BearerToken。
  • 回應酬載中的錯誤訊息格式為：{"error" : "xxx", "error_description" :"yyy"}，表示權杖重新整理錯誤。

預設

false：根據預設，這項政策允許某些不符合 RFC 的行為。 詳情請參閱「不符合 RFC 的行為」。將這個元素設為 true，即可啟用 RFC 規範。

外觀狀態

選用
類型 布林值
有效值 true或false
搭配授權類型使用 全部

<SecretKey>/<Value>

<SecretKey>
  <Value ref="your-variable-name"/>
</SecretKey>

提供用於以 HMAC 演算法驗證或簽署 JWT 格式存取權杖的密鑰。僅在演算法為 HS256、HS384 或 HS512 時使用。使用 ref 屬性在流程變數中傳遞金鑰。詳情請參閱「使用 JWT OAuth 權杖作業」。

Apigee 會針對 HS256/HS384/HS512 演算法強制執行最低金鑰強度。HS256 的金鑰長度下限為 32 個位元組，HS384 為 48 個位元組，HS512 則為 64 個位元組。使用強度較低的金鑰會導致執行階段錯誤。

預設 不適用
外觀狀態 HMAC 演算法需要這項資訊。
類型 字串
有效值 流程變數

<Scope> 元素

<Scope>request.queryparam.scope</Scope>

如果 GenerateAccessToken 或 GenerateAuthorizationCode 政策中存在這個元素，系統會使用該元素指定要授予權杖或授權碼的範圍。這些值通常會從用戶端應用程式的要求傳遞至政策。您可以設定元素來取得流程變數，選擇在要求中傳遞範圍的方式。在以下範例中，request.queryparam.scope 表示範圍應以查詢參數的形式呈現，例如 ?scope=READ。如要在 HTTP 標頭中要求範圍，請將這個值設為 request.header.scope。

如果這個元素出現在「VerifyAccessToken」政策中，則用於指定政策應強制執行的範圍。在這類政策中，值必須是「硬式編碼」範圍名稱，您無法使用變數。例如：

<Scope>A B</Scope>

另請參閱「使用 OAuth2 範圍」和「取得 OAuth 2.0 權杖」。

預設

沒有範圍

外觀狀態

選用
類型 字串
有效值

如果搭配 Generate* 政策使用，則為流程變數。

如果與 VerifyAccessToken 一併使用，則為以空格分隔的範圍名稱清單 (字串)。
搭配授權類型使用
  • authorization_code
  • 隱含
  • 密碼
  • client_credentials
  • 也可以搭配 GenerateAuthorizationCode 和 VerifyAccessToken 作業使用。

<State> 元素

<State>request.queryparam.state</State>

如果用戶端應用程式必須將狀態資訊傳送至授權伺服器，您可以使用這個元素指定 Apigee 應在何處尋找狀態值。舉例來說，可以做為查詢參數或在 HTTP 標頭中傳送。狀態值通常會做為安全措施，防止 CSRF 攻擊。

舉例來說，request.queryparam.state 表示狀態應以查詢參數的形式呈現，例如 ?state=HjoiuKJH32。如要在 HTTP 標頭中要求狀態，請將這個值設為 request.header.state。另請參閱「取得 OAuth 2.0 權杖」。

預設

沒有任何狀態

外觀狀態

選用
類型 字串
有效值 政策在執行階段可存取的任何流程變數
搭配授權類型使用
  • 全部
  • 也可以搭配 GenerateAuthorizationCode 作業使用

<StoreToken> 元素

 <StoreToken>true</StoreToken>

當 <ExternalAuthorization> 元素為 true 時，將這個元素設為 true。<StoreToken> 元素會告知 Apigee 儲存外部存取權杖。否則系統不會保留該值。

預設

false

外觀狀態

選用
類型 布林值
有效值 true 或 false
搭配授權類型使用
  • authorization_code
  • 密碼
  • client_credentials

<SupportedGrantTypes>/<GrantType> 元素

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

指定 Apigee 上 OAuth 權杖端點支援的授權類型。端點可能支援多種授權類型 (也就是說，您可以將單一端點設為針對多種授權類型發布存取權杖)。如要進一步瞭解端點，請參閱「瞭解 OAuth 端點」。授權類型會透過 grant_type 參數傳遞至權杖要求。

如果未指定任何支援的授權類型，則只允許 authorization_code 和 implicit 授權類型。另請參閱 <GrantType> 元素 (這個較高層級的元素用於指定 Apigee 應在何處尋找用戶端要求中傳遞的 grant_type 參數。Apigee 會確保 grant_type 參數的值符合其中一種支援的授權類型。

預設

授權碼和隱含

外觀狀態

必填
類型 字串
有效值
  • client_credentials
  • authorization_code
  • 密碼
  • 隱含

<Tokens> 元素/<Token> 元素

與 ValidateToken 和 InvalidateToken 作業搭配使用。另請參閱核准及撤銷存取權杖。<Token> 元素會識別定義要撤銷權杖來源的流程變數。如果開發人員應提交存取權杖做為名為 access_token 的查詢參數，請使用 request.queryparam.access_token。

<UserName> 元素

<UserName>request.queryparam.user_name</UserName>

這個元素只能搭配 密碼授權類型使用。使用密碼授權類型時，必須向 OAuthV2 政策提供使用者憑證 (密碼和使用者名稱)。<PassWord> 和 <UserName> 元素用於指定變數，Apigee 可在其中找到這些值。如未指定這些元素，政策會預期在名為 username 和 password 的表單參數中找到值 (預設)。如果找不到值，政策就會擲回錯誤。您可以使用 <PassWord> 和 <UserName> 元素，參照任何含有憑證的流程變數。

舉例來說，您可以在查詢參數中傳遞使用者名稱，並將 <UserName> 元素設為如下：<UserName>request.queryparam.username</UserName>.如要在 HTTP 標頭中要求使用者名稱，請將這個值設為 request.header.username。

OAuthV2 政策不會對這些憑證值執行任何其他操作，Apigee 只是驗證這些值是否存在。API 開發人員必須先擷取要求值並傳送至身分識別供應商，然後才能執行權杖產生政策。

另請參閱「取得 OAuth 2.0 權杖」。

預設

request.formparam.username (x-www-form-urlencoded，且在要求主體中指定)

外觀狀態

選用
類型 字串
有效值 任何變數設定。
搭配授權類型使用 密碼

驗證存取權杖

為 API Proxy 設定權杖端點後，系統會將指定 VerifyAccessToken 作業的對應 OAuthV2 政策，附加至公開受保護資源的 Flow。

舉例來說，如要確保所有 API 要求都經過授權，下列政策會強制執行存取權杖驗證：

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

這項政策會附加至要保護的 API 資源。如要確保所有 API 要求都經過驗證，請將政策附加至 ProxyEndpoint 要求 PreFlow，如下所示：

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

下列選用元素可用於覆寫 VerifyAccessToken 作業的預設設定。

名稱 說明
範圍

以空格分隔的範圍清單。如果存取權杖中至少有一個所列範圍，驗證就會成功。舉例來說，下列政策會檢查存取權杖，確保權杖至少包含列出的其中一個範圍。如果存在 READ 或 WRITE，驗證就會成功。

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>
AccessToken 預期存取權杖所在位置的變數。例如 request.queryparam.accesstoken。根據預設，應用程式應根據 OAuth 2.0 規格，在 Authorization HTTP 標頭中提供存取權杖。如果存取權杖預計會出現在非標準位置 (例如查詢參數)，或名稱不是 Authorization 的 HTTP 標頭，請使用這項設定。

另請參閱「驗證存取權杖」和「取得 OAuth 2.0 權杖」。

指定要求變數位置

對於每種授權類型，政策都會對要求訊息中的位置或必要資訊做出假設。這些假設是根據 OAuth 2.0 規格而來。如果應用程式需要偏離 OAuth 2.0 規格，您可以為每個參數指定預期位置。舉例來說，處理授權碼時，您可以指定授權碼、用戶端 ID、重新導向 URI 和範圍的位置。這些參數可以指定為 HTTP 標頭、查詢參數或表單參數。

以下範例說明如何將必要授權碼參數指定為 HTTP 標頭：

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

或者，如果需要支援用戶端應用程式，可以混用標頭和查詢參數：

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

每個參數只能設定一個位置。

流程變數

執行對應的 OAuth 政策時，系統會填入這個表格中定義的流程變數，因此 API Proxy 流程中執行的其他政策或應用程式可以使用這些變數。

VerifyAccessToken 作業

執行 VerifyAccessToken 作業時，系統會在 Proxy 的執行環境中填入大量流程變數。這些變數會提供與存取權杖、開發人員應用程式和開發人員相關的屬性。舉例來說，您可以使用 AssignMessage 或 JavaScript 政策讀取任何這類變數，並在流程中視需要使用。這些變數也可用於偵錯。

權杖專屬變數

變數 說明
organization_name 執行 Proxy 的機構名稱。
developer.id 與已註冊的用戶端應用程式相關聯的開發人員或AppGroup ID。
developer.app.name 與已註冊的用戶端應用程式相關聯的開發人員或AppGroup應用程式名稱。
client_id 已註冊用戶端應用程式的用戶端 ID。
grant_type 與要求相關聯的授權類型。不支援 VerifyJWTAccessToken 作業。
token_type 與要求相關聯的權杖類型。
access_token 要驗證的存取權杖。
accesstoken.{custom_attribute} 存取權杖中的具名自訂屬性。
issued_at 存取權杖的核發日期，以 Unix 紀元時間表示 (以毫秒為單位)。
expires_in 存取權杖的到期時間，以秒為單位。雖然 ExpiresIn 元素會以毫秒為單位設定到期時間，但在權杖回應和流程變數中，值是以秒為單位表示。
status 存取權杖的狀態 (例如已核准或已撤銷)。
scope 與存取權杖相關聯的範圍 (如有)。
apiproduct.<custom_attribute_name> 與已註冊的用戶端應用程式相關聯的 API 產品具名自訂屬性。
apiproduct.name 與已註冊用戶端應用程式相關聯的 API 產品名稱。
revoke_reason

(僅限 Apigee Hybrid) 說明存取權杖遭撤銷的原因。不支援 VerifyJWTAccessToken 作業。

值可以是 REVOKED_BY_APP、REVOKED_BY_ENDUSER、REVOKED_BY_APP_ENDUSER 或 TOKEN_REVOKED。

應用程式專屬變數

這些變數與權杖相關聯的開發人員應用程式有關。

變數 說明
app.name
app.id
app.accessType
app.callbackUrl
app.status 已核准或已撤銷
app.scopes
app.appFamily
app.apiproducts
app.appParentStatus
app.appType 例如：開發人員
app.appParentId
app.created_by
app.created_at
app.last_modified_at
app.last_modified_by
app.{custom_attributes} 已註冊用戶端應用程式的具名自訂屬性。

AppGroup 專屬變數

下列流程變數包含權杖的 AppGroup 相關資訊，並由政策填入。只有在 verifyapikey.{policy_name}.app.appType 為「AppGroup」時，系統才會填入這些 AppGroup 屬性。

變數 說明
appgroup.displayName AppGroup 顯示名稱。
appgroup.name AppGroup 的名稱。
appgroup.id 應用程式群組 ID。
appOwnerStatus 應用程式擁有者的狀態：「active」、「inactive」或「login_lock」。
created_at 建立 AppGroup 的日期/時間戳記。
created_by 建立 AppGroup 的開發人員電子郵件地址。
last_modified_at 上次修改 AppGroup 的日期/時間戳記。
last_modified_by 上次修改 AppGroup 的開發人員電子郵件地址。
{appgroup_custom_attributes} 任何自訂 AppGroup 屬性。指定自訂屬性的名稱。

開發人員專用變數

如果 app.appType 為「開發人員」，系統就會填入開發人員屬性。

變數 說明
開發人員專用變數
developer.id
developer.userName
developer.firstName
developer.lastName
developer.email
developer.status 有效或無效
developer.apps
developer.created_by
developer.created_at
developer.last_modified_at
developer.last_modified_by
developer.{custom_attributes} 開發人員的具名自訂屬性。

GenerateAuthorizationCode 作業

這些變數會在 GenerateAuthorizationCode 作業成功執行時設定：

前置字串： oauthv2authcode.{policy_name}.{variable_name}

示例：oauthv2authcode.GenerateCodePolicy.code

變數 說明
code 政策執行時產生的授權碼。
redirect_uri 與已註冊的用戶端應用程式相關聯的重新導向 URI。
scope 用戶端要求中傳遞的選用 OAuth 範圍。
client_id 在用戶端要求中傳遞的用戶端 ID。

GenerateAccessToken 和 RefreshAccessToken 作業

系統會在 GenerateAccessToken 和 RefreshAccessToken 作業成功執行時設定這些變數。請注意，重新整理權杖變數不適用於用戶端憑證授權類型流程。

前置字串： oauthv2accesstoken.{policy_name}.{variable_name}

示例：oauthv2accesstoken.GenerateTokenPolicy.access_token

變數名稱 說明
access_token 系統產生的存取權杖。
client_id 與這個權杖相關聯的開發人員應用程式用戶端 ID。
expires_in 權杖的到期值。詳情請參閱 <ExpiresIn> 元素。請注意，在回應中，expires_in 會以秒為單位表示。
scope 為權杖設定的可用範圍清單。請參閱「使用 OAuth2 範圍」。
status approved 或 revoked。
token_type 設為 BearerToken。
developer.email 與權杖相關聯的開發人員應用程式所屬註冊開發人員的電子郵件地址。
organization_name Proxy 執行的機構。
api_product_list 與權杖對應開發人員應用程式相關聯的產品清單。
refresh_count
refresh_token 系統產生的更新權杖。請注意，系統不會為用戶端憑證授權類型產生重新整理權杖。
refresh_token_expires_in 重新整理權杖的生命週期 (以秒為單位)。
refresh_token_issued_at 這個時間值是相應 32 位元時間戳記量的字串表示法。舉例來說，「Wed, 21 Aug 2013 19:16:47 UTC」對應的時間戳記值為 1377112607413。
refresh_token_status approved 或 revoked。

GenerateAccessTokenImplicitGrant

當隱含授權類型流程的 GenerateAccessTokenImplicit 作業成功執行時，系統會設定這些變數。

前置字串： oauthv2accesstoken.{policy_name}.{variable_name}

示例：oauthv2accesstoken.RefreshTokenPolicy.access_token

變數 說明
oauthv2accesstoken.access_token 政策執行時產生的存取權杖。
oauthv2accesstoken.{policy_name}.expires_in 權杖的到期值 (以秒為單位)。詳情請參閱 <ExpiresIn> 元素。

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

錯誤代碼 HTTP 狀態 原因 由作業擲回
steps.oauth.v2.access_token_expired 401 存取權杖已過期。

VerifyAccessToken
InvalidateToken
steps.oauth.v2.access_token_not_approved 401 已撤銷存取權杖。 VerifyAccessToken
steps.oauth.v2.apiproduct_doesnot_exist 401 要求的 API 產品不在與存取權杖相關聯的任何 API 產品中。 VerifyAccessToken
steps.oauth.v2.FailedToResolveAccessToken 500 政策預期在 <AccessToken> 元素中指定的變數中找到存取權存證，但無法解析該變數。 GenerateAccessToken
steps.oauth.v2.FailedToResolveAuthorizationCode 500 政策預期會在 <Code> 元素中指定的變數中找到授權碼，但無法解析該變數。 GenerateAuthorizationCode
steps.oauth.v2.FailedToResolveClientId 500 政策預期會在 <ClientId> 元素中指定的變數中找到用戶端 ID，但無法解析該變數。 GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.FailedToResolveRefreshToken 500 政策預期會在 <RefreshToken> 元素中指定的變數中找到重新整理權杖，但無法解析該變數。 RefreshAccessToken
steps.oauth.v2.FailedToResolveToken 500 政策預期會在 <Tokens> 元素中指定的變數中找到符記，但無法解析該變數。

ValidateToken
InvalidateToken
steps.oauth.v2.InsufficientScope 403 要求中提供的存取權權杖範圍與驗證存取權權杖政策中指定的範圍不符。如要瞭解範圍，請參閱「使用 OAuth2 範圍」。 VerifyAccessToken
steps.oauth.v2.invalid_client 401

當政策的 <GenerateResponse> 屬性設為 true，且要求中傳送的用戶端 ID 無效時，系統會傳回這個錯誤名稱。請確認您為與 Proxy 相關聯的開發人員應用程式使用正確的用戶端金鑰和密鑰值。通常，這些值會以 Base64 編碼的 Basic Authorization 標頭傳送。

 GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.InvalidRequest 400 這個錯誤名稱用於多種不同類型的錯誤，通常是指在要求中傳送的參數遺漏或錯誤。如果 <GenerateResponse> 設為 false，請使用錯誤變數 (如下所述) 擷取錯誤的詳細資料，例如錯誤名稱和原因。 GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.InvalidAccessToken 401 授權標頭中沒有 Bearer 字詞，但這是必要的。例如：Authorization: Bearer your_access_token VerifyAccessToken
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401

目前執行的 API 代理程式或作業不在與存取權杖相關聯的產品中。

提示：請確認與存取權杖相關聯的產品已正確設定。舉例來說，如果您在資源路徑中使用萬用字元，請確認萬用字元使用正確。詳情請參閱「 管理 API 產品」。

如需有關此錯誤原因的更多指引，請參閱 OAuth 2.0 存取權憑證驗證會擲回「找不到相符的 API 產品，因此 API 呼叫無效」錯誤訊息。

 VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier 500

如果政策的 <GenerateResponse> 屬性設為 false，且要求中傳送的用戶端 ID 無效，系統就會傳回這個錯誤名稱。請確認您為與 Proxy 相關聯的開發人員應用程式使用正確的用戶端金鑰和密鑰值。通常，這些值會以 Base64 編碼的 Basic Authorization 標頭傳送。

GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.InvalidParameter 500 政策必須指定存取權存證或授權碼，但不能同時指定兩者。 GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.InvalidTokenType 500 <Tokens>/<Token> 元素需要您指定符記類型 (例如 refreshtoken)。如果用戶端傳遞的類型有誤，系統就會擲回這個錯誤。 ValidateToken
InvalidateToken
steps.oauth.v2.MissingParameter 500 回應類型為 token，但未指定授權類型。 GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.UnSupportedGrantType 500

用戶端指定的授權類型不受政策支援 (未列於 <SupportedGrantTypes> 元素中)。

 GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken

JWT 權杖專屬的執行階段錯誤

JWT 驗證權杖流程的執行階段錯誤代碼和說明取決於 OAuth2 流程內容：

JWT 權杖產生和重新整理流程的錯誤代碼

對於產生或更新 JWT 權杖的 OAuth2 流程，錯誤回應會遵循 RFC6749 中指定的錯誤回應。詳情請參閱「第 5.2 節：錯誤回應」。

權杖驗證流程的錯誤代碼

下表列出的錯誤代碼僅適用於 VerifyAccessToken 作業。

錯誤代碼 HTTP 狀態 原因 由作業擲回
oauth.v2.JWTSigningFailed 401 政策無法為 JWT 簽署。

GenerateJWTAccessToken
oauth.v2.InvalidValueForJWTAlgorithm 401 當 JWT 存取權杖中沒有演算法，或系統不支援該值時，就會發生這種情況。

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.InsufficientKeyLength 401 在產生 JWT 時，如果金鑰小於 HS384 或 HS512 演算法的最小大小

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.JWTAlgorithmMismatch 401 產生政策中指定的演算法與驗證政策中預期的演算法不符。指定的演算法必須相符。

VerifyJWTAccessToken
oauth.v2.JWTDecodingFailed 401 政策無法解碼 JWT。JWT 可能已損毀。

VerifyJWTAccessToken
oauth.v2.MissingMandatoryClaimsInJWT 401 當 Jwt 存取權杖中未提供必要的聲明時，就會發生

VerifyJWTAccessToken
oauth.v2.InvalidJWTSignature 401 當無法驗證 JWT 存取權杖的簽名，或簽名無效時，就會發生這種情況。

VerifyJWTAccessToken
oauth.v2.InvalidTypeInJWTHeader 401 當 JWT 類型不是 at+Jwt 時，就會發生

VerifyJWTAccessToken

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱 原因
InvalidValueForExpiresIn

對於 <ExpiresIn> 元素，有效值為正整數。
InvalidValueForRefreshTokenExpiresIn 對於 <RefreshTokenExpiresIn> 元素，有效值為正整數。
InvalidGrantType <SupportedGrantTypes> 元素中指定了無效的授權類型。如需有效類型的清單，請參閱政策參考資料。
ExpiresInNotApplicableForOperation 請確認 <Operations> 元素中指定的作業支援到期日。例如，VerifyToken 運算不會。
RefreshTokenExpiresInNotApplicableForOperation 請確認 <Operations> 元素中指定的作業支援權杖到期日更新功能。例如，VerifyToken 作業就沒有。
GrantTypesNotApplicableForOperation 請確認 <SupportedGrantTypes> 中指定的授權類型支援指定的作業。
OperationRequired

您必須使用 <Operation> 元素，在這項政策中指定作業。
InvalidOperation

您必須使用 <Operation> 元素，在這個政策中指定有效的作業。
TokenValueRequired 您必須在 <Tokens> 元素中指定符記 <Token> 值。

JWT 權杖專屬部署錯誤

這些部署錯誤僅適用於使用 JWT 權杖運算的政策。

錯誤名稱 原因
InvalidValueForAlgorithm <Algorithm> 元素中指定的演算法不在可用演算法清單中，或不存在。
MissingKeyConfiguration 缺少必要的 <SecretKey>、<PrivateKey> 或 <PublicKey> 元素，具體取決於使用的演算法。
EmptyValueElementForKeyConfiguration 必要的子元素 <Value> 未在 <PrivateKey>、<PublicKey> 或 <SecretKey> 元素中定義
InvalidKeyConfiguration <PrivateKey> 元素未與 RSA 家族演算法搭配使用，或 <SecretKey> 元素未與 HS 家族演算法搭配使用。
EmptyRefAttributeForKeyconfiguration <PrivateKey>、<PublicKey> 或 <SecretKey> 元素的子元素 <Value> 的 ref 屬性為空白。
InvalidVariableNameForKey <PrivateKey>、<PublicKey> 或 <SecretKey> 元素子項元素 <Value> 的 ref 屬性中指定的流程變數名稱不含 private 前置字元。

錯誤變數

當這項政策在執行階段觸發錯誤時，系統就會設定這些變數。

變數 地點 範例
fault.name="fault_name" fault_name 是錯誤名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤代碼的最後一個部分。 fault.name = "InvalidRequest"
oauthV2.policy_name.failed policy_name 是擲回錯誤的政策的使用者指定名稱。 oauthV2.GenerateAccesstoken.failed = true
oauthV2.policy_name.fault.name policy_name 是擲回錯誤的政策的使用者指定名稱。 oauthV2.GenerateAccesstoken.fault.name = InvalidRequest
oauthV2.policy_name.fault.cause policy_name 是擲回錯誤的政策的使用者指定名稱。 oauthV2.GenerateAccesstoken.cause = Required param : grant_type

錯誤回應範例

如果 <GenerateResponse> 元素為 true，這些回應會傳回給用戶端。

如果 <GenerateResponse> 為 true，則政策會針對產生符記和代碼的作業，以此格式傳回錯誤。如需完整清單，請參閱 OAuth HTTP 錯誤回應參考資料。

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

如果 <GenerateResponse> 為 true，政策會以此格式傳回錯誤，用於驗證和驗證作業。如需完整清單，請參閱 OAuth HTTP 錯誤回應參考資料。

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

錯誤規則範例

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

儲存空間中的權杖經過雜湊處理

如果您使用 Apigee Hybrid 或 Apigee，系統預設會將 OAuthV2 存取權杖和重新整理權杖雜湊處理，然後儲存在執行階段 Cassandra 資料庫。如果資料庫遭盜用，雜湊可防止權杖遭到使用。

使用預設 OAuth 設定

Apigee 上的每個機構 (包括免費試用機構) 都會佈建 OAuth 權杖端點。端點已在名為 oauth 的 API Proxy 中預先設定政策。在 Apigee 上建立帳戶後，即可開始使用權杖端點。詳情請參閱「瞭解 OAuth 端點」。

清除存取權杖

根據預設，存取權杖和更新權杖 (如有) 過期後，OAuth2 權杖會在 3 天 (259200 秒) 內從 Apigee 系統清除。

不符合 RFC 規範的行為

根據預設，OAuthV2 政策 (搭配 GenerateAccessToken 作業) 會傳回權杖回應，其中包含特定不符合 RFC 規範的屬性。下表列出 OAuthV2 政策傳回的不符規定屬性，以及對應的符合規定屬性。

OAuthV2 會傳回： 符合 RFC 的屬性為：
"token_type":"BearerToken" "token_type":"Bearer"
"expires_in":"3600" "expires_in":3600

(符合規定的值是數字，而非字串)。

此外，如果 grant_type = refresh_token 是：

{"ErrorCode" : "InvalidRequest", "Error" :"Refresh Token expired"}

不過，符合 RFC 規範的回應如下： 

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

相關主題