intra-mart Accel Platform Webサービス 認証・認可 仕様書 第6版 2020-12-01

付録

aarファイルを作成する

aarファイル(Axis2 Archiveファイル)を作成するツールについて紹介します。
ここでは、Antタスク「aarGenerate」を利用します。このAntタスクは、services.xml を作成し、services.xmlを含んだaarファイルを作成します。
aarファイルの構成は、Axis2 プロジェクトの「Apache Axis2 Web Administrator’s Guide Step 3: Create Archive File」を参照してください。
この手順は以下の条件を満たしている環境で行うことを前提とします。
  • Apache Ant がインストールされていること

  • 「Webサービス用ツール」が存在すること

    「Webサービス用ツール」は プロダクトファイルダウンロード より <WebService_Tools.zip> をダウンロードしてください。

    ※ ダウンロードには製品のライセンスキーが必要です。

Webサービス用ツールを展開したディレクトリを %WEBSERVICE_TOOL_HOME% として以降記述します。

コラム

ビルドツール「Ant」がインストールされていない場合は以下のサイトを参考にしてインストールを行ってください。

注意

このツールでは、jarやクラスをaarファイルに含めることはできません。aarファイルの Webサービス を実行するには、アプリケーションサーバのクラスパス上に Webサービス の実装クラスを配置する必要があります。
具体的には、jarファイルを %CONTEXT_PATH%/WEB-INF/lib 配下に、クラスを %CONTEXT_PATH%/WEB-INF/classes 配下に配置してください。
  1. 公開する Webサービス 用の各種設定を行います。

    1. AarGen.propertiesの編集を行います。

      %WEBSERVICE_TOOL_HOME%/AarGen.propertiesの編集を行います。
      各プロパティの説明は以下の通りです。
      プロパティ名 必須 説明
      serviceName Webサービス として公開する名称を指定します。この値はaarファイルの名称です。
      className Webサービス の実装クラスを指定します。クラスは完全修飾名で指定します。
      destDir aarファイルを出力するディレクトリを指定します。
      moduleRef ×
      Webサービス に適用する Axis2 モジュール 名を指定します。
      ,(カンマ)を使用することで複数指定が可能です。
      wsdlDir ×
      aarファイルに含める WSDL やXSDが配置されているディレクトリ。
      未指定の場合、services.xml以外のファイルをaarファイルに含めません。
      serviceAuthzUri ×
      Webサービス が提供するサービスに対して認可リソースをURIで指定します。
      未指定の場合、サービスに対しての認可リソース設定を行いません。
      opeAuthzUriFile ×
      Webサービス・オペレーション への認可リソース設定が記述されたCSVファイルを指定します。
      未指定の場合、Webサービス・オペレーション に対しての認可リソース設定を行いません。
      verbose ×
      Ant タスク実行時に詳細情報を出力するかを指定します。

      注意

      Windows環境でパスを指定する場合は区切り文字を / または \ としてください。

    2. opeAuthzUriFile.csvの編集を行います。

      Webサービス が提供する Webサービス・オペレーション に対して認可リソースをURIで指定します。
      %WEBSERVICE_TOOL_HOME%/opeAuthzUri.csvを編集します。(AarGen.propertiesの opeAuthzUriFile で指定した値のファイルを編集します。)
      Webサービス・オペレーション に対して認可リソースを指定しない場合は、このファイルを編集する必要はありません。
      このファイルはCSV形式で記述します。フィールド区切り文字は ,(カンマ)、レコード区切り文字は改行です。
      以下の例の場合、
      • Webサービス・オペレーション add に対して URI service://sample/web_service/member_info/add
      • Webサービス・オペレーション find に対して URI service://sample/web_service/member_info/find
      • Webサービス・オペレーション findAll に対して URI service://sample/web_service/member_info/findAll
      です。
      add,service://sample/web_service/member_info/add
      find,service://sample/web_service/member_info/find
      findAll,service://sample/web_service/member_info/findAll
      

      コラム

      サービス と Webサービス・オペレーション の両方に認可リソースが指定されている場合は、Webサービス・オペレーション に指定されている認可リソースが優先されます。
      詳細は「services.xmlに認可リソースを指定する」を参照してください。

      注意

      認可リソースを指定した場合、指定したURIに該当する認可リソースが存在しないと Webサービス・オペレーション 実行時に以下のようなエラーが発生します。
      [E.IWP.AUTHZ.DECISION.10007] リソースグループが登録されていません。
      
      あらかじめ認可リソースを作成の上、Webサービス・オペレーション を実行してください。
      認可リソースの追加方法については「テナント管理者操作ガイド」-「認可を設定する」の「リソースを追加する」を参照してください。
    3. AarGenを実行するための環境情報を指定します。

      Apache Antがインストールされているディレクトリを指定します。
      %WEBSERVICE_TOOL_HOME%/AarGen.bat(Unix系OSの場合はAarGeb.sh)を編集します。
      環境変数「ANT_HOME」に対してAntがインストールされているディレクトリを指定します。
      (Windows系OSの場合)
      REM AarGen.bat
      set ANT_HOME=C:/apache-ant
      
      (Unix系OSの場合)
      # AarGen.sh
      export ANT_HOME=/apache-ant
      
  2. AarGenを実行します。

    同梱されているバッチファイルを実行します。
    (Windows系OSの場合)
    > %WEBSERVICE_TOOL_HOME%\AarGen.bat
    
    (Unix系OSの場合)
    $ sh %WEBSERVICE_TOOL_HOME%/AarGen.sh
    

    AarGen.propertiesの destDir で指定されているディレクトリの配下にaarファイルが出力されます。

