Flujo de código de autorización

Este esquema de autenticación se considera el más seguro, ya que, en lugar de dirigir la solicitud de autenticación al usuario, la aplicación la envía al servidor de autorización de Vantage. El servidor de autorización autentica al usuario y devuelve el código de autorización al cliente. Para evitar la interceptación del código de autorización, este escenario de autenticación utiliza una extensión de seguridad llamada PKCE (Proof Key for Code Exchange). Esta extensión funciona así: cada solicitud de autorización requiere generar un número aleatorio criptográfico y almacenarlo en code_verifier, que luego se usa para obtener un valor firmado criptográficamente, almacenado en code_challenge. Este nuevo valor se envía al servidor de autorización para obtener un código de autorización. Para obtener más información sobre PKCE, visite este enlace.

Obtención del código de autorización

Para iniciar el proceso de autenticación, redirija al usuario al endpoint de autorización y pase los siguientes parámetros:

Parameter	Descripción
client_id	Identificador de la aplicación. Para saber cómo crear un cliente de Vantage API (client_id y client_secret), consulte el artículo Managing Tenant Vantage API Clients.
redirect_uri	La URL de su aplicación o sitio web a la que se redirigirá el navegador una vez otorgados los permisos de acceso.
response_type=code	Especifica que se utiliza el tipo de respuesta de código de autorización.
scope=openid permissions global.wildcard	Especifica el ámbito de permisos.
state	Un valor de cadena arbitrario que contendrá el resultado de la autorización en la respuesta.
code_challenge	Valor firmado digitalmente del code_verifier (usando code_challenge_method).
code_challenge_method	El método de firma digital para code_verifier (S256).
productId=a8548c9b-cb90-4c66-8567-d7372bb9b963	Identificador de Vantage.

Los valores de response_type, scope y productId deben ser exactamente los indicados arriba. Estas claves, excepto response_type, pueden cambiar. Considere mantenerlas en la configuración.

Solicitud de ejemplo

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

https://vantage-eu.abbyy.com/auth2/connect/authorize?client_id=client_id&redirect_uri=https%3A%2F%2Fvantage-eu.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

https://vantage-au.abbyy.com/auth2/connect/authorize?client_id=client_id&redirect_uri=https%3A%2F%2Fvantage-au.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

Un parámetro llamado redirect_uri que contiene el identificador de su recurso se utiliza en OAuth 2.0 para permitir que Vantage envíe el código de autorización a su recurso y luego intercambie ese código por el token de acceso, necesario para la autenticación en todas las llamadas posteriores a la API. El uso de este método de autenticación requiere proporcionar el valor del parámetro redirect_uri al soporte técnico de ABBYY para que los administradores lo incluyan en la lista de permitidos. Una vez verificado que se han concedido los permisos de acceso solicitados mediante el parámetro scope, el navegador se redirige a una página web específica configurada por el servidor de Vantage. Esta página web contiene un cuadro de diálogo que se utiliza para completar la autorización con su cuenta. Esta página debe abrirse en un navegador que tenga visible la barra de direcciones, lo que le permitirá verificar la URL de la página y el estado del certificado SSL de la conexión. Si su dirección de correo electrónico está asociada a varias cuentas en distintos tenants, se le pedirá que seleccione un tenant e introduzca su contraseña después de especificar su dirección de correo electrónico. También puede proporcionar directamente el identificador de su tenant (el parámetro tokenId) mediante uno de los siguientes 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

https://vantage-eu.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-au.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

https://vantage-eu.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

https://vantage-au.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

Deberá introducir la contraseña de su cuenta de tenant. Una vez que haya introducido sus credenciales, la autorización se completa en el servidor, se concede a la aplicación acceso a la Vantage API y recibe el código de autorización en la respuesta a su solicitud. Tenga en cuenta que, si un sitio o aplicación utiliza este tipo de autenticación, los usuarios de Vantage concederán acceso a la Vantage API en su nombre al sitio o aplicación que está añadiendo a la lista de URL de redirección permitidas. Para proporcionar acceso al sitio o a la aplicación, se pedirá a los usuarios que se autentiquen en Vantage con su nombre de usuario y contraseña. Una vez que el usuario se haya autenticado, al sitio o a la aplicación se le otorgarán los siguientes permisos:

