OAuthV2 政策

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

結果

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

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

範例

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

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

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

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">

The following table describes attributes that are common to all policy parent elements:

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

<AccessToken> 元素

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

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

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

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

<AccessTokenPrefix> 元素

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

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

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

目前僅支援 Bearer 前置字元。

<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 存取權杖的擷取和撤銷功能」。

<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 政策，手動擷取您不想在回應中看到的任何自訂屬性。

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

<ClientId> 元素

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

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

<Code> 元素

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

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

變數 request.queryparam.auth_code 表示授權碼應以查詢參數的形式存在，例如 ?auth_code=AfGlvs9。如要在 HTTP 標頭中要求授權碼，請將這個值設為 request.header.auth_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 屬性設定。如要設定這項屬性，請按照下列步驟操作：

1. 在編輯器中開啟 message-processor.properties 檔案。如果檔案不存在，請建立檔案：

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

2. 視需要設定屬性：

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

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

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

4. 重新啟動訊息處理器。

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

<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 權杖」。

<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 是以秒為單位。

<GenerateErrorResponse> 元素

<GenerateErrorResponse enabled='true'/>

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

<GrantType>

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

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

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

<Operation> 元素

<Operation>GenerateAuthorizationCode</Operation>

政策執行的 OAuth 2.0 作業。

<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 開發人員必須先擷取要求值並傳送至身分識別供應商，才能執行權杖產生政策。

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

<RedirectUri> 元素

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

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

關於重新導向 URI

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

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

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

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

<RefreshToken> 元素

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

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

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

<RefreshTokenExpiresIn> 元素

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

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

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

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

<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 屬性設定。如要設定這項屬性，請按照下列步驟操作：

1. 在編輯器中開啟 message-processor.properties 檔案。如果檔案不存在，請建立檔案：

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

2. 視需要設定屬性：

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

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

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

4. 重新啟動訊息處理器。

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

<ResponseType> 元素

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

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

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

<ReuseRefreshToken> 元素

<ReuseRefreshToken>true</ReuseRefreshToken>

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

<Scope> 元素

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

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

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

<Scope>A B</Scope>

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

<State> 元素

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

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

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

<StoreToken> 元素

 <StoreToken>true</StoreToken>

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

<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 參數的值符合其中一種支援的授權類型。

<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。

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

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

驗證存取權杖

為 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 作業的預設設定。

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

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

指定要求變數位置

對於每種授權類型，政策都會對要求訊息中的位置或必要資訊做出假設。這些假設是根據 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 政策讀取這些變數，並在流程中視需要使用。這些變數也可用於偵錯。

權杖專屬變數

應用程式專屬變數

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

開發人員專用變數

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

公司專屬變數

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

GenerateAuthorizationCode 作業

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

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

範例：oauthv2authcode.GenerateCodePolicy.code

GenerateAccessToken 和 RefreshAccessToken 作業

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

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

範例：oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

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

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

範例：oauthv2accesstoken.RefreshTokenPolicy.access_token

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when this policy triggers an error at runtime.

Example error response

These responses are sent back to the client if the <GenerateResponse> element is true.

If <GenerateResponse> is true, the policy returns errors in this format for operations that generate tokens and codes. For a complete list, see see OAuth HTTP error response reference.

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

If <GenerateResponse> is true, the policy returns errors in this format for verify and validate operations. For a complete list, see see OAuth HTTP error response reference.

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

Example fault rule

<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 以上版本的清除設定

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

更新 Edge Private Cloud 4.15.07 的清除設定

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

不符合 RFC 的行為

OAuthV2 政策傳回的權杖回應含有特定不符 RFC 規範的屬性。下表列出 OAuthV2 政策傳回的不符規定屬性，以及對應的相容屬性。

此外，如果 grant_type = refresh_token 為：

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

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

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

相關主題

• OAuth 2.0 簡介