ここでは、OpenAM(旧SSO)を使用した認証システムの構築について紹介していきます。使用したのはOpenAM12.0.0ですが、OpenAM13.0.0(現在目下開発中)においても使えるはずです。尚、ここで前提とする認証方式はエージェント方式とします。(他に、リバースプロキシやトークンなどあります)

事前準備

簡単な用語の説明

OpenAMで重要な用語を私の理解で説明します。

認証サーバ：認証を実施するサーバ
エージェント：認証を実施したいアプリと同じサーバなどに入れ、認証サーバとの連携をする存在
エージェントプロファイル：エージェントが認証サーバとの間でやり取りをすべきかの設定を記載したもの
ポリシー：認証サーバがどのように認証すべきか(認証を実施するURL、認証時に認可するユーザやグループの判別など)を決めたもの

ダウンロード

今回の設定に必要なソフトウェアをダウンロードします。

OpenAM enterprise：configurator, zip, war, toolsと選べますが、ここではzipを選びましょう。
Web Policy Agents

なお、"subscription only"のラベルが付いているものは有償です。また、ダウンロードに際してはOpenAMのコミュニティへの登録が必要(無償)です。

Tomcat及びhttpdの準備

OpenAMの認証を利用するには、認証サーバではTomcatが必要となります。(=Tomcat利用のためにJavaも必要となります)
また、エージェントについては、Apache Httpd Serverの他、IISサーバやTomcatでも利用が可能なようですが、今回はhttpdを前提として進めていきますので、エージェントを入れるサーバに対してhttpdの準備も必要になります。

認証サーバ設定

まず認証サーバの設定を済ませます。認証サーバの設定を完了せずにエージェントの設定を開始してもエージェントの設定は通らないので注意が必要です。

ダウンロードしたOpenAM enterpriseの設置・解凍

ダウンロードしたzipファイルを認証サーバに置き、解凍します。解凍場所は任意ですが、Tomcatを動かす予定のユーザのホームディレクトリ直下に置くのがお薦めです。解凍したフォルダ内にある、”OpenAM_12.0.0.war"を”openam.war”にリネーム後、Tomcatのwebapps/以下に設置します。
なお、もしこのとき可能であれば、bin/setenv.shにおいて${CATALINA_BASE}の位置を変更して、万が一認証サーバ上に別アプリを起動したくなった際に簡単にプロセスを分けれるようにしておくと良いです。(詳細は検索すればわかると思いますが、bin, conf, logs, work, webappをコピーして別避けするイメージ)

認証サーバでの設定

Tomcatが起動済でなければ起動します。そして、webapps以下に置いたopenamにアクセスします。(例えばverify.example.comの場合verify.example.com/openam)
重要：localhostやIPでのOpenAMの利用はできません。ホスト名の設定をしていない場合は事前にホスト名の設定をする必要があります。
アクセス後の画面で、今回はカスタム設定を選びます。設定内容は次を参考にしてください。

一般
- デフォルトの管理ユーザのパスワードです。忘れると辛い思いをします
サーバー設定
- サーバーURL：https://verify.example.com:8443
- Cookieドメイン：.example.com
- プラットフォームロケール：en_USja_JPでも問題ありません
- 設定ディレクトリ：/home/tomcat/openamtomcatを動かすユーザのディレクトリの下に作るのが良いです
設定ストア
- 既存の設定を何も変えず次へ
ユーザーストア
- OpenAMのユーザーデータストアを選択
- 警告メッセージが表示されますが、問題なく使用できます
サイト設定
- ロードバランサがある場合には設定しますが、今回は割愛します
エージェント情報
- こちらは今回は使用しませんのでお任せしますが、デフォルトの管理ユーザのパスワードと同じにすることはできません
概要
- ここまでの設定内容について簡易的に表示されますので先へ進めると、インストールが開始されます

無事設定ができている場合、完了した旨が表示されます。

エージェントプロファイルの作成

