本頁面由 Cloud Translation API 翻譯而成。

OAuthV2 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

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

注意：OAuthV2 政策會傳回某些不符合 RFC 規定的回應元素。舉例來說，政策會傳回權杖屬性 "token_type":"BearerToken"，其中符合規定的權杖屬性為 "token_type":"Bearer"。如要進一步瞭解這些不符規定的回應元素，請參閱「不符合 RFC 規範的行為」一節。

提示：如要進一步瞭解 Apigee Edge 的 OAuth，請參閱 OAuth 首頁。並提供資源、範例、影片等內容的連結。如要瞭解如何在實際運作的應用程式中使用這項政策，請參閱 GitHub 上的進階 OAuth 範例。

範例

VerifyAccessToken

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

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

注意：僅支援 OAuth 2.0 不記名憑證。不支援訊息鑑別碼 (MAC) 權杖。

例如：

$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

根據預設，Edge 會接受 Authorization 標頭中的存取權杖，並加上 Bearer 前置字元。你可以使用 <AccessToken> 元素變更這項預設值。

GenerateAccessToken

產生存取權杖

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

GenerateAuthorizationCode

產生授權碼

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

RefreshAccessToken

重新整理存取權杖

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

回覆流程權杖

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

有時您可能需要在回應流程中產生存取權杖。舉例來說，您可能會在後端服務中完成某些自訂驗證後，執行這項操作。在本範例中，用途需要存取權杖和更新權杖，因此排除隱含授權類型。在本例中，我們會使用密碼授權類型產生權杖。如您所見，讓這項功能運作的訣竅是傳遞含有 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 client_id = context.getVariable("local_clientid");
var client_secret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(client_id + ':' + client_secret)));

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

元素參考資料

