5.2.8 REST APIの認証方法
APIのリクエストを発行してレスポンスを取得するには,ユーザー認証を受ける必要があります。インテリジェント統合管理基盤の認証方法には,次に示す種類があります。
-
ログインAPIによる認証
-
REST APIに付加したログイン情報による認証(Basic認証)
-
REST APIに付加したログイン情報による認証(OpenID認証)
- 〈この項の構成〉
(1) ログインAPIによる認証
ログインAPIによる認証の流れを次に示します。
-
ログインAPIを呼び出す。
JP1ユーザー名とパスワードで認証を行い,token情報とCookie情報を取得します。ログインAPIについては「5.4.1 ログイン」を参照してください。
-
任意のREST APIを呼び出す。
ログインAPIで取得したtoken情報を,次の形式でHTTPリクエストヘッダーに設定してREST APIを呼び出します。
呼び出し対象となるのはlogin,logout以外のREST APIです。
- リクエストヘッダー
-
Authorization
- 設定値
-
"Bearer△" +tokenの文字列
(凡例)
△:半角スペース
- 設定例
-
ログインAPIで取得したtoken情報が"anAxYWRtaW46TUdGa01tTTJNMlV3TURFNFh6STNYekE0T2p"の場合の設定例を次に示します。
Authorization: Bearer anAxYWRtaW46TUdGa01tTTJNMlV3TURFNFh6STNYekE0T2p
-
ログアウト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. 定義ファイル)を参照してください。
-
任意の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. 定義ファイル)を参照してください。
-
任意の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. 定義ファイル)参照してください。
-