Passer au contenu principal
Ce mécanisme d’authentification est considéré comme le plus sûr, car au lieu d’adresser la requête d’authentification à l’utilisateur, l’application l’envoie au serveur d’autorisation Vantage. Le serveur d’autorisation authentifie ensuite l’utilisateur et renvoie le code d’autorisation au client. Pour empêcher l’interception du code d’autorisation, ce scénario d’authentification utilise une extension de sécurité appelée PKCE (Proof Key for Code Exchange). Son fonctionnement est le suivant : chaque requête d’autorisation nécessite la génération d’un nombre aléatoire cryptographiquement sûr, stocké dans code_verifier, lequel est ensuite utilisé pour obtenir une valeur signée de manière cryptographique, stockée dans code_challenge. Cette valeur est ensuite envoyée au serveur d’autorisation afin d’obtenir un code d’autorisation. Pour plus d’informations sur PKCE, consultez cet article.

​
Obtention du code d’autorisation

Pour lancer le processus d’authentification, redirigez l’utilisateur vers l’endpoint authorize en transmettant les paramètres suivants :
ParameterDescription
client_idL’identifiant de l’application. Pour savoir comment créer un client de l’API Vantage (client_id et client_secret), consultez l’article Managing Tenant Vantage API Clients.
redirect_uriL’URL de votre application ou de votre site web utilisée pour rediriger le navigateur une fois les autorisations d’accès accordées.
response_type=codeIndique que le type de réponse « authorization code » est utilisé.
scope=openid permissions global.wildcardIndique le périmètre d’autorisation.
stateUne valeur string arbitraire qui contiendra le résultat de l’autorisation dans la réponse.
code_challengeValeur signée numériquement du code_verifier (en utilisant la méthode code_challenge_method).
code_challenge_methodLa méthode de signature numérique pour le code_verifier (S256).
productId=a8548c9b-cb90-4c66-8567-d7372bb9b963L’identifiant Vantage.
Les valeurs pour response_type, scope et productId doivent être exactement celles indiquées ci-dessus. Ces clés, à l’exception de response_type, sont susceptibles de changer. Envisagez de les conserver dans une configuration.
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
Un paramètre appelé redirect_uri, qui contient l’identifiant de votre ressource, est utilisé dans OAuth 2.0 afin de permettre à Vantage d’envoyer le code d’autorisation à votre ressource, puis d’échanger ce code contre le jeton d’accès, requis pour l’authentification lors de tous les appels API ultérieurs. L’utilisation de cette méthode d’authentification nécessite de fournir la valeur du paramètre redirect_uri à l’assistance technique d’ABBYY afin qu’elle soit ajoutée à la liste d’autorisation par les administrateurs. Une fois que les autorisations d’accès demandées à l’aide du paramètre scope ont été confirmées comme accordées, le navigateur est redirigé vers une page Web spéciale configurée par le serveur Vantage. Cette page comporte une fenêtre de dialogue permettant de procéder à l’autorisation avec votre compte. Cette page doit être ouverte dans un navigateur doté d’une barre d’adresse visible, ce qui vous permettra de vérifier l’URL de la page et l’état du certificat SSL de la connexion. Si votre adresse e-mail est associée à plusieurs comptes dans différents tenants, il vous sera demandé de sélectionner un tenant et de saisir votre mot de passe après avoir indiqué votre adresse e-mail. Vous pouvez également transmettre l’identifiant de votre tenant (le paramètre tokenId) directement en utilisant l’une des ressources suivantes : 
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
Vous devrez saisir le mot de passe de votre compte client. Une fois vos identifiants saisis, l’autorisation est effectuée côté serveur, l’application se voit accorder l’accès à l’API Vantage et vous recevez le code d’autorisation dans la réponse à votre requête. Veuillez noter que si un site ou une application utilise ce type d’authentification, les utilisateurs de Vantage accorderont l’accès à l’API Vantage, en leur nom, au site ou à l’application que vous ajoutez à la liste des url de redirection autorisées. Pour donner l’accès au site ou à l’application, il sera demandé aux utilisateurs de s’authentifier dans Vantage à l’aide de leur identifiant et de leur mot de passe. Une fois l’utilisateur authentifié, le site ou l’application recevra les autorisations suivantes :
  • Gérer les catalogues de données dans le tenant Vantage au nom de l’utilisateur,
  • Accéder aux compétences dans le tenant Vantage au nom de l’utilisateur,
  • Créer et accéder aux transactions Vantage au nom de l’utilisateur.
