認可コードフロー

この認証方式は最も安全と考えられます。認証リクエストをユーザーに直接送るのではなく、アプリケーションが Vantage の認可サーバーに送信するためです。認可サーバーがユーザーを認証し、クライアントに認可コードを返します。認可コードの傍受を防ぐために、この認証シナリオでは PKCE (Proof Key for Code Exchange) というセキュリティ拡張を使用します。動作は次のとおりです。各認可リクエストで暗号学的に安全な乱数を生成して code_verifier に保存し、それを用いて code_challenge に格納する暗号学的に導出された値を生成します。続いてこの値を認可サーバーへ送信し、認可コードを取得します。 PKCE の詳細についてはこちらをご覧ください。

認可コードの取得

認証プロセスを開始するには、以下のパラメーターを渡してユーザーを authorize エンドポイントにリダイレクトします。

Parameter	説明
client_id	アプリケーション識別子。Vantage API Client (client_id と client_secret) の作成方法については、「Managing Tenant Vantage API Clients」を参照してください。
redirect_uri	アクセス権限が付与された後にブラウザーをリダイレクトするために使用する、アプリケーションまたは Web サイトの URL。
response_type=code	認可コードのレスポンスタイプを使用することを指定します。
scope=openid permissions global.wildcard	権限スコープを指定します。
state	レスポンスに認可結果を含めるための任意の文字列値。
code_challenge	code_verifier コードのデジタル署名値 (code_challenge_method メソッドを使用) 。
code_challenge_method	code_verifier コードのデジタル署名方式 (S256) 。
productId=a8548c9b-cb90-4c66-8567-d7372bb9b963	Vantage の識別子。

response_type、scope、productId の値は、必ず上記のとおり正確に指定してください。response_type を除くこれらのキーは変更される可能性があります。設定で管理することをお勧めします。

サンプルリクエスト

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

リソースの識別子を含む redirect_uri パラメーターは OAuth 2.0 で使用されます。これにより、Vantage は認可コードをリソースに送信し、そのコードをアクセストークンに交換できます。アクセストークンは、以降のすべての API call での認証に必要です。この認証方法を使用するには、redirect_uri パラメーターの値を ABBYY technical support に提供し、管理者によってホワイトリストに登録してもらう必要があります。 scope パラメーターで要求したアクセス権限の付与が確認されると、ブラウザーは Vantage server で設定された専用の Web ページにリダイレクトされます。この Web ページには、アカウントを使用して認可を行うためのダイアログウィンドウが表示されます。このページは、ページ URL と接続の SSL 証明書の状態を確認できるよう、アドレスバーが表示されるブラウザーで開く必要があります。メールアドレスが異なるテナントの複数のアカウントに関連付けられている場合は、メールアドレスを指定した後にテナントを選択してパスワードを入力するよう求められます。次のいずれかのリソースを使用して、テナント識別子 (tokenId パラメーター) を直接指定することもできます。

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

テナントアカウントのパスワードを入力する必要があります。認証情報を入力すると、サーバー側で認可が完了し、アプリケーションに Vantage API へのアクセス権が付与され、リクエストに対するレスポンスで認可コードを受け取ります。この認証タイプをサイトまたはアプリケーションが使用する場合、Vantage ユーザーは、自分に代わって、許可されたリダイレクト URL のリストに追加するそのサイトまたはアプリに Vantage API へのアクセス権を与えることになります。サイトまたはアプリにアクセス権を与えるために、ユーザーは自分のログイン名とパスワードを使って Vantage にログインして認証を行うよう求められます。ユーザーが認証されると、そのサイトまたはアプリには次の権限が付与されます。

ユーザーに代わって Vantage テナント内のデータカタログを管理すること
ユーザーに代わって Vantage テナント内の Skill にアクセスすること
ユーザーに代わって Vantage トランザクションを作成および参照すること

そのサイトまたはアプリは、ユーザーのパスワードを変更したり、Vantage テナントのユーザー一覧を変更したり、Skill を編集したりすることはできません。許可されるのは Vantage API へのアクセスのみです。一度アクセス権が付与されると、ユーザーがそのアクセス権を取り消すことはできません。

認可トークンの取得

認可コードを取得したら、1分以内にアクセストークンへ交換します。application/x-www-form-urlencoded データを使用して、トークンエンドポイントに POST リクエストを送信します。リクエスト本文のパラメーター:

Parameter	説明
code_verifier	生成したコード。認可リクエストの開始を確認するために必要です。
client_id	アプリケーションの識別子。
client_secret	アプリケーションの機密キー。
code	サーバーから取得した認可コード。
redirect_uri	認可ステップで使用したリダイレクト URL。
grant_type=authorization_code	認可コードのグラントタイプを使用することを指定します。
scope=openid permissions global.wildcard offline_access	権限スコープを指定します。Refresh トークンを取得するには、スコープに offline_access を追加します。

サンプルリクエスト: 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"

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'

サーバーからの応答にはアクセストークンが含まれます。

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

認可コードフローの詳細は、こちらをご覧ください。各フローでは、access_token キーにトークンが格納され、expires_in キーにトークンの失効までの時間（秒）が指定されます。デフォルトでは、アクセストークンの有効期間は 24 時間です（詳細は Token lifetimes を参照してください）。すべてのリクエストに次の Authorization ヘッダーを追加し、token を取得した値に置き換えてください。

-H "Authorization: Bearer token"

同じアカウントを使用して複数のトークンを取得することもできます。認可トークンの詳細については、こちらを参照してください。

Refresh トークンの取得

Vantage API クライアントを設定する際に Allow issuing refresh tokens to refresh access tokens オプションを有効にし、アクセストークンを取得するためのリクエストに scope=openid permissions global.wildcard offline_access パラメーターが含まれていた場合、レスポンスとして追加の Refresh トークンも受け取ります。Refresh トークンを取得したら、次のパラメーターを指定してトークンエンドポイントに POST リクエストを送信することで、アクセストークンを更新できます。

Parameter	Description
client_id	アプリケーション識別子。
client_secret	アプリケーションの機密キー。
refresh_token	サーバーから取得した Refresh トークン。
grant_type=refresh_token	Refresh トークンのグラントタイプを使用することを指定します。

サンプルリクエスト: 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"

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'

トークンの有効期間

Access トークンと Refresh トークンには、次の有効期間が設定されています。

Access トークンの有効期間: 発行された Access トークンを使用してユーザーが Vantage にアクセスできる期間を定義します。Access トークンの既定の有効期間は 24 時間です。
Refresh トークンの有効期間: 最初の Access トークンが発行された時点から起算される固定の期間を定義し、その期間中は発行された Refresh トークンを使用して Access トークンを更新できます。Refresh トークンの既定の有効期間は 30 日です。

概要

開発者ガイド

認可コードの取得

認可トークンの取得

Refresh トークンの取得

トークンの有効期間

​認可コードの取得

​認可トークンの取得

​Refresh トークンの取得

​トークンの有効期間

認可コードの取得

認可トークンの取得

Refresh トークンの取得

トークンの有効期間