OpenAM Web Policy Agent for Apache 導入について

# はじめに
#### 本記事は、[OpenAM/OpenIGを使用したシングルサインオン環境の構築](http://qiita.com/gzock/items/af6f820b5e872366e853) という記事から続く関連記事の一部です

既にOpenAMが構築してあることを前提に、Apacheに対するエージェント方式のSSOの実現を目指す。


# 前提
* 既にTomcatおよびOpenAMはインストール済であること
* TomcatおよびOpenAMがインストールされているサーバはCentOS7.3を想定
* OpenAMは無料で手に入る中では最新のv13.0を使用
* 同一ホスト内のApache v2.4をSPとする (そのため、事前にyum install httpdなどでインストールしておくこと)
  * ただし、他のSPでも同じです。Apache v2.2でもIISでも正直やることは変わらず、エージェントのインストール方法が少し変わるだけ。聞かれる内容はほぼ変わらないので、本記事を呼んでとりあえずのやり方をマスターできれば、他のエージェントやるときもやり方を流用できる。
* 検証目的の構成を行う

# 環境
* サーバOS: CentOS7.3
* ホスト名: sso.test.local
* IPアドレス: 172.16.1.130
* JDK Ver: 1.8.0_111
* Tomcat Ver: 8.0.39
* OpenAM Ver: 13.0.0

# 構築作業

## OpenAM側の設定

### OpenAM上でエージェントプロファイルを作成

