跳转到主要内容
此身份验证方案被认为是最安全的，因为应用程序不会将身份验证请求直接发给用户，而是将其发送到 Vantage 授权服务器。授权服务器随后对用户进行身份验证，并将授权代码返回给客户端。 为防止授权代码被拦截，此身份验证场景使用名为 PKCE（证明密钥用于代码交换，Proof Key for Code Exchange）的安全扩展。其工作原理如下：每个授权请求都会生成一个加密随机数并将其存储在 code_verifier 中，然后用它生成一个经过加密签名的值，存储在 code_challenge 中。随后将该新值发送至授权服务器以获取授权代码。 有关 PKCE 的更多信息，请访问此链接。

​
获取授权码

要开始身份验证流程，将用户重定向到 authorize 端点，并传递以下参数：
Parameter描述
client_id应用程序标识符。关于如何创建 Vantage API Client（client_id 和 client_secret），请参阅“Managing Tenant Vantage API Clients”一文。
redirect_uri授予访问权限后用于重定向浏览器的应用程序或网站的 URL。
response_type=code指定使用授权码响应类型。
scope=openid permissions global.wildcard指定权限范围。
state一个任意的 string 值，响应中将包含授权结果。
code_challengecode_verifier 的数字签名值（使用 code_challenge_method 方法）。
code_challenge_methodcode_verifier 的数字签名方法（S256）。
productId=a8548c9b-cb90-4c66-8567-d7372bb9b963Vantage 标识符。
response_type、scope、productId 的取值必须与上文完全一致。除 response_type 外，这些键可能会变更。建议将它们放入配置中。
Sample Request 
https://vantage-us.abbyy.com/auth2/connect/authorize?client_id=client_id&redirect_uri=https%3A%2F%2Fvantage-us.abbyy.com%2Flogin-callback&response_type=code&scope=openid%20permissions%20global.wildcard&state=ef30939211cc4ecb9a7a349b855c6a10&code_challenge=tA6ayQ5VUjLX2tufAKaHh-9bTAQ4hQQY5VZAoB2kG9o&code_challenge_method=S256&productId=a8548c9b-cb90-4c66-8567-d7372bb9b963
在 OAuth 2.0 中，会使用一个名为 redirect_uri 的 Parameter，其中包含你的资源标识符，用于使 Vantage 能将授权码发送到你的资源，然后再将该授权码交换为访问令牌。访问令牌是在所有后续 API 调用中进行身份验证所必需的。使用此身份验证方法需要将 redirect_uri Parameter 的值提供给 ABBYY 技术支持，以便由管理员将其加入白名单。 一旦使用 scope Parameter 请求的访问权限被验证并授予，浏览器将被重定向到由 Vantage 服务器设置的一个特殊网页。该网页包含一个对话窗口，用于使用你的账户进行授权。应使用带有可见地址栏的浏览器打开此页面，以便你核验页面的 URL 和连接的 SSL 证书状态。 如果你的电子邮件地址关联了不同租户中的多个账户，在指定电子邮件地址后，你将被要求选择一个租户并输入密码。你也可以直接通过以下资源之一传递你的租户标识符（tokenId Parameter）： 
https://vantage-us.abbyy.com/auth2/{tenantId}/connect/authorize?client_id=client_id&redirect_uri=external_app_redirect_uri&response_type=code
&scope=openid%20permissions%20global.wildcard&state=state&code_challenge=code_challenge
&code_challenge_method=S256&productId=a8548c9b-cb90-4c66-8567-d7372bb9b963
或 
https://vantage-us.abbyy.com/auth2/connect/authorize?client_id=client_id&redirect_uri=external_app_redirect_uri&response_type=code
&scope=openid%20permissions%20global.wildcard&state=state&code_challenge=code_challenge
&code_challenge_method=S256&productId=a8548c9b-cb90-4c66-8567-d7372bb9b963&tenantId=tenantId
系统会要求你输入租户账户的密码。提交凭据后，授权将在服务器端完成，应用将被授予访问 Vantage API 的权限，你也会在对请求的响应中收到授权码。 请注意，如果某个站点或应用程序使用此类身份验证方式，Vantage 用户将代表自己，向您添加到允许重定向 URL 列表中的该站点或应用程序授予对 Vantage API 的访问权限。为向该站点或应用程序提供访问权限，系统会要求用户使用其登录名和密码在 Vantage 中进行身份验证。一旦用户通过身份验证，该站点或应用程序将被授予以下权限：
  • 代表用户管理其 Vantage 租户中的数据目录（data catalog），
  • 代表用户访问其 Vantage 租户中的 Skill，
  • 代表用户在 Vantage 中创建和访问处理事务。
该站点或应用程序将无法更改用户的密码、更改 Vantage 租户中的用户列表或编辑 Skill。仅会提供对 Vantage API 的访问权限。一旦授予访问权限，用户将无法将其撤销。

​
获取授权令牌

