Vai al contenuto principale
Questo schema di autenticazione è considerato il più sicuro perché, invece di inviare la richiesta di autenticazione all’utente, l’applicazione la invia al server di autorizzazione di Vantage. Il server di autorizzazione autentica quindi l’utente e restituisce al client il codice di autorizzazione. Per impedire l’intercettazione del codice di autorizzazione, questo scenario di autenticazione utilizza un’estensione di sicurezza chiamata PKCE (Proof Key for Code Exchange). Funziona così: per ogni richiesta di autorizzazione viene generato un numero casuale crittograficamente sicuro, salvato in code_verifier, che viene poi usato per calcolare un valore firmato crittograficamente, salvato in code_challenge. Questo valore viene quindi inviato al server di autorizzazione per ottenere un codice di autorizzazione. Per ulteriori informazioni su PKCE, consultare questo documento.

​
Ottenere il codice di autorizzazione

Per avviare il processo di autenticazione, reindirizza l’utente all’endpoint authorize, passando i seguenti parametri:
ParameterDescrizione
client_idL’identificatore dell’applicazione. Per informazioni su come creare un Vantage API Client (client_id e client_secret), vedi l’articolo Managing Tenant Vantage API Clients.
redirect_uriL’URL della tua applicazione o del tuo sito web a cui reindirizzare il browser una volta concesse le autorizzazioni di accesso.
response_type=codeSpecifica che viene utilizzato il tipo di risposta “authorization code”.
scope=openid permissions global.wildcardSpecifica l’ambito delle autorizzazioni.
stateUn valore arbitrario di tipo string che conterrà l’esito dell’autorizzazione nella risposta.
code_challengeValore firmato digitalmente del code_verifier (utilizzando il metodo code_challenge_method).
code_challenge_methodIl metodo di firma digitale per il code_verifier (S256).
productId=a8548c9b-cb90-4c66-8567-d7372bb9b963L’identificatore di Vantage.
I valori per response_type, scope, productId devono essere esattamente quelli indicati sopra. Queste chiavi, ad eccezione di response_type, possono cambiare. Valuta di mantenerle nella configurazione.
Richiesta di esempio 
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 parametro denominato redirect_uri, che contiene l’identificatore della tua risorsa, viene utilizzato in OAuth 2.0 per consentire a Vantage di inviare il codice di autorizzazione alla tua risorsa e quindi scambiarlo con il token di accesso, necessario per l’autenticazione in tutte le chiamate API successive. L’uso di questo metodo di autenticazione richiede di fornire il valore del parametro redirect_uri all’assistenza tecnica di ABBYY affinché gli amministratori possano inserirlo nella lista consentita (whitelist). Una volta verificato che le autorizzazioni di accesso richieste tramite il parametro scope siano state concesse, il browser viene reindirizzato a una pagina web dedicata predisposta dal server Vantage. Questa pagina contiene una finestra di dialogo per eseguire l’autorizzazione con il tuo account. Questa pagina deve essere aperta in un browser con la barra degli indirizzi visibile, che ti consenta di verificare l’URL della pagina e lo stato del certificato SSL della connessione. Se il tuo indirizzo email è associato a più account in tenant diversi, dopo aver specificato l’indirizzo email ti verrà chiesto di selezionare un tenant e inserire la password. Puoi anche passare direttamente l’identificatore del tuo tenant (il parametro tokenId) utilizzando una delle seguenti risorse: 
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
oppure 
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
Ti verrà richiesto di inserire la password dell’account del tuo tenant. Dopo aver inserito le credenziali, l’autorizzazione viene completata lato server, all’applicazione viene concesso l’accesso alla Vantage API e riceverai il codice di autorizzazione nella risposta alla tua richiesta. Si tenga presente che, se un sito o un’applicazione utilizza questo tipo di autenticazione, gli utenti di Vantage concederanno al sito o all’app che si sta aggiungendo all’elenco degli url di reindirizzamento consentiti l’accesso alla Vantage API per loro conto. Per concedere l’accesso al sito o all’app, agli utenti verrà chiesto di autenticarsi in Vantage utilizzando le proprie credenziali (nome utente e password). Una volta autenticato l’utente, al sito o all’app saranno concessi i seguenti permessi:
  • Gestire i cataloghi di dati nel tenant di Vantage per conto dell’utente,
  • Accedere alle skill nel tenant di Vantage per conto dell’utente,
  • Creare e accedere alle transaction di Vantage per conto dell’utente.