Apache Axis2 管理コンソールについて

注意

Apache Axis2 管理コンソールは、 intra-mart Accel Platform 2020 Winter(Azalea) 以降の環境で使用できません。
Apache Axis2 から提供されている管理用コンソールです。
http://<HOST>:<PORT>/<CONTEXT_PATH>/axis2-web/index.jsp でアクセスできます。
この管理コンソールを利用することで、ブラウザ経由でデプロイされている Webサービス の情報の閲覧や、Webサービス のデプロイが可能です。
../../_images/axis2_web_index.png
Apache Axis2 管理コンソールの詳細については「Apache Axis2 Web Administrator’s Guide」を参照してください。

コラム

標準のユーザ名は admin、 パスワードは axis2 です。この値は %CONTEXT_PATH%/conf/axis2.xml で変更可能です。

services.xmlについて

Apache Axis2 には、Webサービス名や Webサービス として公開するJavaクラスなどのサービス情報を設定するための「services.xml」があります。
このファイルを規定のフォルダに配置したり、aarファイルに配置したりすることで Webサービス のデプロイが可能です。
Webサービス のデプロイについては、「Webサービス をデプロイする」を参照してください。
<?xml version="1.0" encoding="UTF-8"?>
<!-- サービスの設定を行います。Webサービス名がSampleServiceであることを指定しています。 -->
<service name="SampleService">
    <!-- Webサービスに対しての説明です。 -->
    <description>The Web service on the intra-mart.</description>

    <!-- このサービスのServiceClassがsample.web_service.provider.SampleServiceであることを指定しています。 -->
    <parameter name="ServiceClass">sample.web_service.provider.SampleService</parameter>

    <!-- このサービスのWebサービス・オペレーション実行時に認証・認可を行うことを指定しています。 -->
    <module ref="im_ws_auth"/>

    <!-- このサービスに対してのメッセージレシーバを指定しています。 -->
    <messageReceivers>
        <!-- 返却値が無いメソッドに対してのレシーバを指定しています。 -->
        <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only" class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver" />
        <!-- 何らかの返却を行うメソッドに対してのレシーバを指定しています。 -->
        <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"  class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
    </messageReceivers>

