Pular para o conteúdo principal
Esse esquema de autenticação é considerado o mais seguro porque, em vez de direcionar a solicitação de autenticação ao usuário, o aplicativo a direciona ao servidor de autorização do Vantage. O servidor de autorização então autentica o usuário e retorna o código de autorização ao cliente. Para evitar que o código de autorização seja interceptado, esse cenário de autenticação usa uma extensão de segurança chamada PKCE (Proof Key for Code Exchange). Ela funciona da seguinte forma: cada solicitação de autorização requer a geração de um número aleatório criptograficamente seguro, que é armazenado em code_verifier e depois usado para obter um valor assinado criptograficamente, armazenado em code_challenge. Esse novo valor é enviado ao servidor de autorização para obter um código de autorização. Para mais informações sobre o PKCE, visite este link.

​
Obtendo o código de autorização

Para iniciar o processo de autenticação, redirecione o usuário para o endpoint de autorização, passando os seguintes parâmetros:
ParameterDescrição
client_idO identificador do aplicativo. Para saber como criar um Vantage API Client (client_id e client_secret), consulte o artigo Managing Tenant Vantage API Clients.
redirect_uriA URL do seu aplicativo ou site usada para redirecionar o navegador após a concessão das permissões de acesso.
response_type=codeEspecifica que o tipo de resposta será o código de autorização.
scope=openid permissions global.wildcardEspecifica o escopo de permissão.
stateUm valor string arbitrário que conterá o resultado da autorização na resposta.
code_challengeValor assinado digitalmente do código code_verifier (usando o método code_challenge_method).
code_challenge_methodO método de assinatura digital para o código code_verifier (S256).
productId=a8548c9b-cb90-4c66-8567-d7372bb9b963O identificador do Vantage.
Os valores de response_type, scope e productId devem ser exatamente os especificados acima. Essas chaves, exceto response_type, estão sujeitas a alteração. Considere mantê-las em configuração.
Exemplo de solicitação 
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
Um parâmetro chamado redirect_uri que contém o identificador do seu recurso é usado no OAuth 2.0 para permitir que o Vantage envie o código de autorização para o seu recurso e depois troque esse código pelo token de acesso, que é necessário para a autenticação em todas as chamadas subsequentes da API. Usar esse método de autenticação requer fornecer o valor do parâmetro redirect_uri ao suporte técnico da ABBYY para que ele seja incluído na lista de permissões pelos administradores. Depois que as permissões de acesso solicitadas usando o parâmetro scope forem verificadas e concedidas, o navegador será redirecionado para uma página da Web especial configurada pelo servidor do Vantage. Essa página da Web contém uma janela de diálogo usada para concluir a autorização com sua conta. Essa página deve ser aberta em um navegador que tenha uma barra de endereços visível, o que permitirá verificar a url da página e o estado do certificado SSL da conexão. Se seu endereço de e-mail estiver associado a várias contas em diferentes tenants, você será solicitado a selecionar um tenant e inserir sua senha depois de informar seu endereço de e-mail. Você também pode passar seu identificador de tenant (o parâmetro tokenId) diretamente usando um dos seguintes recursos: 
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
ou 
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
Será necessário inserir a senha da sua conta de tenant. Após inserir suas credenciais, a autorização é concluída no servidor, o aplicativo recebe acesso à Vantage API e você recebe o código de autorização na resposta à sua solicitação. Esteja ciente de que, se um site ou aplicativo usar este tipo de autenticação, os usuários do Vantage concederão acesso à Vantage API, em seu nome, ao site ou app que você está adicionando à lista de URLs de redirecionamento permitidos. Para conceder acesso ao site ou app, os usuários serão solicitados a se autenticar no Vantage usando seu login e senha. Depois que um usuário for autenticado, o site ou app receberá as seguintes permissões:
  • Gerenciar catálogos de dados no tenant do Vantage em nome do usuário,
  • Acessar skills no tenant do Vantage em nome do usuário,
  • Criar e acessar transações do Vantage em nome do usuário.
O site ou app não poderá alterar a senha do usuário, alterar a lista de usuários em um tenant do Vantage ou editar skills. Somente o acesso à Vantage API será fornecido. O usuário não poderá revogar o acesso depois que ele tiver sido concedido.

​
Obtendo o token de autorização

Depois de obter o código de autorização, você tem um minuto para trocá-lo pelo token de acesso. Use uma solicitação POST para o endpoint de token com dados application/x-www-form-urlencoded. Parâmetros do corpo da solicitação:
ParameterDescrição
code_verifierO código que você gerou. Necessário para confirmar a iniciação da solicitação de autorização.
client_idO identificador do aplicativo.
client_secretChave segura do aplicativo.
codeSeu código de autorização obtido do servidor.
redirect_uriA URL de redirecionamento usada na etapa de autorização.
grant_type=authorization_codeEspecifica que o tipo de concessão “authorization code” é usado.
scope=openid permissions global.wildcard offline_accessEspecifica o escopo de permissões. Para obter um token de renovação, adicione offline_access ao escopo.
Exemplo de solicitação (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"
Também disponível em outras regiões: 
# América do Norte
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"

# Austrália
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"
Exemplo de requisição (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'
Também disponível em outras regiões: 
# América do Norte
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'

# Austrália
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'
A resposta do servidor à sua requisição conterá o token de acesso: 
{
  "id_token": "<redacted>",
  "access_token": "<redacted>",
  "expires_in": 86400,
  "token_type": "Bearer",
  "refresh_token": "<redacted>",
  "scope": "openid permissions global.wildcard offline_access legacy.client"
}
Para mais informações sobre o fluxo Authorization Code, visite este link. Para cada fluxo, a chave access_token contém o token, enquanto a chave expires_in indica em quanto tempo o token expirará (em segundos). Por padrão, a validade do token de acesso é de 24 horas (para mais informações, consulte Token lifetimes). Adicione o seguinte cabeçalho de autorização a todas as suas requisições e substitua token pelo valor que você recebeu: 
-H "Authorization: Bearer token"
Observe que é possível obter vários tokens usando a mesma conta. Para mais informações sobre o token de autorização, acesse este link.

​
Obtendo o token de atualização

Se a opção Allow issuing refresh tokens to refresh access tokens foi habilitada ao configurar o cliente da Vantage API e a solicitação para obter o token de acesso continha o parâmetro scope=openid permissions global.wildcard offline_access, você também receberá um token de atualização adicional na resposta. Depois que você tiver um token de atualização, poderá renovar o token de acesso usando uma solicitação POST para o endpoint de token com os seguintes parâmetros:
ParameterDescription
client_idO identificador do aplicativo.
client_secretUma chave segura do aplicativo.
refresh_tokenSeu token de atualização obtido do servidor.
grant_type=refresh_tokenEspecifica que o tipo de concessão de token de atualização está sendo usado.
Exemplo de solicitação (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"
Também disponível para outras regiões e para Linux, com comandos equivalentes.

​
Validade dos tokens

Os tokens de acesso e de atualização são configurados com as seguintes validades:
  • Validade do token de acesso: 24 horas. Período durante o qual o token de acesso emitido é válido.
  • Validade do token de atualização: 30 dias. Um token de atualização é emitido após a autenticação inicial junto com o primeiro token de acesso. Enquanto o token de atualização estiver ativo, ele pode ser usado para obter novos tokens de acesso. O token de atualização não pode ser prorrogado. Você só pode obter um novo por meio de reautenticação.