ここまでで一先ず認証サーバ上にOpenAMがインストールできたことになるので、続いてエージェントプロファイルを作成します。エージェントプロファイルの作成は、ログイン画面ID:amadmin, pw:"認証サーバでの設定"にて管理ユーザのパスワードとして定めた値にて入り実施します。
ログイン後、"アクセス制御>/ （最上位のレルム）>エージェント"にて、エージェントという囲みの中の"新規..."で作成します。
入力項目についてですが、

名前：エージェントの名前を決めます、こちらは複数のエージェントの中から各エージェントを一意に識別するために使用するもので、後ほどエージェントのインストールで使用します
パスワード：後ほどエージェントのインストールで使用します
サーバーURL：認証サーバのURLです、今回だと例えばhttps://verify.example.com:8443/openamのようにします。
エージェントURL：エージェントのURLです。認証サーバとはドメインが一致していても構いませんが、その場合ホスト名は別である必要があります。今回だと例えば、https://agent.example.com:443のようにします。

HTTPS証明書の導入

こちらはhttps環境にてOpenAMを利用する場合のみ必須です。OpenAMの設定に証明書を読み込ませること及び認証サーバのJavaに自己証明書を登録することの２つを実施します。

OpenAMのToolsでOpenAMに対して自己証明書を信頼できる証明書として登録します。
Javaに自己証明書を信頼できる証明書として登録します。

OpenAMへの証明書登録

ssoadmと呼ばれるツールをインストールします。
ダウンロード時に取得したzipファイルの中にあるSSOAdminTools-12.0.0.zipを解凍します。解凍するとファイルの中身が展開されるので、事前に解凍用のフォルダe.g. openam-tools/adminを作成し、当該フォルダへ移動しておくと良いでしょう。
setupファイルに証明書の記載を追加します。
- 具体的には下記最後の2行(javax.net...及びacceptLicense)を追加します。

$JAVA_HOME/bin/java -D"load.config=yes" \
(中略)
 -D"path.log=$path_log" \
 -D"javax.net.ssl.trustStore=${Tomcatで使用している証明書へのパス}" \
 --acceptLicense

記載に追加が終わったら、./setupを実行します。
- 無事完了したかの確認は次のとおり実行できます。実行後、https://verify.example.com:8443/openamと出力されればOKです。

echo ${管理ユーザのパスワード} > /tmp/pwd.txt
chmod 400 /tmp/pwd.txt
cd ${SSOAdminTools-12.0.0.zipを解凍したフォルダ}/openam/bin/
./ssoadm list-servers -u amadmin -f /tmp/pwd.txt

続いて、ダウンロード時に取得したzipファイルの中にあるSSOConfiguratorTools-12.0.0.zipを解凍します。解凍するとファイルの中身が展開されるので、事前に解凍用のフォルダe.g. openam-tools/configを作成し、当該フォルダへ移動しておくと良いでしょう。
これから作成するプロパティファイルは、一から作成するよりも、サンプルを更新していく方が早いためコピーをします。cp sampleconfiguration config.properties
次のとおりconfig.propertiesを変更していきます。(変更箇所のみ記載)

########
SERVER_URL=https://verify.example.com:8443
BASE_DIR=/home/tomcat/openam #認証サーバでの設定の、サーバーの設定内設定ディレクトリに指定した値
ADMIN_PWD=password #管理者ユーザのパスワード
COOKIE_DOMAIN=.example.com #".から始める点に注意"
ACCEPT_LICENSES=true
######
######
DIRECTORY=SSL
DIRECTORY_SERVER=verify.example.com
######
######
:

認証サーバが起動中であることを確認の上、次のとおりに実行します。尚、下記はopenam-tools/configがカレントディレクトリであることを前提にしています。

java '-Djavax.netssl.trustStore=${証明書のパス}' \
 -jar openam-configurator-tool-12.0.0.jar \
 --file config.properties

Javaへの証明書登録(自己証明書の場合のみ必須)

次のとおりに実行します。
- keytool -importcert -alias ${証明書の名前} -file ${証明書のパス} -trustcacerts -keystore ${JAVA_HOME}/bin/lib/security/cacerts
証明書の名前は、後で、その証明書がどこの証明に使っているものかなどがわかるように、例えばverify.example.com.certのようにすると良いです
証明書のパスは、Tomcatで使用する証明書のパスを指定してください
長かったですが、これで認証サーバの設定は完了です。HTTPS環境にてOpenAMを使用する準備の8割が完了しました。