Le site ou l’application ne pourra pas changer le mot de passe de l’utilisateur, modifier la liste des utilisateurs dans un tenant Vantage, ni modifier des compétences. Seul l’accès à l’API Vantage sera accordé. L’utilisateur ne pourra pas révoquer l’accès une fois celui-ci accordé.

​
Obtention du jeton d’autorisation

Une fois que vous avez obtenu le code d’autorisation, vous disposez d’une minute pour l’échanger contre le jeton d’accès. Utilisez une requête POST vers le point de terminaison du jeton avec des données application/x-www-form-urlencoded. Paramètres du corps de la requête :
ParameterDescription
code_verifierLe code que vous avez généré. Nécessaire pour confirmer l’initialisation de la demande d’autorisation.
client_idL’identifiant de l’application.
client_secretLa clé sécurisée de l’application.
codeVotre code d’autorisation obtenu auprès du serveur.
redirect_uriL’URL de redirection utilisée lors de l’étape d’autorisation.
grant_type=authorization_codeIndique que le type d’octroi « authorization code » est utilisé.
scope=openid permissions global.wildcard offline_accessSpécifie le périmètre d’autorisation. Pour obtenir un jeton d’actualisation, ajoutez offline_access au périmètre.
Exemple de requête (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"
Également disponible dans d’autres régions : 
# Amérique du Nord
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"

# Australie
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"
Exemple de requête (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'
Également disponible dans d’autres régions : 
# Amérique du Nord
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'

# Australie
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 réponse du serveur à votre demande contiendra le jeton d’accès : 
{
  "id_token": "<redacted>",
  "access_token": "<redacted>",
  "expires_in": 86400,
  "token_type": "Bearer",
  "refresh_token": "<redacted>",
  "scope": "openid permissions global.wildcard offline_access legacy.client"
}
Pour plus d’informations sur le flux d’autorisation par code (Authorization Code Flow), consultez ce lien. Pour chaque flux, la clé access_token contient le jeton, tandis que la clé expires_in indique dans combien de temps le jeton expirera (en secondes). Par défaut, la durée de vie d’un jeton d’accès est de 24 heures (pour plus d’informations, voir Durées de vie des jetons). Ajoutez l’en-tête d’autorisation suivant à toutes vos requêtes et remplacez token par la valeur reçue : 
-H "Authorization: Bearer token"
Notez que vous pouvez obtenir plusieurs jetons avec le même compte. Pour en savoir plus sur le jeton d’autorisation, consultez ce lien.

​
Obtention du jeton d’actualisation

Si l’option Allow issuing refresh tokens to refresh access tokens a été activée lors de la configuration du client de l’API Vantage et que la requête visant à obtenir le jeton d’accès contenait le paramètre scope=openid permissions global.wildcard offline_access, vous recevrez également un jeton d’actualisation supplémentaire dans la réponse. Une fois en possession d’un jeton d’actualisation, vous pouvez actualiser le jeton d’accès en envoyant une requête POST au point de terminaison du jeton avec les paramètres suivants :
ParameterDescription
client_idL’identifiant de l’application.
client_secretUne clé d’application sécurisée.
refresh_tokenVotre jeton d’actualisation obtenu auprès du serveur.
grant_type=refresh_tokenIndique que le type d’autorisation « refresh token » est utilisé.
Exemple de requête (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"
Aussi disponible pour d’autres régions et pour Linux avec des commandes équivalentes.

​
Durées de vie des jetons

Les jetons d’accès et d’actualisation sont configurés avec les durées de vie suivantes :
  • Durée de vie du jeton d’accès : 24 heures. Période pendant laquelle le jeton d’accès émis reste valide.
  • Durée de vie du jeton d’actualisation : 30 jours. Un jeton d’actualisation est émis après l’authentification initiale, en même temps que le premier jeton d’accès. Tant qu’il est actif, il peut être utilisé pour obtenir de nouveaux jetons d’accès. Le jeton d’actualisation ne peut pas être prolongé. Vous ne pouvez en obtenir un nouveau que via une nouvelle authentification.