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

實作授權碼授權類型

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

授權碼是最常用的 OAuth 2.0 授權類型之一，授權碼流程為「三足式 OAuth」設定。在這項設定中，使用者會透過資源伺服器自行驗證，並授權應用程式存取受保護資源，而不必將使用者名稱/密碼提供給用戶端應用程式。

關於這個主題

本主題提供 OAuth 2.0 授權授權類型流程的一般說明與總覽，並探討如何在 Apigee Edge 中實作此流程。

影片

請觀看短片，瞭解如何使用 OAuth 2.0 授權類型保護 API。

應用情境

此授權類型適用於由不與 API 供應商有信任的業務關係的第三方開發人員編寫的應用程式。舉例來說，註冊公用 API 計畫的開發人員通常不應成為信任的開發人員。採用這個授權類型後，資源伺服器上的使用者憑證一律不會與應用程式共用。

程式碼範例

您可以在 GitHub 的 api-platform-samples 存放區中，找到 Apigee Edge 授權代碼授權類型的完整工作範例。請參閱 api-platform-samples/sample-proxies 目錄中的 oauth-advanced 範例。如需範例的詳細資料，請參閱 README 檔案。

流程圖

下列流程圖說明以 Apigee Edge 服務做為授權伺服器時的授權碼 OAuth 流程。

提示：如要查看較大版本的圖表，請按一下滑鼠右鍵，並在新分頁中開啟圖表，或是儲存圖表並在圖片檢視器中開啟。

授權碼流程中的步驟

以下摘要說明實作授權碼授權類型 (其中 Apigee Edge 做為授權伺服器) 的必要步驟。請記住，此流程的關鍵在於用戶端絕對不會在資源伺服器上查看使用者憑證。

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

1. 使用者啟動流程

如果應用程式必須從資源伺服器 (例如社群媒體網站上的聯絡人清單) 存取使用者受保護的資源，就會向 Apigee Edge 傳送 API 呼叫來驗證用戶端 ID。如果使用有效，即可將使用者的瀏覽器重新導向至登入頁面，使用者會在該頁面輸入憑證。API 呼叫包含用戶端應用程式註冊時取得的資訊：用戶端 ID 和重新導向 URI。

2. 使用者輸入憑證

使用者現在會看到登入頁面，請在其中輸入登入憑證。登入成功後，我們就會繼續進行下一個步驟。

3. 使用者表示同意

在這個步驟中，使用者同意應用程式存取資源。同意聲明表單通常包含範圍選項，讓使用者選擇應用程式可在資源伺服器上執行的操作。例如，使用者可能會提供唯讀權限或應用程式更新資源的權限。

4. 登入應用程式傳送要求 Apigee Edge

如果登入和同意聲明成功，登入應用程式 POST 資料就會傳送至 Apigee Edge 的 /Authorizationcode 端點。資料包括重新導向 URI、用戶端 ID、範圍、需要納入的任何使用者特定資訊，以及指出登入是否成功。

5. Apigee Edge 產生授權碼

當 Edge 收到登入應用程式在其 /licensecode 端點上的 GET 要求時，會發生兩個情況。首先，Edge 會檢查 HTTP 狀態或其他方式，判斷登入成功。接下來的 Edge 會進行檢查，確認從登入應用程式傳送的重新導向 URI 與您在向 Apigee Edge 註冊應用程式時指定的重新導向 URI 相符。如果一切正常，Edge 會產生授權碼。例如：

http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

6. Edge 將授權碼傳回給用戶端

Edge 傳送 302 重新導向，並將驗證碼做為查詢參數附加給用戶端。

7. 用戶端從 Edge 擷取授權碼並要求存取碼

現在有了有效的驗證碼，用戶端即可向 Edge 要求存取權杖。方法是 POST 發布用戶端 ID 和用戶端密鑰 (在應用程式在 Edge 上註冊時取得)、授權類型和範圍。透過加入用戶端 ID 和密鑰，Apigee Edge 可以驗證用戶端應用程式是否屬於已註冊的應用程式。例如：

$ curl https://{org_name}-test.apigee.net/my_oauth_proxy/accesstoken?code=Xyz123&grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpKNhGar6K&client_secret=hAr4GngA9vAyvI4'

8. 用戶端收到存取權杖

如果一切順利，Edge 會將存取權杖傳回用戶端。存取權杖設有有效期限，且只有在使用者同意應用程式存取資源時，指定範圍才會有效。

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

現在，只要具備有效的存取碼，用戶端就能呼叫受保護的 API。在這個情境中，要求會向 Apigee Edge (Proxy) 發出，且 Edge 會負責驗證存取權杖，然後再將 API 呼叫傳送至目標資源伺服器。存取權杖會透過「授權」標頭傳遞。例如：

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