Administrar catálogos de datos en el tenant de Vantage en nombre del usuario.
Acceder a skills en el tenant de Vantage en nombre del usuario.
Crear y acceder a transacciones de Vantage en nombre del usuario.

El sitio o la aplicación no podrá cambiar la contraseña del usuario, modificar la lista de usuarios en un tenant de Vantage ni editar skills. Solo se concederá acceso a la Vantage API. El usuario no podrá revocar este acceso una vez que haya sido concedido.

Obtención del token de autorización

Una vez que haya obtenido el código de autorización, dispone de un minuto para intercambiarlo por el token de acceso. Use una solicitud POST al endpoint de token con datos application/x-www-form-urlencoded. Parámetros del cuerpo de la solicitud:

Parameter	Descripción
code_verifier	El código que generó. Necesario para confirmar el inicio de la solicitud de autorización.
client_id	El identificador de la aplicación.
client_secret	Clave segura de la aplicación.
code	Su código de autorización obtenido del servidor.
redirect_uri	La URL de redirección utilizada en el paso de autorización.
grant_type=authorization_code	Especifica que se utiliza el tipo de concesión “authorization code”.
scope=openid permissions global.wildcard offline_access	Especifica el ámbito de permisos. Para obtener un token de actualización, agregue offline_access al ámbito.

Ejemplo de solicitud: Para Windows:

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-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-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"

Para Linux:

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-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-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'

La respuesta del servidor a su solicitud contendrá el token de acceso:

{
  "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 obtener más información sobre el flujo de código de autorización, visita este enlace. Para cada flujo, la clave access_token contiene el token, mientras que la clave expires_in especifica en cuánto tiempo expirará el token (en segundos). De forma predeterminada, el período de validez del token de acceso es de 24 horas (para obtener más información, consulta Token lifetimes). Agrega el siguiente encabezado de autorización a todas tus solicitudes y reemplaza token con el valor que recibiste:

-H "Authorization: Bearer token"

Ten en cuenta que puedes obtener más de un token con la misma cuenta. Para obtener más información sobre el token de autorización, consulta este enlace.

Obtención del token de actualización

Si la opción Allow issuing refresh tokens to refresh access tokens estaba habilitada al configurar el cliente de Vantage API y la solicitud para obtener el token de acceso contenía el parámetro scope=openid permissions global.wildcard offline_access, también recibirá un token de actualización adicional en la respuesta. Una vez que tenga un token de actualización, puede renovar el token de acceso mediante una solicitud POST al endpoint de token con los siguientes parámetros:

Parámetro	Descripción
client_id	El identificador de la aplicación.
client_secret	Una clave segura de la aplicación.
refresh_token	Su token de actualización obtenido del servidor.
grant_type=refresh_token	Especifica que se usa el tipo de concesión de token de actualización.

Ejemplo de solicitud: Para Windows:

curl --location --request POST "https://vantage-us.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"

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"

curl --location --request POST "https://vantage-au.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"

Para Linux:

curl --location --request POST 'https://vantage-us.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'

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'

curl --location --request POST 'https://vantage-au.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'

Vigencia de los tokens

Los tokens de acceso y actualización se configuran con las siguientes vigencias:

Vigencia del token de acceso: Define el periodo durante el cual el token de acceso emitido permite el acceso del usuario a Vantage. La vigencia predeterminada de un token de acceso es de 24 horas.
Vigencia del token de actualización: Define el periodo absoluto que comienza con la emisión del primer token de acceso, durante el cual el token de actualización emitido puede utilizarse para renovar el token de acceso. La vigencia predeterminada de un token de actualización es de 30 días.

Descripción general

Guía para desarrolladores

Flujo de código de autorización

Obtención del código de autorización

Obtención del token de autorización

Obtención del token de actualización

Vigencia de los tokens

​Obtención del código de autorización

​Obtención del token de autorización

​Obtención del token de actualización

​Vigencia de los tokens

Obtención del código de autorización

Obtención del token de autorización

Obtención del token de actualización

Vigencia de los tokens