1. Apache版
Apache版のWAMプラグインモジュールは、有償版iPLAss SDKにビルド済プラグインとして同梱されます。
iPLAss 4.0.22でビルド済プラグインの提供形態が変更されているため、初期設定の手順とWAMシステムライブラリの構成はバージョンによって異なります。ご利用のバージョンに応じた節を参照してください。
| iPLAssのバージョン | 同梱されるビルド済プラグイン |
|---|---|
|
|
|
linux-gcc 形式および win64-vc 形式のビルド済プラグインは非推奨です。iPLAss 4.0.22以降のSDKにも当面同梱されますが、今後の機能改善や不具合修正は提供されず、将来的に削除されます。iPLAss 4.0.22以降をご利用の場合は、 el9-gcc-x86_64 形式のビルド済プラグイン、またはソースコードから独自にビルドしたWAMプラグインモジュールを使用してください。RHEL9系以外のOSについてはソースコードからのビルドを参照してください。
|
| 設定方法/設定例はiPLAssのバージョンによらず共通です。 |
iPLAss 4.0.22以降
初期設定
-
事前準備/前提
-
有償版のSDKに同梱されている
iplass-ee-wam-apache-[バージョン]-el9-gcc-x86_64.tar.gzをWebサーバーの任意のパスに配置してください。 -
以降の説明では、Apacheのインストールディレクトリを
%APACHE_HOME%と表記します。 -
Apacheをデーモン形式で実行することを前提とします。
-
以降の手順はRHEL9系を前提としています。ソースコードから独自にビルドしたWAMプラグインモジュールを使用する場合も、モジュールと依存ライブラリの配置、環境変数の設定は同様です。ただし、パッケージのインストールコマンドとSELinux関連の手順は、使用するOSに読み替えてください。
-
-
WAMプラグインモジュールの配置
-
Webサーバーの
%APACHE_HOME%/modulesにWAMプラグインモジュールを配置します。iplass-ee-wam-apache-[バージョン]-el9-gcc-x86_64.tar.gz内の以下のファイルが対象です。-
mod_iplass_ee_wam_apache.so
-
-
-
Apacheの設定
-
WAMプラグインモジュールの設定ファイル(iplass-wam.conf)を
%APACHE_HOME%/conf.modules.dに配置します。設定項目の詳細はWAMプラグインモジュールの設定を参照してください。
※ Apacheの設定ファイル(httpd.conf)から、配置したiplass-wam.confをIncludeしていることを確認してください。 -
WAMシステムライブラリのうち、RHEL9系の標準リポジトリで提供されるものを導入します。
dnf install boost-regex boost-random
-
続けて、httpdプロセスの環境変数を設定し、配布パッケージに同梱されたWAMシステムライブラリを参照可能にします。
iplass-ee-wam-apache-[バージョン]-el9-gcc-x86_64.tar.gz内のlib/ディレクトリ一式(同梱ライブラリ・文字コード変換モジュール)を任意のパスに配置します。
以下は、lib/の配置先を/opt/iplass-wam/libとした場合の設定例です。
systemd管理のhttpdでは、systemctl edit httpdでドロップイン用ファイルを作成し、次のように設定します。ドロップイン用ファイル(/etc/systemd/system/httpd.service.d/override.conf)[Service] Environment="LD_LIBRARY_PATH=/opt/iplass-wam/lib" Environment="APR_ICONV_PATH=/opt/iplass-wam/lib/iconv"
保存後はhttpdを再起動してください。
/etc/sysconfig/httpdに設定を記載する場合は、ドロップイン用ファイルにEnvironmentFile=/etc/sysconfig/httpdを追記してください。SELinuxが有効(enforcing)な環境では次の設定が必要です。
(1)WAMプラグインモジュール本体へのrestorecon -vの適用。
(2)同梱ライブラリへのセキュリティコンテキストの付与。semanage fcontext -a -t lib_t "/opt/iplass-wam/lib(/.*)?"で登録したうえでrestorecon -Rv /opt/iplass-wam/libを適用します。
(3)httpdからiPLAssへのHTTP接続の許可。setsebool -P httpd_can_network_connect 1を設定します。未設定のときは権限チェックの通信が拒否され、保護対象パスへのアクセスが503エラーとなることがあります。 -
配置後の確認として、以下を実行してください。
# WAMプラグインモジュールが依存するライブラリをすべて解決できるかを確認します(出力が無ければOK) LD_LIBRARY_PATH=/opt/iplass-wam/lib ldd "$APACHE_HOME/modules/mod_iplass_ee_wam_apache.so" | grep "not found" # 同梱ライブラリを配置先から参照しているかを確認します(libjsoncpp.so、libapriconv-1.soが配置先のパス配下と出力されればOK) LD_LIBRARY_PATH=/opt/iplass-wam/lib ldd "$APACHE_HOME/modules/mod_iplass_ee_wam_apache.so" | grep "/opt/iplass-wam" # Apacheの設定ファイルの構文を確認します(Syntax OKと出力されればOK) LD_LIBRARY_PATH=/opt/iplass-wam/lib httpd -t systemctl restart httpd # WAMプラグインモジュールがロードされているかを確認します(iplass_ee_wam_apache_module (shared)と出力されればOK) LD_LIBRARY_PATH=/opt/iplass-wam/lib httpd -M 2>/dev/null | grep iplass
-
-
WAMシステムライブラリ
WAMシステムライブラリを参照してください。
WAMシステムライブラリ
Apache版WAMプラグインモジュールが依存するライブラリは以下のとおりです。
| ライブラリ | バージョン | 提供形態 |
|---|---|---|
libcurl |
8.21.0 |
WAMプラグインモジュールへ静的リンク |
JsonCpp |
1.9.7 |
配布パッケージのlib/に同梱 |
APR-iconv |
1.2.2 |
配布パッケージのlib/に同梱 |
Boost(regex/random) |
1.75 |
システム参照 |
GMP |
6.2 |
システム参照 |
APR |
1.7 |
システム参照 |
APR-util |
1.6 |
システム参照 |
OpenSSL |
3系 |
システム参照 |
zlib |
1.2 |
システム参照 |
libidn2 |
2.3 |
システム参照 |
「システム参照」は、OSが提供するライブラリを使用することを示します。
上表のバージョンは、RHEL9系の標準リポジトリが供給するバージョンです。
JsonCpp・APR-iconvは、RHEL9系の標準リポジトリで取得できないため配布パッケージに同梱しています。
|
OpenSSL・zlib・libidn2・APR・APR-utilは、httpdプロセス自身が使用するライブラリのため同梱していません。 httpdプロセス内でシステム側とバージョンが混在する可能性があるため、これらのライブラリを配布パッケージの lib/ へ追加しないでください。
|
(ソースコードからのビルドで独自ビルドする場合は)libcurlは7.84以降を使用してください。7.84より前のバージョンは curl_global_init() / curl_global_cleanup() がスレッドセーフではありません。スレッドを使用するMPM構成で並行リクエストを処理した際に、問題が生じる可能性があります。 |
ビルド済プラグインの動作環境
ビルド済プラグイン iplass-ee-wam-apache-[バージョン]-el9-gcc-x86_64.tar.gz はRHEL9系を対象としています。
RHEL・Rocky Linux・AlmaLinux・Oracle Linux 9の全マイナーリリースで動作します。RHEL10系での動作は保証されません。
実行環境に必要なRPMパッケージは、httpd(2.4系)・boost-regex・boost-random・openssl-libs・zlib・libidn2です。いずれもRHEL9系の標準リポジトリで供給され、EPELなどの外部リポジトリは不要です。
RHEL9系以外のOSで使用する場合は、ソースコードからのビルドを参照してください。
脆弱性対応時のライブラリ更新
依存ライブラリに脆弱性が発見された場合の更新方法は、提供形態ごとに異なります。
-
システム参照のライブラリ(OpenSSL・zlib・libidn2・APR・APR-util・Boost・GMP)
OSのパッケージ更新を適用してください。WAMプラグインモジュールの依存はsoname単位で解決されるため、sonameを維持するパッケージ更新であれば再配布・再ビルドは不要です。
更新後はhttpdを再起動してください。 -
同梱ライブラリ(JsonCpp・APR-iconv)
原則としてiPLAssのリリースで更新版を提供します。 緊急に利用者側で更新する場合は、ソースコードからのビルドの手順で対象ライブラリの修正版をビルドします。 ビルドしたファイルで、lib/内の同名ファイル(soname名)を差し替えてください。 ただしsonameが変わる更新はファイルの差し替えでは動作せず、WAMプラグインモジュール自体の再ビルドが必要です。 -
静的リンクのlibcurl
WAMプラグインモジュールへ静的リンクしているため、単体での差し替えはできません。 iPLAssのリリースで更新するか、ソースコードからのビルドの手順で新しいlibcurlに対してWAMプラグインモジュールを再ビルドしてください。 なおHTTP/HTTPS以外のプロトコルと不要な機能を無効化してビルドされているため、無効化済み機能の脆弱性の影響は受けません。
ソースコードからのビルド
有償版iPLAss SDKに同梱されているソースパッケージから、独自にビルドする場合の手順概要を示します。
ビルド済プラグインを提供していないOSで使用する場合や、依存ライブラリのバージョンを独自に選定する場合に参照してください。
| 動作確認済みの実行環境はRHEL9系およびAmazon Linux 2023です。それ以外のOSでの動作は個別に検証してください。 |
-
ビルドツールと開発パッケージ
C++コンパイラ・make・autoconf・automake・libtool・cmakeに加え、httpd(2.4系)・APR・APR-util・OpenSSL・zlib・libidn2・Boost・GMPの開発パッケージ(ヘッダ)が必要です。
利用しているパッケージマネージャでインストールしてください。以下はRHEL9系での例です。
# dnf install gcc-c++ make autoconf automake libtool cmake pkgconf-pkg-config \
httpd-devel apr-devel apr-util-devel openssl-devel zlib-devel libidn2-devel \
boost-devel gmp-devel
-
APR-iconv、JsonCpp
この2つはRHEL9系の標準リポジトリに存在しないため、上流ソースからビルドします。
利用しているパッケージマネージャで取得できる場合は、そちらを使用しても構いません。インストール先(この例では /opt/wam-build )は任意です。
# tar zxf apr-iconv-1.2.2.tar.gz # cd apr-iconv-1.2.2 # ./configure --prefix=/opt/wam-build/apr-iconv --with-apr=[apr-1-configのパス] # make # make install
# tar zxf jsoncpp-1.9.7.tar.gz # cd jsoncpp-1.9.7 # mkdir build # cd build # cmake .. -DCMAKE_INSTALL_PREFIX=/opt/wam-build/jsoncpp -DBUILD_SHARED_LIBS=ON # make # make install
-
libcurl
静的ライブラリとしてビルドします。OpenSSL・zlib・libidn2を有効にし、HTTP/HTTPS以外のプロトコルと不要な機能は無効化してください。
# tar zxf curl-8.21.0.tar.gz
# cd curl-8.21.0
# ./configure --prefix=/opt/wam-build/curl \
--disable-shared --enable-static --with-pic \
--with-openssl --with-zlib --with-libidn2 \
[不要なプロトコル・機能を無効化するオプション]
# make
# make install
無効化の対象と指定できるオプションはlibcurlのバージョンによって異なるため、 ./configure --help で確認してください。configureのサマリー出力で、Protocolsに不要なプロトコルが含まれていないこと、IDNが enabled(libidn2)であることを確認してください。 CA証明書バンドルのパスはconfigureが自動検出します。自動検出されない環境では --with-ca-bundle オプションでパスを指定してください。
|
-
WAMプラグインモジュール
# cd [ソースパッケージの展開先] # make clean build
ビルド成果物は bin/release/mod_iplass_ee_wam_apache.so に生成されます。
依存ライブラリのインストール先を /opt/wam-build 以外にした場合は make WAM_DEPS_ROOT=[インストール先] clean build としてください。
iPLAss 4.0.22未満
本節が対象とするビルド済プラグイン( linux-gcc 、 win64-vc 形式)は非推奨です。今後の機能改善や不具合修正は提供されず、将来的に削除されます。これらのビルド済プラグインはiPLAss 4.0.22以降のSDKにも当面同梱されるため、iPLAss 4.0.22以降で継続して利用する場合も本節を参照してください。新規に導入する場合はiPLAss 4.0.22以降を参照してください。 |
初期設定
-
事前準備/前提
-
有償版のSDKに同梱されている
iplass-ee-wam-apache-[バージョン]-[OS/処理系].[拡張子](例 : iplass-ee-wam-apache-[バージョン]-linux-gcc.tar.gz)をWebサーバーの任意のパスに配置してください。 -
以降の説明では、Apacheのインストールディレクトリを
%APACHE_HOME%と表記します。 -
Apacheをデーモン形式で実行することを前提とします。
-
-
WAMプラグインモジュールの配置
-
Webサーバーの
%APACHE_HOME%/modulesにWAMプラグインモジュールを配置します。iplass-ee-wam-apache-[バージョン]-[OS/処理系].[拡張子]内の以下のファイルが対象です。-
mod_iplass_ee_wam_apache.so
-
-
-
Apacheの設定
-
WAMプラグインモジュールの設定ファイル(iplass-wam.conf)を
%APACHE_HOME%/conf.modules.dに配置します。設定項目の詳細はWAMプラグインモジュールの設定を参照してください。
※ Apacheの設定ファイル(httpd.conf)で、%APACHE_HOME%/conf.modules.dに配置したWAMプラグインモジュールの設定ファイル(iplass-wam.conf)をIncludeしていることを確認してください。 -
Linux環境の場合、httpdプロセスの環境変数を編集し、WAMプラグインモジュールの依存するシステムライブラリを参照可能とする必要があります。
initスクリプトでApacheをデーモン起動している場合、httpdプロセスの環境変数LD_LIBRARY_PATHからWAMプラグインモジュールの依存するシステムライブラリを参照可能とします。
以下、ライブラリのインストール先を/opt/wam/localとした場合の設定例です。/etc/sysconfig/httpdに以下を追加します。WAM_LOCAL=/opt/wam/local WAM_LIB_PATH=\ ${WAM_LOCAL}/boost/lib\ :${WAM_LOCAL}/jsoncpp/lib\ :${WAM_LOCAL}/openssl/lib\ :${WAM_LOCAL}/zlib/lib\ :${WAM_LOCAL}/libidn/lib\ :${WAM_LOCAL}/curl/lib\ :${WAM_LOCAL}/apr/lib\ :${WAM_LOCAL}/apr-iconv/lib\ :${WAM_LOCAL}/apr-util/lib\ :${WAM_LOCAL}/gmp/lib LD_LIBRARY_PATH="$WAM_LIB_PATH:$LD_LIBRARY_PATH" export LD_LIBRARY_PATHSELinuxを有効にしている環境では、ライブラリにセキュリティコンテキストを付与する必要があります。
まず、他の.soファイルに付与されているコンテキストをls -Zコマンドで確認します。
次に、上記パスの各ライブラリに対して、chconコマンドで当該コンテキストを付与します。
この操作により、httpdプロセスからライブラリへのアクセスが可能となります。 -
Windows環境の場合、
iplass-ee-wam-apache-[バージョン]-win64-vc.zip内のbin/にあるDLLファイルを%APACHE_HOME%/binにコピーします。
-
-
WAMシステムライブラリ
WAMシステムライブラリを参照してください。
WAMシステムライブラリ
Apache版WAMプラグインモジュールの依存するライブラリは以下のとおりです。
| ライブラリ | バージョン |
|---|---|
Boost |
1.5.5 |
jsoncpp |
0.6.0 |
GMP |
5.1.2 |
GNU IDN |
1.18 |
zlib |
1.2.11 |
OpenSSL |
1.0.2.k |
libcurl |
7.34.0 |
APR |
1.5.2 |
APR-iconv |
1.2.1 |
APR-util |
1.5.4 |
以下、AmazonLinux環境/GCC4.8.2におけるシステムライブラリインストール手順を示します。
yum等、利用しているリポジトリマネージャに該当ライブラリが存在しない場合、参考にしてください。
-
ビルドツール
以下のyumコマンドにより、ビルド中に使用するツールをインストールしておきます。
# yum install gcc gcc-c++ autoconf automake # yum install unzip # yum install cmake # yum install bzip2 # yum install libtool # yum install dos2unix # yum install zip
以降、各ライブラリのビルド手順を示します。必要に応じて、prefixオプションで任意ディレクトリにインストールしてください。
-
Boost
# cd [your/build/work/dir] # tar zxf [your/scp/upload/path/to]/boost_1_55_0.tar.gz # cd boost_1_55_0 #./bootstrap.sh --prefix=/usr/local #./b2 install
-
jsoncpp
# unzip [your/scp/upload/path/to]/jsoncpp-master.zip # cd jsoncpp-master # mkdir build # cd build # cmake -DCMAKE_BUILD_TYPE=release -DJSONCPP_LIB_BUILD_SHARED=ON -DJSONCPP_WITH_TESTS=OFF -G "Unix Makefiles" .. # make # mkdir /usr/local # cd .. # cp -r include/ /usr/local # cp -r build/lib/ /usr/local
-
GMP
# bzip2 -dc [your/scp/upload/path/to]/gmp-5.1.2.tar.bz2 | tar xf - # cd gmp-5.1.2 #./configure --prefix=/usr/local # make # make install
-
GNU IDN
# tar zxf [your/scp/upload/path/to]/libidn-1.18.tar.gz # cd libidn-1.18 #./configure --prefix=/usr/local # make # make install
-
zlib
# tar zxf [your/scp/upload/path/to]/zlib-1.2.11.tar.gz # cd zlib-1.2.11/ #./configure --prefix=/usr/local # make # make install
-
OpenSSL
# tar zxf [your/scp/upload/path/to]/openssl-1.0.2k.tar.gz # cd openssl-1.0.2k #./config --prefix=/usr/local threads shared zlib-dynamic # vi Makefile ZLIB_INCLUDE= →ZLIB_INCLUDE= -I/mnt/ebs/opt/wam/local/zlib/include # make # make -W install_docs install
-
libcurl
# tar zxf [your/scp/upload/path/to]/curl-7.34.0.tar.gz # cd curl-7.34.0/ # export LD_LIBRARY_PATH=/usr/local /lib (LD_LIBRARY_PATHにopenssl、zlib、libidnのlib/のパスを含めます) # CPPFLAGS="-I/usr/local/include" \ LDFLAGS="-L/usr/local/lib" \ ./configure --prefix=/usr/local (openssl、zlib、libidnの各include/パスを-Iオプション、各lib/のパスを-Lオプションで1つずつ指定します。) # make # make install
|
libcurlでは、利用する機能によってはzlib、OpenSSLなど他のライブラリが 必要な場合があります。configureの出力で、各機能の有効無効を示す表示を確認することができます。 上記手順では、SSL support、zlib support、IDN supportが enabled となることを確認してください。 |
-
APR
# tar zxf [your/scp/upload/path/to]/apr-1.5.2.tar.gz # cd apr-1.5.2 #./configure --prefix=/usr/local # make # make install
| configure実行時、rm: cannot remove 'libtoolT': No such file or directory と出力された場合がありますが、WAMモジュール利用には影響ありません。無視して進めてください。 |
-
APR-iconv
# tar zxf [your/scp/upload/path/to]/apr-iconv-1.2.1.tar.gz # cd apr-iconv-1.2.1 #./configure --prefix=/usr/local --with-apr=/usr/local # make # make install
-
APR-util
# tar zxf [your/scp/upload/path/to]/apr-util-1.5.4.tar.gz # cd apr-util-1.5.4 #./configure --prefix=/usr/local --with-apr=/usr/local --with-apr-iconv=../apr-iconv-1.2.1 (--with-apr-iconvオプションではapr-iconvのソースコードパスを指定します) # make # make install
|
Windows環境でのCurlライブラリは、OpenSSL/1.0.2k、zlib/1.2.11、libidn/1.18、libssh2/1.4.3、librtmp/2.3に 依存しており、これらはApache実行環境に含まれている必要があります。 OpenSSLはlibeay32, ssleay32 (Linuxでのライブラリ名はlibssl、libcrypto)に依存していますが、 Apache2.4にビルトインされているため特に何か作業をする必要はありません。 |
設定方法/設定例
Apache版のWAMプラグインモジュールでは、iplass-wam.conf を使ってWAMプラグインモジュールの設定を行います。
# WAMプラグインモジュールをロードします. LoadModule iplass_wam_plugin_apache_module modules/mod_iplass_wam_plugin_apache.so # 管理対象サイトの識別情報です. AdminConsoleで設定した値と一致させてください. IplassSiteId local IplassSiteSecret 123 # 管理対象サイトのドメインとプロトコルを指定します. IplassSiteCookieDomain mysite.example.com IplassSiteScheme https # WAMモジュールが稼働するiPLAssサーバーのURLを指定します. IplassWamBaseUrl https://my.iplass.jp/myiplassapp/mytenant/ IplassWamCookieDomain my.iplass.jp # 管理対象サイトで認証処理を組み込みたいパスパターンを正規表現で指定します. IplassProtectedPathPattern "^/contents/.*$" # 認証時にコールバックとして使う管理対象サイトのパスを指定します. そのサイトで未使用のパスとしてください. IplassWamAuthCallbackPath /wamauthcallback # WAMモジュールとWAMプラグインモジュールでアクセストークンをやり取りするためのCookie名とパスを指定します. IplassWamCookieName JSESSIONID IplassWamCookiePath / IplassSiteCookieName ipw IplassSiteCookiePath / # CSRFトークンをやり取りするためのCookie名を指定します. IplassCsrfTokenCookieName _csrft # WAMモジュールからのJSONレスポンスの文字コードを指定します. IplassCharset utf-8
iPLAssのUserエンティティを連携する
管理対象サイト側のプログラム言語で独自に認可処理を組み込んだり、ユーザー情報を利用したりしたい場合、次のように設定します。
この例では、独自に定義したリクエストヘッダーにWAMモジュールから返却されたユーザー情報が格納されるようになります。
IplassMapUserAttribute On IplassAttributeMap x-wam-user-id accountId IplassAttributeMap x-wam-user-name name
例えばPHPの場合、次のようなソースコードでUserエンティティ情報を取得可能です。
<?php
header("Content-Type: text/html; charset=UTF-8");
echo “get user data from WAM Headers. <br/>";
foreach (getallheaders() as $name => $value) {
echo “ '$name': '$value' <br/> ";
}
<br/>";
?>
Apacheの基本認証と統合する
以下は、Apacheの基本認証と統合する設定です。基本認証に成功した場合、WAM機能の認証処理をスキップできます。
IplassIntegrateBasicAuth On
localhostのiPLAssと連携する
以下は、管理対象サイトとiPLAssを同一サーバーで稼動させる環境の設定です。
IplassWamBaseUrl http://localhost:8080/mytenant/ IplassWamRedirectUrl https://mysite.example.com/myiplassapp/mytenant/ IplassWamCookieDomain RewriteRule ^/wamauthcallback(.*) /wamauthcallback$1 [L] (1) RewriteRule ^/contents/(.*) /contents/$1 [L] (1)
| 1 | ApacheからiPLAssのアプリケーションサーバーにプロキシしている環境では、コールバックのパスと認証対象のコンテンツのパスをプロキシしないようにリライトルールを定義します。 |
コンテンツにJavaScriptを追加する
以下は、指定したパスパターンにマッチするコンテンツの末尾に任意のJavaScriptを追加する設定です。
IplassJavaScriptPath "/iplasswam/jquery-1.11.0.min.js,/iplasswam/sitexhr2.js" (1)
IplassJavaScriptSrc "iplass.wam.init({wamBaseUrl: \"https://my.iplass.jp/myiplassapp/mytenant/\", funcSignIn: addWamSignInNavi, funcSignOut: addWamSignOutNavi}); $(document).ready(function(){addCss();iplass.wam.addUserInfoContent();});" (2)
IplassAddScriptTagPathPattern "/index.php" (3)
| 1 | script要素のsrc属性で読み込むJavaScriptファイルを指定します。 |
| 2 | JavaScriptを記述します。 |
| 3 | パスのパターンを指定します。 |
開発環境向けの設定
管理対象サイトのサーバーとiPLAssが稼働するサーバーの間にプロキシがある環境では、次のように設定します。
IplassProxyHost my.proxy.host IplassProxyPort 8080
iPLAssサーバーに自己署名のサーバー証明書を利用する場合、次のように設定します。
IplassSslVerifyPeer Off IplassSslVerifyHost Off
WAMプラグインモジュールのデバッグログを有効にする場合、次のように設定します。
合わせて、Apache本体のログレベルをdebugに指定してください。
IplassWamVerbose On IplassHttpVerbose On LogLevel debug