Il sito o l’app non potrà cambiare la password dell’utente, modificare l’elenco degli utenti in un tenant di Vantage o modificare le skill. Sarà fornito esclusivamente l’accesso alla Vantage API. L’utente non potrà revocare l’accesso una volta che è stato concesso.

​
Ottenere il token di autorizzazione

Una volta ottenuto il codice di autorizzazione, hai un minuto per scambiarlo con il token di accesso. Invia una richiesta POST all’endpoint del token con dati application/x-www-form-urlencoded. Parametri del corpo della richiesta:
ParameterDescrizione
code_verifierIl codice che hai generato. Necessario per confermare l’avvio della richiesta di autorizzazione.
client_idL’identificatore dell’applicazione.
client_secretChiave sicura dell’applicazione.
codeIl tuo codice di autorizzazione ottenuto dal server.
redirect_uriL’URL di reindirizzamento utilizzato nella fase di autorizzazione.
grant_type=authorization_codeSpecifica che viene utilizzato il tipo di grant “authorization code”.
scope=openid permissions global.wildcard offline_accessSpecifica l’ambito delle autorizzazioni. Per ottenere un refresh token, aggiungi offline_access allo scope.
Esempio di richiesta (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"
Disponibile anche per altre aree: 
# Nord America
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"

# Australia
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"
Esempio di richiesta (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'
Disponibile anche in altre regioni: 
# Nord America
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'

# Australia
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 risposta del server alla tua richiesta conterrà il token di accesso: 
{
  "id_token": "<redacted>",
  "access_token": "<redacted>",
  "expires_in": 86400,
  "token_type": "Bearer",
  "refresh_token": "<redacted>",
  "scope": "openid permissions global.wildcard offline_access legacy.client"
}
Per ulteriori informazioni sull’Authorization Code Flow, consulta questo riferimento. Per ogni flow, la chiave access_token contiene il token, mentre la chiave expires_in indica in quanti secondi il token scadrà. Per impostazione predefinita, la durata del token di accesso è di 24 ore (per maggiori informazioni, vedere Durata dei token). Aggiungi la seguente intestazione di autorizzazione a tutte le richieste e sostituisci token con il valore ricevuto: 
-H "Authorization: Bearer token"
Nota che puoi ottenere più token utilizzando lo stesso account. Per ulteriori informazioni sul token di autorizzazione, consulta questo link.

​
Ottenere il refresh token

Se, durante la configurazione del client Vantage API, è stata abilitata l’opzione Allow issuing refresh tokens to refresh access tokens e la richiesta per ottenere l’access token conteneva il parametro scope=openid permissions global.wildcard offline_access, nella risposta riceverai anche un refresh token aggiuntivo. Una volta ottenuto un refresh token, puoi rinnovare l’access token inviando una richiesta POST all’endpoint del token con i seguenti parametri:
ParameterDescription
client_idL’identificatore dell’applicazione.
client_secretUna chiave sicura dell’applicazione.
refresh_tokenIl refresh token ottenuto dal server.
grant_type=refresh_tokenSpecifica che viene usato il grant type del refresh token.
Richiesta di esempio (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"
Disponibile anche per altre regioni e per Linux con comandi equivalenti.

​
Durata dei token

I token di accesso e di aggiornamento sono configurati con le seguenti durate:
  • Durata del token di accesso: 24 ore. Intervallo di tempo durante il quale il token di accesso emesso rimane valido.
  • Durata del token di aggiornamento: 30 giorni. Un token di aggiornamento viene emesso dopo l’autenticazione iniziale insieme al primo token di accesso. Finché il token di aggiornamento è attivo, può essere utilizzato per ottenere nuovi token di accesso. Il token di aggiornamento non può essere prorogato. È possibile ottenerne uno nuovo solo tramite nuova autenticazione.