intra-mart Accel Platform Webサービス 認証・認可 仕様書 第5版 2017-04-01

認証・認可

機能概要

intra-mart Accel Platform では、Webサービス 実行時に、認証、認可および intra-mart Accel Platform へのログインを行います。認証・認可を用いて Webサービス・クライアント から利用可能な Webサービス を制限します。

認証

受信したユーザ情報のユーザが intra-mart Accel Platform を利用可能であるかを確認します。
認証に失敗した場合、Webサービス を実行することはできません。
これにより、ユーザベースでのアクセス制御を行うことが可能です。

認可

受信したユーザ情報のユーザによる Webサービス・オペレーション の実行が「許可」されているかどうかを確認します。
これにより、権限ベースでのアクセス制御を行うことが可能です。
認可に関する詳細な情報は、「認可仕様書」を参照してください。
Webサービス への認可リソースの設定はservices.xmlで行います。
詳細は「services.xmlに認可リソースを指定する」を参照してください。
管理者による認可設定方法については、「Webサービス・オペレーション への認可設定」を参照してください。

ログイン

認証、認可が行われた後、ログインを行います。これにより Webサービス 実装者はログイン処理を意識することなく、業務処理の実装を行うことが可能です。
加えて、既存の業務処理の再利用が容易になります。具体的には アクセスコンテキスト を利用した処理を Webサービス の業務処理としてそのまま利用可能になります。
アクセスコンテキスト に関する詳細な情報は以下のドキュメントを参照してください。

システム概要

認証・認可の流れ

Webサービス に対する認証・認可の流れは以下の通りです。
../../_images/flow.png
SOAPボディ に格納されたユーザ情報を元に認証・認可を行います。詳細は「認証モジュール」を参照してください。

ユーザ情報

ユーザ情報は、以下で構成されています。
  • ログイングループID
  • ユーザID
  • 認証タイプ
  • パスワード
ログイングループIDに指定する値については、ログイングループID を参照してください。
ユーザIDにはアカウントのユーザコードを指定します。
認証タイプは Webサービス・プロバイダ で利用する 認証モジュール を指定します。
パスワードに格納する内容は、認証タイプによって異なります。

ログイングループID

認証・認可と Webサービス を実行する対象のテナントを指定します。
指定するべき値は、intra-mart Accel Platform のバージョンや設定により異なります。
intra-mart Accel Platform 2013 Winter 以前の場合
ログイングループIDには特に何も指定しなくてもかまいません。(指定した値により 認証・認可や Webサービス の動作が変わることはありません。)
intra-mart Accel Platform 2014 Spring 以降の場合
ログイングループIDには Webサービス 実行対象となるテナントのテナントIDを指定します。
ログイングループIDを省略した場合の動作は以下の通りです。
リクエスト情報を利用したテナント自動解決機能を利用している場合
リクエスト情報を利用して自動解決されたテナントで認証・認可と Webサービス の実行を行います。
ただし、Webサービス・プロバイダ の認証・認可の設定wsTenantIdResolveType 設定が strict である場合は省略できません。(省略した場合、SOAPフォルト wsse:InvalidLoginGroupID が発生します。)
リクエスト情報を利用したテナント自動解決機能を利用していない場合
デフォルトテナントで認証・認可と Webサービス の実行を行います。

コラム

「リクエスト情報を利用したテナント自動解決機能」については、セットアップガイドの「テナント解決機能」を参照してください。

WSDL におけるユーザ情報の定義について

ユーザ情報 で述べたユーザ情報を受け渡すためのメッセージ形式を WSDL に定義する必要があります。
具体的には、下記のXMLスキーマで定義される型 WSUserInfo を Webサービス・オペレーション の第1引数に要素名 wsUserInfo として定義する必要があります。
<xs:schema
   attributeFormDefault="qualified"
   elementFormDefault="qualified"
   targetNamespace="http://auth.web_service.foundation.intra_mart.co.jp/xsd">
   <xs:complexType name="WSUserInfo">
      <xs:sequence>
         <xs:element minOccurs="0" name="authType" nillable="true" type="xs:string"/>
         <xs:element minOccurs="0" name="loginGroupID" nillable="true" type="xs:string"/>
         <xs:element minOccurs="0" name="password" nillable="true" type="xs:string"/>
         <xs:element minOccurs="0" name="userID" nillable="true" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
</xs:schema>

コラム

引数の要素名 wsUserInfoWebサービス・プロバイダ の認証・認可の設定<wsUserInfoArgumentName>タグ で設定しています。

コラム