エージェント設定

認証サーバの設定が完了していればあと一息です。認証サービスを使用するアプリと同じサーバ上にエージェントをインストールします。

インストール事前準備

インストールを始める前にいくつかの準備項目を処理します。(フォルダ階層イメージは下記)

.
└── opt
    └── APACHE
       └── httpd
          └── web_agents(zipファイル解凍後のフォルダ)

エージェントzipファイルの解凍
- 解凍先はどこでも良いが例えば下記のようにhttpdの下の階層にあることが望ましい
エージェントPasswordファイルの作成
- 同じく作成先はどこでも良い、例えばecho AGENTPASSWORD > /tmp/pw.txtのような形で作成する
- ここで作成したファイルは後ほどインストール時に使用する
- パスワードは平文で保存すること(インストール時に平文を読み取り、暗号化して保存される)、ここで使用するパスワードの文字列は、認証サーバでエージェントプロファイル作成時に設定したもの
hostsファイルへ認証サーバの追加記載
- エージェントを導入するサーバの/etc/hostsへの記載 e.g. xxx.xxx.xxx.xxx verify.example.com
- アクセス確認するクライアントPCのC:/Windows/System32/drivers/etc/hostsへの記載 e.g. xxx.xxx.xxx.xxx verify.example.com
httpdサーバの停止
- エージェントインストール中はhttpdを停止させる

インストール

エージェントをインストールします。このとき、認証サーバは起動している必要があります。

エージェントフォルダへ移動 e.g. cd /opt/APACHE/httpd/web_agents/apache22_agent/bin/
インストール実行 ./agentadmin --install --acceptLicense
設定項目への入力
1. Apache Server Config Directory: httpdのconfフォルダ e.g. /opt/APACHE/httpd/conf
2. OpenAM Server URL: 認証サーバのURL(プロトコル・ポート付き) e.g. https://verify.example.com:8443/openam
3. Agent URL: エージェントを使用するhttpdサーバのURL e.g. https://agent.example.com:443
4. Agent Profile Name: 事前に認証サーバで設定したエージェントのプロファイル名 e.g. agent01
5. Agent Profile Password file name: エージェントパスワードファイルへのパス e.g. /tmp/pw.txt
6. インストール状況の確認
事前準備で止めていたhttpdを起動する
httpdのエラーログ(未変更ならlogs/error_log)内にWeb Policy Agent/3.0 configured -- resuming normal operationsの記載があることを確認する
- 平文で保存していたパスワードファイルを削除するこれでエージェントのインストールも完了しました。

インストール結果確認

インストールが無事終了したかの確認をします。

OpenAMの認証を使用したいアプリへアクセスする e.g. https://agent.example.com/myapp
OpenAMの認証ページにリダイレクトされることを確認する
ID及びパスワードを入力する e.g. ID:amadmin及びそのパスワード
認証確認後アプリページヘと再度リダイレクトされることを確認する確認できればOpenAMによる認証の環境構築が完了したことになります！おめでとうございます、そしてお疲れ様でした。

その他

インストール中に困った際ややり直しをしたいときには下記にあるログやアンインストール方法を参考にしてください。

Web Policy Agentのログ設置場所
- 既存の設定では${Agentをインストールしたフォルダ}/web_agents/apache22_agent/Agent_001/logs/debug/amAgent に出力される
Web Policy Agentのアンインストール
- httpdが起動中であれば停止する
- インストール時と同じフォルダから次の内容を実行 ./agentadmin --uninstall

使用可能になってからの追加設定

ここまででひとまず動く状態にはなっていますが、使っていく上では次の幾つかについて追加の設定が必要でしょう。
管理ユーザ(amadminなど)で https://verify.example.com:8443/openam にアクセス後、アクセス制御>/ (最上位のレルム)へ移動します。

ユーザ、グループ管理

