自訂權杖與授權碼

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

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

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

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 代理程式可以根據附加至權杖的自訂資料，做出精細的授權或路由決策。

如要將任意資料附加至權杖，請在 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 // 以秒為單位
  • status
  • scope
  • apiproduct.name*

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

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

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

在某些情況下，您可能會希望 API Proxy 在 Apigee 處理 API 呼叫時，更新與存取權表示有關聯的中繼資料。為協助您完成這項工作，Apigee 提供可用於取得及設定權杖屬性的政策。詳情請參閱「取得 OAuth V2 資訊政策」和「設定 OAuth V2 資訊政策」。

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