この文書にはuApprove Jet Pack 4.0 (以下、「uApprove JP」) のインストールガイドと総合マニュアルが記されています。
uApprove JPはShibboleth Identity Provider 4を拡張するプラグインです。uApprove Jet Pack 3.4で提供していた機能をShibboleth Identity Provider 4でも利用できるようにすることを目的としています。これを利用することにより、利用者はIdentity Providerで認証する際に、属性を選択的に送信することができます。 uApprove JPのコンセプトに関するより詳細な情報はこちらを参照してください。
本ガイドに関する注意事項:
- このガイドでは、uApprove JPはLinuxシステムにインストールされると仮定しています。Windows等の他のオペレーティングシステムにインストールすることも可能です。その場合は、いくつかのパスやコマンドを適切なものに置き換えてください。
- このガイドでは、パスやコマンドは
$IDP_HOME$
、$UAPPROVE_INSTALL$
といった変数で示されます。明示的に置き換えが不要と書かれていない限りは、これらの変数は実際のパスに置き換えてください。
...
目次
目次 | ||
---|---|---|
|
想定
...
1. Shibboleth Identity Provider のための uApprove.jp のインストールおよび設定方法
1.1 はじめに
uApprove.jp (uApproveを機能拡張しました)は、 エンドユーザに利用するサービスに送信する属性の表示の選択を提供するアプリケーションです。
本ガイドでは Shibboleth Identity Provider (IdP)のための uApprove.jp のインストールおよび設定方法を説明します。
IdP プラグインおよび uApprove.jp viewer のインストール方法と、 ストレージとしてファイルもしくは SQL データベースを用いた設定方法を示します。
このガイドでは例として以下の設定値を使用します。
idp.example.org
- Identity Provider の DNS 名
/opt/uApprove
- uApprove.jp をインストールするディレクトリ
/opt/uApprove/conf
- uApprove.jp の設定ファイルのディレクトリ
/opt/shibboleth-identityprovider-2.x
- Shibboleth IdP のインストール時にZIPファイルを展開したディレクトリ (
install.sh
が存在するディレクトリ)
- Shibboleth IdP のインストール時にZIPファイルを展開したディレクトリ (
/opt/shibboleth-idp
- Shibboleth IdP のインストール先
${CATALINA_HOME}
- Tomcat のインストール先 (例えば、
/usr/java/tomcat
)
- Tomcat のインストール先 (例えば、
1.2 前提条件
uApprove.jp のインストールと設定の前に、以下の前提条件が揃っていることを確認してください。
- Shibboleth Identity Provider 2.3.
- 正しく配備した Shibboleth Identity Provider が必要です。
Java と Tomcat が動作することも含みます。
- 正しく配備した Shibboleth Identity Provider が必要です。
- SQL Database
- ストレージとして SQL データベースを使用する場合は SQL サーバが必要です。
uApprove.jp は既に MySQL 用の設定が行われていますが、他の SQL サーバも使用できます。
- ストレージとして SQL データベースを使用する場合は SQL サーバが必要です。
1.3 インストール
uApprve.jp をダウンロードして unzip してください:
パネル |
---|
|
1.3.1 IdP-Plugin
ライブラリファイルと設定ファイルをコピーしてください:
パネル |
---|
|
1.3.2 Viewer
ライブラリファイルと設定ファイルをコピーしてください:
パネル |
---|
|
1.4 設定
uApprove.jp は二つのソフトウェアから成り立っています。 IdP コンテクストの中で動作する IdP プラグインと IdP コンテクストから独立した uApprove.jp viewer アプリケーションです。
どちらも共通のデータストレージとその操作のためのライブラリを使用します。
1.4.1 uApprove.jp 共通: ストレージ等
- ユーザ名
- ユーザが同意した Term of use の最終バージョン
- Shibboleth SP にリリースされた暗号化された属性のリスト
- Shibboleth SP の Entity ID
最初にどちらのストレージを使用するか決めなければなりません:
- ファイルベース
- 少人数の構成で利用することを推奨します。(100 ユーザ未満)
- SQL データベース
- MySQL データベースを完全にサポートしています。JDBC コネクタを持つデータベースでも動くでしょう。もしかしたら 動かすために高等な設定が必要になるかもしれません。
ファイルベース
ファイルベースストレージの設定は /opt/uApprove/conf/common.properties で行います:
...
注意 |
---|
uApprove-log.xml が置かれるディレクトリが Tomcat から読み書きできることを確認してください。 |
警告 |
---|
uApprove-log.xml は uApprove.jp が生成しますので、事前に作成しないでください。 |
データベース
最初にデータベースとユーザを作成します:
パネル |
---|
|
次に、テーブルを作成します:
...
注意 |
---|
以下のテーブルはuApprove.jp-2.2.1で追加しました。
以下のテーブルはuApprove.jp-2.2.1cで追加しました。
|
簡単にデータベースの設定が正しいかを確認するためには、下記コマンドを利用できます:
パネル |
---|
|
データベースを利用する設定は /opt/uApprove/conf/common.properties で行います:
...
注意 |
---|
uApprove.jp は BoneCP ライブラリにより提供される JDBC コネクションプーリングサービスをサポートしています。 |
データベース固有の設定すべては /opt/uApprove/conf/database.properties で行います:
...
- Shibboleth Identity Providerは、
$IDP_HOME$
(例:/opt/shibboleth-idp
) にインストールされているものとします。 - Tomcatではなく、Jettyがインストールされているものとします。
- uApprove JP は、
$UAPPROVE_INSTALL$
(例:/usr/local/src/uApproveJP-#version#
) にダウンロード、展開されているものとします。
前提条件
Shibboleth Identity Provider 4.0.0以降がインストールされている必要があります。
警告 Shibboleth Identity Provider 4.0.0未満のバージョンでは動作しません。
1 基本的なデプロイ
1.1 ライブラリのインストール
ライブラリをIdPのライブラリディレクトリにコピーします:
書式設定済み |
---|
# cp $UAPPROVE_INSTALL$/lib/*.jar $IDP_HOME$/edit-webapp/WEB-INF/lib/ |
注意 |
---|
|
1.2 Velocity テンプレートファイル
属性選択画面用のVelocityテンプレートファイルをIdPのviews
ディレクトリに上書きコピーします:
書式設定済み |
---|
# cp $UAPPROVE_INSTALL$/manual/examples/views/intercept/* $IDP_HOME$/views/intercept/
以下のメッセージが表示される場合がありますが、y を入力してください。
cp: `/opt/shibboleth-idp/views/intercept/attribute-release.vm' を上書きしますか? |
1.3 CSS ファイル
CSSファイルをIdPのedit-webapp
ディレクトリにコピーします:
書式設定済み |
---|
# cp $UAPPROVE_INSTALL$/manual/examples/edit-webapp/css/* $IDP_HOME$/edit-webapp/css/ |
1.4 メッセージファイル
メッセージファイルをIdPのメッセージディレクトリにコピーします:
書式設定済み |
---|
# cp $UAPPROVE_INSTALL$/manual/examples/messages/* $IDP_HOME$/messages/ |
$IDP_HOME$/conf/services.xml
に、以下の変更を行います。id="shibboleth.MessageSourceResources"
に<value>%{idp.home}/messages/uApproveJP</value>
を追加してください:
パネル | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
|
1.5 設定のカスタマイズ
$IDP_HOME$/conf/idp.properties
に、以下の変更を行います。idp.consent.allowPerAttribute
とidp.consent.compareValues
の値をtrue
に設定してください:
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
$IDP_HOME$/conf/global.xml
に、以下の属性選択画面で使用するbean
定義を追加します:
ヒント |
---|
挿入する場所に制限はありませんが、よく分からなければ末尾の行に |
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
警告 | |||||
---|---|---|---|---|---|
Shibboleth IdP 4.1以降では、以下の2つのファイルの変更(
|
$IDP_HOME$/system/conf/services-system.xml
に、以下の変更を行います。id="shibboleth.AttributeFilterService"
のbean
定義の<constructor-arg name="strategy">
を以下のように変更してください:
注意 |
---|
この変更は、Shibboleth Identity Providerを再インストール(アップグレード等)する際に上書きされるため、再インストールを行った際には、再度変更を行う必要があります。 |
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
$IDP_HOME$/system/flows/intercept/attribute-release-beans.xml
に、以下の変更を行います。id="IsConsentRequiredPredicate"
のbean
定義のclass
を変更してください:
注意 |
---|
この変更は、Shibboleth Identity Providerを再インストール(アップグレード等)する際に上書きされるため、再インストールを行った際には、再度変更を行う必要があります。 |
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
1.6 カスタムテンプレート
テンプレートをカスタマイズしたい場合は、 テンプレートのカスタマイズ を参照してください。
少なくとも、所属機関のロゴを変更する必要があります。変更方法は以下のリンク先を参照してください。
GakuNinShare:Shibboleth IdP 3 - ロゴの変更
1.7 ログの設定
uApprove JPのログを出力するには、$IDP_HOME$/conf/logback.xml
に以下を追加します:
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
1.8 デプロイ
IdP で uApprove JP を有効にするには IdP を再デプロイする必要があります:
パネル |
---|
# cd $IDP_HOME$ # ./bin/build.sh Installation Directory: [/opt/shibboleth-idp] [Enter] ←入力なし Rebuilding /opt/shibboleth-idp/war/idp.war ... ...done BUILD SUCCESSFUL Total time: 16 seconds |
$CATALINA_BASE$/conf/Catalina/localhost/idp.xml
が存在しない場合は、追加の作業としてidp.war
を$CATALINA_BASE$/webapps
にコピーします:
書式設定済み |
---|
# ls $CATALINA_BASE$/conf/Catalina/localhost/idp.xml
ls: cannot access /usr/java/tomcat/conf/Catalina/localhost/idp.xml: そのようなファイルやディレクトリはありません
# cp $IDP_HOME$/war/idp.war $CATALINA_BASE$/webapps/ |
Jettyを再起動します:
書式設定済み |
---|
# systemctl restart jetty |
2 高度なデプロイ
この節では高度な設定についてのトピックを取り上げます。
2.1 リレーショナルデータベースを用いたユーザ同意情報の保存
リレーショナルデータベース(以下、「RDB」とします)を用いて、ユーザ同意情報の保存を行うことができます。
2.1.1. MySQLの設定
注意 |
---|
以下のデータベースパラメータは一例です。実際の値は必要に応じて変更してください。特にパスワードは安全なものを用意してください。 |
MySQLの設定を行います。
データベース
shibboleth
の作成
Shibboleth IdPで使用するデータベースshibboleth
を作成します:情報 rootにパスワードが設定してあってコマンドが以下のエラーで失敗する場合は、
-p
オプションを追加してください。書式設定済み ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: NO)
パネル borderColor silver bgColor white db$ mysql -u root
mysql>
CREATE DATABASE shibboleth;
ユーザ作成
IdPからデータベースshibboleth
にアクセスするためのユーザshibboleth
を作成し、データベースshibboleth
への権限を付与します:パネル borderColor silver bgColor white db$ mysql -u root
mysql>
CREATE USER 'shibboleth'@'localhost' IDENTIFIED BY '
shibpassword
'; #←任意のパスワード
GRANT INSERT, SELECT, UPDATE, DELETE ON shibboleth.* TO 'shibboleth'@'localhost';
StorageRecords
テーブル作成JPAStorageServic
eが使用するテーブルStorageRecords
を作成します:パネル borderColor silver bgColor white db$ mysql -u root
mysql>
use shibboleth;
CREATE TABLE `StorageRecords` (
`context` varchar(255) NOT NULL,
`id` varchar(255) NOT NULL,
`expires` bigint(20) DEFAULT NULL,
`value` longtext NOT NULL,
`version` bigint(20) NOT NULL,
PRIMARY KEY (`context`,`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin;
2.1.3. MySQL Connector/Jのインストール
MySQLへのアクセスに必要なMySQL Connector/J(
mysql-connector-java.jar
)をインストールします:書式設定済み # yum install mysql-connector-java
/usr/share/java
配下にインストールされているので、edit-webapp/
配下のlib
ディレクトリにシンボリックリンクを作成します:パネル # rpm -ql mysql-connector-java
(省略)
/usr/share/java/mysql-connector-java.jar
(省略)
# ln -s /usr/share/java/mysql-connector-java.jar $IDP_HOME$/
edit-webapp/WEB-INF
/lib/- 1.8 デプロイの手順に従って再デプロイします。
2.1.4. idp.consent.StorageServiceの設定変更
idp.consent.StorageService
の設定をshibboleth.JPAStorageService
に変更します:
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
# Set to "shibboleth.StorageService" or custom bean for alternate storage of consent |
2.1.5. shibboleth.JPAStorageServiceの設定
2.1.4. idp.consent.StorageServiceの設定変更でidp.consent.StorageService
に設定したshibboleth.JPAStorageService
を定義します。
id="Shibboleth.MySQLDataSource"
のbean
定義のp:url, p:username, p:password
は、2.1.1. MySQLの設定に合わせて設定します:
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
2.1.6. Jettyの再起動
Jettyを再起動します:
書式設定済み |
---|
# systemctl restart jetty |
2.2 テンプレート
テンプレートのカスタマイズ
$IDP_HOME$/views/
にある Velocityテンプレートファイル 、 $IDP_HOME$/edit-webapp/
にあるCSS や画像ファイルは自由にカスタマイズすることができます。 Velocity を用いているので容易にカスタマイズ出来るようになっています。
Velocity については Velocity User Guide を参照してください。
2.3 ローカライズ
Relying Partyの名前と説明
現状では、ローカライズされた Relying Party の名前と説明を取得する際には、メタデータのうち<AttributeConsumingService>
要素および<mdui:UIInfo>
要素がサポートされています。
この名前と説明を使用する場合は、SPのメタデータを以下のように記述します:
パネル | ||||
---|---|---|---|---|
| ||||
|
ヒント |
---|
両方記載されている場合には 学認のSPについても海外SPの一部を除いてこの情報が含まれています。 |
3 AttributeInMetadata
3.1 AttributeInMetadataマッチングルールの設定
このルールは、SP がその属性を必要とした場合に、そのメタデータにより属性の送信を許可します。属性は<SPSSODescriptor>
中の<AttributeConsumingService>
によって示されます。 <RequestedAttribute>
でisRequired="true"
を記述した属性は必須とマークされ、isRequired="false"
を記述した属性はオプションとマークされます。詳細は SAMLメタデータを参照してください。
注意 |
---|
以下の点に注意してください:
|
名前空間の定義
属性フィルタのポリシーにおいて、このプラグイン用に名前空間の定義を加える必要があります。以下のように行います:
- ルート
<AttributeFilterPolicyGroup>
のxmlns:xsi
属性の前に xmlns:uajpmf="http://www.gakunin.jp/ns/uapprove-jp/afp/mf"
属性を追加します。 xsi:schemaLocation
属性のホワイトスペースで区切られた値のリストの最後に以下を追加します:http://www.gakunin.jp/ns/uapprove-jp/afp/mf http://www.gakunin.jp/schema/idp/gakunin-afp-mf-uapprovejp.xsd
ルールの定義
このルールは<PermitValueRule xsi:type="uajpmf:AttributeInMetadata">
のように記述します。以下のオプショナルな属性を使用できます:
onlyIfRequired | 必須とマークされた属性のみ送信を許可し、オプションとマークされたものは送信しないブーリアンフラグです。 デフォルト値は |
matchIfMetadataSilent | メタデータに デフォルト値は |
onlyIfChecked | オプションとマークされた属性の送信を利用者が許可/拒否できるかどうかを示すブーリアンフラグです。 デフォルト値は |
AttributeInMetadata
マッチファンクションを使用した<PermitValueRule>
の書き方は下記のようになります:
パネル | ||||
---|---|---|---|---|
| ||||
<PermitValueRule xsi:type="uajpmf:AttributeInMetadata" onlyIfRequired="false"
onlyIfChecked="true"/> |
オプションとマークされた属性をチェックボックスつきで表示します。チェックボックスをチェックしたときだけ送信します。
AttributeInMetadata
マッチファンクションを使用した<PermitValueRule>
の設定例を示します:
パネル | ||||
---|---|---|---|---|
| ||||
<!-- ==================================================================================
case 1: mail 属性、eduPersonPrincipalName属性、eduPersonAffiliation属性を、メタデータの
定義と照合するルールです。
メタデータでisRequired="true"が指定されている属性は、すべて必須情報になり常に
送信されます。
メタデータでisRequired="false"が指定されている属性は以下の通りです。
* mail属性は必須情報となり常に送信されます。
* eduPersonPrincipalName属性はオプション情報となります。属性選択画面ではチェック
ボックスつきで表示されます。利用者がチェックボックスをチェックした場合に限り送信
されます。
* eduPersonAffiliation属性は送信されません。
メタデータにAttributeConsumingServiceをもたないSPの場合はどの属性も送信しません。
================================================================================== -->
<AttributeFilterPolicy id="PolicyforSPwithAttributeConsumingService">
<PolicyRequirementRule xsi:type="ANY" />
<AttributeRule attributeID="mail">
<PermitValueRule xsi:type="uajpmf:AttributeInMetadata"
onlyIfRequired="false" />
</AttributeRule>
<AttributeRule attributeID="eduPersonPrincipalName">
<PermitValueRule xsi:type="uajpmf:AttributeInMetadata"
onlyIfRequired="false"
onlyIfChecked="true" />
</AttributeRule>
<AttributeRule attributeID="eduPersonAffiliation">
<PermitValueRule xsi:type="uajpmf:AttributeInMetadata" />
</AttributeRule>
</AttributeFilterPolicy>
<!-- ==================================================================================
case 2: メタデータに AttributeConsumingServiceがないSPに対するルールを追加したルール
です。
AttributeConsumingService要素を持たないSPの場合は以下の通りです。
* mail属性は必須情報となり常に送信されます。
* eduPersonPrincipalName属性はオプション情報となります。属性選択画面ではチェック
ボックスつきで表示されます。利用者がチェックボックスをチェックした場合に限り送信
されます。
* eduPersonAffiliation属性は送信されません。
AttributeConsumingService要素を持つSPの場合はcase 1と同じです。
================================= |
注意 |
---|
MySQL 以外の SQL サーバを使用する場合は上記の値を使用する SQL サーバに合わせる必要があります。 |
共通設定
使用条件のテキストをユーザに表示するためのオプション TermsOfUseManager があります。 TermsOfUseManager を有効にしたい場合は、/opt/uApprove/conf/common.properties で定義します:
パネル |
---|
|
注意 |
---|
含まれている terms-of-use.xml は空のファイルですので、独自の使用条件のバージョンと本文を記述できます。実例として SWITCHaai VHO terms of use ( doc/terms-of-use-SWITCH.xml ) がありますので、参照してください。 |
IdP プラグインおよび viewer アプリケーションは機密情報を交換するため、 /opt/uApprove/conf/common.properties で定義される共通秘密鍵(128bit, 16バイト)により暗号化と復号を行います。
パネル |
---|
|
簡単に 16 バイトの乱数を生成するためには、以下コマンドを利用できます:
パネル |
---|
openssl rand -base64 16 2>/dev/null |
1.4.2 IdP プラグインの設定
Shibboleth IdP の調整
IdP プラグインは Shibboleth IdP web アプリケーション /opt/shibboleth-identityprovider-2.x/src/main/webapp/WEB-INF/web.xml で有効にする必要があります:
...
注意 |
---|
filter および filter-mapping の定義は web.xml の他の filter および filter-mapping より後に記述しなければなりません。 |
Shibboleth IdP を再デプロイします:
...
idp.war
ファイルを${CATALINA_HOME}/webapps
にコピーします:
パネル |
---|
cp /opt/shibboleth-idp/war/idp.war ${CATALINA_HOME}/webapps/ |
SP ブラックリスト
SP ブラックリストはユーザの同意対象から除外するリソースを定義します。
SP ブラックリストはオプションで設定は /opt/uApprove/conf/idp-plugin.properties で行います:
パネル |
---|
spBlacklist=/opt/uApprove/conf/sp-blacklist |
sp-blacklist
中の各行ではブラックリスト対象のリソースを表す正規表現の定義を行います:
パネル |
---|
# 例 1: 特定のリソース
https://sp\.example\.org/shibboleth
# 例 2: SP に存在するすべてのアプリケーション
https://sp\.example\.org/.*
# 例 3: 特定ドメインにあるすべての SP
https://.*\.example\.org/.* |
属性の順序とブラックリストの作成
属性リストの順序を定義できます。さらに、必要ならば属性の隠蔽もできます。属性リストの設定はオプションで、 /opt/uApprove/conf/idp-plugin.properties で行います:
パネル |
---|
attributeList=/opt/uApprove/conf/attribute-list |
attribute-list
は下記のようになります:
パネル |
---|
# 属性の順序を定義
surname
givenName
postalAddress
...
# 隠す属性
!persistentId
!transientId |
注意 |
---|
attribute-list の属性名は /opt/shibboleth-idp/conf/attribute-resolver.xml の 属性 id に従わなければいけません。 |
その他の設定
データベースを使用する場合は各プロバイダのアクセスに対して記録を残すことが可能で、 これはすべての属性の送信がデータベースに保存されていることを意味します。
IdP プラグイン は monitoring only mode で実行することも可能で、 これはすべてのプロバイダのアクセスを記録しますが、ユーザの同意のためのやりとりは行いません。
viewer web アプリケーションを使用する場合、 IdP プラグインは viewer web アプリケーションのデプロイ先を知っている必要があります。
IdP プラグインに、isPassiveリクエストに関して考慮の必要があることを伝えることができます。
設定は /opt/uApprove/conf/idp-plugin.properties で行います:
パネル |
---|
logProviderAccess=false |
1.4.3 Viewer 設定
uApprove.jp webapp のための tomcat のデプロイの記述を ${CATALINA_HOME}/conf/Catalina/localhost/uApprove.xml で定義します:
パネル |
---|
<Context docBase="/opt/uApprove/war/uApprove.war"
privileged="true"
antiResourceLocking="false"
antiJARLocking="false"
unpackWAR="false" />
|
設定ディレクトリに従って、viewer アプリケーション の設定を修正します。 変更は/opt/uApprove/viewer-2.2.1c/webapp/WEB-INF/web.xml で行います:
パネル |
---|
<web-app>
...
<context-param>
<param-name>Config</param-name>
<param-value>
/opt/uApprove/conf/viewer.properties;
/opt/uApprove/conf/common.properties;
</param-value>
</context-param>
...
<web-app>
|
必要であれば、ロゴやナビゲーションメニューを変更します。 ロゴは/opt/uApprove/viewer-2.2.1c/webapp/images以下のイメージファイルやURLを 使うことができます。
設定は/opt/uApprove/viewer-2.2.1c/webapp/header.jspで行います:
パネル |
---|
<body class="switchaai"> <div class="box-aai" style="width: 650px;"> <img src="images/GakuNin_logo.png" alt="GakuNin-logo" class="switchaai" height="32" width="162"> |
uApprove webapp をデプロイします:
パネル |
---|
cd /opt/uApprove/viewer-2.2.1c/
ant deploy -Duapprove.deployment=/opt/uApprove/war
|
ローカライズ
viewer web アプリケーションは属性名や説明といった静的なテキストと動的なテキストに対して多言語対応です。
静的なテキストは次の言語が対応しています: 英語(en), ドイツ語(de), フランス語(fr), イタリア語(it), ポルトガル語(pt), 日本語(ja)
ローカライズされた属性名と説明は /opt/shibboleth-idp/conf/attribute-resolver.xml (Shibboleth IdP resolver) から取得します。ローカライズされた属性名や説明は変更や追加ができます:
パネル |
---|
...
<resolver:AttributeDefinition id="postalAddress" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="postalAddress">
<resolver:Dependency ref="myLDAP" />
<resolver:DisplayName xml:lang="en">Business postal address</resolver:DisplayName>
<resolver:DisplayName xml:lang="de">Geschäftsadresse</resolver:DisplayName>
<resolver:DisplayName xml:lang="fr">Adresse Professionnelle</resolver:DisplayName>
<resolver:DisplayName xml:lang="it">Indirizzo professionale</resolver:DisplayName>
<resolver:DisplayName xml:lang="ja">所属組織住所</resolver:DisplayName>
<resolver:DisplayDescription xml:lang="en">Business postal address: Campus or office address</resolver:DisplayDescription>
<resolver:DisplayDescription xml:lang="de">Adresse am Arbeitsplatz</resolver:DisplayDescription>
<resolver:DisplayDescription xml:lang="fr">Adresse de l'institut, de l'universite</resolver:DisplayDescription>
<resolver:DisplayDescription xml:lang="it">Indirizzo professionale: Indirizzo dell'istituto o dell'ufficio</resolver:DisplayDescription>
<resolver:DisplayDescription xml:lang="ja">所属組織(大学、会社など)の住所</resolver:DisplayDescription>
<resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
name="urn:mace:dir:attribute-def:postalAddress" />
<resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
name="urn:oid:2.5.4.16" friendlyName="postalAddress" />
</resolver:AttributeDefinition>
... |
情報 |
---|
SWITCHaai 属性については |
特定の言語を強制することもできます。設定は /opt/uApprove/conf/viewer.properties で行います:
パネル |
---|
useLocale=en_US |
包括的な同意
ユーザが包括的な属性送信同意を与えることができます。これはユーザが二度と uApprove から送信する属性を問われないということです。 ユーザが異なるリソースのアクセスに対してそれぞれ同意を行うようにするためには /opt/uApprove/conf/viewer.properties に より機能を無効にできます:
パネル |
---|
globalConsentPossible=true |
ログ出力
viewer web アプリケーションは Shibboleth IdP のように LogBack (1.7 リファレンス)を使用します。
logback の設定ファイルは /opt/uApprove/conf/viewer.properties で定義します:
パネル |
---|
loggingConfig=/opt/uApprove/conf/logging.xml |
ログファイルは logging.xml
で設定します。 Tomcat から書き込みできることを確認してください:
パネル |
---|
<configuration>
...
<appender class="ch.qos.logback.core.FileAppender" name="RootFileAppender">
<file>/opt/uApprove/logs/uApprove.log</file>
...
</appender>
...
</configuration> |
Tomcat のフロントエンドとしての Apache
Apache HTTPd を tomcat のフロントエンドに使用している場合は、viewer web アプリケーション にプロキシーする設定を /etc/httpd/conf.d/ssl.conf で行います:
パネル |
---|
<VirtualHost idp.example.org:443>
...
<Location /uApprove>
Allow from all
ProxyPass ajp://localhost:8009/uApprove
</Location>
...
</VirtualHost>
|
Apache HTTPd を再起動してください:
パネル |
---|
/sbin/service httpd restart |
1.4.4 Shibboleth IdP の profile handler
uApprove.jpはAttribute QueryのSAML応答メッセージの属性のリストをユーザーの同意内容に応じて生成します。
ネームスペースの定義
プロファイルハンドラファイル(例えば、/opt/shibboleth-idp/conf/handler.xml)内に このプラグインのためにネームスペース宣言を追加する必要があります。以下のように行います:
<ProfileHandlerGroup>
ルート要素のxmlns:xsi
属性の前にxmlns:uajpph="http://www.gakunin.jp/ns/uapprove-jp/profile-handler"
属性を追加xsi:schemaLocation
属性の値のリストの最後に下記を追加http://www.gakunin.jp/ns/uapprove-jp/profile-handler classpath:/schema/shibboleth-2.0-idp-profile-handler-uapprovejp.xsd
パネル |
---|
|
Attribute Queryプロファイルハンドラの変更
Attribute Queryプロファイルハンドラを変更する必要があります。以下のように行います:
xsi:type
属性の値をph:SAML1AttributeQuery
からuajpph:SAML1AttributeQueryUApprove
に変更xsi:type
属性の値をph:SAML2AttributeQuery
からuajpph:SAML2AttributeQueryUApprove
に変更
パネル |
---|
|
1.4.5 Shibboleth IdP の attribute filter
uApprove.jpはSPのメタデータ内の <RequestedAttribute>
要素 (2. Shibboleth Service Providerの設定を参照ください)と IdP の属性フィルターポリシーファイル内の<AttributeFilterPolicy>
要素を 理解することで、属性が必須であるかオプショナルであるかを決定します。
ネームスペースの定義
属性フィルターポリシーファイル(例えば、/opt/shibboleth-idp/conf/attribute-filter.xml)内に このプラグインのためにネームスペース宣言を追加する必要があります。以下のように行います:
<AttributeFilterPolicyGroup>
ルート要素のxmlns:xsi
属性の前にxmlns:uajpmf="http://www.gakunin.jp/ns/uapprove-jp/afp/mf"
属性を追加xsi:schemaLocation
属性の値のリストの最後に下記を追加http://www.gakunin.jp/ns/uapprove-jp/afp/mf classpath:/schema/shibboleth-2.0-afp-mf-uapprovejp.xsd
パネル |
---|
|
警告 |
---|
uApprove.jp-2.2.1a 以降はネームスペースの URI が変更になりました。
|
ルールの定義
uApprove.jpはPolicy RequirementルールとAttribute RulesのPermit/Deny Valueルールを拡張します:
- Policy Requirementルール
- このルールは
<afp:PolicyRequirementRule xsi:type="uajpmf:AttributeUapprove">
要素によって定義されます。 そして、SPのメタデータ内に<AttributeConsumingService>
要素が存在する場合に適用されます。
- このルールは
Attribute RuleのPermit/Deny Value Rule
このルールは下記のオプショナルな属性を持つ
<afp:PermitValueRule xsi:type="uajpmf:AttributeUapprove"/>
要素と<afp:DenyValueRule xsi:type="uajpmf:AttributeUapprove"/>
要素両方によって定義されます。isApproved (オプショナル)
ユーザによってSPへ送信を許可された属性を示すブーリアン値です。
デフォルト値: true
しかし、もし SPのメタデータ内の<AttributeConsumingService>
要素内の<RequestedAtrribute>
要素でisRequired="true"
となっている属性は、必須属性として扱われ、常にSPに送信されます。
requestedOnly (オプショナル)
SPのメタデータで定義された属性のみを表示するか否かを示すブーリアン値です。
デフォルト値: false
xsi:type="uajpmf:AttributeUapprove"
を持たない許可された属性は必須属性として扱われます。
uajpmf:AttributeUapprove Matchファンクションを用いたPermit Valueルールの例を示します:
コード ブロック | ||
---|---|---|
| ||
<!-- ================================================================================== case 1: メタデータ内に AttributeConsumingService 要素を持つSPにマッチします。 --> <AttributeFilterPolicy id="PolicyforSPwithoutAttributeConsumingService"> eduPersonPrincipalName 属性はオプショナル属性で、ユーザは送信するか否かを選択できます。<PolicyRequirementRule xsi:type="ANY" /> <AttributeRule attributeID="mail"> eduPersonAffiliation 属性は必須属性で、常に送信されます。 <PermitValueRule xsi:type="uajpmf:AttributeInMetadata" ================================================================================== --> <afp:AttributeFilterPolicy id="PolicyforSPwithAttributeConsumingService"> <afp:PolicyRequirementRule xsi:type="uajpmf:AttributeUapprove" /> <afp:AttributeRule attributeID="eduPersonPrincipalName"> matchIfMetadataSilent="true" <afp:PermitValueRule xsi:type onlyIfRequired="uajpmf:AttributeUapprovefalse" /> </afp:AttributeRule> <afp:AttributeRule<AttributeRule attributeID="eduPersonAffiliationeduPersonPrincipalName"> <afp:PermitValueRule<PermitValueRule xsi:type="basicuajpmf:ANYAttributeInMetadata" /> </afp:AttributeRule> ... </afp:AttributeFilterPolicy> <!-- ================================================================================== case 2: メタデータ内に AttributeConsumingService 要素を持たないSPにマッチします。 eduPersonPrincipalName 属性 および eduPersonAffiliation 属性共に必須属性です。 ================================================================================== --> <afp:AttributeFilterPolicy id="PolicyforSPwithoutAttributeConsumingService"> <afp:PolicyRequirementRule xsi:type="basic:NOT"> <basic:Rule xsi:type="uajpmf:AttributeUapprove"/> </afp:PolicyRequirementRule> <afp:AttributeRule attributeID="eduPersonPrincipalName"> <afp:PermitValueRule xsi:type="basic:ANY" /> </afp:AttributeRule> <afp:AttributeRule attributeID="eduPersonAffiliation"> matchIfMetadataSilent="true" onlyIfRequired="false" onlyIfChecked="true" /> </AttributeRule> <AttributeRule attributeID="eduPersonAffiliation"> <PermitValueRule xsi:type="uajpmf:AttributeInMetadata" /> </AttributeRule> </AttributeFilterPolicy> |
4 トラブルシューティング
4.1 トラブルシューティング
ERROR
ないしWARN
メッセージについては、$IDP_HOME$/logs/idp-process.log
をチェックしてください。$CATALINA_BASE$/logs
にあるTomcatのログファイルにエラーメッセージがないかチェックしてください。
4.2 詳細なログ設定
DEBUG
ないしTRACE
ログレベルを有効にしたい場合は、$IDP_HOME$/conf/idp.properties
にて以下を追加します:
パネル | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
idp.loglevel.uApproveJP = DEBUG |
A SPでの属性使用用途通知
SP管理者はSPのメタデータに属性の使用用途を記述することで、SPの利用者に属性の使用用途 (例えば、プロファイルの初期値として使用) をuApprove JPで表示することができます。
A.1 設定
属性使用用途通知機能は、<RequestedAttribute>
にuajpmd:description
属性を追加する、または、<SPSSODescriptor>
の<Extensions>
に<uajpmd:RequestedAttributeExtension>
を追加することで利用できます。
<uajpmd:RequestedAttributeExtension>
は多言語に対応しています。また、一つの属性に両方が設定されている場合は、<uajpmd:RequestedAttributeExtension>
が優先されます。
これらを使う場合はメタデータの先頭に名前空間 xmlns:uajpmd="http://www.gakunin.jp/ns/uapprove-jp/metadata"
の宣言を忘れないでください。
uajpmd:description
この属性は<ResquestedAttribute>
にて定義します:
uajpmd:description | 属性の使用用途の文字列です。 |
uajpmd:descrption
を使用した<RequestedAttribute>
の設定例:
パネル | ||||
---|---|---|---|---|
| ||||
<md:RequestedAttribute FriendlyName="mail" Name="urn:oid:0.9.2342.19200300.100.1.3" <afp:PermitValueRule xsi:type="basic:ANY" />NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" </afp:AttributeRule> ... </afp:AttributeFilterPolicy> <!-uajpmd:description="The mail attribute is used as the initial value of the mail address field of the registration form."/> |
<uajpmd:RequestedAttributeExtension>
<uajpmd:RequestedAttributeExtension>
は以下の必須属性と一つ以上の<uajpmd:
Description>
と共に設定します:
uajpmd:FriendlyName | 関連づけたい<RequestedAttribute> のFriendlyName 属性の値です。 |
<uajpmd:Description>
には属性の使用用途を記述します。<uajpmd:RequestedAttributeExtension>
は以下の必須属性と共に設定します:
xml:lang | 属性の使用用途の言語です。 |
<uajpmd:RequestedAttributeExtension>
の設定例:
パネル | ||||
---|---|---|---|---|
| ||||
<md:EntitiesDescriptor Name="uapprovejp-dev-metadata.xml" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"- ================================================================================== case 3: 全てのSPにマッチします。 eduPersonPrincipalName 属性 および eduPersonAffiliation 属性はオプショナル属性です。 ================================================================================== --> <afp:AttributeFilterPolicy id="PolicyforAnyone"> <afp:PolicyRequirementRule xsi:type="basic:ANY" /> <afp:AttributeRule attributeID="eduPersonPrincipalName"> xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:shibmd="urn:mace:shibboleth:metadata:1.0" xmlns:uajpmd="http://www.gakunin.jp/ns/uapprove-jp/metadata" <afpxmlns:PermitValueRule xsi:type="uajpmf:AttributeUapprove" /http://www.w3.org/2001/XMLSchema-instance"> </afp:AttributeRule> <afp:AttributeRule attributeID="eduPersonAffiliation... <md:EntityDescriptor entityID="..."> <md:SPSSODescriptor> <afp:PermitValueRule xsi:type="uajpmf:AttributeUapprove" /> ... </afp:AttributeRule> <md:Extensions> ... </afp:AttributeFilterPolicy> |
1.4.6 Reset-approvals 設定
警告 |
---|
list-approvalsアプリケーションを使用する場合は設定しないでください。 |
オプションである reset-approvals は以下の二通りの方法で操作可能です:
- In-flow モード
- ユーザがログイン手続きにおいてリセット可能であることを意味します。 たとえばログインフォームのチェックボックスを使用するといった方法です。
- Standalone モード
- JSP などを直接呼ぶ操作です。
In-flow モード
In-Flow の reset-approvals アプリケーションを有効にするには、Shibboleth の UsernamePassword ログインフォーム ${CATALINA_HOME}/webapps/idp/login.jsp にチェックボックスの追加で対応可能です。
警告 |
---|
in-flow の reset-approvals アプリケーションの設定は提供されている JAAS UsernamePassword ログインハンドラのためのものです。 他のログインハンドラ(例えば RemoteUser)を使用している場合は GET パラメータが IdP プラグインに送信されることを確かめてください。 |
パネル |
---|
|
Standalone モード
Standalone モードのためには、JSP はコンテナ管理による認証、もしくは REMOTE_USER
を提供する Shibboleth Service Provider のどちらかで JSP が保護されている必要があります。
standalone JSP は下記のように呼ばれます。この際パラメータ standalone-next-url
が設定される必要があります。
https://idp.example.org/uApprove/reset-approvals.jsp?standalone-next-url=http://go.here.org/after/reset
1.4.7 List-approvals 設定
警告 |
---|
reset-approvalsアプリケーションを使用する場合は設定しないでください。 以前のバージョンでreset-approvalsアプリケーションを使用するように設定している場合は、その設定を削除してから以下の設定を行ってください。 |
オプションである list-approvals はStandalone モードで使用します。 REMOTE_USER
を提供するShibboleth Service Provider で JSP が保護されている必要があります。
SPの設定
- IdPサーバにShibboleth SPをインストールしてください。IdPとメタデータ交換し、SPでのシボレス認証時にDSを経由せず直接IdPに遷移するように設定してください。
/etc/shibboleth/shibboleth2.xmlで uid を REMOTE_USERに設定します。
パネル <!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. --> <ApplicationDefaults entityID="https://idp.example.jp/shibboleth" REMOTE_USER="uid eppn persistent-id targeted-id">
/etc/shibboleth/attribute-map.xmlに IdP から uid を受取る設定を追加します。
パネル <Attribute name="urn:mace:dir:attribute-def:uid" id="uid"/> <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid"/>
IdPの設定
- /opt/shibboleth-idp/conf/attribute-resolver.xmlにuidを設定します。
- /opt/shibboleth-idp/conf/attribute-filter.xmlでuidのみを送出するように設定します。
JSPの設定
/etc/httpd/conf.d/ssl.conf で以下のように設定します。
パネル ... <LocationMatch /uApprove/list-approvals.jsp> AuthType shibboleth ShibRequestSetting requireSession 1 require valid-user </LocationMatch> ...
下記のように実行します。
https://idp.example.org/uApprove/list-approvals.jsp
1.5 実行
Tomcat を再起動してください:
パネル |
---|
/sbin/service tomcat6 stop && sleep 10 && /sbin/service tomcat6 start |
注意 |
---|
http://idp.example.org:8080/manager/html/ )がインストールされている場合、web アプリケーションは Tomcat とは独立に容易に再起動できます。 |
注意 |
---|
もし成功している場合はあなたの Identity Provider を用いて適当な Service Provider へのアクセスを試みてください。 |
1.6 トラブルシューティング
1.6.1 ログ出力
IdP プラグインは Shibboleth IdP web アプリケーション中で動作するため IdP logger を使用します。IdP logger の設定は /opt/shibboleth-idp/conf/logging.xml で行います:
パネル |
---|
... <logger name="ch.SWITCH.aai" level="DEBUG"> |
uApprove.jp viewer のログは 1.4.3 で説明したように設定します。log level を DEBUG
に変更します。
1.6.2 Tomcat, Jasper JSP compiling for 1.5 target
uApprove.jp は JDK1.5 を対象に提供されています。あなたの Tomcat がバージョン 1.5 以上の JDK で実行していたとしても Jasper エンジンは実行中の JSP を別ターゲット(例 1.3)向けにコンパイルしている可能性があります。 以下の ${CATALINA_HOME}/conf/web.xml の設定は JSP のコンパイルターゲットを指定するものです:
パネル |
---|
<servlet>
...
<init-param>
<param-name>compilerSourceVM</param-name>
<param-value>1.5</param-value>
</init-param>
<init-param>
<param-name>compilerTargetVM</param-name>
<param-value>1.5</param-value>
</init-param>
...
</servlet> |
1.7 リファレンス
2. Shibboleth Service Providerの設定
2.1 Metadata
SPは <SPSSODescriptor>
要素内の <AttributeConsumingService>
要素内の <RequestedAttribute>
要素を用いて SP が必須とする、もしくは希望する属性を定義できます。 <RequestedAttribute>
要素は下記の属性を持ちます:
- isRequired (optional)
- SPによって必須である、もしくは希望する属性を示すブーリアン値。
デフォルト値: false (希望する)。
- SPによって必須である、もしくは希望する属性を示すブーリアン値。
2.1.1 属性の説明
<RequestedAttribute>
要素に以下の属性を記述して、属性の説明文を定義できます。定義した説明文は、uApprove.jp の viewer アプリケーションによって表示されます。
- uajpmd:description (optional)
- 属性の説明文。
<uajpmd:RequestedAttributeExtension>
要素を用いると、複数の言語で説明文を定義することができます。 <uajpmd:RequestedAttributeExtension>
要素の定義は uajpmd:description
属性の定義に優先します。 <uajpmd:RequestedAttributeExtension>
要素は <SPSSODescriptor>
要素の子要素 <Extensions>
に記述します。
<uajpmd:RequestedAttributeExtension>
要素には以下の属性が必要です。
- uajpmd:FriendlyName
- 関連づけたい
<RequestedAttribute>
要素のFriendlyName
属性の値と同じ値を記述します。
- 関連づけたい
説明文は <uajpmd:Description>
要素に記述します。<uajpmd:RequestedAttributeExtension>
要素は一つ以上の <uajpmd:Description>
要素をもつことができます。
<uajpmd:Description>
要素には以下の属性が必要です。
- uajpmd:FriendlyName
- 関連づけたい
<RequestedAttribute>
要素のFriendlyName
属性の値と同じ値を記述します。
- 関連づけたい
<AttributeConsumingService>
要素の例を下記に示します:
...
3 アップデート
2.2.1bから2.2.1cへのアップデートについては、基本的には1.3 インストールおよび1.4 設定に記述しているようにあるようにShibboleth IdPおよびViewerを再デプロイしていただきますが、特に注意いただきたい手順を以下に挙げます。
3.1 テーブルの追加
2.2.1cでは以下のテーブルを追加する必要があります。
- BackChannelAccess
バックチャネルアクセスの記録用 - NamesOfApprovedService
同意済みSPのサービス名
...
3.2 mysql.commandsの更新
SQLを定義したmysql.commandsファイルを2.2.1c付属のファイルに差し換えます。
パネル |
---|
|
3.3 古いjarファイルの削除
以下のディレクトリに2.2.1bのjarファイル(common-2.2.1b.jar, idp-plugin-2.2.1b.jar)が残っている場合は、Shibboleth IdP および Viewer をデプロイする前に削除します。
- /opt/shibboleth-identityprovider-2.x/lib/
- $CATALINA_HOME/work/Catalina/localhost/idp/WEB-INF/lib/
- $CATALINA_HOME/work/Catalina/localhost/uApprove/WEB-INF/lib/
3.4 web.xmlの確認
- /opt/shibboleth-identityprovider-2.x/src/main/webapp/WEB-INF/web.xml
に追加した設定が 1.4.2 IdP プラグインの設定 の通りになっているか確認してください。
特にuApprove.jpの以前のバージョンでは以下の要素が無かったようですので、この部分に特にご注意ください。
...
language | xml |
---|
...
<uajpmd:RequestedAttributeExtension FriendlyName="mail">
<uajpmd:Description xml:lang="en">The mail attribute is used as the initial value of the mail address field of the registration form.</uajpmd:Description>
<uajpmd:Description xml:lang="ja">mail 属性を登録ページのメールアドレス欄の初期値として使用します</uajpmd:Description>
</uajpmd:RequestedAttributeExtension>
...
</md:Extensions>
...
<md:AttributeConsumingService index="1">
<md:ServiceName xml:lang="en">Sample Service</md:ServiceName>
<md:RequestedAttribute FriendlyName="eduPersonPrincipalName"
Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
isRequired="true"/>
<md:RequestedAttribute FriendlyName="mail"
Name="urn:oid:0.9.2342.19200300.100.1.3"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"/>
</md:AttributeConsumingService>
...
</md:SPSSODescriptor>
...
</md:EntityDescriptor>
...
</md:EntitiesDescriptor> |