政策參考資料說明 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>` 元素，為政策加上標籤：管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。	不適用	必填
`continueOnError`	如果設為「`false`」，系統會在政策失敗時傳回錯誤。這是可預期的情況大多數政策的行為如果設為 `true`，即使政策已發生，流程執行作業仍會繼續執行失敗。	false	選用
`enabled`	如要強制執行政策，請設為 `true`。設為 `false` 即可停用政策。這項政策不會仍會強制執行政策。	true	選用
`async`	此屬性已淘汰。	false	已淘汰

<DisplayName>元素

除 name 屬性外，一併使用管理 UI Proxy 編輯器，使用不同的自然語言名稱。

<DisplayName>Policy Display Name</DisplayName>

預設

預設	不適用如果省略這個元素，政策的 `name` 屬性值會是
存在必要性	選用
類型	字串

不適用

如果省略這個元素，政策的 name 屬性值會是

存在必要性選用

類型字串

<AccessToken> 元素

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

根據預設，VerifyAccessToken 會預期存取權杖會透過 Authorization 標頭傳送。您可以使用這個元素變更預設值。舉例來說，request.queryparam.access_token 表示存取權杖應以名為 access_token 的查詢參數形式呈現。

指定 <AccessToken>request.header.access_token</AccessToken> 的範例：

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

指定 <AccessToken>request.queryparam.access_token</AccessToken> 的範例：

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

預設值：	不適用
外觀狀態：	選用
類型：	字串
搭配作業使用：	VerifyAccessToken

<AccessTokenPrefix> 元素

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

根據預設，VerifyAccessToken 會預期存取權杖以不記名權杖的形式，在授權標頭中傳送。例如：

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

目前僅支援 Bearer 前置字元。

預設值：	Bearer
外觀狀態：	選用
類型：	字串
有效值：	Bearer
搭配作業使用：	VerifyAccessToken

<AppEndUser> 元素

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

如果必須將應用程式使用者 ID 傳送至授權伺服器，這個元素可讓您指定 Edge 應從何處尋找使用者 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 即可達成這個目標。不過，如果之後使用更新權杖產生新的存取權杖，更新權杖回應中就會顯示存取權杖的原始自訂屬性。這是因為 Edge 不會記得 display 屬性原本在產生存取權杖政策中設為 false，自訂屬性只是存取權杖中繼資料的一部分。

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

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

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

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

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

<ClientId> 元素

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

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

預設值：	request.formparam.client_id (x-www-form-urlencoded，且在要求主體中指定)
外觀狀態：	選用
類型：	字串
有效值：	流程變數：`request.formparam.client_id`
適用於下列授權類型：	authorization_code 密碼隱含 client_credentials 也可搭配 GenerateAuthorizationCode 作業使用。

<Code> 元素

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

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

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

預設值：	request.formparam.code (x-www-form-urlencoded，且在要求內文中指定)
外觀狀態：	選用
類型：	字串
有效值：	政策在執行階段可存取的任何流程變數
適用於下列授權類型：	authorization_code

<ExpiresIn> 元素

<ExpiresIn>10000</ExpiresIn>

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

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

使用 Apigee Edge for Public Cloud 時，Edge 會在實體存取後，將下列實體保留在快取中至少 180 秒。

OAuth 存取權杖。也就是說，遭撤銷的權杖在快取限制到期前，最多仍可成功使用三分鐘。
金鑰管理服務 (KMS) 實體 (應用程式、開發人員、API 產品)。
OAuth 權杖和 KMS 實體的自訂屬性。

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

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

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

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

Private Cloud：如果是 Edge for Private Cloud 安裝作業，預設值是由 conf_keymanagement_oauth_auth_code_expiry_time_in_millis 屬性設定。如要設定這項屬性，請按照下列步驟操作：

在編輯器中開啟 message-processor.properties 檔案。如果檔案不存在，請建立檔案：
```
vi /opt/apigee/customer/application/message-processor.properties
```

視需要設定屬性：

conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

確認屬性檔案的擁有者是「apigee」使用者：

chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

重新啟動訊息處理器。

/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

預設值：	如未指定，系統會套用系統層級設定的預設值。
外觀狀態：	選用
類型：	整數
有效值：	任何正整數，不得為零。以毫秒為單位指定到期時間。雖然這個元素的值是以毫秒為單位，但權杖 `expires_in` 屬性和 `expires_in` 流程變數中設定的值是以秒為單位。 -1 會根據最長 OAuth 存取權杖到期時間到期。注意：指定任何其他負整數或零都會導致部署錯誤。另請參閱「反模式：為 OAuth 憑證設定較長的到期時間」。
適用於下列授權類型：	authorization_code 隱含密碼 client_credentials refresh_token 也用於 GenerateAuthorizationCode 作業。

注意：請注意，如果將 ExpiresIn 設為 -1，產生的權杖中會顯示下列到期值：

"expires_in" :
  "0"

。

<ExternalAccessToken> 元素

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

告知 Apigee Edge 外部存取權杖 (非由 Apigee Edge 產生的存取權杖) 的位置。

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

<ExternalAuthorization> 元素

<ExternalAuthorization>true</ExternalAuthorization>

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

預設值：	false
外觀狀態：	選用
類型：	布林值
有效值：	true 或 false
適用於下列授權類型：	authorization_code 密碼 client_credentials

<ExternalAuthorizationCode> 元素

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

告知 Apigee Edge 要從何處尋找外部授權碼 (非由 Apigee Edge 產生的授權碼)。

變數 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 Edge 要從何處尋找外部更新權杖 (非由 Apigee Edge 產生的更新權杖)。

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

<GenerateResponse> 元素

<GenerateResponse enabled='true'/>

如果設為 true，政策會生成並傳回回應。舉例來說，如果是 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，系統不會傳送任何回覆。而是會填入一組與政策功能相關的值。舉例來說，系統會以新產生的授權碼填入名為 oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code 的流程變數。請注意，回應中的 expires_in 是以秒為單位。

預設值：	false
外觀狀態：	選用
類型：	字串
有效值：	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。另請參閱「要求存取權杖和授權碼」。

預設值：	request.formparam.grant_type (x-www-form-urlencoded，且在要求主體中指定)
外觀狀態：	選用
類型：	字串
有效值：	如上所述的變數。
適用於下列授權類型：	authorization_code 密碼隱含 client_credentials refresh_token

<Operation> 元素

<Operation>GenerateAuthorizationCode</Operation>

政策執行的 OAuth 2.0 作業。

預設值：	如果未指定 `<Operation>`，Edge 會查看 `<SupportedGrantTypes>` 清單。只有這些授權類型的作業才會成功。換句話說，如果您在 `<SupportedGrantTypes>` 清單中指定 `<GrantType>`，可以省略 `<Operation>`。如果未指定 `<Operation>` 或 `<SupportedGrantTypes>`，預設授權類型為 authorization_code。也就是說，authorization_code 授權類型要求會成功，但其他要求都會失敗。
外觀狀態：	選用
類型：	字串
有效值：	`GenerateAccessToken` - 產生存取權杖。另請參閱「要求存取權杖和授權碼」。 `GenerateAccessTokenImplicitGrant` - 產生隱含授權類型的存取權杖。另請參閱「要求存取權杖和授權碼」。 `GenerateAuthorizationCode` - 生成驗證碼。使用授權碼授權類型。另請參閱「要求存取權杖和授權碼」。 `RefreshAccessToken` - 使用更新權杖換取新的存取權杖。另請參閱要求存取權杖和授權碼。 `VerifyAccessToken` - 驗證要求中傳送的存取權杖是否有效。請參閱上方的 VerifyAccessToken 範例和「驗證存取權杖」。 `InvalidateToken` - 撤銷存取權杖。權杖遭撤銷後，用戶端就無法使用該權杖呼叫受保護的 API。另請參閱核准及撤銷存取權杖。 `ValidateToken` - 恢復或「核准」先前撤銷的存取權杖。另請參閱核准及撤銷存取權杖。

<PassWord> 元素

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

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

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

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

另請參閱「要求存取權杖和授權碼」。

預設值：	request.formparam.password (x-www-form-urlencoded，且在要求內文中指定)
外觀狀態：	選用
類型：	字串
有效值：	政策在執行階段可用的任何流程變數。
適用於下列授權類型：	密碼

<RedirectUri> 元素

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

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

關於重新導向 URI

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

(必要) 如果回呼網址已向與要求用戶端金鑰相關聯的開發人員應用程式註冊，且要求中含有 redirect_uri，則兩者必須完全相符。如果兩者不相符，系統會傳回錯誤。如要瞭解如何在 Edge 註冊開發人員應用程式及指定回呼網址，請參閱「註冊應用程式及管理 API 金鑰」。
注意：為確保 Edge 會檢查「回呼網址」和「redirect_uri」是否完全相符 (而非前向相符)，請在貴機構中設定下列屬性：features.isStrictOAuthUriValidation = true。預設值為 false (正向比對)。
如果您是雲端客戶，請與 Apigee Edge 支援團隊聯絡，啟用這項屬性。如果您是 Apigee Edge for Private Cloud 客戶，請使用系統管理員憑證，透過下列 API PUT 呼叫設定標記。
```
curl -u email:password -X PUT -H "Content-type:application/xml" http://host:port/v1/o/{myorg} -d \
"<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isStrictOAuthUriValidation">true</Property>
        
    </Properties>