1. トップページから`Top Level Realm` => `Agents` => `Web`の`新規`をクリックしてエージェントプロファイルを作成
![2017-03-15-11-32-04.png](https://qiita-image-store.s3.amazonaws.com/0/80163/dd9b806f-0914-026e-45db-0a9dc3874b0b.png)


1. 下記を参考に適宜設定を行う。入力が終わったら保存すること。あとで変更はできるのであまり深く考えなくて良い。
`名前`: 任意のプロファイル名を指定
`パスワード`: 適当なものを。ただし後で使用するので忘れないように。
`設定`: 基本的に集中でOK。集中にすることで、OpenAMの管理画面上でエージェントの動作設定を行える。ローカルにすると、いちいちエージェントのコンフィグファイルを弄らないといけなくなる。
`サーバーURL`: OpenAMが動作しているURLを指定する。今回の場合、http://sso.test.local:8080/openam となる
`エージェントURL`: エージェントが動作しているURLを記述する。というか、SPのURLと考えれば良い。今回の場合は同一仮想マシン内にSPを構成しているので、http://sso.test.local:80となる。ポート番号は必須。

![2017-03-15-11-36-12.png](https://qiita-image-store.s3.amazonaws.com/0/80163/ed35d03c-d8ed-ad1f-f7d9-4e9343305de8.png)


### OpenAM上でAuthorization Policyを作成
1. トップページから`Top Level Realm` => `Authorization` => `Policy Sets`へ移動する。`iPlanetAMWebAgentService`の右側のEditアイコンをクリック。`Add a New policy`で新しいポリシーを作成する。
![2017-03-15-11-37-31.png](https://qiita-image-store.s3.amazonaws.com/0/80163/636d517d-e560-f055-47e8-8f506b0afdce.png)



1. `Name`にポリシーの名前を入力する。何でも良い。`Resource Type`はURLのままで、`Resources`タブにてSPのURLを指定する。ここで指定されたURLに対するアクセスがポリシーの管理対象 = Web Policy Agentの管理対象になる。`*://*:/*`を選択し、それぞれの箇所に適合するようにSPのURLを入力してAdd、問題なければ`create`をクリック
![2017-03-15-13-35-48.png](https://qiita-image-store.s3.amazonaws.com/0/80163/d5a74624-e5ad-6b08-1a5a-82ac499f004c.png)


1. これでポリシー自体は作成できたが、もう少し設定を変更する。`Actions`タブへ移動し、`Select an action...`からGETとPOSTを選んでそれぞれ`Add action`をクリック。設定変更後は必ず`Save Changes`を行う。
![2017-03-15-11-40-04.png](https://qiita-image-store.s3.amazonaws.com/0/80163/42cae957-626f-f793-2913-b5c3c0bb90f9.png)


1. `Subjects`タブへ移動し、Typeを`Authenticated Users`に変更する。最初からなっていたら別にそのままで良い。`
![2017-03-15-11-40-32.png](https://qiita-image-store.s3.amazonaws.com/0/80163/76228712-3ba8-5665-7533-98df2e26b499.png)


1. `Environments`と`Response attributes`と`Details`はスルーでok


## Web Policy Agentをインストール

### 下準備
#### ダウンロード
Web Policy AgentもOpenAMと同じような手順で、Forgerock社から入手する必要がある。
下のURLからOpenAM => Web Policy Agents => 4.0.0 => APACHE => 2.4 => LINUX => 64-BIT と辿って、.zipを落としてくる。
OpenAMと同じくダウンロードにはサインインが必要。
[https://backstage.forgerock.com/downloads/OpenAM](https://backstage.forgerock.com/downloads/OpenAM
)

#### ユーザの有効化
Web Policy AgentはSPとなるサーバ、今回であればApacheを実行するユーザで、インストールを進める必要がある。
CentOS7.3でyumを使ってhttpdをインストールした場合、実行ユーザは`apache`になる。
しかし、デフォでは/sbin/nologinによってシェルが使えない状態になっているため、まずこの辺を何とかする。
Web Policy Agentのインストールが終わったら、/sbin/nologinに戻しておいたほうが良いと思う。
また、コンフィグファイルたちが格納されている/etc/httpdのオーナーに指定してあげて、Agentが動作するために必要な権限が振られている状態にする。

```
[root@sso httpd]# su - apache
This account is currently not available.
[root@sso httpd]# vim /etc/passwd
※略
apache:x:48:48:Apache:/usr/share/httpd:/sbin/nologin  <== /bin/bash に変更する

[root@sso httpd]#
[root@sso httpd]# su - apache
-bash-4.2$ exit
[root@sso httpd]# chown apache:root -R /etc/httpd
```


### 展開
SPとなるサーバ(本記事内ではOpenAMと同一ホスト)にDLした.zipを持っていき展開する。
上述の通り、インストールはSP実行ユーザ(apache)で行う必要があるため、apacheのホームディレクトリ(といっても/usr/share/httpdだが)に移す。

```
[root@sso ~]# unzip Apache_v24_Linux_64bit_4.0.0.zip
Archive:  Apache_v24_Linux_64bit_4.0.0.zip
   creating: web_agents/apache24_agent/
   creating: web_agents/apache24_agent/log/
   creating: web_agents/apache24_agent/instances/
   creating: web_agents/apache24_agent/config/
  inflating: web_agents/apache24_agent/config/agent.vcl3.template
  inflating: web_agents/apache24_agent/config/agent.vcl.template
  inflating: web_agents/apache24_agent/config/agent.conf.template
  inflating: web_agents/apache24_agent/config/mod_iis_openam_schema.xml
   creating: web_agents/apache24_agent/legal/
  inflating: web_agents/apache24_agent/legal/THIRDPARTYREADME.txt
  inflating: web_agents/apache24_agent/legal/CDDLv1.0.txt
  inflating: web_agents/apache24_agent/legal/Forgerock_License.txt
   creating: web_agents/apache24_agent/lib/
  inflating: web_agents/apache24_agent/lib/mod_openam.so
   creating: web_agents/apache24_agent/bin/
  inflating: web_agents/apache24_agent/bin/agentadmin

[root@sso ~]# chown apache -R web_agents
[root@sso ~]# mv web_agents ~apache
```
#### パスワードファイルの作成
インストール過程でパスワードが記述されたファイルを指定する必要がある。
パスはどこでも良いのだが、本記事内では/tmp/passwdという形で作成しておく。
ここで指定するパスワードは、OpenAMで作成したエージェントプロファイルの中で指定したパスワードであるので、間違えないように。
間違えても後述のインストールが失敗するだけなので直せば良いのだが・・・

```
[root@sso ~]# echo hogehoge > /tmp/passwd
```

### インストール
インストールを始める前にSPであるhttpdが実行状態である場合は事前に停止しておくこと。
SP実行ユーザ(apache)へ切り替えて、展開したWeb Policy Agentの中にある`agentadmin`を実行する。
`--i`をつけることでインストールモードになる。
ウィザードの中で色々聞かれるが、基本的にはOpenAM上でエージェントプロファイルを作ったときの内容になる。
詳細について以下のログの中で記述している。

```
-bash-4.2$ cd web_agents/apache24_agent/bin/
-bash-4.2$ ./agentadmin --i
Please read the following License Agreement carefully:

READ THIS SOFTWARE LICENSE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING
THE FORGEROCK SOFTWARE, YOU, ON BEHALF OF YOURSELF AND YOUR COMPANY, AGREE TO
BE BOUND BY THIS SOFTWARE LICENSE AGREEMENT. IF YOU DO NOT AGREE TO THESE
TERMS, DO NOT DOWNLOAD OR INSTALL THE FORGEROCK SOFTWARE.

1. Software License.

1.1. Development Right to Use. If Company intends to or does use the ForgeRock
Software only for the purpose(s) of developing, testing, prototyping and

※略

7.7. Entire Agreement. This Agreement constitutes the entire and exclusive
agreement between the parties with respect to the subject matter hereof and
supersede any prior agreements between the parties with respect to such subject
matter


Do you completely agree with all the terms and conditions
of this License Agreement (yes/no): [no]: yes

OpenAM Web Agent for Apache Server interactive installation.


Enter the complete path to the httpd.conf file which is used by Apache HTTP
Server to store its configuration.
[ q or 'ctrl+c' to exit ]
Configuration file [/opt/apache/conf/httpd.conf]: /etc/httpd/conf/httpd.conf  <== httpdのコンフィグファイルのパスを入力

Change ownership of created directories using User and Group settings in httpd.conf
[ q or 'ctrl+c' to exit ]
(yes/no): [no]: yes    <== 新しく作るディレクトリをhttpd.confに書かれているユーザの権限にして良いかどうか。yesで良いと思う。

To set properties from an existing configuration enter path to file
[ q or 'ctrl+c' to exit, return to ignore ]
Existing OpenSSOAgentBootstrap.properties file: <== 空エンターでok

Enter the URL where the OpenAM server is running. Please include the
deployment URI also as shown below:
(http://openam.example.com:58080/openam)
[ q or 'ctrl+c' to exit ]
OpenAM server URL: http://sso.test.local:8080/openam <== OpenAMのURLを指定

Enter the Agent URL as shown below:
(http://agent.example.com:1234)
[ q or 'ctrl+c' to exit ]
Agent URL: http://sso.test.local <== SPのURLを指定、これはOpenAMで作成するときと違ってポート番号はなくても良い。

Enter the Agent profile name
[ q or 'ctrl+c' to exit ]
Agent Profile name: web_agent <== エージェントプロファイルの名前を指定。OpenAM側と同一にしておいたほうが良い。

Enter the Agent realm/organization
[ q or 'ctrl+c' to exit ]
Agent realm/organization name: [/]: <== 空エンターでok

Enter the path to a file that contains the password to be used
for identifying the Agent
[ q or 'ctrl+c' to exit ]
The path and name of the password file: /tmp/passwd <== 下準備のときに作ったパスワードファイルを指定

Installation parameters:

   OpenAM URL: http://sso.test.local:8080/openam
   Agent URL: http://sso.test.local
   Agent Profile name: web_agent
   Agent realm/organization name: /
   Agent Profile password source: /tmp/passwd

Confirm configuration (yes/no): [no]: yes <== ただの確認

Validating...

Validating... Success.

Cleaning up validation data...

Creating configuration...

Installation complete. <== うまくいけばこうなる

-bash-4.2$ ./agentadmin --l <== --l でインストール済エージェントの一覧を表示

OpenAM Web Agent configuration instances:

   id:            agent_1
   configuration: /usr/share/httpd/web_agents/apache24_agent/bin/../instances/agent_1
   server/site:   /etc/httpd/conf/httpd.conf

-bash-4.2$ tail /etc/httpd/conf/httpd.conf
IncludeOptional conf.d/*.conf

LoadModule amagent_module /usr/share/httpd/web_agents/apache24_agent/bin/../lib/mod_openam.so
AmAgent On
AmAgentConf /usr/share/httpd/web_agents/apache24_agent/bin/../instances/agent_1/config/agent.conf

-bash-4.2$ exit
[root@sso ]# systemctl start httpd
[root@sso ]# rm -rf /tmp/passwd  <== パスワードファイルは削除しておきましょう
```


# 動作確認
* Webブラウザから、SPのURL、今回でいえばsso.test.localへアクセスし、OpenAMのログイン画面へリダイレクトされたら、まずはOK
* ログイン後、Apacheのトップページが表示されたら、エージェントはうまく動作している

# 備考
エージェント方式は、OpenAM認証後のCookieを持っているかどうかで、SPへのアクセスを制御しているだけなので、ログインを代行したりするものではない。
SPとなるWebアプリケーション、普通は社内システムが主だと思うが、そういったシステムはOpenAMの認証後Cookieを持っていても、何か挙動が変わるわけではないので、この方式を実装したとして、ユーザが辿り着くのは結局各Webアプリケーションのログインページであり、手動でのログインが再度必要になってしまう。
SSOの意味ねー！！

そのため、現実的にSSO対応させるとなると、SPとなるWebアプリケーションでは以下のような実装が必要になる (と思う)

* OpenAMの認証後Cookieを持っている場合はログイン済とみなして、ログイン後ページへ遷移させる
* 認証後Cookieを使ってOpenAMへ問合せ、各種情報を取得する

OpenAMの認証後Cookieはデフォでは、`iPlanetDirectoryPro`という名称になる。
OpenAMに対して、`/openam/identity/attributes`というパスに対して、クエリで`subjectid=[iPlanetDirectoryPro]`を付けてGETすると、OpenAMから様々情報を取得できる。例えば、ActiveDirectoryと連携している場合、設定さえすればAD上の任意の属性値をこの手段で取得も出来る。

```
ex)
http://sso.test.local:8080/openam/identity/attributes?subjectid=[iPlanetDirectoryPro]
```


# トラブルシュート
## Agentのインストールに失敗する・・・
インストールログを読もう！読めばだいたいの目星はつきます。
個人的に思う見るべきポイントは以下です。
* 実行ユーザは正しいか (Apacheの/etc/httpd/配下に書き込める権限を持っている？)
* OpenAM上でエージェントプロファイルを作成しているか、あるいは設定が間違っていないか

もしインストールを何度か失敗させちゃったときは、web_agentsフォルダを丸ごと削除して、綺麗にしてからやり直したほうが良いかもです。

## ログイン画面にはリダイレクトされたけど、ログイン後、Apacheのトップページが表示されない(403エラーになる)
OpenAMのAuthorization Policyの設定を見直してみましょう。URLの指定が間違ってませんか？
あるいは、エージェントインストール時の実行ユーザが間違っている可能性もあります。
CentOS7.xの場合、本当はapacheユーザでやらないといけないところ、rootでやっちゃったりすると、こういった事象が発生します。(経験済み)