</service>
<parameter> タグの name 属性の属性値を ServiceClass と指定し、タグ内部に Webサービス の実装クラスのJava完全修飾名を指定します。これにより、指定したクラスのpublicメソッドが Webサービス・オペレーション として公開されます。
各種メッセージレシーバは、XMLの Webサービス メッセージとJavaのオブジェクトのマッピングを行うためのものです。
上記以外にも、「RowXMLxxxxMessageReceiver」というXMLを直接扱うためのメッセージレシーバも提供されています。
services.xmlの詳細は、Axis2プロジェクトの「Service Configuration」を参照してください。
メッセージレシーバの詳細は、Axis2のAPIドキュメントを参照してください。

services.xmlに認可リソースを指定する

Webサービス・オペレーション に対して認可リソースを指定します。認可リソースはURI形式で指定します。
認可リソースのURIについては「認可仕様書 リソース管理」を参照してください。
認可リソースは、サービスまたは、オペレーションに対して設定することが可能です。
認可リソースはservices.xmlの <parameter> タグを利用して指定します。<parameter name="auth-uri"> の内部に認可リソースのURIを指定します。
<?xml version="1.0" encoding="UTF-8"?>
<service name="SampleService">
    <description>The Web service on the intra-mart.</description>

    <parameter name="ServiceClass">sample.web_service.provider.SampleService</parameter>

    <module ref="im_ws_auth"/>

    <messageReceivers>
        <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only" class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver" />
        <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"  class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
    </messageReceivers>

    <!-- サービスSampleServiceに対して認可リソースを指定します。 -->
    <parameter name="authz-uri">service://sample/web_service/sample</parameter>
    <operation name="foo">
        <!-- サービスSampleServiceのオペレーションfooに対しての認可リソースを指定します。 -->
        <parameter name="authz-uri">service://sample/web_service/sample/foo</parameter>
    </operation>
    <operation name="bar">
        <!-- サービスSampleServiceのオペレーションbarに対しての認可リソースを指定します。 -->
        <parameter name="authz-uri">service://sample/web_service/sample/bar</parameter>
    </operation>
    <!--
    <operation name="baz">
        <parameter name="authz-uri">service://sample/web_service/sample/baz</parameter>
    </operation>
    -->

</service>
サービスとオペレーションの両方に認可リソースが指定された場合は、オペレーションに指定された認可リソースが有効です。上記の例の場合、オペレーション bar に対しての認可リソースURIは service://sample/web_service/sample/bar (オペレーションの認可リソースを利用)、オペレーション baz に対しての認可リソースURIは service://sample/web_service/sample (サービスの認可リソースを利用)です。

注意

サービスとオペレーションの両方とも認可リソースが未指定の場合、そのオペレーションの認可は常に「許可」です。

注意

認可は Axis2 モジュール 「im_ws_auth」が適用されている Webサービス に対してのみ有効です。
Axis2 モジュール 「im_ws_auth」の適用方法については「Axis2 モジュール 「im_ws_auth」の適用方法について」を参照してください。

注意

認可は Webサービス・プロバイダ の認可の設定が有効であるときのみ動作します。

注意

認可リソースを指定した場合、指定したURIに該当する認可リソースが存在しないと Webサービス・オペレーション 実行時に以下のようなエラーが発生します。
[E.IWP.AUTHZ.DECISION.10007] リソースグループが登録されていません。
あらかじめ認可リソースを作成の上、Webサービス・オペレーション を実行してください。
認可リソースの追加方法については「テナント管理者操作ガイド」-「認可を設定する」の「リソースを追加する」を参照してください。

コラム

URIについては以下の形式を推奨しています。

  • サービスに対して設定する場合

    service://%アプリケーションID%/web_service/%サービス名%

  • Webサービス・オペレーション に対して設定する場合

    service://%アプリケーションID%/web_service/%サービス名%/%オペレーション名%

Webサービス をデプロイする

Webサービス のデプロイ方法について紹介します。

ディレクトリ形式のデプロイ

%CONTEXT_PATH%/WEB-INF/services ディレクトリ配下に Webサービス の資材が格納された任意の名称のディレクトリを配置することで Webサービス をデプロイすることが可能です。
このディレクトリ配下に、Webサービス に関連するライブラリ、クラス、プロパティ・ファイル、WSDL ファイル、XSDファイルおよび、services.xmlを格納することで Webサービス がデプロイされます。

