OAuthV2 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

優勢

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

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

<DisplayName> 元素

除了 name 屬性外，您還可以使用不同的自然語言名稱，在管理 UI Proxy 編輯器中為政策加上標籤。

<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 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 傳送至授權伺服器。這個元素可讓您指定 Edge 尋找用戶端 ID 的位置。唯一可以設定的有效位置是預設位置，也就是資料流變數 request.formparam.client_id。系統不支援將 ClientId 設為任何其他變數。另請參閱要求存取權杖和授權碼。

<Code> 元素

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

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

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

<ExpirationIn> 元素

<ExpiresIn>10000</ExpiresIn> 

強制要求存取權杖和授權碼的到期時間 (以毫秒為單位)。(如需更新權杖，請使用 <RefreshTokenExpiresIn>)。到期時間值是系統產生的值加上 <ExpiresIn> 值。如果將 <ExpiresIn> 設為 -1，權杖或代碼就會根據OAuth 存取權杖到期時間上限到期。如未指定 <ExpiresIn>，系統會套用在系統層級設定的預設值。

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

有了 Apigee Edge for Public Cloud，Edge 能在存取實體後，將下列實體保留在快取中至少 180 秒。

• OAuth 存取權杖。這表示撤銷的權杖可能仍有最多三分鐘的成功，直到快取限製到期為止。
• Key Management Service (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 可在哪裡找到外部存取權杖 (API 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 可在何處找到外部更新權杖 (API 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>.如果想在 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 會接受 ANY 網址。這可能會產生安全性問題， 因此只應與信任的用戶端應用程式搭配使用。如果用戶端應用程式不受信任，最佳做法就是一律要求註冊回呼網址。

您可以在查詢參數或標頭中傳送此參數。變數 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，另請參閱要求存取權杖和授權碼。

<RefreshTokenExpirationIn> 元素

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

強制執行更新權杖的到期時間 (以毫秒為單位)。到期時間值是系統產生的值加上 <RefreshTokenExpiresIn> 值。如果將 <RefreshTokenExpiresIn> 設為 -1，更新權杖就會根據OAuth 更新權杖到期時間上限到期。如未指定 <RefreshTokenExpiresIn>，則預設到期時間為無限期。

您也可以在執行階段使用硬式編碼、預設值或參照流程變數來設定到期時間。例如，您可以將權杖效期值儲存在鍵/值對應中、擷取該值、指派給變數，以及在政策中參照。例如：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> 元素

可與 ValidationToken 和 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 政策就會附加至公開受保護資源的流程。

舉例來說，為確保所有對 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

錯誤參考資料

本節說明當這項政策觸發錯誤時，傳回的錯誤代碼和錯誤訊息，以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤，請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

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

部署錯誤

若您部署包含這項政策的 Proxy，就可能會發生這些錯誤。

錯誤變數

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

錯誤回應範例

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

政策架構

每個政策類型都是由 XML 結構定義 (.xsd) 定義。如需參考，GitHub 提供政策結構定義。

使用預設 OAuth 設定

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

清除存取權杖

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

如果您使用 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" : "invalid_request", "Error" :"Refresh Token expired"}

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

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

相關主題

• OAuth 2.0 簡介