自訂權杖與授權碼

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

關於權杖中繼資料

Apigee Edge 會產生 OAuth 存取權杖、更新權杖和授權碼,並將權杖提供給通過驗證的應用程式。Edge 會在產生時儲存這些權杖和代碼。之後,當 Edge 收到含有這些權杖或代碼的傳入 API 要求時,Edge 會使用儲存的資訊來授權要求。

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

Edge 存取權杖的 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 Edge 中,這類資料稱為「自訂屬性」。之後,如果權杖在 API 要求範圍內通過驗證,這些資料即可透過結構定義變數提供給 API Proxy。API Proxy 可以根據附加至權杖的自訂資料,做出精細的授權或轉送決策。

如要將任意資料附加至權杖,請使用 OAuthV2 政策中的 <Attributes> 元素。您可以指定自訂屬性名稱和應採用的值。舉例來說,下列政策設定會產生權杖,並將名為「ten_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 Edge 會在權杖存放區中查詢權杖,以便驗證權杖。接著,Apigee Edge 會填入一組內容變數,其中包含權杖的相關資訊。這些服務包括:

  • organization_name
  • developer.id
  • developer.app.name
  • client_id
  • grant_type
  • token_type
  • access_token
  • issued_at
  • validation_in //--秒
  • 資格
  • 範圍
  • apiproduct.name*

如果符記中有任何自訂屬性,則這些自訂屬性可在名為 accesstoken.{custom_attribute} 的內容變數中使用。舉例來說,假設憑證是由上述政策核發。驗證這類權杖後,會有一個名為 accesstoken.tenant_list 的額外內容變數,其中包含在權杖產生時儲存的值。

這樣一來,政策或條件就能參照這些變數,並根據儲存在其中的值修改行為。

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

在某些情況下,您可能希望在 Apigee Edge 處理 API 呼叫時,在執行階段更新與存取權杖相關聯的中繼資料。為解決這個問題,Apigee 提供取得及設定權杖屬性的政策。詳情請參閱「取得 OAuth V2 資訊政策」和「設定 OAuth V2 資訊政策」。

在各項政策中,AccessToken 元素應參照包含存取權杖的變數。

您也可以使用 Edge API 更新附加至權杖的自訂屬性。請參閱更新 OAuth 2.0 存取權杖方法的 API 說明文件。