跳轉到主要內容
此驗證方式被認為是最安全的，因為應用程式不是將驗證要求導向使用者，而是改為將其導向 Vantage 授權伺服器。授權伺服器接著會驗證使用者身分，並將授權碼傳回給用戶端。 為了防止授權碼在傳輸過程中被攔截，此驗證情境使用了一種稱為 PKCE（Proof Key for Code Exchange）的安全延伸功能。其運作方式如下：每個授權要求都必須產生一個密碼學隨機數，並將其儲存在 code_verifier 中，接著使用它來取得一個經密碼學簽署的值，並將其儲存在 code_challenge 中。然後會將這個新值傳送至授權伺服器，以取得授權碼。 如需有關 PKCE 的更多資訊，請造訪此連結。

​
取得授權碼

要開始驗證流程，請將使用者重新導向至 authorize 端點，並傳遞下列參數：
ParameterDescription
client_id應用程式識別碼。如何建立 Vantage API Client（client_id 和 client_secret）的相關資訊，請參閱〈Managing Tenant Vantage API Clients〉一文。
redirect_uri您的應用程式或網站的 URL，用於在授予存取權限後重新導向瀏覽器。
response_type=code指定使用授權碼（authorization code）做為回應型別。
scope=openid permissions global.wildcard指定權限範圍。
state任意的字串值，在回應中將包含授權結果。
code_challengecode_verifier 程式碼的數位簽章值（使用 code_challenge_method 方法）。
code_challenge_method用於 code_verifier 程式碼的數位簽章方法（S256）。
productId=a8548c9b-cb90-4c66-8567-d7372bb9b963Vantage 識別碼。
response_type、scope、productId 的值必須與上方所示完全相同。除了 response_type 以外，這些鍵可能會變更。建議將它們放在組態中管理。
Sample Request 在 OAuth 2.0 中，會使用名為 redirect_uri 的參數（其中包含您資源的識別碼），讓 Vantage 能夠將授權碼傳送到您的資源，接著再用該授權碼換取存取權杖。存取權杖是後續所有 API 呼叫進行驗證所必需的。使用此驗證方法時，您必須將 redirect_uri 參數的值提供給 ABBYY 技術支援，讓管理員將其加入允許清單。 當以 scope 參數請求的存取權限確認已被授與後，瀏覽器會被重新導向到由 Vantage 伺服器設定的特殊網頁。此網頁包含一個對話視窗，供您使用帳戶完成授權。此頁面應在具有可見網址列的瀏覽器中開啟，以便您檢查頁面的 URL 以及連線的 SSL 憑證狀態。 如果您的電子郵件地址關聯到數個不同租戶的帳戶，在輸入電子郵件地址後，系統會要求您選擇租戶並輸入密碼。您也可以透過下列其中一個資源，直接傳遞您的租戶識別碼（tokenId 參數）： or 系統會要求您輸入租戶帳戶的密碼。輸入認證資料後，授權會在伺服器端完成，應用程式會被授與對 Vantage API 的存取權，並且您會在對請求的回應中收到授權碼。 請注意，如果網站或應用程式使用此驗證類型，Vantage 使用者將會代表其本人，向您新增到允許的重新導向 URL 清單中的該網站或應用程式提供對 Vantage API 的存取權。為了向該網站或應用程式提供存取權，系統會要求使用者使用其登入帳號與密碼在 Vantage 中進行驗證。使用者一旦通過驗證，該網站或應用程式將被授予下列許可權：
  • 代表使用者在 Vantage 租用戶中管理資料目錄，
  • 代表使用者在 Vantage 租用戶中存取 skills，
  • 代表使用者建立與存取 Vantage 處理作業。
該網站或應用程式將無法變更使用者的密碼、變更 Vantage 租用戶中的使用者清單，或編輯 skills。系統只會提供對 Vantage API 的存取權。一旦存取權被授予，使用者將無法撤銷該存取權。

​
取得授權權杖

取得授權碼後，您有一分鐘的時間將其交換為存取權杖。請使用對 token 端點的 POST 請求，並以 application/x-www-form-urlencoded 格式傳送資料。 請求本文參數：
ParameterDescription
code_verifier您所產生的代碼。用於確認授權請求的啟動。
client_id應用程式識別碼。
client_secret安全的應用程式金鑰。
code您從伺服器取得的授權碼。
redirect_uri在授權步驟中使用的重新導向 URL。
grant_type=authorization_code指定使用授權碼授權型別。
scope=openid permissions global.wildcard offline_access指定權限範圍。若要取得重新整理權杖，請在 scope 中加入 offline_access。
範例請求： 伺服器對您請求的回應將包含存取權杖： 
{
  "id_token": "<redacted>",
  "access_token": "<redacted>",
  "expires_in": 86400,
  "token_type": "Bearer",
  "refresh_token": "<redacted>",
  "scope": "openid permissions global.wildcard offline_access legacy.client"
}
如需進一步了解 Authorization Code Flow，請參閱此連結。 對於每種流程，access_token 鍵包含權杖本身，而 expires_in 鍵則指定權杖在多久之後會過期（以秒為單位）。預設情況下，access token 的有效期限為 24 小時（如需更多資訊，請參閱 Token lifetimes）。請在所有請求中加入以下 Authorization 標頭，並將 token 替換為您收到的值： 
-H "Authorization: Bearer token"
請注意，您可以使用同一個帳戶取得多個權杖。若要深入了解授權權杖，請參閱此連結。

​
取得重新整理權杖

如果在設定 Vantage API 用戶端時啟用了 Allow issuing refresh tokens to refresh access tokens 選項，且取得存取權杖的請求中包含 scope=openid permissions global.wildcard offline_access 這個 Parameter，則在回應中也會收到額外的重新整理權杖 (refresh token)。取得重新整理權杖之後，您可以透過向權杖端點送出 POST 請求，並使用下列參數來重新整理存取權杖：
ParameterDescription
client_id應用程式識別碼。
client_secret安全的應用程式金鑰。
refresh_token您從伺服器取得的重新整理權杖。
grant_type=refresh_token指定使用重新整理權杖 (refresh token) 的授權類型。
範例請求：

​
權杖有效期限

存取權杖與重新整理權杖的有效期限會設定如下：
  • Access token lifetime： 指已發行的存取權杖可讓使用者存取 Vantage 的時間長度。存取權杖的預設有效期限為 24 小時。
  • Refresh token lifetime： 指自第一個存取權杖發行時起算，在此絕對時間範圍內，可使用已發行的重新整理權杖來更新存取權杖。重新整理權杖的預設有效期限為 30 天。