設定流程和政策

Edge 身為授權伺服器，需要處理多項 OAuth 要求，包括存取權杖、驗證碼、重新整理權杖、登入頁面重新導向等。設定這些端點有以下兩個基本步驟：

建立自訂流程
新增及設定 OAuthV2 政策

自訂流程設定

通常會設定此授權類型流程，使流程的各個步驟或「路段」是由 Apigee Edge Proxy 中的流程定義。每個流程都有端點和政策，用於執行必要的 OAuth 專屬工作，例如產生授權碼或存取權杖。例如，如以下 XML 所示，/oauth/authorizationcode 端點有一個名為 GenerateAuthCode 的關聯政策 (這是帶有指定 GenerateAuthorizationCode 作業的 OAuthV2 政策)。

如要顯示流程設定，最簡單的方法就是使用 XML 範例。請參閱內嵌註解，瞭解各個流程的相關資訊。此為範例，您可以自行設定流程和路徑的名稱。另請參閱「設定 OAuth 端點和政策」，概略瞭解建立這類自訂流程所需的步驟。

另請參閱 GitHub 上的實作範例。

<Flows>
  <Flow name="RedirectToLoginApp">
         <!-- 
         Publish this URI to developers to use for their 'login' link 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorize"</Condition>
    <Request>
        <Step><Name>RedirectToLoginPage</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAuthCode">
         <!-- 
         Call this URL from your Login app after you authenticate the user.
         The policy will automatically return the auth code in the response to the 
         redirect_uri registered by the calling app 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorizationcode"</Condition>
    <Request>
        <Step><Name>GenerateAuthCode</Name></Step>
    </Request>
  </Flow>
  <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>GenerateAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

使用政策設定流程

每個端點都有相關聯的政策。以下舉例說明政策。請參閱設定 OAuth 端點和政策，快速瞭解將 OAuthV2 政策新增至 Proxy 端點所需的步驟。

此為 /oauth/authorize 路徑。附加政策負責將使用者重新導向至登入應用程式，其中使用者可以安全地驗證及授權用戶端應用程式存取受保護的資源，而不必將使用者名稱和密碼提供給用戶端應用程式。您可以透過服務呼叫政策、JavaScript、Node.js 或其他方式來完成這項操作。

用於提出要求的 API 呼叫為 GET，且需要查詢參數 client_id、response_type、redirect_uri、 scope 和狀態。

$ curl http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

取得驗證碼

此為 /oauth/authorizationcode 路徑。這個指令會使用 OAuthV2 政策，並指定 GenerateAuthorizationCode 作業。

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GetAuthCode">
    <DisplayName>GetAuthCode</DisplayName>
    <Operation>GenerateAuthorizationCode</Operation>
    <ExpiresIn>600000</ExpiresIn>
    <GenerateResponse/>
</OAuthV2>

要取得授權碼的 API 呼叫是 GET，且需要查詢參數 client_id、response_type，以及可選用的範圍和狀態，如以下範例所示：

$curl http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&scope=scope1%20scope2&state={some_string}

取得存取權杖

這項政策已附加至 /oauth/accesstoken 路徑。這個指令會使用 OAuthV2 政策，並指定 GenerateAccessCode 作業。在這種情況下，Grant_type 參數應做為查詢參數：

<OAuthV2 name="GetAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>360000000</ExpiresIn> 
    <SupportedGrantTypes> 
        <GrantType>authorization_code</GrantType> 
    </SupportedGrantTypes> 
    <GrantType>request.queryparam.grant_type</GrantType> 
    <GenerateResponse/> 
</OAuthV2>

取得存取碼的 API 呼叫為 POST，且必須包含 client_id、client_secret、Grant_type=authorization_code，以及範圍 (選用)。例如：

$ curl https://{org_name}-test.apigee.net/oauth/accesstoken?grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

這只是基本的摘要，實際工作環境範例包含建立網址、執行轉換和執行其他工作的多項其他政策。如要瞭解完整的工作專案，請參閱 GitHub 上的範例。

附加驗證存取權杖政策

將 VerifyAccessToken 政策 (指定 VerifyAccessToken 作業指定的 OAuthV2 政策) 附加到所有存取受保護 API 的流程開頭，這樣系統就會在收到受保護的資源要求時執行該政策。邊緣檢查確認每項要求都具備有效的存取權杖。否則系統會傳回錯誤。如要瞭解基本步驟，請參閱「驗證存取權杖」。

<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

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