</Organization>"
```
警告：使用 API 呼叫更新機構時，請務必在酬載中加入所有現有的機構屬性。否則，系統會只使用您透過這次呼叫設定的屬性，覆寫所有現有的機構屬性。
(選用) 如果已註冊回呼網址，且要求中缺少 redirect_uri，Edge 會重新導向至已註冊的回呼網址。
(必要) 如果未註冊回呼網址，則必須提供 redirect_uri。請注意，在這種情況下，Edge 會接受任何網址。這個案例可能會造成安全問題， 因此只能搭配信任的用戶端應用程式使用。如果用戶端應用程式不受信任，最佳做法是一律要求註冊回呼網址。

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

預設值：	request.formparam.redirect_uri (x-www-form-urlencoded，且在要求主體中指定)
外觀狀態：	選用
類型：	字串
有效值：	可在執行階段存取政策中的任何流程變數
適用於下列授權類型：	authorization_code 隱含也用於 GenerateAuthorizationCode 作業。

<RefreshToken> 元素

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

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

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

預設值：	request.formparam.refresh_token (x-www-form-urlencoded，且在要求主體中指定)
外觀狀態：	選用
類型：	字串
有效值：	可在執行階段存取政策中的任何流程變數
適用於下列授權類型：	refresh_token

<RefreshTokenExpiresIn> 元素

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

強制設定重新整理權杖的到期時間 (以毫秒為單位)。到期時間值是系統產生的值加上 <RefreshTokenExpiresIn> 值。如果 <RefreshTokenExpiresIn> 設為 -1，更新權杖會根據OAuth 更新權杖最長到期時間到期。如未指定 <RefreshTokenExpiresIn>，系統會套用系統層級設定的預設值。如要進一步瞭解預設系統設定，請與 Apigee Edge 支援團隊聯絡。

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

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

Private Cloud：如果是 Edge for Private Cloud 安裝作業，預設值是由 conf_keymanagement_oauth_refresh_token_expiry_time_in_millis 屬性設定。如要設定這項屬性，請按照下列步驟操作：

在編輯器中開啟 message-processor.properties 檔案。如果檔案不存在，請建立檔案：
```
vi /opt/apigee/customer/application/message-processor.properties
```

視需要設定屬性：

conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

確認屬性檔案的擁有者是「apigee」使用者：

chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

重新啟動訊息處理器。

/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

預設值：	63072000000 毫秒 (2 年) (2024 年 8 月 5 日生效)
外觀狀態：	選用
類型：	整數
有效值：	任何正整數，不得為零。指定到期時間 (以毫秒為單位)。 -1 會根據OAuth 更新權杖最長效期到期。注意：指定任何其他負整數或零都會導致部署錯誤。另請參閱「反模式：為 OAuth 憑證設定較長的到期時間」。
適用於下列授權類型：	authorization_code 密碼 refresh_token

<ResponseType> 元素

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

這個元素會告知 Edge 用戶端應用程式要求的授權類型。僅適用於授權碼和隱含授權類型流程。

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

預設值：	request.formparam.response_type (x-www-form-urlencoded，且在要求主體中指定)
外觀狀態：	(選用步驟) 如要覆寫預設行為，請使用這個元素。
類型：	字串
有效值：	`code` (適用於授權碼授權類型) 或 `token` (適用於隱含授權類型)
適用於下列授權類型：	隱含也用於 GenerateAuthorizationCode 作業。

<ReuseRefreshToken> 元素

<ReuseRefreshToken>true</ReuseRefreshToken>

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

預設值：	`false`
外觀狀態：	選用
類型：	布林值
有效值：	`true` 或 `false`
搭配授權類型使用：	refresh_token

<Scope> 元素

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

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

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

<Scope>A B</Scope>

另請參閱「使用 OAuth2 範圍」和「要求存取權杖和授權碼」。

預設值：	沒有範圍
外觀狀態：	選用
類型：	字串
有效值：	如果搭配 Generate* 政策使用，則為流程變數。如果與 VerifyAccessToken 搭配使用，則為以空格分隔的範圍名稱清單 (字串)。
適用於下列授權類型：	authorization_code 隱含密碼 client_credentials 也可以搭配 GenerateAuthorizationCode 和 VerifyAccessToken 作業使用。

<State> 元素

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

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

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

預設值：	沒有任何狀態
外觀狀態：	選用
類型：	字串
有效值：	政策在執行階段可存取的任何流程變數
適用於下列授權類型：	全部也可以搭配 GenerateAuthorizationCode 作業使用

<StoreToken> 元素

 <StoreToken>true</StoreToken>

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

預設值：	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 Edge 上 OAuth 權杖端點支援的授權類型。端點可能支援多種授權類型 (也就是說，單一端點可設定為針對多種授權類型發布存取權杖)。如要進一步瞭解端點，請參閱「瞭解 OAuth 端點」。授權類型會透過 grant_type 參數傳遞至權杖要求。

如果未指定任何支援的授權類型，則只允許 authorization_code 和 implicit 授權類型。另請參閱 <GrantType> 元素 (這個較高層級的元素用於指定 Apigee Edge 應在何處尋找用戶端要求中傳遞的 grant_type 參數。Edge 會確保 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> 元素用於指定 Edge 可從中找出這些值的變數。如未指定這些元素，政策會預期在名為 username 和 password 的表單參數中 (依預設) 找到值。如果找不到值，政策就會擲回錯誤。您可以使用 <PassWord> 和 <UserName> 元素，參照任何含有憑證的流程變數。

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

另請參閱「要求存取權杖和授權碼」。

預設值：	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 規格，您可以為每個參數指定預期位置。舉例來說，處理授權碼時，您可以指定授權碼、用戶端 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 政策讀取這些變數，並在流程中視需要使用。這些變數也可用於偵錯。

注意：如果 API 產品已設定有效的環境、Proxy 和 API 資源 (衍生自 proxy.pathsuffix)，系統會自動填入 API 產品變數。您不需要明確設定 flow.resource.name 變數。

如果 API 產品未設定有效的環境和 API Proxy，則必須明確設定 flow.resource.name，才能在流程中填入 API 產品變數。如要瞭解產品設定詳情，請參閱「使用 Edge Management API 發布 API」。

權杖專屬變數

變數	說明
`organization_name`	執行 Proxy 的機構名稱。
`developer.id`	與已註冊用戶端應用程式相關聯的開發人員 ID。
`developer.app.name`	與已註冊的用戶端應用程式相關聯的開發人員名稱。
`client_id`	已註冊用戶端應用程式的用戶端 ID。
`grant_type`	與要求相關聯的授權類型。
`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) 指出存取權杖遭撤銷的原因。值可以是 `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}`	已註冊用戶端應用程式的具名自訂屬性。

