本頁面由 Cloud Translation API 翻譯而成。

使用 OAuth2 範圍

查看 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 可讓 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"
}

權杖的中繼資料包括實際的存取權杖字串、到期時間資訊、與權杖相關聯的開發人員應用程式、開發人員和產品的身分識別。您您會發現中繼資料也包含「範圍」

權杖的範圍如何？

要瞭解這個範圍，首先必須謹記開發人員應用程式中的每項產品指派給這個 API 的範圍是零個或多個範圍。當產品處於建立狀態時，可以指派這些範圍也可以日後再新增會以名稱清單的形式存在，並包含在「中繼資料」或是與各項產品相關的 ANR

當你建立開發人員應用程式並新增產品後，Edge 會檢視並為開發人員應用程式建立包含這些產品所有範圍的清單 (應用程式的主全域範圍清單 -- 所有可辨識範圍的聯集)。

，瞭解如何調查及移除這項存取權。

當用戶端應用程式向 Apigee Edge 要求存取權杖時，可以視需要指定要與該權杖建立關聯的範圍舉例來說，以下要求會詢問。也就是說，用戶端要求授權伺服器 (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 則涵蓋範圍 C 和 D 或任何組合如果用戶端未指定 scope 參數 (或會指定範圍參數，不設定值)，符記會將這四個範圍授予：A、B、C、和 D.同樣地，權杖會接收一組範圍，也就是所有已辨識的範圍聯集是由開發人員應用程式提供

還有一種預設行為是傳回存取權杖，識別範圍，此時 GenerateAccessToken 政策就是產生存取權杖) 時「不會」指定 <Scope> 元素。舉例來說，以下是「GenerateAccessToken」政策，其中 <Scope> is 指定。如果缺少該 <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 流程的開頭)。政策必須包含已指定 VerifyAccessToken 作業。這項政策規定如下：

<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 強制執行特定範圍如要這麼做，您可以使用範圍感知 VerifyAccessToken 設計自訂流程以及所有附加政策

假設 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 中設計範圍強制執行。做法是建立自訂流程來處理特定範圍，然後附加 VerifyAccessToken 強制執行這些範圍

程式碼範例

最後，來看看一些 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」(也就是 VerifyAccessToken 需要「A」範圍。VerifyAccessToken 政策如下：

<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"
 }

之所以成功，是因為呼叫端點時觸發的 VerifyAccessToken 政策需要範圍 A，且存取權杖為範圍 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"
 }

驗證成功，因為 VerifyAccessToken 政策需要範圍 A 或 X 範圍，以及存取權杖包含範圍 A 和 X當然，如果 <Scope> 元素設為「B」，呼叫失敗

摘要

請務必瞭解 Apigee Edge 如何處理 OAuth 2.0 範圍。以下分享幾個重點分數：

開發人員應用程式「辨識」所有產品定義的所有範圍聯集。
應用程式要求存取權杖時，可以指定其適用的範圍。須由 Apigee Edge (授權伺服器) 判斷哪些範圍實際上會根據 (a) 要求的範圍和 (b) 指派存取權杖以便辨識開發人員應用程式可辨識的字詞
如果未設定 Apigee Edge 以檢查範圍 (<Scope> 元素) ，只要存取權杖內嵌的範圍符合已註冊的開發人員應用程式 (應用程式「主要」範圍清單中的其中一個範圍)。
如果存取權杖沒有任何相關聯的範圍，則只會成功在 Edge 未考量範圍 (缺少 <Scope> 元素) 的情況下否則就會傳回空值)。