使用第三方 OAuth 憑證

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

在本主題中，我們將討論如何將外部產生的存取權杖、重新整理權杖或驗證碼匯入 Apigee 權杖儲存庫。如果您想設定 Apigee 來驗證在 Apigee 外產生的符記，可以使用這項技術。

在一般情況下，Apigee 會產生並儲存 OAuth 權杖，然後將其傳回至呼叫應用程式。接著，在要求服務時，呼叫應用程式會將該權杖傳回給 Apigee，而 Apigee 會透過 OAuthV2 政策 (Operation = VerifyAccessToken) 驗證權杖是否有效。本主題說明如何設定 Apigee 儲存在其他位置產生的 OAuth 權杖，同時讓權杖驗證部分保持不變，就像是權杖是由 Apigee 產生一樣。

範例

如要查看說明本主題中所述技巧的實際範例，請參閱 Apigee 委派權杖管理範例。

這是什麼意思？

假設您已建立現有的授權系統，並希望使用該系統產生的權杖或代碼值，取代 Apigee 產生的 OAuth2 權杖或代碼值。接著，您可以使用替換的權杖或代碼提出安全的 API Proxy 要求，Apigee 會驗證這些要求，就如同這些要求是由 Apigee 產生一樣。

背景資訊

在一般情況下，Apigee 會產生由字母和數字組成的隨機字串，用來產生權杖。Apigee 會將該權杖與其他資料建立關聯，例如權杖核發時間、到期時間、權杖有效的 API 產品清單，以及範圍。所有這類資訊都可以透過回應傳回，而這項回應是由使用 Operation = GenerateAccessToken 設定的 OAuthV2 政策自動產生。回應的形式如下所示：

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "[email protected]",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "zBC90HhCGmGlaMBWeZAai2s3za5j",
  "organization_name": "myorg",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

Apigee 會使用 access_token 值擷取符記中繼資料。舉例來說，假設 API Proxy 要求包含了權杖 zBC90HhCGmGlaMBWeZAai2s3za5j。Apigee 會使用權杖值擷取權杖中繼資料，判斷權杖是否有效。

只要按照本文所述的步驟操作，即可設定 Apigee 儲存由外部服務產生的 access_token 值權杖。舉例來說，假設您有一個 Apigee 外部的系統，會產生格式為「TOKEN-<16 個隨機號碼>」的權杖。在這種情況下，Apigee 儲存的完整權杖中繼資料可能會是：

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "[email protected]",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "TOKEN-1092837373654221",
  "organization_name": "myorg",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

在這種情況下，應用程式可以向 API Proxy 提出要求，並附帶權杖權杖 TOKEN-1092837373654221，Apigee 就能驗證該權杖。您可以將類似的匯入模式套用至授權碼和更新權杖。

讓我們來談談如何驗證用戶端憑證

產生權杖的必要條件之一，就是驗證要求的用戶端。根據預設，Apigee 中的 OAuthV2/GenerateAccessToken 政策會隱含驗證用戶端憑證。通常在要求 OAuthV2 權杖時，系統會在授權標頭中傳遞 client_id 和 client_secret，並透過 HTTP 基本授權 (先以冒號連接，再以 base64 編碼) 進行編碼。Apigee 中的 OAuthV2/GenerateAccessToken 政策會對該標頭進行解碼，並查詢 client_id，驗證傳入的 client_secret 是否適用於該 client_id。如果 Apigee 知道憑證，這項做法就會有效。換句話說，如果 Apigee 儲存的開發人員應用程式包含憑證，而該憑證本身包含指定的 client_id 和 client_secret，就會有效。

如果 Apigee 無法驗證用戶端憑證，您必須在 API Proxy 產生權杖之前設計 API Proxy，以便透過其他方式明確驗證用戶端。這通常是透過ServiceCallout 政策連線至網路中的遠端端點。

無論是隱含或明確，您都必須確保產生權杖的 API Proxy 會先驗證用戶端憑證。請注意，驗證用戶端與產生存取權杖無關。您可以設定 Apigee 同時執行這兩項作業，或只執行其中一個作業，也可以不執行任何作業。

如果您希望 Apigee 中的 OAuthV2/GenerateAccessToken 政策能根據 Apigee 商店驗證用戶端憑證，請在政策設定中將 <ExternalAuthorization> 元素設為 false，或完全省略該元素。如果您想使用外部授權服務明確驗證用戶端憑證，請將 <ExternalAuthorization> 設為 true。

