實作用戶端憑證授權類型

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

使用用戶端憑證授權類型時,應用程式會將自己的憑證 (用戶端 ID 和用戶端密鑰) 傳送至 Apigee Edge 上的端點,該端點已設為產生存取權杖。如果憑證有效,Edge 會將存取權杖傳回用戶端應用程式。

關於這個主題

本主題提供 OAuth 2.0 用戶端憑證授權類型的一般說明,並探討如何在 Apigee Edge 中實作此流程。

應用情境

大多數情況下,如果應用程式也是資源擁有者,系統就會使用此授權類型。舉例來說,應用程式可能需要存取後端雲端式儲存空間服務,才能儲存及擷取用於執行工作的資料,而非使用者明確擁有的資料。這種授權類型流程嚴格執行在用戶端應用程式和授權伺服器之間。使用者未參與這個授權類型流程。

角色

角色會指定參與 OAuth 流程的「執行者」。以下概略介紹用戶端憑證角色,以便說明 Apigee Edge 的使用情境。如需 OAuth 2.0 角色的完整討論,請參閱 IETF OAuth 2.0 規格

  • 用戶端應用程式 - 應用程式需要存取使用者受保護資源。一般來說,透過此流程,應用程式會在伺服器上執行,而非在使用者筆記型電腦或裝置本機上執行。
  • Apigee Edge:在這個流程中,Apigee Edge 是 OAuth 授權伺服器。角色的作用是產生存取權杖、驗證存取權杖,並將受保護資源的授權要求傳遞至資源伺服器。
  • 資源伺服器 -- 後端服務,儲存用戶端應用程式需要存取的受保護資料。如果您要保護在 Apigee Edge 上託管的 API Proxy,Apigee Edge 也是資源伺服器。

程式碼範例

您可以在 GitHub 中找到完整且有效的 用戶端憑證授權類型實作範例。如要查看更多範例,請參閱下方的其他資源

流程圖

下列流程圖說明以 Apigee Edge 服務做為授權伺服器時的用戶端憑證流程。一般而言,Edge 也是此流程中的資源伺服器,也就是說,API Proxy 是受保護的資源。


用戶端憑證流程步驟

以下摘要說明實作用戶端憑證授權類型所需的步驟,其中 Apigee Edge 用來做為授權伺服器。提醒您,在這個流程中,用戶端應用程式只會顯示其用戶端 ID 和用戶端密鑰;如果有效,Apigee Edge 就會傳回存取權杖。

事前準備:用戶端應用程式必須向 Apigee Edge 註冊,才能取得用戶端 ID 和用戶端密鑰。詳情請參閱「註冊用戶端應用程式」。

1. 用戶端要求存取權杖

為了接收存取權杖,用戶端會向 Edge 發布 API 呼叫,其中包含用戶端 ID 和用戶端密碼的值,該值會從已註冊的開發人員應用程式取得。此外,Grant_type=client_credentials 參數必須以查詢參數的形式傳遞。(不過,您可以將 OAuthV2 政策設定為在要求標頭或內文中接受此參數,詳情請參閱 OAuthV2 政策)。

例如:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials&client_id=ns4fQc14Zg4hKFCNaSzArVuwszX95X&client_secret=ZIjFyTsNgQNyxI'

注意:雖然您可以隨上所示傳送 client_id 和 client_secret 值做為查詢參數,但最好是在 Authorization 標頭中以 Base64 網址編碼字串的形式傳遞。為此,您需要使用 Base64 編碼工具或公用程式,將兩個值以冒號分隔,一起編碼。如下所示: aBase64EncodeFunction(clientidvalue:clientsecret)。因此,上述範例採用的編碼方式如下:

result = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // 請注意用來分隔兩個值的冒號。

對上述字串進行 Base64 編碼的結果為:bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

然後發出權杖要求,如下所示:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg=='

2. Edge 會驗證憑證

請注意,API 呼叫會傳送至 /accesstoken 端點。這個端點附加的政策會驗證應用程式憑證。也就是說,這項政策會比較提交的金鑰與 Apigee Edge 在應用程式註冊時建立的金鑰。如要進一步瞭解 Edge 上的 OAuth 端點,請參閱設定 OAuth 端點和政策

3. Edge 傳回回應

如果憑證正確無誤,Edge 會將存取權杖傳回用戶端。否則系統會傳回錯誤。

4. 用戶端會呼叫受保護的 API

現在,用戶端只要具備有效的存取權杖,就可以呼叫受保護的 API。在這個情境中,要求會向 Apigee Edge (Proxy) 發出,且 Edge 會負責驗證存取權杖,然後再將 API 呼叫傳送至目標資源伺服器。如需範例,請參閱下方的呼叫受保護的 API

設定流程和政策

做為授權伺服器,Edge 會處理存取權杖的要求。API 開發人員需要建立具備自訂流程的 Proxy 來處理權杖要求,以及新增及設定 OAuthV2 政策。本節說明如何設定該端點。

自訂流程設定

如想瞭解 API Proxy 流程的設定方式,最簡單的方法就是顯示 XML 流程定義。以下的 API Proxy 流程範例旨在處理存取權杖要求。舉例來說,當要求傳入且路徑後置字串與 /accesstoken 相符時,就會觸發 GetAccessToken 政策。請參閱「設定 OAuth 端點和政策」一文,概略瞭解建立這類自訂流程所需的步驟。

<Flows>
  <Flow name="GetAccessToken">
         <!-- This policy flow is triggered when the URI path suffix
         matches /oauth/accesstoken. Publish this URL to app developers 
         to use when obtaining an access token using an auth code   
         -->
    <Condition>proxy.pathsuffix == "/oauth/accesstoken"</Condition>
    <Request>
        <Step><Name>GetAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

使用政策設定流程

您必須將政策附加至端點,如下所示。請參閱設定 OAuth 端點和政策一文,概略瞭解將 OAuthV2 政策新增至 Proxy 端點所需的步驟。

取得存取權杖

這項政策已附加至 /accesstoken 路徑。這個指令會使用 OAuthV2 政策,並指定 GenerateAccessToken 作業。

<OAuthV2 name="GetAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse/>
</OAuthV2>

取得存取權杖的 API 呼叫為 POST,且包含包含 Base64 編碼 client_id + client+secret 的 Authorization 標頭,以及 Grant_type=client_credentials 查詢參數。您也可以加入範圍和狀態的選用參數。例如:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVgT1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'

附加驗證存取權杖政策

為了保障您的 API 獲得 OAuth 2.0 安全性,您必須透過 VerifyAccessToken 作業新增 OAuthV2 政策。這項政策會檢查傳入要求是否具備有效的存取權杖。 如果權杖有效,Edge 就會處理要求。如果無效,Edge 會傳回錯誤。如需基本步驟,請參閱「驗證存取權杖」。

<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
    <DisplayName>VerifyAccessToken</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <SupportedGrantTypes/>
    <GenerateResponse enabled="true"/>
    <Tokens/>
</OAuthV2>

呼叫受保護的 API

如要呼叫受 OAuth 2.0 安全性保護的 API,您必須提供有效的存取權杖。正確模式是在授權標頭中加入權杖,如下所示:請注意,存取權杖又稱為「不記名權杖」。

$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
  http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282 

另請參閱「傳送存取權杖」。

其他資源

  • Apigee 為 API 開發人員提供線上訓練課程,包括 API 安全性課程,其中包含 OAuth。
  • OAuthV2 政策:提供許多範例,說明如何向授權伺服器發出要求,以及如何設定 OAuthV2 政策。