開發人員專用變數

如果 app.appType 為「Company」，系統會填入公司屬性；如果 app.appType 為「Developer」，系統則會填入開發人員屬性。

變數	說明
開發人員專用變數
`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}`	開發人員的具名自訂屬性。

公司專屬變數

如果 app.appType 為「Company」，系統會填入公司屬性；如果 app.appType 為「Developer」，系統則會填入開發人員屬性。

變數	說明
`company.id`
`company.displayName`
`company.apps`
`company.appOwnerStatus`
`company.created_by`
`company.created_at`
`company.last_modified_at`
`company.last_modified_by`
`company.{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> 元素。

錯誤參考資料

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

執行階段錯誤

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

錯誤代碼	HTTP 狀態	原因	由作業擲回
`steps.oauth.v2.access_token_expired`	401	存取權杖已過期。	VerifyAccessToken InvalidateToken
`steps.oauth.v2.access_token_not_approved`	401	已撤銷存取權杖。	VerifyAccessToken
`steps.oauth.v2.apiresource_doesnot_exist`	401	要求的資源不存在於與存取權杖相關聯的任何 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_access_token`	401	從用戶端傳送的存取權杖無效。	VerifyAccessToken
`steps.oauth.v2.invalid_client`	401	當政策的 `<GenerateResponse>` 屬性設為 true，且要求中傳送的用戶端 ID 無效時，系統會傳回這個錯誤名稱。請確認您為與 Proxy 相關聯的開發人員應用程式使用正確的用戶端金鑰和密鑰值。通常，這些值會以 Base64 編碼的 Basic Authorization 標頭傳送。注意：建議您變更現有錯誤規則的條件，以便同時擷取 `invalid_client` 和 `InvalidClientIdentifier` 名稱。如需詳細資訊和範例，請參閱16.09.21 版本資訊。	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 產品」。如要進一步瞭解導致這項錯誤的原因，請參閱這篇 Apigee 社群貼文。	VerifyAccessToken
`steps.oauth.v2.InvalidClientIdentifier`	500	如果政策的 `<GenerateResponse>` 屬性設為 false，且要求中傳送的用戶端 ID 無效，系統就會傳回這個錯誤名稱。請確認您為與 Proxy 相關聯的開發人員應用程式使用正確的用戶端金鑰和密鑰值。通常，這些值會以 Base64 編碼的 Basic Authorization 標頭傳送。注意：在這種情況下，這個錯誤原本稱為 `invalid_client`。建議您變更現有的錯誤規則條件，同時擷取 `invalid_client` 和 `InvalidClientIdentifier` 名稱。如需詳細資訊和範例，請參閱 16.09.21 版本資訊。	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> 元素中)。注意：目前有個錯誤，導致系統無法正確擲回不支援的授權類型錯誤。如果發生不支援的授權類型錯誤，Proxy 不會如預期進入錯誤流程。	GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken

部署錯誤

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

錯誤名稱	原因
`InvalidValueForExpiresIn`	對於 `<ExpiresIn>` 元素，有效值為正整數和 `-1`。
`InvalidValueForRefreshTokenExpiresIn`	對於 `<RefreshTokenExpiresIn>` 元素，有效值為正整數和 `-1`。
`InvalidGrantType`	`<SupportedGrantTypes>` 元素中指定的授權類型無效。如需有效類型的清單，請參閱政策參考資料。
`ExpiresInNotApplicableForOperation`	請確認 <Operations> 元素中指定的作業支援到期日。例如，VerifyToken 作業就沒有。
`RefreshTokenExpiresInNotApplicableForOperation`	請確認 <Operations> 元素中指定的作業支援權杖到期日更新功能。例如，VerifyToken 作業就沒有。
`GrantTypesNotApplicableForOperation`	請確認指定作業支援 <SupportedGrantTypes> 中指定的授權類型。
`OperationRequired`	您必須使用 `<Operation>` 元素，在這項政策中指定作業。注意：如果缺少 `<Operation>` 元素，UI 會擲回結構定義驗證錯誤。
`InvalidOperation`	您必須使用 `<Operation>` 元素，在這個政策中指定有效的作業。注意：如果 `<Operation>` 元素無效，UI 會擲回結構定義驗證錯誤。
`TokenValueRequired`	您必須在 `<Tokens>` 元素中指定符記 `<Token>` 值。

