Hitachi

JP1 Version 12 JP1/Integrated Management 2 - Manager コマンド・定義ファイル・APIリファレンス


5.2.8 REST APIの認証方法

APIのリクエストを発行してレスポンスを取得するには,ユーザー認証を受ける必要があります。インテリジェント統合管理基盤の認証方法には,次に示す種類があります。

〈この項の構成〉

(1) ログインAPIによる認証

ログインAPIによる認証の流れを次に示します。

  1. ログインAPIを呼び出す。

    JP1ユーザー名とパスワードで認証を行い,token情報とCookie情報を取得します。ログインAPIについては「5.4.1 ログイン」を参照してください。

  2. 任意のREST APIを呼び出す。

    ログインAPIで取得したtoken情報を,次の形式でHTTPリクエストヘッダーに設定してREST APIを呼び出します。

    呼び出し対象となるのはloginlogout以外のREST APIです。

    リクエストヘッダー

    Authorization

    設定値

    "Bearer△" +tokenの文字列

    (凡例)

      △:半角スペース

    設定例

    ログインAPIで取得したtoken情報が"anAxYWRtaW46TUdGa01tTTJNMlV3TURFNFh6STNYekE0T2p"の場合の設定例を次に示します。

    Authorization: Bearer anAxYWRtaW46TUdGa01tTTJNMlV3TURFNFh6STNYekE0T2p

  3. ログアウトAPIを呼び出す。

    ログインAPIで取得したCookie情報で,ログイン中の認証情報を破棄します。ログアウトAPIについては「5.4.2 ログアウト」を参照してください。

(2) REST APIに付加したログイン情報による認証(Basic認証)

REST APIに付加したログイン情報によるBasic認証の流れを次に示します。

Basic認証の設定は,デフォルトで無効です。有効にする場合はインテリジェント統合管理基盤定義ファイル(imdd.properties)のjp1.imdd.authBasicプロパティにtrueを指定する必要があります。