認証・認可を必要としない Webサービス についてはこの限りではありません。
詳細は「認証・認可を必要としない Webサービス について」を参照してください。

認証モジュール実行クラス

認証モジュール を実行するための org.apache.axis2.engine.Handler を実装した Apache Axis2 ハンドラです。
このハンドラは Webサービス・クライアント が送信したユーザ情報を解析後、認証タイプで特定される 認証モジュール に認証・認可処理を委譲しています。
intra-mart Accel Platform 2014 Spring 以降では、ユーザ情報の ログイングループID の値により、認証・認可と Webサービス を実行する対象となるテナントへの切り替えを行います。
このクラスは Axis2 モジュール 「im_ws_auth」が適用されている Webサービス に対して実行されます。

認証モジュール

認証・認可・ログインを行います。
詳細は、後述の「認証モジュール」を参照してください。

Webサービス の実装クラス(Webサービス・プロバイダ)

Webサービス として公開する業務処理が記述されたクラスです。
認証モジュール の各処理がすべて正常終了した後に、Webサービス・クライアント が要求した Webサービス・オペレーション が実行されます。そのため、Webサービス の実装クラスは認証・認可・ログインを考慮することなく業務処理を記述することが可能です。
Webサービス 実行後はログアウトを行います。従って、Webサービス 実行中のみユーザ情報で指定したユーザがログイン状態となります。
Webサービス・オペレーション の認証・認可・ログインを行うには、Webサービス・オペレーション に対して以下の2つの条件が満たされている必要があります。
  • Axis2 モジュール 「im_ws_auth」が適用されていること
  • ユーザ情報 を格納するための引数が第1引数に付与されていること

Webサービス・クライアント

