跳转到主要内容
此身份验证方案被认为是最安全的，因为应用程序不会将身份验证请求直接发给用户，而是将其发送到 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 选项，并且获取访问令牌的请求包含 scope=openid permissions global.wildcard offline_access 参数，则你还会在响应中收到一个额外的刷新令牌。获得刷新令牌后，你可以向令牌端点发送包含以下参数的 POST 请求以刷新访问令牌：
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，可使用等效命令。

​
令牌有效期

访问令牌和刷新令牌的有效期如下：
  • **访问令牌有效期：**24 小时。签发的访问令牌在此期间有效。
  • **刷新令牌有效期：**30 天。首次完成身份验证并获取第一个访问令牌后，会同时签发刷新令牌。在刷新令牌有效期间，可用其获取新的访问令牌。刷新令牌不可延长，只能通过重新进行身份验证获取新的刷新令牌。