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

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

&lt;DisplayName&gt;元素

除 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，自訂屬性只是存取權杖中繼資料的一部分。

如果您在授權碼中新增自訂屬性，也會看到相同的行為。當系統使用該代碼產生存取權杖時，這些自訂屬性就會顯示在存取權杖回應中。再次提醒，這可能不是你預期的行為。

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

• 請在更新權杖政策中明確重設自訂屬性，並將顯示屬性設為「否」。在這種情況下，您可能需要使用 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 存取權杖。也就是說，在快取限制到期前，已撤銷的權杖最多可使用三分鐘。
• Key Management Service (KMS) 實體 (應用程式、開發人員、API 產品)。
• OAuth 權杖和 KMS 實體的自訂屬性。

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

<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>. 如要要求在 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。另請參閱要求存取權杖和授權碼。

<RefreshTokenExpirationIn> 元素

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

舉例來說，為確保向 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 作業時，代理程式執行內容會填入大量流程變數。這些變數會提供與存取權權杖、開發人員應用程式、開發人員和公司相關的屬性。舉例來說，您可以使用 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 端點」。

清除存取權杖

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

如果您使用的是 Edge for Private Cloud，可以按照本節所述設定機構屬性，變更這個預設值。(過期權杖的 3 天清除作業適用於 Private Cloud 版 Edge 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 簡介