Webサービス・クライアント では、WSDL からスタブを作成するなどして、Webサービス を呼び出します。WSDL の中にはユーザ情報を受け渡すためのメッセージ形式が定義されています。(WSDL におけるユーザ情報の定義について
これに則り、Webサービス・クライアント はユーザ情報を設定します。
Webサービス・プロバイダ で実行される 認証モジュール は、Webサービス・クライアント で指定された ユーザ情報 の認証タイプにより決定します。
認証タイプが未設定の場合、平文パスワード用認証モジュール が利用されます。
平文パスワード用認証モジュール についての詳細は、「平文パスワード用認証モジュール」を参照してください。

注意

Webサービス・プロバイダ に存在しない認証タイプを指定した場合は、SOAPフォルト (wsse:BadRequest)が発生します。

認証モジュール

認証モジュールでは、認証、認可およびログインを行います。
Webサービス 実行時に使用する 認証モジュールは Webサービス・クライアント から送信されたユーザ情報の認証タイプにより、決定します。
認証、認可およびログインで行う処理は利用する認証モジュールごとに異なります。各認証モジュールでの、認証・認可およびログイン処理については後述の各認証モジュールの仕様を参照してください。
認証モジュールは jp.co.intra_mart.foundation.web_service.auth.WSAuthModule インタフェースを利用して動作しています。
認証モジュールは、以下の順番で処理を行います。
  1. 初期化(WSAuthModule#init(WSUserInfo, MessageContext) が実行されます。)
  2. SOAP メッセージのチェック(WSAuthModule#check(WSUserInfo, MessageContext) が実行されます。)
  3. 認証(WSAuthModule#authentication(WSUserInfo) が実行されます。)
  4. 認可(WSAuthModule#authorization(WSUserInfo, String, String) が実行されます。)
  5. ログイン(WSAuthModule#login(WSUserInfo) が実行されます。)
この一連の処理は、Webサービス・クライアント から要求があるたびに実行されます。
認証・認可などすべての処理に成功した場合のみ指定された Webサービス・オペレーション が実行されます。
各処理のいずれかに失敗するとエラーコードを格納した SOAPフォルト が Webサービス・クライアント に返却されます。
エラーコードの詳細については「認証・認可のSOAPフォルト・コード」を参照してください。
WSAuthModuleの詳細は、「WSAuthModuleインタフェースのAPIリスト」を参照してください。
intra-mart Accel Platform では標準で以下の認証モジュールが提供されています。
認証タイプ 提供モジュール 実装クラス名 概要
WSSE Webサービス 認証・認可 WSAuthModule4WSSE パスワードのダイジェスト化方法に、WS-SecurityのUsernameToken形式を採用した認証モジュール。
PlainTextPassword Webサービス 認証・認可 WSAuthModule4PlainTextPassword 平文パスワード用認証モジュール。
Anonymous Webサービス 認証・認可 WSAuthModule4Anonymous 未認証ユーザ用認証モジュール。

WSSE認証モジュール

WSSE認証モジュール は、パスワード・ダイジェスト 化方式にWS-SeurityのUsernameToken形式を採用した認証モジュールです。
完全修飾クラス名は jp.co.intra_mart.foundation.web_service.auth.impl.WSAuthModule4WSSE です。
Webサービス・クライアント は、以下を元に パスワード・ダイジェスト を作成します。
  • Webサービス・クライアント が作成した「Nonce」
  • Webサービス・クライアント が作成した「Created」
  • Webサービス・クライアント が管理している認証対象ユーザの「パスワード」
WS-SecurityのUsernameToken形式の認証用文字列(以降、WSSE認証文字列)の具体例を示します。
UsernameToken Username="the_who", PasswordDigest="tLDSsdGqfvraHRh8BpqTYRBVy+U=", Nonce="YTBiMWI2OGI2OTE3N2RlZQ==", Created="1966-12-01T12:34:56Z"
Webサービス・プロバイダ の認証モジュールでは、WSSE認証文字列 を解析し以下を元に パスワード・ダイジェスト を作成します。
  • Webサービス・クライアント から送られてきた「Nonce」
  • Webサービス・クライアント から送られてきた「Created」
  • Webサービス・プロバイダ のサーバで管理されている認証対象ユーザの「パスワード」
Webサービス・クライアント から送信された パスワード・ダイジェスト と Webサービス・プロバイダ で作成した パスワード・ダイジェスト を比較し、その結果が同一であれば該当ユーザである(認証に成功)と判断します。同一でない場合は不正なユーザであると判別します。
WSSE認証文字列 の各項目は以下の通りです。
項目 説明
Username ユーザ名(ユーザコード)。
Nonce ランダムな値をBase64エンコードした文字列。
Created Nonceが作成された日時をISO-8601表記で記述した文字列。
PasswordDigest
Nonce、Createdおよびパスワードを文字列連結し、SHA-1アルゴリズムでダイジェスト化して生成された文字列を、Base64エンコーディングした文字列。
具体的な作成方法は以下の通りです。

PasswordDigest = Base64 ( SHA-1 ( Nonce + Created + パスワード))
認可はユーザ情報で指定されたユーザIDのユーザに対して行います。

コラム

WSSE認証モジュール は パスワード・ダイジェスト の有効期限チェックを行います。
Createdの時間と比較し有効期限が経過している場合、認証に失敗します。有効期限の初期値は5分です。
有効期限の設定については「WSSE認証モジュール <expire>タグ」を参照してください。

コラム


上記の仕様と WSSE認証モジュール で生成する パスワード・ダイジェスト の相違点は以下の通りです。
  • NonceおよびCreatedが必須である
  • Nonceの符号化の種類が常にBase64である

注意

受信した WSSE認証文字列 のCreatedとNonceを有効期限まで Webサービス・プロバイダ で保持します。既に保持されているCreatedとNonceで認証しようとした場合、認証に失敗します。このチェックは、クラスタ単位で行います。

注意

認証対象のユーザは ユーザ情報 から特定します。WSSE認証文字列 のUsernameは利用しません。

注意

パスワードの保存方式が「ハッシュ化」方式である場合に利用できません。
パスワードの保存方式については「 システム管理者操作ガイド 」-「 パスワード保存方式設定 」を参照してください。

WSSE パスワード・ダイジェスト 生成API

認証タイプWSSEに対応した パスワード・ダイジェスト 生成用のユーティリティAPIは以下の通りです。
  • スクリプト開発モデル API

    WSAuthDigestGenerator4WSSE オブジェクト

  • Java API

    jp.co.intra_mart.foundation.web_service.util.impl.WSAuthDigestGenerator4WSSE

このAPIは Webサービス 認証・認可クライアント モジュールに同梱されています。
詳細な情報は、「WSAuthDigestGenerator4WSSEオブジェクトのAPIリスト」、または「WSAuthDigestGenerator4WSSEクラスのAPIリスト」を参照してください。

平文パスワード用認証モジュール

平文パスワード用認証モジュール は、パスワードを平文で送受信するための認証モジュールです。
完全修飾クラス名は jp.co.intra_mart.foundation.web_service.auth.impl.WSAuthModule4PlainTextPassword です。
ユーザ情報で指定されたパスワードが Webサービス・プロバイダ のサーバに登録されているアカウントのパスワードと一致した場合該当ユーザである(認証に成功)と判断します。
認可はユーザ情報で指定されたユーザIDのユーザに対して行います。

コラム

Webサービス・クライアント から送信される認証タイプが未設定の場合、この認証モジュールを利用します。

注意

平文パスワード用認証モジュール は標準では利用できません。

注意

平文パスワード用認証モジュール はパスワードが平文で送信されるため、SOAP メッセージの中身やネットワーク通信内容を閲覧可能な利用者による成り済ましが可能になることに注意してください。
この認証モジュールはSSLのような外部のセキュアなシステムと併用されないのであれば利用すべきではありません。

未認証ユーザ用認証モジュール

未認証ユーザ用認証モジュール は、未認証ユーザ で Webサービス を実行するための認証モジュールです。
完全修飾クラス名は jp.co.intra_mart.foundation.web_service.auth.impl.WSAuthModule4Anonymous です。
未認証ユーザ とは、ログインを行っていないユーザのことを指します。(ゲストユーザともいいます)
この認証タイプを利用した場合、認証処理は行われません。
認可処理は特定のユーザに対してではなく、未認証ユーザ に対して認可を行います。
ユーザ情報に格納されている、ユーザIDとパスワードは無視されます。

注意

未認証ユーザ用認証モジュール は標準では利用できません。設定方法については「認証モジュールを追加する」を参照してください。

独自の認証モジュール利用する

以下を行うことで独自に認証モジュールを利用することも可能です。
  • jp.co.intra_mart.foundation.web_service.auth.WSAuthModule インタフェースを実装したクラスを作成する
  • %CONTEXT_PATH%/WEB-INF/conf/axis2.xml に <authModule> タグを設定する
WSAuthModuleの詳細は、「WSAuthModuleインタフェースのAPIリスト」を参照してください。
%CONTEXT_PATH%/WEB-INF/conf/axis2.xml の詳細は「Webサービス・プロバイダ の認証・認可の設定」を参照してください。
作成した認証モジュールの設定方法については「認証モジュールを追加する」を参照してください。

Webサービス・オペレーション への認可設定

intra-mart Accel Platform では認可設定により Webサービス・オペレーション へのアクセス権限を設定します。
  1. 「サイトマップ」→「テナント管理」→「認可」をクリックします。

  2. リソースの種類を「Webサービス」に変更します。

    ../../_images/authz_resourcetype.png
  3. 「権限設定を開始する」をクリックし、認可設定を行います。

認可設定画面の詳細な操作方法は、「テナント管理者操作ガイド 認可を設定する」を参照してください。

コラム

認可設定画面を利用するには、標準では以下のいずれかを満たすユーザでログインする必要があります。

  • テナント管理者ロールを保持している
  • 認可管理者ロールを保持している

Webサービス・プロバイダ の認証・認可の設定

Webサービス・プロバイダ による認証・認可の設定は %CONTEXT_PATH%/WEB-INF/conf/axis2.xml で行います。
設定は、parameter名 jp.co.intra_mart.foundation.web_service の子要素として記述します。

コラム

IM-Juggling では設定ファイル出力機能にて「Webサービス 認証・認可」の「Axis2設定(axis2.xml)」より出力が行えます。

注意

この設定は Axis2 モジュール 「im_ws_auth」 が適用されている Webサービス すべてに対して影響します。

以下は設定例です。
<axisconfig name="AxisJava2.0">

    <!-- ================================================= -->
    <!-- Parameters for intra-mart -->
    <!-- ================================================= -->
    <parameter name="jp.co.intra_mart.foundation.web_service">

        <enablePlainTextPassword>false</enablePlainTextPassword>
        
        <authModule class="jp.co.intra_mart.foundation.web_service.auth.impl.WSAuthModule4WSSE">
            <expire>300</expire>
        </authModule>

        <enableAuthentication>true</enableAuthentication>
        <enableAuthorization>true</enableAuthorization>
        
        <showSoapFaultDetail>true</showSoapFaultDetail>
        <wsUserInfoArgumentName>wsUserInfo</wsUserInfoArgumentName>
        <wsTenantIdResolveType>standard</wsTenantIdResolveType>

    </parameter>

    <!-- 省略 -->

</axisconfig>

<authModule>タグ

<authModule class="jp.co.intra_mart.foundation.web_service.util.impl.WSAuthDigestGenerator4WSSE">
   <expire>300</expire>
</authModule>
必須項目 ×
複数設定
設定値・設定する内容 なし
単位・型 なし
省略時のデフォルト値 なし
親タグ parameter

【属性】

属性名 説明 必須 デフォルト値
class 認証モジュールを設定します。WSAuthModule インタフェースを実装したクラスの完全修飾クラス名を指定します。 なし

コラム

authModule の子要素は設定値として扱われます。設定値は WSAuthModule#setConfiguration(OMElement) メソッドの引数に渡されます。

<enablePlainTextPassword>タグ

<enablePlainTextPassword>false</enablePlainTextPassword>
必須項目 ×
複数設定 ×
設定値・設定する内容
false 平文パスワード用認証モジュール を利用しません。
true 平文パスワード用認証モジュール を利用することを許可します。
単位・型 真偽値 (true/false)
省略時のデフォルト値 false
親タグ parameter

【属性】

なし

<enableAuthentication>タグ

<enableAuthentication>true</enableAuthentication>
必須項目 ×
複数設定 ×
設定値・設定する内容
true Webサービス 実行前に 認証 を実行します。
false Webサービス 実行前に 認証 を実行しません。
単位・型 真偽値 (true/false)
省略時のデフォルト値 true
親タグ parameter

【属性】

なし

<enableAuthorization>タグ

<enableAuthorization>true</enableAuthorization>
必須項目 ×
複数設定 ×
設定値・設定する内容
true Webサービス 実行前に 認可 を実行します。
false Webサービス 実行前に 認可 を実行しません。
単位・型 真偽値 (true/false)
省略時のデフォルト値 true
親タグ parameter

【属性】

なし

<showSoapFaultDetail>タグ

<showSoapFaultDetail>true</showSoapFaultDetail>
必須項目 ×
複数設定 ×
設定値・設定する内容
true 認証モジュールで行われる処理に失敗した際に SOAPフォルト に詳細メッセージを含めます。
false 認証モジュールで行われる処理に失敗した際に SOAPフォルト に詳細メッセージを含めません。
単位・型 真偽値 (true/false)
省略時のデフォルト値 true
親タグ parameter

【属性】

なし

注意

この設定で行う SOAPフォルト に詳細メッセージを含めるか否かは、認証モジュールで発生した SOAPフォルト についてのみ有効です。Webサービス で発生した SOAPフォルト には影響しません。

<wsUserInfoArgumentName>タグ

<wsUserInfoArgumentName>wsUserInfo</wsUserInfoArgumentName>
必須項目 ×
複数設定 ×
設定値・設定する内容 ユーザ情報を格納するための引数名。
単位・型 文字列
省略時のデフォルト値 wsUserInfo
親タグ parameter

【属性】

なし

<wsTenantIdResolveType>タグ

この設定は intra-mart Accel Platform 2014 Spring 以降、利用可能です。

<wsTenantIdResolveType>standard</wsTenantIdResolveType>
必須項目 ×
複数設定 ×
設定値・設定する内容

ユーザ情報に含まれる ログイングループID の検証モードを指定します。指定可能な値と動作については、以下の通りです。

standard とくに検証を行いません。
strict
ユーザ情報に含まれる loginGroupID と自動解決されたテナントIDが一致する場合のみ、認証を許可します。
ユーザ情報に含まれる loginGroupID と自動解決されたテナントIDが一致しない場合は、SOAPフォルト wsse:TenantIdNotMatch が発生します。
アクセス先のテナントに対して、予期しないテナントIDによるWebサービスの実行を防ぐ場合、この設定を使用します。
この設定は、「リクエスト情報を利用したテナント自動解決機能」を利用している場合のみ、利用してください。
単位・型 文字列
省略時のデフォルト値 standard
親タグ parameter

【属性】

なし

コラム

「リクエスト情報を利用したテナント自動解決機能」については、セットアップガイドの「テナント解決機能」を参照してください。

認証モジュール固有設定

intra-mart Accel Platform が標準で提供する認証モジュールで利用可能な設定について記述します。

WSSE認証モジュール <expire>タグ

<authModule class="jp.co.intra_mart.foundation.web_service.util.impl.WSAuthDigestGenerator4WSSE">
   <expire>300</expire>
</authModule>
必須項目 ×
複数設定 ×
設定値・設定する内容
認証時に利用されるユーザ情報の有効期限。
システム日時と WSSE認証文字列 のCreated を比較し、ここで設定された期限が過ぎている場合、認証に失敗します。
WSSE認証文字列 のCreatedとNonceをここで設定された期間、サーバ側で保持されます。既に保持されているCreatedとNonceで認証を行った場合、認証に失敗します。(リプレイ攻撃対策)
この設定が「0」の場合、有効期限チェックおよびCreatedとNonceの保持は行いません。
単位・型 数値型(秒)
省略時のデフォルト値 300
親タグ class 属性が jp.co.intra_mart.foundation.web_service.util.impl.WSAuthDigestGenerator4WSSE である)authModule

【属性】

なし