您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。
本主題討論如何使用 Apigee Edge 的 OAuth 2.0 範圍。
什麼是 OAuth2 範圍？
OAuth 2.0 範圍可讓您限制授予存取權杖的存取權。例如，向用戶端應用程式發出的存取權杖可能會授予受保護資源的 READ 和 WRITE 權限，或只授予 READ 存取權。您可以實作 API 來強制執行需要的任何範圍或組合範圍。因此，如果用戶端收到有 READ 範圍的權杖，且嘗試呼叫需要 WRITE 存取權的 API 端點，呼叫就會失敗。
在本主題中，我們會討論如何指派存取權杖的範圍，以及 Apigee Edge 如何強制執行 OAuth 2.0 範圍。閱讀這個主題後，您就能放心使用範圍。
如何指定存取權杖的範圍？
Edge 產生存取權杖時，可能會為該權杖指派範圍。如要瞭解運作方式，您必須先熟悉這些 Apigee Edge 實體：API 產品、開發人員和開發人員應用程式。如需簡介，請參閱「發布簡介」一文。建議您先詳閱這份資料，然後再繼續操作。
「存取權杖」是一個隨機的外觀字元字串，可讓 Edge 驗證連入的 API 要求 (將其視為一般使用者名稱/密碼的憑證)。從技術層面來看，權杖是參照一組中繼資料的金鑰，如下所示：
{
"issued_at" : "1416962591727",
"application_name" : "0d3e1d41-a59f-4d74-957e-d4e3275d4781",
"scope" : "A",
"status" : "approved",
"api_product_list" : "[scopecheck1-bs0cSuqS9y]",
"expires_in" : "1799", //--in seconds
"developer.email" : "scopecheck1-AdBmANhsag@apigee.com",
"organization_id" : "0",
"token_type" : "BearerToken",
"client_id" : "eTtB7w5lvk3DnOZNGReBlvGvIAeAywun",
"access_token" : "ODm47ris5AlEty8TDc1itwYPe5MW",
"organization_name" : "wwitman",
"refresh_token_expires_in" : "0", //--in seconds
"refresh_count" : "0"
}
權杖的中繼資料包括實際存取權杖字串、到期時間資訊、開發人員應用程式、開發人員，以及與權杖相關聯的產品。您也會發現中繼資料也包含「範圍」。
權杖如何取得範圍？
瞭解範圍的第一個鍵是提醒您，開發人員應用程式中的每項產品都能獲派零或多個範圍。您可以在建立產品時指派這些範圍，或是稍後再新增。清單會以名稱清單的形式列出，並且包含在與各項產品相關聯的「中繼資料」中。
建立開發人員應用程式並新增產品時，Edge 會查看開發人員應用程式中的所有產品，並列出這些產品的所有範圍 (應用程式的主要或全域範圍清單，包含所有可辨識的範圍)。
當用戶端應用程式向 Apigee Edge 要求存取權杖時，可以選擇指定與該權杖相關聯的範圍。舉例來說，下列要求會要求「A」範圍。也就是說，用戶端會要求授權伺服器 (Edge) 產生具有「A」範圍的存取權杖 (讓應用程式授權可呼叫範圍為「A」的 API)。應用程式會傳送如下的 POST 要求：
curl -i -X POST -H Authorization: Basic Mg12YTk2UkEIyIBCrtro1QpIG -H content-type:application/x-www-form-urlencoded http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A
會發生什麼？
Edge 收到這項要求後，即可知道哪個應用程式正在發出要求，並瞭解該用戶端註冊的開發人員應用程式 (用戶端 ID 和用戶端密鑰在基本驗證標頭中編碼)。由於包含 scope 查詢參數，因此 Edge 必須判斷與開發人員應用程式相關的任何 API 產品是否屬於「A」範圍。如果發生這種情況，系統會產生範圍為「A」的存取權杖。另一個看法是，範圍查詢參數是一種篩選器。如果開發人員應用程式識別範圍為「A、B、X」，且查詢參數指定「scope=X Y Z」，則只有「X」範圍會指派給權杖。
如果用戶端未附加範圍參數，該怎麼辦？在此情況下，Edge 會產生權杖，其中包含開發人員應用程式識別的所有範圍。請務必瞭解預設行為，會針對包含開發人員應用程式所含所有產品的全部範圍，傳回包含其所有範圍的存取權杖。
如果與開發人員應用程式相關聯的產品都未指定範圍，且權杖有範圍，則無法使用該權杖進行呼叫。
假設開發人員應用程式可辨識這些範圍：A B C D。這是應用程式的主要範圍清單。這可能是因為應用程式中的一項產品含有範圍 A 和 B，而第二種產品包含範圍 C 和 D 的組合，或是各種組合。如果用戶端未指定 scope 參數 (或者指定未指定值的範圍參數)，則系統會授予 A、B、C 和 D 這四個範圍的權杖。同樣地，這個權杖會收到一組範圍，其中包含開發人員應用程式識別的所有範圍。
另外，預設行為是傳回含有所有可辨識範圍的存取權杖，也就是 GenerateAccessToken 政策 (產生存取權杖的 Apigee Edge 政策)「不」指定 <Scope> 元素。例如，以下是 GenerateAccessToken 政策，其中指定了 <Scope> 。如果缺少 <Scope> 元素 (或存在，但存在空白)，系統就會執行預設行為。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-GenerateAccessToken">
<DisplayName>OAuthV2 - Generate Access Token</DisplayName>
<Attributes>
<Attribute name='hello' ref='system.time' display='false'>value1</Attribute>
</Attributes>
<Scope>request.queryparam.scope</Scope>
<GrantType>request.formparam.grant_type</GrantType>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>GenerateAccessToken</Operation>
<SupportedGrantTypes>
<GrantType>client_credentials</GrantType>
</SupportedGrantTypes>
<GenerateResponse enabled="true"/>
</OAuthV2>
如何強制執行範圍？
首先，請記住，在 Apigee Edge 中，存取權杖會透過 OAuthV2 政策驗證 (通常位於 Proxy 流程的開頭)。政策必須指定 VerificationAccessToken 作業。我們來看看這項政策：
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
<DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>VerifyAccessToken</Operation>
<Scope>A</Scope> <!-- Optional: space-separated list of scope names. -->
<GenerateResponse enabled="true"/>
</OAuthV2>
請注意 <Scope> 元素。用於指定政策接受的範圍。
在本範例中，只有在存取權杖含有「A」範圍時，這項政策才會生效。如果省略 <Scope> 元素或沒有值，政策會忽略存取權杖的範圍。
現在，開發人員可以根據範圍驗證存取權杖，進而設計 API 以強制執行特定範圍。做法是藉由附加範圍感知的 AccessAccessToken 政策設計自訂流程。
假設您的 API 有針對端點 /resourceA 定義的流程：
<Flow name="resourceA">
<Condition>(proxy.pathsuffix MatchesPath "/resourceA") and (request.verb = "GET")</Condition>
<Description>Get a resource A</Description>
<Request>
<Step>
<Name>OAuthV2-VerifyAccessTokenA</Name>
</Step>
</Request>
<Response>
<Step>
<Name>AssignMessage-CreateResponse</Name>
</Step>
</Response>
</Flow>
觸發這個流程 (要求路徑路徑內含 /resourceA 時) 會立即呼叫 OAuthV2-VerifyAccessTokenA 政策。這項政策會驗證存取權杖是否有效，並查看權杖支援的範圍。如果將這項政策設為下方政策，且使用 <Scope>A</Scope> 時，只有在存取範圍為「A」時，這項政策才會生效。否則，系統會傳回錯誤。
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
<DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>VerifyAccessToken</Operation>
<Scope>A</Scope>
<GenerateResponse enabled="true"/>
</OAuthV2>
總而言之，API 開發人員負責將 API 範圍的強制執行設計。方法是建立自訂流程來處理特定範圍，並附加 VerificationAccessToken 政策以強制執行這些範圍。
程式碼範例
最後，讓我們來看看一些 API 呼叫範例，以說明權杖接收範圍的方式及強制執行方式。
預設大小寫
假設您有一款產品有產品，且這些產品的範圍是 A、B 和 C。這個 API 呼叫會要求存取權杖，但不會指定範圍查詢參數。
curl -X POST -H content-type:application/x-www-form-urlencoded http://wwitman-test.apigee.net/scopecheck1/token?grant_type=client_credentials
在這個範例中，產生的權杖會有範圍 A、B 和 C (預設行為)。權杖的中繼資料看起來會像這樣：
{
"issued_at" : "1417016208588",
"application_name" : "eb1a0333-5775-4116-9eb2-c36075ddc360",
"scope" : "A B C",
"status" : "approved",
"api_product_list" : "[scopecheck1-yEgQbQqjRR]",
"expires_in" : "1799", //--in seconds
"developer.email" : "scopecheck1-yxiuHuZcDW@apigee.com",
"organization_id" : "0",
"token_type" : "BearerToken",
"client_id" : "atGFvl3jgA0pJd05rXKHeNAC69naDmpW",
"access_token" : "MveXpj4UYXol38thNoJYIa8fBGlI",
"organization_name" : "wwitman",
"refresh_token_expires_in" : "0", //--in seconds
"refresh_count" : "0"
}
現在，假設您有一個 API 端點，其範圍是「A」(也就是的 VerificationAccessToken 需要「A」)。以下是「AccessAccessToken」政策：
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
<DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>VerifyAccessToken</Operation>
<Scope>A</Scope>
<GenerateResponse enabled="true"/>
</OAuthV2>
以下是強制執行範圍 A 的呼叫和端點範例：
curl -X GET -H Authorization: Bearer MveXpj4UYXol38thNoJYIa8fBGlI http://wwitman-test.apigee.net/scopecheck1/resourceA
這個 GET 呼叫成功：
{
"hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
}
因為呼叫端點需要範圍 A 而觸發的「AccessAccessToken」政策，且存取範圍已授予 A、B 和 C，也就是預設行為。
篩選案件
假設您有一款開發人員應用程式，其產品範圍為 A、B、C 和 X。您要求存取權杖並包含 scope 查詢參數，如下所示：
curl -i -X POST -H content-type:application/x-www-form-urlencoded 'http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A X'
在這種情況下，產生的權杖 A 和 X 都會獲得範圍，因為 A 和 X 都是有效的範圍。提醒你，開發人員應用程式會識別 A、B、C 和 X 的範圍。在這種情況下，您正在根據這些範圍篩選 API 產品清單。如果產品設有範圍 A 或 X，您可以設定強制執行這些範圍的 API 端點。如果產品沒有 A 或 X 範圍 (假設具有 B、C 和 Z)，則無法透過權杖呼叫強制執行範圍 A 或 X 的 API。
使用新權杖呼叫 API：
curl -X GET -H Authorization: Bearer Rkmqo2UkEIyIBCrtro1QpIG http://wwitman-test.apigee.net/scopecheck1/resourceX
存取權杖會通過 API Proxy 驗證。例如：
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenX">
<DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>VerifyAccessToken</Operation>
<Scope>A X</Scope>
<GenerateResponse enabled="true"/>
</OAuthV2>
GET 呼叫觸發條件成功，並會傳回回應。例如：
{
"hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
}
由於「AccessAccessToken」政策需要範圍 A 或 X，而且存取權杖包含 A 和 X 範圍，因此會成功。當然，如果 <Scope> 元素設為「B」，這項呼叫就會失敗。
摘要
請務必瞭解 Apigee Edge 如何處理 OAuth 2.0 範圍。以下是一些要點：
- 開發人員應用程式「認可」定義其所有產品的所有範圍組合。
- 當應用程式要求存取權杖時，您可以指定要使用的範圍。推出 Apigee Edge (授權伺服器) 時，必須決定要 (a) 要求的範圍，以及 (b) 開發人員應用程式開發人員認可的範圍，決定實際指派給存取權杖的範圍。
- 如果 Apigee Edge 未設為檢查範圍 (VerifyAccessToken 政策缺少
<Scope>元素，或是空白)，只要部署權杖內嵌的範圍與已註冊開發人員應用程式所認可的其中一個範圍相符 (API 的「主要」範圍清單的一部分)，API 呼叫就會成功。 - 如果存取權杖沒有任何相關聯的範圍，則只有在邊緣不將範圍視為範圍時 (AuthAccessToken 政策中缺少
<Scope>元素或空白)，該權杖才會成功。