自訂權杖與授權碼

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

關於權杖和授權碼中繼資料

Apigee 會產生 OAuth 存取權杖、更新權杖和授權碼，並將這些權杖和授權碼發放給已驗證的應用程式。Apigee 會在產生時儲存這些權杖和代碼。 之後，當 Apigee 收到含有這些權杖或代碼的 API 要求時，Apigee 會使用儲存的資訊授權要求。

Apigee 產生這些 OAuth 構件時，也會將中繼資料附加至權杖或程式碼。舉例來說，存取權杖會與定義到期時間、相關聯的應用程式和開發人員，以及其他資訊的名稱/值組建立關聯。

Apigee 存取權杖的 JSON 表示法如下所示：

{
  "issued_at" : "1372170159093",
  "application_name" : "ccd1803b-b557-4520-bd62-ddd3abf8e501",
  "scope" : "READ",
  "status" : "approved",
  "api_product_list" : "[Product1,Product2]",
  "api_product_list_json" : ["Product1", "Product2"],
  "expires_in" : "3599", //--in seconds
  "developer.email" : "joe@weathersample.com",
  "organization_id" : "0",
  "refresh_token" : "82XMXgDyHTpFyXOaApj8C2AGIPnN2IZe",
  "client_id" : "deAVedE0W9Z9U35PAMaAJYphBJCGdrND",
  "access_token" : "shTUmeI1geSKin0TODcGLXBNe9vp",
  "organization_name" : "apifactory",
  "refresh_count" : "0"
}

在 OAuth 權杖和授權碼中新增自訂屬性

有時將自訂中繼資料附加至存取權杖會很有用。舉例來說，您可能想在權杖中加入使用者名稱、使用者所屬群組或角色、客戶 ID、工作階段 ID，或其他任意資訊。在 Apigee 中，這些資料稱為「自訂屬性」。隨後，當權杖在 API 要求範圍內經過驗證時，該資料會透過內容變數提供給 API Proxy。API Proxy 可以根據附加至權杖的自訂資料，做出精細的授權或路徑決策。

如要將任意資料附加至權杖，請使用 OAuthV2 政策中的 <Attributes> 元素。您可以指定自訂屬性的名稱和值。舉例來說，以下政策設定會產生權杖，並將名為「tenant_list」的自訂屬性附加至權杖：

<OAuthV2 name="GenerateAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>600000</ExpiresIn>
  <GenerateResponse />
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <Attributes> 
    <Attribute name="tenant_list" ref="tenant_list_retrieved_from_external_service" display="false"/>
  </Attributes>
</OAuthV2>

您可以指定多個自訂屬性，並在產生授權碼 (<Operation>GenerateAuthorizationCode</Operation>) 或權杖 (<Operation>GenerateAccessToken</Operation>) 時，將這些屬性隱含附加至授權碼或權杖。

如果將 display 設為 true (預設值)，回應中會傳回自訂屬性，應用程式可查看這些屬性，或將其傳遞給使用者。如果 display 設為 false，自訂屬性會儲存在資料儲存區，但不會在回應訊息中傳回。無論是哪種情況，權杖驗證完成後，API Proxy 內的政策就能使用自訂資料。

如要進一步瞭解 display 選項，請參閱「 在回應中顯示或隱藏自訂屬性」。

在執行階段取得自訂存取權杖屬性

當呼叫 OAuthV2/VerifyAccessToken 時，Apigee 會在權杖商店中查詢權杖，藉此驗證權杖。Apigee 接著會填入一組含有權杖資訊的環境變數。包括：

  • organization_name
  • developer.id
  • developer.app.name
  • client_id
  • grant_type
  • token_type
  • access_token
  • issued_at
  • expires_in //--in seconds
  • status
  • scope
  • apiproduct.name*

如果權杖上有任何自訂屬性，這些屬性會以 accesstoken.{custom_attribute} 名稱的內容變數提供。舉例來說，假設權杖是根據上述政策核發，驗證這類權杖後，系統會新增名為 accesstoken.tenant_list 的背景資訊變數，其中包含權杖產生時儲存的值。

政策或條件隨後可參照這些變數，並根據儲存的值修改行為。

在執行階段設定及更新自訂屬性

在某些情況下，您會希望 API Proxy 在 Apigee 處理 API 呼叫時，更新與存取權杖相關聯的中繼資料。為此，Apigee 提供可取得及設定權杖屬性的政策。詳情請參閱「取得 OAuth V2 資訊政策」和「設定 OAuth V2 資訊政策」。

在這些政策中，AccessToken 元素應參照包含存取權杖的變數。