获取授权码后，您有一分钟时间将其兑换为访问令牌。向令牌端点发送携带 application/x-www-form-urlencoded 数据的 POST 请求。 请求正文参数：
Parameter描述
code_verifier您生成的验证码。用于确认授权请求的发起。
client_id应用程序标识符。
client_secret应用程序的安全密钥。
code您从服务器获取的授权码。
redirect_uri在授权步骤中使用的重定向 URL。
grant_type=authorization_code指定使用授权码授权类型。
scope=openid permissions global.wildcard offline_access指定权限范围。要获取刷新令牌，请在 scope 中包含 offline_access。
示例请求（Windows）： 
curl --location --request POST "https://vantage-eu.abbyy.com/auth2/connect/token" \
  --data-urlencode "code_verifier=code_verifier" \
  --data-urlencode "client_id=client_id" \
  --data-urlencode "client_secret=client_secret" \
  --data-urlencode "code=authorization code" \
  --data-urlencode "redirect_uri=external app redirect uri" \
  --data-urlencode "grant_type=authorization_code"
亦适用于其他地区： 
# 北美
curl --location --request POST "https://vantage-us.abbyy.com/auth2/connect/token" \
  --data-urlencode "code_verifier=code_verifier" \
  --data-urlencode "client_id=client_id" \
  --data-urlencode "client_secret=client_secret" \
  --data-urlencode "code=authorization code" \
  --data-urlencode "redirect_uri=external app redirect uri" \
  --data-urlencode "grant_type=authorization_code"

# 澳大利亚
curl --location --request POST "https://vantage-au.abbyy.com/auth2/connect/token" \
  --data-urlencode "code_verifier=code_verifier" \
  --data-urlencode "client_id=client_id" \
  --data-urlencode "client_secret=client_secret" \
  --data-urlencode "code=authorization code" \
  --data-urlencode "redirect_uri=external app redirect uri" \
  --data-urlencode "grant_type=authorization_code"
示例请求（Linux）： 
curl --location --request POST 'https://vantage-eu.abbyy.com/auth2/connect/token' \
  --data-urlencode 'code_verifier=code_verifier' \
  --data-urlencode 'client_id=client_id' \
  --data-urlencode 'client_secret=client_secret' \
  --data-urlencode 'code=authorization code' \
  --data-urlencode 'redirect_uri=external app redirect uri' \
  --data-urlencode 'grant_type=authorization_code'
亦适用于其他地区： 
# 北美
curl --location --request POST 'https://vantage-us.abbyy.com/auth2/connect/token' \
  --data-urlencode 'code_verifier=code_verifier' \
  --data-urlencode 'client_id=client_id' \
  --data-urlencode 'client_secret=client_secret' \
  --data-urlencode 'code=authorization code' \
  --data-urlencode 'redirect_uri=external app redirect uri' \
  --data-urlencode 'grant_type=authorization_code'

# 澳大利亚
curl --location --request POST 'https://vantage-au.abbyy.com/auth2/connect/token' \
  --data-urlencode 'code_verifier=code_verifier' \
  --data-urlencode 'client_id=client_id' \
  --data-urlencode 'client_secret=client_secret' \
  --data-urlencode 'code=authorization code' \
  --data-urlencode 'redirect_uri=external app redirect uri' \
  --data-urlencode 'grant_type=authorization_code'
服务器对您的请求的响应将包含访问令牌： 
{
  "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 键指定令牌在多长时间后过期（以秒为单位）。默认情况下，访问令牌的有效期为 24 小时（更多信息参见 Token lifetimes）。将以下 Authorization 请求头添加到你所有的请求中，并将 token 替换为你收到的值： 
-H "Authorization: Bearer token"
请注意，您可以使用同一账户获取多个令牌。有关授权令牌的更多信息，请参见此链接。

​
获取刷新令牌

如果在配置 Vantage API 客户端时启用了 Allow issuing refresh tokens to refresh access tokens 选项，并且获取 access token 的请求中包含 scope=openid permissions global.wildcard offline_access 参数，则在响应中还会额外收到一个刷新令牌（refresh token）。获得刷新令牌后，您可以通过向令牌端点发送包含以下参数的 POST 请求来刷新 access token：
ParameterDescription
client_id应用程序标识符。
client_secret应用程序的安全密钥。
refresh_token从服务器获取的刷新令牌。
grant_type=refresh_token指定使用刷新令牌授权类型。
示例请求（Windows）： 
curl --location --request POST "https://vantage-eu.abbyy.com/auth2/connect/token" \
  --data-urlencode "client_id=client_id" \
  --data-urlencode "client_secret=client_secret" \
  --data-urlencode "refresh_token=refresh_token" \
  --data-urlencode "grant_type=refresh_token"
在其他区域和 Linux 上同样适用，只需使用等效命令。

​
令牌有效期

访问令牌和刷新令牌被配置为具有以下有效期：
  • 访问令牌有效期： 定义已签发的访问令牌允许用户访问 Vantage 的时间段。访问令牌的默认有效期为 24 小时。
  • 刷新令牌有效期： 定义从首次签发访问令牌开始计算的固定时间段，在此期间已签发的刷新令牌可用于刷新访问令牌。刷新令牌的默认有效期为 30 天。