錯誤變數

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

注意：您可以使用這些變數建立錯誤規則條件。如果 <GenerateResponse> 設為 false，系統會在發生錯誤時填入這些變數。如果 <GenerateResponse> 為 true，則在發生錯誤時，政策會立即傳回回應給用戶端，因此會略過錯誤流程，且不會填入這些變數。詳情請參閱「關於政策錯誤的相關資訊」。

變數	地點	範例
`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` 注意：針對 VerifyAccessToken 作業，錯誤名稱會包含以下後置字串：`keymanagement.service` 例如：`keymanagement.service.invalid_access_token`
`oauthV2.policy_name.fault.cause`	`policy_name` 是使用者指定的政策名稱，該政策會擲回錯誤。	`oauthV2.GenerateAccesstoken.cause = Required param : grant_type`

錯誤回應範例

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

注意：如要處理錯誤，最佳做法是擷取錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為該文字可能會變更。

如果 <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>

政策結構定義

每個政策類型都由 XML 架構 (.xsd) 定義。如需參考，請前往 GitHub 查看政策架構。

使用預設 OAuth 設定

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

清除存取權杖

根據預設，存取權杖和更新權杖 (如有) 過期後，Apigee Edge 系統會在 3 天 (259200 秒) 內清除 OAuth2 權杖。在某些情況下，您可能會想變更這項預設值。舉例來說，如果產生大量權杖，您可能會想縮短清除時間，以節省磁碟空間。