対象タブから追加します。次に設定するポリシーでは、ここで管理しているユーザやグループを対象に、アクセスの可否などを指定できます。また、管理ユーザは初めはamadminだけですが後から追加も可能です。
追加は下記のように行います。

グループを追加する
権限タブから追加したグループを選ぶ
次の項目についてチェックをする
- すべての設定済みエージェントに対する読み取りおよび書き込みのアクセス(エージェントの追加や設定の変更ができるようになる)
- ポリシープロパティーのみに対する読み取りおよび書き込みのアクセス(ポリシーの変更や、ユーザの追加などができるようになる)

ポリシーの設定

ポリシータブから、アクセス可否の設定を行います。

"iPlanetAMWebAgentService"を選択(名前のところをクリックするイメージ)
"Add New Policy"ボタンより新しいポリシーの追加
Step 1はなるべくスペースや全角などを含まない名前に指定(どのポリシーを適用するか、ポリシー名を指定して選ぶこともできるので必要になったときのために)
Step 2は、ポリシー適用先のURLの指定。*://*:*/*はすべてのプロトコルの(1番目の＊)、すべてのホスト・ドメインの(2番目の＊)、すべてのポートの(3番目の＊)、Getリクエストパラメータのついたリクエスト以外のすべてのページ(4番目の＊)を示します。*://*:*/*?*と合わせて指定すれば、Getリクエストパラメータのついたリクエストについてもすべて対象とできます。これらの意味については、5.5.2. Configuring Web Policy Agent Application Propertiesに詳細がありますのでご覧ください。
Step 3は、許可するアクションの指定です。通常であれば、GET, HEAD, POSTについて許可しておけばよいでしょう。
Step 4は、許可するユーザの指定です。例えば、作成済のグループとして"manager"グループがあったとしたら、Type=Users & Group, Goup Subjects=manaerのように指定します。
Step 5は、許可する環境状況(アクセスしてきたマシンの環境や時間など)の指定です。例えば、Type=Timeににした上で、アプリの使用を許可したい時間を記載するようなイメージです。
Step 6は、応答時の属性についての設定のようです。ようです、という言い方なのは、こちらについて設定を何度か試みていますが、反映されているのか、されているとしてどこに影響が出たのか、を把握できていない状況にあるためです。推測ですが、エージェントのクッキー情報/ヘッダー情報設定の際に、応答属性の設定があるので、そこで使用したい項目と連動させるのが良さそうです。例えば、Subject attributesにはユーザIDである"uid"、ユーザ名である"cn"を指定します。
Step 7は設定項目の確認です。Finishボタンを押した後、右上の"OpenAM Console"から戻ります。

適用対象外ページの設定

エージェントタブにて、Welcomeページのように、ログインしなくても見れるページを作りたい場合の指定をします。

作成済のエージェントを選択
アプリケーションタブを選択
「適用されないURL処理」にて
- 適用されないURLのパス情報を無視する、にチェックがついていたら外す
- 適用されないURL、について、ログインしなくても見れるようにしたいページを追加する
右上の保存ボタンで保存

次のようなフォルダ構成を例にとって指定の例示をします。

index.html：ログインなしでも見れるようにする
├── css：ログインなしでも見れるようにする
├── js：ログインなしでも見えるようにする
├── img：
| ├── open.png：ログインなしでも見れるようにする
| └── secret：要ログイン
| └── secret.png：要ログイン
└── views
    ├── sample：ログインなしでも見れるようにする
    | ├── sample00.html
    | └── sample01.html　
    └── content.html：要ログイン

指定例：

https://agent.example.com:443/index.html
https://agent.example.com:443/css/*
https://agent.example.com:443/js/*
https://agent.example.com:443/img/-*-
https://agent.example.com:443/views/sample/*
https://agent.example.com:443/views/sample/*?*

尚、imgフォルダに指定した-*-はそのフォルダの直下だけ、という意味になります。なので、上記のように指定するとsecretフォルダ以下はログイン後でないと見れません。

ログアウト処理を実行させるページの設定

エージェントタブにて、アプリ側で特定のページヘのアクセスをするとOpenAMのセッションを破棄しログアウト処理を実行させるページの指定をします。

