使用第三方 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 產品清單和範圍) 與該權杖建立關聯。所有這些資訊都會在 OAuthV2 政策自動產生的回應中傳回，該政策已設定 Operation = GenerateAccessToken。回應的形式如下所示：

{
  "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": "joe@weathersample.com",
  "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": "joe@weathersample.com",
  "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，然後在產生權杖前，透過其他方式明確驗證用戶端。通常是透過 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 就不會嘗試驗證用戶端憑證。如果未設定變數或值不是 true，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>

    請注意，這項政策必須位於 OAuthV2 政策之前，且 Operation = GenerateAccessToken。

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 授權服務。