如果您使用 Edge for Private Cloud，可以按照本節說明設定機構屬性，變更這個預設值。(過期權杖的 3 天清除期限適用於 Edge for Private Cloud 4.19.01 以上版本。(如果是較早的版本，預設清除間隔為 180 天)。

更新 Edge Private Cloud 4.16.01 以上版本的清除設定

注意：只有在套用這些設定後產生的權杖會受到影響，先前產生的權杖則不受影響。

Private Cloud：

開啟這個檔案進行編輯：

/opt/apigee/customer/application/message-processor.properties

新增下列屬性，設定權杖過期後清除權杖前的等待秒數：

conf_keymanagement_oauth.access.token.purge.after.seconds=<number of seconds>

重新啟動訊息處理器。例如：

/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

如果存取權杖永不過期，系統就不會清除。您可以使用 OAuthV2 政策中的 <ExpiresIn> 和 <RefreshTokenExpiresIn> 屬性，設定權杖到期時間。

更新 Edge Private Cloud 4.15.07 的清除設定

注意：只有在套用這些設定後產生的權杖會受到影響，先前產生的權杖則不受影響。

Private Cloud：

在 OAuthV2 政策中，將 <ExpiresIn> 和 <RefreshTokenExpiresIn> 屬性設為正值。值以毫秒為單位。例如：
```
<ExpiresIn>1000</ExpiresIn>
<RefreshTokenExpiresIn>10000</RefreshTokenExpiresIn>
```
重新部署 Proxy。

使用這項 API 更新貴機構的權杖清除屬性：

POST https://<host-name>/v1/organizations/<org-name>

酬載：

<Organization name="AutomationOrganization">
 <Description>Desc</Description>
 <Properties>
     <Property name="keymanagement.oauth20.access.token.purge">true</Property>
     <Property name="keymanagement.oauth20.access.token.purge.after.seconds">120</Property>
 </Properties>
</Organization>

重新啟動訊息處理器。例如：
```
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
```
這個 API 會將 AutomationOrganization 機構的權杖清除屬性設為 true。在這種情況下，存取權杖和更新權杖失效後，資料庫會在 120 秒內清除存取權杖。

另請參閱 <ExpiresIn> 元素。

不符合 RFC 的行為

OAuthV2 政策傳回的權杖回應含有特定不符 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"}

OAuthV2 政策

結果

範例

VerifyAccessToken

VerifyAccessToken

GenerateAccessToken

產生存取權杖

GenerateAuthorizationCode

產生授權碼

RefreshAccessToken

重新整理存取權杖

回覆流程權杖

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

元素參考資料

<OAuthV2> 屬性

&lt;DisplayName&gt;元素

<AccessToken> 元素

<AccessTokenPrefix> 元素

<AppEndUser> 元素

<Attributes/Attribute>

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

<ClientId> 元素

<Code> 元素

<ExpiresIn> 元素

<ExternalAccessToken> 元素

<ExternalAuthorization> 元素

<ExternalAuthorizationCode> 元素

<ExternalRefreshToken> 元素

<GenerateResponse> 元素

<GenerateErrorResponse> 元素

<GrantType>

<Operation> 元素

<PassWord> 元素

<RedirectUri> 元素

關於重新導向 URI

<RefreshToken> 元素

<RefreshTokenExpiresIn> 元素

<ResponseType> 元素

<ReuseRefreshToken> 元素

<Scope> 元素

<State> 元素

<StoreToken> 元素

<SupportedGrantTypes>/<GrantType> 元素

<Tokens> 元素/<Token> 元素

<UserName> 元素

驗證存取權杖

指定要求變數位置

流程變數

VerifyAccessToken 作業

GenerateAuthorizationCode 作業

GenerateAccessToken 和 RefreshAccessToken 作業

GenerateAccessTokenImplicitGrant

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

政策結構定義

使用預設 OAuth 設定

清除存取權杖

更新 Edge Private Cloud 4.16.01 以上版本的清除設定

更新 Edge Private Cloud 4.15.07 的清除設定

不符合 RFC 的行為

相關主題

<DisplayName>元素