本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
授權碼是最常用的 OAuth 2.0 授權類型之一。授權碼流程是三足式 OAuth 設定。在此設定中，使用者會向資源伺服器驗證身分，並授權應用程式存取受保護的資源，而不必向用戶端應用程式透露使用者名稱/密碼。
關於這個主題
本主題將概略說明 OAuth 2.0 授權授予類型流程，並討論如何在 Apigee 上實作這個流程。
影片
觀看短片，瞭解如何使用 OAuth 2.0 授權授與類型保護 API 安全。
用途
這類授權類型適用於由第三方開發人員編寫的應用程式，這些開發人員與 API 供應商沒有信任的業務關係。舉例來說，註冊公用 API 計畫的開發人員通常不應受到信任。使用這類授權類型時，資源伺服器上的使用者憑證絕不會與應用程式共用。
程式碼範例
您可以在 GitHub 的 api-platform-samples 存放區中，找到 Apigee 授權碼授權類型的完整實作範例。請參閱 api-platform-samples/sample-proxies 目錄中的 oauth-advanced 範例。如要進一步瞭解範例，請參閱
README 檔案。
流程圖
下圖說明授權碼 OAuth 流程，其中 Apigee 是授權伺服器。
.png?hl=zh-tw)
授權碼流程的步驟
以下摘要說明實作授權碼授權類型時的必要步驟，其中 Apigee 會做為授權伺服器。請注意，這個流程的重點在於，用戶端絕不會在資源伺服器上看到使用者的憑證。
先決條件：用戶端應用程式必須向 Apigee 註冊，才能取得用戶端 ID 和用戶端密鑰。詳情請參閱「註冊用戶端應用程式」。
1. 使用者啟動流程
當應用程式需要從資源伺服器存取使用者的受保護資源 (例如社群媒體網站上的聯絡人清單) 時，會向 Apigee 發出 API 呼叫，Apigee 會驗證用戶端 ID，如果 ID 有效，就會將使用者的瀏覽器重新導向至登入頁面，讓使用者輸入憑證。API 呼叫包含用戶端應用程式註冊時取得的資訊：用戶端 ID 和重新導向 URI。
2. 使用者輸入憑證
使用者現在會看到登入頁面，要求輸入登入憑證。如果登入成功，請繼續下一個步驟。
3. 使用者同意
在這個步驟中，使用者會同意應用程式存取自己的資源。同意表單通常會包含範圍選項，使用者可選擇允許應用程式在資源伺服器上執行的操作。舉例來說，使用者可能會授予唯讀權限，或是允許應用程式更新資源。
4. 登入應用程式會將要求傳送至 Apigee
如果登入和同意程序順利完成，登入應用程式會將資料 POST 至 Apigee 的 /authorizationcode 端點。資料包括重新導向 URI、用戶端 ID、範圍、任何要納入的使用者專屬資訊，以及登入成功的指標。
5. Apigee 產生授權碼
當 Apigee 從登入應用程式的 /authorizationcode 端點收到 GET 要求時，會發生兩件事。首先，Apigee 會判斷登入是否成功 (檢查 HTTP 狀態或其他方式)。接著，Apigee 會檢查登入應用程式傳送的重新導向 URI，是否與向 Apigee 註冊應用程式時指定的重新導向 URI 相符。如果一切正常，Apigee 會產生授權碼。例如：
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. Apigee 將授權碼傳回給用戶端
Apigee 會將 302 重新導向傳送至用戶端，並將授權碼附加為查詢參數。
7. 用戶端擷取授權碼，並向 Apigee 要求存取碼
現在有了有效的授權碼，用戶端就能向 Apigee 要求存取權杖。方法是 POST 用戶端 ID 和用戶端密鑰 (在 Apigee 註冊應用程式時取得)、授權類型和範圍。加入用戶端 ID 和密鑰後，Apigee 就能驗證用戶端應用程式是否為已註冊的應用程式。例如：
$ 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. 用戶端會收到存取權杖
如果一切順利，Apigee 會將存取權杖傳回給用戶端。存取權杖會過期，且僅在使用者同意應用程式存取資源時指定的範圍內有效。
9. 用戶端呼叫受保護的 API
現在，只要有有效的存取代碼，用戶端就能呼叫受保護的 API。在這個情境中，要求會傳送至 Apigee (Proxy)，而 Apigee 負責驗證存取權杖，然後再將 API 呼叫傳送至目標資源伺服器。存取權杖會傳送至授權標頭。例如：
$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282
設定流程和政策
Apigee 是授權伺服器，因此需要處理多項 OAuth 要求，包括存取權杖、授權碼、重新整理權杖、登入頁面重新導向等。設定這些端點時，有兩個基本步驟：
- 建立自訂流程
- 新增及設定 OAuthV2 政策
自訂流程設定
您通常會設定這類授權類型流程，讓流程的每個步驟或階段都由 Apigee Proxy 中的流程定義。每個流程都有端點和政策，可執行所需的 OAuth 專屬工作，例如產生授權碼或存取權杖。舉例來說，如下方 XML 所示，/oauth/authorizationcode 端點具有名為 GenerateAuthCode 的相關聯政策 (這是 OAuthV2 政策，其中指定了 GenerateAuthorizationCode 作業)。
如要顯示流程設定，最簡單的方法是使用 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>
使用政策設定流程
每個端點都有相關聯的政策。以下列舉幾個政策示例。如要快速瞭解將 OAuthV2 政策新增至 Proxy 端點的步驟，請參閱「設定 OAuth 端點和政策」。
登入重新導向
這是 /oauth/authorize 路徑。附加的政策會將使用者重新導向登入應用程式，讓使用者安全地驗證身分，並授權用戶端應用程式存取受保護的資源，而不必向用戶端應用程式透露使用者名稱和密碼。您可以透過服務呼叫政策、JavaScript 或其他方式達成此目的。
用於提出要求的 API 呼叫是 GET，且需要查詢參數 client_id、response_type、redirect_uri、scope 和 state。
$ 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，以及選用的 scope 和 state，如以下範例所示：
$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 的任何流程開頭，以便在收到受保護資源的要求時執行該政策。Apigee 會檢查每個要求是否都有有效的存取權杖。否則會傳回錯誤。如需基本步驟，請參閱「驗證存取權杖」。
<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，您必須提供有效的存取權杖。正確做法是在 Authorization 標頭中加入權杖，如下所示：請注意，存取權杖也稱為持有者權杖。
$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \ http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282
另請參閱「傳送存取權杖」。