作成済のエージェントを選択
OpenAMサービスタブを選択
ページ中程、エージェントログアウトURLにログアウト処理実行のページを指定尚、OpenAMの既知のバグで、Web Policy Agentをエージェントとして使用する場合、ログアウト後のリダイレクト先URLを指定してもリダイレクトされません。つまり、本来はログアウトページへ飛んだ後は、アプリのトップページに戻ってほしいと思っていても、OpenAMのログアウトページに飛ばされてしまいます。これは、OpenAMがリダイレクトに"goto"というパラメータを指定してリダイレクトさせようとしているところ、"goto"が有効なのはOpenAMへのログインセッションが有効な間のみなので、アプリログアウト→OpenAMのセッション破棄→リダイレクト、とするところ、最後のリダイレクト時には既にセッションが破棄されているためリダイレクトができないというものです。こちらをどうしても使用したい場合は、J2EE Agentを使用すると機能するようです。

ログ出力量の変更

エージェントタブにて、エージェントのログをどの程度精緻に残すかの設定をします。

作成済のエージェントを選択
グローバルタブ中程、一般に記載のエージェントデバッグレベルのラジオボタンを「情報」に変更
すぐ下、監査に記載の監査アクセスタイプを"LOG_BOTH"に変更
同じく監査に記載の監査ログ位置を「ローカル」に変更これでエージェントのログがある程度詳細に出力されるようになります。また、監査アクセスタイプを指定することで、どのアカウントがいつログインに成功/失敗したかが記録されるようになります。

その他

その他、細かな点についていくつか記載します。

SSOのみモードについてエージェントタブ内のグローバルタブ中程、一般に記載のSSOのみモードですが、こちらはチェックをすると、OpenAM上に作成済のユーザはすべてアプリを閲覧可能にする、という設定になります。つまり、ポリシーで、「ユーザxxxのみALLOW、その他はDENY」と指定していてもSSOのみモードがONになっている場合には、期待通りの動作をしないので注意が必要です。
クッキー情報/ヘッダー情報の不可についてエージェントタブ内のアプリケーションタブ後半、ログインに成功した際にクッキーやヘッダーに当該ユーザの情報を付与することが出来る設定です。マップキー側にはOpenAM独自のプロパティ名(ユーザIDなら"uid", ユーザ名なら"cn")を指定、対応するマップ値側にはアプリが使用したいクッキー/ヘッダー名を指定します。ようこそ○○さん、といった記載をするためには不可欠な設定です。
プロキシ利用についてエージェントタブ内の高度タブ前半、ロードバランサにて設定が行えます。「ロードバランサの設定」は認証サーバがロードバランサの後ろに設置されている場合にチェックします。要求～や通知～については、アプリ及びエージェントがロードバランサの後ろに設置されている場合にチェックします。

最後に

OpenAMはかつてSSOという名称だったこともあり、まだまだ"SSO"の名で探して出てくる情報もあります。
ただ、総じて私の経験として言えるのは、OpenAMについてはあまりネット上に情報がなく、あったとしてもあてにならない(古い)ものが多いということです（そしてもちろんこの記事も、探している情報とは違うものだった、という人も多いことでしょう）。
日本語の情報も非常に限られているのが現状です。OpenAMを使用する場合には、隅々までOpenAMの公式ドキュメントを読んでいくのが結果的には近道になりそうです。
そんな辛い状況下にあるますが、この記事で少しでもその苦労が軽減されれば幸いです。

リファレンス

OpenAM Core Documentation 見ていく順番は次のとおりにしていくとよいでしょう。また、Installation Guide及びAdministation Guideはボリュームがあるので、頭から読んでいくよりも知りたいことを目次から探すのが良いかもしれません。
1. Getting Started With OpenAM
2. OpenAM Installation Guide
3. Web Policy Agent User's Guide
4. OpenAM Administration Guide
OpenAM インストール図もあり、説明もわかりやすかったです。少しバージョンが古いです。
The OpenAM Archives 地道ですが、メーリングリストに投げられた質問の中から自分の悩んでいる内容について探すのも一つの手です。

OpenAMによる認証環境の構築