インテリジェント統合管理基盤定義ファイル(imdd.properties)については,「インテリジェント統合管理基盤定義ファイル(imdd.properties」(2. 定義ファイル)を参照してください。

  1. 任意のREST APIを呼び出す。

    REST API呼び出し時のHTTPリクエストヘッダーに,認証方式"Basic"に続けて,ユーザー名とパスワードを":"(ASCII:0x3A)で連結した文字列をBase64エンコードしたもの(basic tokenと呼びます)を指定します。

    リクエストヘッダー

    Authorization

    設定値

    "Basic△" + JP1ユーザー名:パスワードをBase64エンコードしたASCII文字列

    (凡例)

      △:半角スペース

    設定例

    JP1ユーザーが"jp1user",パスワードが"password"の場合に,"jp1user:password"をBase64エンコードした文字列"anAxdXNlcjpwYXNzd29yZA=="を使用して,次に示すようにbasic tokenを設定します。

    Authorization: Basic anAxdXNlcjpwYXNzd29yZA==

重要
  • Basic認証はステートレスな認証手段のため,リクエストヘッダーにCookieは指定しないでください。

  • Basic認証はHTTP,およびHTTPSのどちらも使用できますが,セキュリティの向上のため,HTTPSによるアクセスを推奨します。

  • REST APIを実行するたびに認証サーバで認証を行うため,認証サーバには,ユーザー管理機能に関するメッセージが実行のたびに出力されます。認証サーバ内に統合トレースログを出力するシステムが混在している場合は,ユーザー管理機能に関するメッセージで統合トレースを圧迫してしまう可能性を考慮し,システム構成の設計をしてください。

(3) REST APIに付加したログイン情報による認証(OpenID認証)

REST APIに付加したログイン情報によるOpenID認証の流れを次に示します。

OpenID認証の設定は,デフォルトで無効です。有効にする場合はインテリジェント統合管理基盤定義ファイル(imdd.properties)でOpenIDプロバイダに関するプロパティの設定が必要です。

インテリジェント統合管理基盤定義ファイル(imdd.properties)については,「インテリジェント統合管理基盤定義ファイル(imdd.properties」(2. 定義ファイル)を参照してください。

  1. 任意のREST APIを呼び出す。

    REST API呼び出し時のHTTPリクエストヘッダーに,認証方式"Bearer"に続けて,OpenIDプロバイダから取得したアクセストークンを指定します。

    リクエストヘッダー

    Authorization

    設定値

    "Bearer△" + アクセストークンの文字列

    (凡例)

      △:半角スペース

    • インテリジェント統合管理基盤側で複数のOpenIDプロバイダを認証基盤として設定している場合,REST API呼び出し時のHTTPリクエストヘッダーX-Token-Issuerに,インテリジェント統合管理基盤定義ファイル(imdd.properties)で定義したOpenIDプロバイダのキー名(アクセストークンの発行者)を指定する必要があります。

    • インテリジェント統合管理基盤側でREST APIの処理を受け付けした際に,HTTPリクエストヘッダーX-Token-Issuerの指定がない場合,またはX-Token-Issuerに指定した値とインテリジェント統合管理基盤定義ファイル(imdd.properties)で定義したOpenIDプロバイダのキー名が一致しない場合は認証エラーとなり,REST APIの呼び出し元にステータスコード403とエラーメッセージKAJY52030-Eが返却されます。

    • インテリジェント統合管理基盤側で一つのOpenIDプロバイダだけを認証基盤として設定している場合,REST API呼び出し時のHTTPリクエストヘッダーX-Token-Issuerの指定を省略できます。省略した場合,インテリジェント統合管理基盤定義ファイル(imdd.properties)で定義されているOpenIDプロバイダをアクセストークンの発行者と仮定して,処理を実行します。

    • X-Token-Issuerはインテリジェント統合管理基盤の独自定義のリクエストヘッダーです。フォーマットを次に示します。

      リクエストヘッダー

      設定値

      X-Token-Issuer

      アクセストークンを発行したOpenIDプロバイダ名です。

      インテリジェント統合管理基盤定義ファイル(imdd.properties)で定義したOpenIDプロバイダのキー名の値を指定します。

    設定例1

    ・アクセストークンの発行者がKeycloak

    ・インテリジェント統合管理基盤側定義ファイルに一つのOpenIDプロバイダを認証基盤として設定している

     OpenIDプロバイダのキー名(Keycloak)

    ・OpenIDプロバイダから取得したアクセストークンが"ABCDEFG.HIJKLMN.OPQRSTUVWXYZ"

    次に示すようにリクエストヘッダーにアクセストークンを設定します。

    Authorization: Bearer ABCDEFG.HIJKLMN.OPQRSTUVWXYZ

    設定例2

    ・アクセストークンの発行者がKeycloak

    ・インテリジェント統合管理基盤側で複数のOpenIDプロバイダ(Keycloak,Okta)を認証基盤として設定している

     OpenIDプロバイダのキー名(Keycloak)

     OpenIDプロバイダのキー名(Okta)

    ・OpenIDプロバイダから取得したアクセストークンが"ABCDEFG.HIJKLMN.OPQRSTUVWXYZ"

    次に示すようにリクエストヘッダーにアクセストークンとトークン発行者を設定します。

    Authorization: Bearer ABCDEFG.HIJKLMN.OPQRSTUVWXYZ

    X-Token-Issuer: Keycloak

重要
  • HTTP,およびHTTPSのどちらも使用できますが,OpenID認証を使用する場合は,中間者攻撃の対策としてHTTPSでの運用を強く推奨します。運用時は必ずHTTPSによるアクセスを使用してください。

  • インテリジェント統合管理基盤で使用するJP1ユーザー名とOpenIDプロバイダに登録されているユーザー名のマッピングのため,アクセストークンのpreferred_usernameクレームにOpenIDプロバイダのログインユーザー名を含める必要があります。アクセストークンの発行者がKeycloakの場合,preferred_usernameクレームはデフォルトでアクセストークンに設定されます。Oktaの場合は手動で設定する必要があります。設定方法については,Oktaのドキュメントを参照してください。

    preferred_usernameクレームが設定されていない場合は,エラーメッセージKAJY52028-Eが返却されます。シングルサインオンマッピングの定義については「シングルサインオンマッピング定義ファイル(imdd_sso_mapping.properties」(2. 定義ファイル)参照してください。