雖然 Apigee 可能不會驗證用戶端憑證，但 Apigee 仍需要知道並管理 client_id。無論是 Apigee 產生的，還是由外部系統產生並匯入 Apigee 的，Apigee 中的每個 access_token 都必須與用戶端應用程式建立關聯，這可由 client_id 表示。因此，即使 Apigee 中的 OAuthV2/GenerateAccessToken 政策不會驗證 client_id 和 client_secret 是否相符，這項政策仍會驗證 client_id 是否有效、是否存在且未遭到撤銷。因此，您可能必須透過 Apigee 管理 API 匯入 client_id，做為必要的設定步驟。

Apigee 第三方 OAuth 的政策流程

如要在 Apigee 中使用第三方 OAuth 系統的權杖，產生存取權杖的流程應遵循下列任一模式。

外部驗證用戶端憑證

1. ServiceCallout：用於驗證傳入的用戶端憑證，並取得外部權杖。
2. ExtractVariables 或 JavaScript 步驟，從回應中擷取外部產生的符記。
3. AssignMessage 可設定名為 oauth_external_authorization_status 的特殊已知變數。值必須為 true，才能表示客戶端憑證有效。
4. OAuthV2/GenerateAccessToken，其中 <ExternalAuthorization> 元素設為 true，且至少包含 <ExternalAccessToken>、<ExternalRefreshToken> 或 <ExternalAuthorizationCode> 其中一個。

用戶端憑證的內部驗證

• ServiceCallout 取得外部權杖。
• ExtractVariables 或 JavaScript 步驟，從回應中擷取外部產生的符記。
• OAuthV2/GenerateAccessToken，其中 <ExternalAuthorization> 元素設為 false，且至少包含 <ExternalAccessToken>、<ExternalRefreshToken> 或 <ExternalAuthorizationCode> 其中一個。

流程和政策設定的注意事項

• 如果您想使用外部系統驗證用戶端憑證，則必須自行開發政策流程，以便執行必要的操作。通常您會使用 ServiceCallout 政策，將外部認證的憑證傳送至外部驗證服務。外部驗證服務通常會傳回回應，如果憑證有效，也會傳回存取權存證。

• 在 ServiceCallout 之後，API 代理程式需要剖析回應，以便擷取有效性狀態，以及外部產生的 access_token 和 refresh_token (可能會產生)。

• 在 OAuthV2/GenerateAccessToken 政策中，將 <StoreToken> 元素設為 true，並視情況將 <ExternalAuthorization> 元素設為 true 或 false。

  執行 OAuthV2/GenerateAccessToken 政策時，系統會讀取變數 oauth_external_authorization_status。如果變數已設定且值為 true，Apigee 就不會嘗試驗證用戶端憑證。如果未設定變數或值為 false，Apigee 會嘗試驗證用戶端憑證。

• OAuthV2 政策有三個元素，可讓您指定要匯入的外部資料：<ExternalAccessToken>、<ExternalRefreshToken> 和 <ExternalAuthorizationCode>。每個元素都會接受流量變數。Apigee 政策會讀取該變數，找出外部產生的存取權杖、重新整理權杖或授權碼。您可以自行導入政策和邏輯，將外部符記或代碼放入適當的變數。

  舉例來說，OAuthV2 政策中的以下設定會告知 Apigee 在名為 external_token 的內容變數中尋找權杖。

  <ExternalAccessToken>external_token</ExternalAccessToken>

  您也需要在先前的步驟中設定該變數。

• 如要設定 oauth_external_authorization_status 變數，常見的做法是使用 AssignMessage 政策搭配 AssignVariable 元素，如下所示：

  <AssignMessage name="AssignMessage-SetVariable">
      <DisplayName>Assign Message - Set Variable</DisplayName>
      <AssignVariable>
          <Name>oauth_external_authorization_status</Name>
          <Value>true</Value>
      </AssignVariable>
      <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  </AssignMessage>

  請注意，這項政策必須在 Operation = GenerateAccessToken 的 OAuthV2 政策之前執行。

OAuthV2 政策範例

在 Apigee 在流程變數 external_access_token 中找到符記值時，下列 OAuthV2 政策會產生存取權杖。

<OAuthV2 name="OAuth-v20-Store-External-Token">
    <DisplayName>OAuth v2.0 1</DisplayName>
    <Attributes/>
    <ExternalAccessToken>external_access_token</ExternalAccessToken>
    <ExternalAuthorization>true</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <GenerateResponse enabled="true">
        <Format>FORM_PARAM</Format>
    </GenerateResponse>
    <ReuseRefreshToken>false</ReuseRefreshToken>
    <StoreToken>true</StoreToken>
    <SupportedGrantTypes>
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <ExpiresIn ref='flow.variable'>2400000</ExpiresIn>
</OAuthV2>

理論上，您可以將此模式套用至任何第三方 OAuth2 授權服務。