Documentation Index
Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
Use this file to discover all available pages before exploring further.
この認証方式は最も安全と考えられます。認証リクエストをユーザーに直接送るのではなく、アプリケーションが Vantage の認可サーバーに送信するためです。認可サーバーがユーザーを認証し、クライアントに認可コードを返します。
認可コードの傍受を防ぐために、この認証シナリオでは PKCE (Proof Key for Code Exchange) というセキュリティ拡張を使用します。動作は次のとおりです。各認可リクエストで暗号学的に安全な乱数を生成して code_verifier に保存し、それを用いて code_challenge に格納する暗号学的に導出された値を生成します。続いてこの値を認可サーバーへ送信し、認可コードを取得します。
PKCE の詳細については こちらをご覧ください。
To begin the authentication process, redirect the user to the authorize endpoint, passing the following parameters:
| Parameter | Description |
|---|
| client_id | The application identifier. For information on how to create a Vantage API Client (client_id and client_secret), see the Managing Tenant Vantage API Clients article. |
| redirect_uri | The URL of your application or website that is used to redirect the browser once access permissions have been granted. |
| response_type=code | Specifies that the authorization code response type is used. |
| scope=openid permissions global.wildcard | Specifies the permission scope. |
| state | An arbitrary string value that will contain the authorization result in the response. |
| code_challenge | Digitally signed value of the code_verifier code (using the code_challenge_method method). |
| code_challenge_method | The digital signature method for the code_verifier code (S256). |
| productId=a8548c9b-cb90-4c66-8567-d7372bb9b963 | The Vantage identifier. |
The values for response_type, scope, productId should be exactly as specified above. These keys, except response_type, are subject to change. Consider keeping them in configuration.
Sample Request
認証プロセスを開始するには、以下のパラメーターを渡して authorize エンドポイントにユーザーをリダイレクトします。
| Parameter | 説明 |
|---|
| client_id | アプリケーション識別子。Vantage API Client（client_id と client_secret）の作成方法については、「Managing Tenant Vantage API Clients」を参照してください。 |
| redirect_uri | アクセス権限が付与された後にブラウザーをリダイレクトするために使用される、アプリケーションまたはウェブサイトの 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 を除くこれらのキーは変更される可能性があります。設定で管理することを検討してください。
または
resource の識別子を含む redirect_uri というパラメーターは、OAuth 2.0 で使用され、Vantage が認可コードをあなたの resource に送信し、その後そのコードをアクセストークンと交換できるようにします。アクセストークンは、以降のすべての API 呼び出しでの認証に必要です。この認証方法を使用するには、redirect_uri パラメーターの値を ABBYY のテクニカルサポートに提供し、管理者によるホワイトリスト登録を受ける必要があります。
scope パラメーターで要求したアクセス権限が付与されていることが検証されると、ブラウザーは Vantage サーバーが用意した専用のウェブページにリダイレクトされます。このウェブページには、あなたのアカウントで認可を行うためのダイアログウィンドウが表示されます。このページは、ページの URL と接続の SSL 証明書の状態を確認できるよう、アドレスバーが表示されるブラウザーで開く必要があります。
あなたのメールアドレスが異なるテナント内の複数のアカウントに関連付けられている場合、メールアドレスを入力した後に、テナントの選択とパスワードの入力を求められます。次のいずれかのリソースを使用して、テナント識別子（tokenId パラメーター）を直接渡すこともできます。
テナントアカウントのパスワードを入力する必要があります。認証情報を入力すると、認可はサーバー側で完了し、アプリケーションに 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 | 権限スコープを指定します。リフレッシュトークンを取得するには、スコープに offline_access を追加します。 |
{
"id_token": "<redacted>",
"access_token": "<redacted>",
"expires_in": 86400,
"token_type": "Bearer",
"refresh_token": "<redacted>",
"scope": "openid permissions global.wildcard offline_access legacy.client"
}
token を取得したトークンの値に置き換えてください。
-H "Authorization: Bearer token"
Allow issuing refresh tokens to refresh access tokens オプションを有効にし、アクセストークンを取得するためのリクエストに scope=openid permissions global.wildcard offline_access パラメーターが含まれていた場合、レスポンスとして追加のリフレッシュトークンも受け取ります。リフレッシュトークンを取得したら、次のパラメーターを指定してトークンエンドポイントに POST リクエストを送信することで、アクセストークンを更新できます。
| Parameter | Description |
|---|
| client_id | アプリケーション識別子。 |
| client_secret | アプリケーション用の機密キー。 |
| refresh_token | サーバーから取得したリフレッシュトークン。 |
| grant_type=refresh_token | リフレッシュトークンのグラントタイプを使用することを指定します。 |
- Access トークンの有効期間: 発行された Access トークンを使用してユーザーが Vantage にアクセスできる期間を定義します。Access トークンの既定の有効期間は 24 時間です。
- Refresh トークンの有効期間: 最初の Access トークンが発行された時点から起算される固定の期間を定義し、その期間中は発行された Refresh トークンを使用して Access トークンを更新できます。Refresh トークンの既定の有効期間は 30 日です。
