Authorization-Code-Flow

Dieses Authentifizierungsverfahren gilt als das sicherste, da die Anwendung die Authentifizierungsanfrage nicht an den Benutzer, sondern an den Vantage-Authorization-Server richtet. Der Authorization-Server authentifiziert anschließend den Benutzer und gibt den Autorisierungscode an den Client zurück. Um zu verhindern, dass der Autorisierungscode abgefangen wird, verwendet dieses Authentifizierungsszenario eine Sicherheitserweiterung namens PKCE (Proof Key for Code Exchange). Diese Erweiterung funktioniert wie folgt: Für jede Autorisierungsanfrage wird eine kryptografische Zufallszahl erzeugt und in code_verifier gespeichert. Diese wird anschließend verwendet, um einen kryptografisch abgeleiteten Wert zu erzeugen, der in code_challenge gespeichert ist. Dieser neue Wert wird dann an den Authorization-Server gesendet, um einen Autorisierungscode zu erhalten. Weitere Informationen zu PKCE finden Sie unter diesem Link.

Abrufen des Autorisierungscodes

Um den Authentifizierungsprozess zu starten, leiten Sie den Benutzer an den Authorize-Endpunkt weiter und übergeben dabei die folgenden Parameter:

Parameter	Beschreibung
client_id	Die Anwendungs-ID. Informationen zum Erstellen eines Vantage-API-Clients (client_id und client_secret) finden Sie im Artikel zur Verwaltung von Mandant Vantage API Clients.
redirect_uri	Die URL Ihrer Anwendung oder Website, an die der Browser weitergeleitet wird, sobald Zugriffsberechtigungen erteilt wurden.
response_type=code	Gibt an, dass der Antworttyp „authorization code“ verwendet wird.
scope=openid permissions global.wildcard	Gibt den Scope an.
state	Ein beliebiger string-Wert, der das Autorisierungsergebnis in der Antwort enthält.
code_challenge	Digital signierter Wert des code_verifier (unter Verwendung der code_challenge_method).
code_challenge_method	Die Signaturmethode für den code_verifier (S256).
productId=a8548c9b-cb90-4c66-8567-d7372bb9b963	Die Vantage-Kennung.

Die Werte für response_type, scope, productId müssen genau wie oben angegeben sein. Diese Schlüssel – außer response_type – können sich ändern. Erwägen Sie, sie in der Konfiguration zu halten.

Beispielanfrage

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

Ein Parameter mit dem Namen redirect_uri, der den Bezeichner Ihrer Ressource enthält, wird in OAuth 2.0 verwendet, damit Vantage den Autorisierungscode an Ihre Ressource senden und diesen Code anschließend gegen das Zugriffstoken eintauschen kann, das für die Authentifizierung bei allen nachfolgenden API-Aufrufen erforderlich ist. Bei Verwendung dieser Authentifizierungsmethode muss der Wert des Parameters redirect_uri dem technischen Support von ABBYY bereitgestellt werden, damit er von den Administratoren auf die Allowlist gesetzt wird. Sobald die mit dem Parameter scope angeforderten Zugriffsberechtigungen als gewährt verifiziert wurden, wird der Browser auf eine spezielle Webseite weitergeleitet, die vom Vantage-Server bereitgestellt wird. Diese Webseite enthält ein Dialogfenster, über das Sie sich mit Ihrem Konto autorisieren. Diese Seite sollte in einem Browser geöffnet werden, der eine sichtbare Adressleiste hat, sodass Sie die Seiten-URL und den Status des SSL-Zertifikats der Verbindung überprüfen können. Wenn Ihre E-Mail-Adresse mit mehreren Konten in verschiedenen Mandanten verknüpft ist, werden Sie nach Angabe Ihrer E-Mail-Adresse aufgefordert, einen Mandanten auszuwählen und Ihr Kennwort einzugeben. Sie können Ihre Mandantenkennung (den Parameter tokenId) auch direkt über eine der folgenden URLs übergeben:

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

oder

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

Sie müssen das Kennwort für Ihr Mandantenkonto eingeben. Nachdem Sie Ihre Zugangsdaten eingegeben haben, wird die Autorisierung serverseitig abgeschlossen, der Anwendung wird Zugriff auf die Vantage-API gewährt, und Sie erhalten den Autorisierungscode in der Antwort auf Ihre Anfrage. Bitte beachten Sie, dass Vantage-Benutzer, wenn eine Website oder Anwendung diesen Authentifizierungstyp verwendet, dieser Website oder App, die Sie zur Liste der zulässigen Redirect-URLs hinzufügen, in ihrem Namen Zugriff auf die Vantage-API gewähren. Um der Website oder App Zugriff zu gewähren, werden Benutzer aufgefordert, sich mit ihrem Benutzernamen und Kennwort in Vantage zu authentifizieren. Sobald ein Benutzer authentifiziert ist, erhält die Website oder App die folgenden Berechtigungen:

Verwalten von Datenkatalogen im Vantage-Tenant im Namen des Benutzers,
Zugriff auf Skills im Vantage-Tenant im Namen des Benutzers,
Erstellen von und Zugriff auf Vantage-Vorgänge im Namen des Benutzers.

Die Website oder App kann das Kennwort des Benutzers nicht ändern, die Liste der Benutzer in einem Vantage-Tenant nicht ändern oder Skills bearbeiten. Es wird nur Zugriff auf die Vantage-API gewährt. Der Benutzer kann den einmal gewährten Zugriff nicht widerrufen.

Abrufen des Autorisierungs-Tokens

Sobald Sie den Autorisierungscode erhalten haben, haben Sie eine Minute Zeit, ihn gegen das Zugriffstoken einzutauschen. Senden Sie dazu eine POST-Anfrage an den Token-Endpunkt mit Daten im Format application/x-www-form-urlencoded. Parameter des Anfragetexts:

Parameter	Beschreibung
code_verifier	Der von Ihnen generierte Code. Wird benötigt, um die Einleitung der Autorisierungsanfrage zu bestätigen.
client_id	Die Anwendungs-ID.
client_secret	Sicherer Anwendungsschlüssel.
code	Ihr vom Server erhaltener Autorisierungscode.
redirect_uri	Die in Schritt „authorize“ verwendete Redirect-URL.
grant_type=authorization_code	Gibt an, dass der Grant-Typ „authorization code“ verwendet wird.
scope=openid permissions global.wildcard offline_access	Gibt den Scope an. Um ein Refresh-Token zu erhalten, fügen Sie offline_access zum Scope hinzu.

Beispielanfrage: Für 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"

Für 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'

Die Serverantwort auf Ihre Anfrage enthält das Zugriffstoken:

{
  "id_token": "<redacted>",
  "access_token": "<redacted>",
  "expires_in": 86400,
  "token_type": "Bearer",
  "refresh_token": "<redacted>",
  "scope": "openid permissions global.wildcard offline_access legacy.client"
}

Weitere Informationen zum Authorization-Code-Flow finden Sie unter diesem Link. Für jeden Flow enthält der Schlüssel access_token das Token, während der Schlüssel expires_in angibt, nach welcher Zeit (in Sekunden) das Token abläuft. Standardmäßig beträgt die Gültigkeitsdauer eines Access-Tokens 24 Stunden (weitere Informationen finden Sie unter Token lifetimes). Fügen Sie allen Ihren Anfragen den folgenden Authorization-Header hinzu und ersetzen Sie token durch den von Ihnen erhaltenen Wert:

-H "Authorization: Bearer token"

Beachten Sie, dass Sie mehrere Token mit demselben Konto anfordern können. Weitere Informationen zum Autorisierungstoken finden Sie unter diesem Link.

Abrufen des Refresh-Tokens

Wenn die Option Allow issuing refresh tokens to refresh access tokens bei der Konfiguration des Vantage-API-Clients aktiviert war und die Anforderung zum Abrufen des Zugriffstokens den Parameter scope=openid permissions global.wildcard offline_access enthielt, erhalten Sie in der Antwort zusätzlich ein Refresh-Token. Sobald Sie ein Refresh-Token haben, können Sie das Zugriffstoken mit einer POST-Anfrage an den Token-Endpunkt und den folgenden Parametern aktualisieren:

Parameter	Beschreibung
client_id	Die Anwendungs-ID.
client_secret	Ein sicherer Anwendungsschlüssel.
refresh_token	Ihr vom Server erhaltenes Refresh-Token.
grant_type=refresh_token	Gibt an, dass der Grant-Typ „refresh_token“ verwendet wird.

Beispielanfrage: Für 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"

Für 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'

Tokenlaufzeiten

Access- und Refresh-Token sind so konfiguriert, dass sie folgende Laufzeiten haben:

Laufzeit des Access-Tokens: Definiert den Zeitraum, in dem das ausgegebene Access-Token dem Benutzer Zugriff auf Vantage gewährt. Die Standardlaufzeit eines Access-Tokens beträgt 24 Stunden.
Laufzeit des Refresh-Tokens: Definiert den absoluten Zeitraum ab der Ausstellung des ersten Access-Tokens, in dem das ausgegebene Refresh-Token verwendet werden kann, um das Access-Token zu erneuern. Die Standardlaufzeit eines Refresh-Tokens beträgt 30 Tage.

Übersicht

Entwicklerhandbuch

Abrufen des Autorisierungscodes

Abrufen des Autorisierungs-Tokens

Abrufen des Refresh-Tokens

Tokenlaufzeiten

​Abrufen des Autorisierungscodes

​Abrufen des Autorisierungs-Tokens

​Abrufen des Refresh-Tokens

​Tokenlaufzeiten

Abrufen des Autorisierungscodes

Abrufen des Autorisierungs-Tokens

Abrufen des Refresh-Tokens

Tokenlaufzeiten