「services.xml」を含めたパスは以下の通りです。

%CONTEXT_PATH%/WEB-INF/services/%任意の名称%/META-INF/services.xml

aarファイル形式のデプロイ

aarファイル(Asix2 Archiveファイル)を、%CONTEXT_PATH%/WEB-INF/services ディレクトリに配置することで、Webサービス をデプロイすることが可能です。
aarファイルとは、Webサービス に関連するライブラリ、クラス、プロパティ・ファイル、WSDL ファイル、XSDファイルおよび、services.xmlを格納したファイルです。
aarファイルの作成については「aarファイルを作成する」を参照してください。
aarファイルの構成は、Axis2 プロジェクトの「Apache Axis2 Web Administrator’s Guide Step 3: Create Archive File」を参照してください。

Axis2 モジュール 「im_ws_auth」の適用方法について

Webサービス を認証・認可の対象とする方法を紹介します。
Webサービス に対して認証・認可の対象とするには Axis2 モジュール 「im_ws_auth」を適用する必要があります。
Axis2 モジュール 「im_ws_auth」を適用する方法としては以下が存在します。

services.xmlで Axis2 モジュール 「im_ws_auth」を指定する

<service> タグ内部に <module ref="im_ws_auth"/> を記述することで Axis2 モジュール 「im_ws_auth」を指定することが可能です。
<operation> タグ内部に記述することで Webサービス・オペレーション 単位で指定することも可能です。
詳細は「services.xmlについて」を参照してください。

axis2.xmlで Axis2 モジュール 「im_ws_auth」を指定する

%CONTEXT_PATH%/WEB-INF/conf/axis2.xml を編集します。
以下の <service> タグのコメントアウトを除去します。
<service> タグに Axis2 モジュール 「im_ws_auth」を適用したい Webサービス 名を指定します。
指定したいサービスが複数ある場合は <service> タグを複数記述します。
<listener class="jp.co.intra_mart.foundation.web_service.axis2.observers.EngageModuleAxisObserver">
    <parameter name="engageModule">
        <module ref="im_ws_auth">
            <!-- <service>ExampleWebServiceName</service> -->
        </module>
    </parameter>
</listener>

Apache Axis2 管理コンソールで Axis2 モジュール 「im_ws_auth」を指定する

注意

Apache Axis2 管理コンソールは、 intra-mart Accel Platform 2020 Winter(Azalea) 以降の環境で使用できません。
Apache Axis2 の管理コンソール機能を利用して Axis2 モジュール 「im_ws_auth」を適用することも可能です。
管理コンソールについては「Apache Axis2 管理コンソールについて」を参照してください。
  1. 稼働中のサーバに対して以下にアクセスします。

    http://<HOST>:<PORT>/<CONTEXT_PATH>/axis2-web/index.jsp

    ../../_images/axis2_web_index.png
  2. 「Administration」をクリックします。

  3. Engage moduleの「For a service」をクリックします。

    ../../_images/axis2_admin_home.png
  4. Select a Module: で「im_ws_auth」を、Select a Service: で任意のサービスを選択します。

    ../../_images/axis2_engage_module.png
  5. 「Engage」をクリックします。

  6. 上記で指定したサービスに対して Axis2 モジュール 「im_ws_auth」が適用されます。

注意

管理コンソールを利用した Axis2 モジュール の設定はアプリケーションサーバの再起動を行うと初期化されます。

分散環境での WSDL について

