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. Tieni presente che, se un sito o un’applicazione utilizza questo tipo di autenticazione, gli utenti di Vantage concederanno, per loro conto, l’accesso alla Vantage API al sito o all’app che stai aggiungendo all’elenco delle URL di reindirizzamento consentite. Per fornire l’accesso al sito o all’app, agli utenti verrà richiesto di autenticarsi in Vantage utilizzando il proprio nome utente e la propria password. Una volta che un utente è autenticato, al sito o all’app verranno concesse le seguenti autorizzazioni:
  • Gestire i cataloghi di dati nel tenant Vantage per conto dell’utente,
  • Accedere alle skill nel tenant 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 Vantage o modificare le skill. Verrà fornito solo l’accesso alla Vantage API. L’utente non potrà revocare l’accesso una volta 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 flusso, la chiave access_token contiene il token, mentre la chiave expires_in specifica tra quanto tempo il token scadrà (in secondi). Per impostazione predefinita, la durata del token di accesso è di 24 ore (per ulteriori informazioni, vedere Token lifetimes). Aggiungi il seguente header di autorizzazione a tutte le tue richieste e sostituisci token con il valore ricevuto: 
-H "Authorization: Bearer token"
Tieni presente che puoi ottenere più token utilizzando lo stesso account. Per ulteriori informazioni sul token di autorizzazione, consulta questo link.

​
Ottenere il refresh token

Se l’opzione Allow issuing refresh tokens to refresh access tokens è stata abilitata durante la configurazione del client Vantage API e la richiesta per ottenere l’access token conteneva il parametro scope=openid permissions global.wildcard offline_access, nella risposta si riceverà anche un refresh token aggiuntivo. Una volta che disponi di un refresh token, puoi aggiornare l’access token utilizzando una richiesta POST all’endpoint del token con i seguenti Parameter:
ParameterDescrizione
client_idL’identificatore dell’applicazione.
client_secretUna chiave sicura dell’applicazione.
refresh_tokenIl tuo refresh token ottenuto dal server.
grant_type=refresh_tokenSpecifica che viene utilizzato il grant type refresh token.
Esempio di richiesta (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 aree geografiche e per Linux con comandi equivalenti.

​
Periodo di validità dei token

I token di accesso e di refresh sono configurati con i seguenti periodi di validità:
  • Validità del token di accesso: Definisce l’intervallo di tempo durante il quale il token di accesso emesso consente all’utente di accedere a Vantage. La validità predefinita di un token di accesso è di 24 ore.
  • Validità del token di refresh: Definisce il periodo di tempo assoluto che decorre dall’emissione del primo token di accesso, durante il quale il token di refresh emesso può essere utilizzato per rinnovare il token di accesso. La validità predefinita di un token di refresh è di 30 giorni.