Apache Axis2 が自動生成する WSDL に記述されているエンドポイントは、クラスタが稼働しているホスト名に依存します。
このため、分散環境時に WSDL の問い合わせを行うとWebサーバによってディスパッチされたアプリケーションサーバのホストがエンドポイントとして取得されてしまいます。
これを回避するためには、以下のいずれかの手段を取ります。
  • WSDL の自動生成が行われないようにする

    ディレクトリ形式のデプロイ を行った場合、あらかじめWebサーバ経由のエンドポイントが記述された WSDL を作成し、 %CONTEXT_PATH%/WEB-INF/services/%任意の名称%/META-INF/%Webサービス名%.wsdl に配置します。
  • Webサービス・クライアント が指定するエンドポイントをWebサーバ経由のものに変更する

    コラム

    スクリプト開発モデル API SOAPClient を利用している場合は、SOAPClientの第4引数のエンドポイントに指定しているURLをWebサーバ経由のものに変更します。

    コラム

    WSDL からスタブを生成している場合は、スタブのコンストラクタで指定するエンドポイントに指定しているURLをWebサーバ経由のものに変更します。

認証モジュールを追加する

認証モジュールを追加するには、axis2.xmlに <authModule>タグ を追加します。
axis2.xml については「Webサービス・プロバイダ の認証・認可の設定」を参照してください。
以下は標準では設定されていない 未認証ユーザ用認証モジュールjp.co.intra_mart.foundation.web_service.auth.impl.WSAuthModule4Anonymous) を認証モジュールとして追加する場合の設定です。
<axisconfig name="AxisJava2.0">

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

        <enablePlainTextPassword>false</enablePlainTextPassword>
        
        <!-- authModuleタグ追加 -->
        <authModule class="jp.co.intra_mart.foundation.web_service.auth.impl.WSAuthModule4Anonymous" />

        <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>

    </parameter>

    <!-- 省略 -->

</axisconfig>

SOAP メッセージのモニタリング

Webサービス 実行時にやり取りされる Webサービス メッセージをモニタリングする方法を紹介します。

TCPMonによるモニタリング

Apache Web Services Projectで提供されているメッセージモニタリングツール「TCPMon」の利用方法を紹介します。
TCPMonの詳細は、「TCPMon」を参照してください。
  1. TCPMonのダウンロードと解凍

    TCPMonのダウンロードページ」からTCPMonをダウンロードし、アーカイブを解凍します。このディレクトリを %TCPMON_HOME% とします。

  2. TCPMonの起動と設定

    %TCPMON_HOME%/build/tcpmon.bat(またはtcpmon.sh)を実行し、TCPMonを起動します。
    「Admin」タブを表示し、Listen Port に適当なポート番号を設定します。ポート番号は他のサービスと重複しないポート番号を指定してください。
    本書では例として「9999」とします。
    Target HostnameTarget Port にWebサービスがデプロイされているホストの情報を設定します。
    本書では例としてTarget Hostnameを「localhost」、Target Portを「8080」とします。
    その後、「Add」をクリックします。
    ../../_images/tcpmon_admin.png
  3. Webサービス・クライアント でエンドポイントを変更する

    Webサービス・クライアント が実行時に指定するエンドポイントのポート番号を先ほど指定した Listen Port に変更します。

    コラム

    スクリプト開発モデル API SOAPClient を利用している場合は、SOAPClientの第4引数のエンドポイントに指定しているポート番号を Listen Port のポート番号に変更します。

    コラム

    WSDL からスタブを生成している場合は、スタブのコンストラクタで指定するエンドポイントに指定しているポート番号を Listen Port のポート番号に変更します。

  4. 「Port <Listen Port のポート番号>」タブから SOAP メッセージを閲覧する

    ../../_images/tcpmon_result.png

認証・認可を必要としない Webサービス について

認証、認可およびログインを必要としない Webサービス を作成する場合、Axis2 モジュール 「im_ws_auth」を適用する必要がありません。
具体的には、services.xmlの<module ref=”im_ws_auth”/>を設定しないことで、該当モジュールが適用されなくなります。
Axis2 モジュール 「im_ws_auth」を適用しないこと以外は、本書で説明している Webサービス と同じ方法で作成することが可能です。
Axis2 モジュール 「im_ws_auth」の適用については「Axis2 モジュール 「im_ws_auth」の適用方法について」を参照してください。

コラム

各 Webサービス・オペレーション の引数に ユーザ情報 を受け取る必要もありません。