この文書にはuApprove Jet Pack 34.20 (以下、「uApprove JP」) のインストールガイドと総合マニュアルが記されています。
uApprove JPはShibboleth Identity Provider 3を拡張するプラグインです。uApprove 4を拡張するプラグインです。uApprove Jet Pack 23.5で提供していた機能の一部をShibboleth 4で提供していた機能をShibboleth Identity Provider 3でも利用できるようにすることを目的としています。これを利用することにより、利用者はIdentity 4でも利用できるようにすることを目的としています。これを利用することにより、利用者はIdentity Providerで認証する際に、属性を選択的に送信することができます。 uApprove JPのコンセプトに関するより詳細な情報はこちらを参照してください。
本ガイドに関する注意事項:
- このガイドでは、uApprove JPはLinuxシステムにインストールされると仮定しています。Windows等の他のオペレーティングシステムにインストールすることも可能です。その場合は、いくつかのパスやコマンドを適切なものに置き換えてください。
- このガイドでは、パスやコマンドは
$IDP_HOME$
、$UAPPROVE_INSTALL$
といった変数で示されます。明示的に置き換えが不要と書かれていない限りは、これらの変数は実際のパスに置き換えてください。
...
目次
目次 | ||
---|---|---|
|
想定
- Shibboleth Identity Providerは、
$IDP_HOME$
(例:/opt/shibboleth-idp
) にインストールされているものとします。Tomcatは、$CATALINA_HOME$
(例:/usr/java/tomcat
) にインストールされているものとし、$CATALINA_BASE$
(例:$CATALINA_HOME$
)にIdPインスタンスの設定がされているものとします。 - Tomcatではなく、Jettyがインストールされているものとします。
- uApprove JP は、
$UAPPROVE_INSTALL$
(例:/usr/local/src/uApproveJP-#version#
) にダウンロード、展開されているものとします。
前提条件
Shibboleth Identity Provider
34.
20.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 |
1.3 CSS ファイル
CSSファイルをIdPのedit-webapp
ディレクトリにコピーします:
/
以下のメッセージが表示される場合がありますが、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/idpservices.properties
に、以下の変更を行います。idp.consent.allowPerAttribute
とidp.consent.compareValues
の値をtrue
に設定してください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
定義を追加します:
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
$IDP_HOME$/conf/global.xml
に、以下の属性選択画面で使用するbean
定義を追加します:
ヒント |
---|
挿入する場所に制限はありませんが、よく分からなければ末尾の行に |
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
<bean class="jp.gakunin.idp.consent.logic.
|
...
警告 |
---|
Shibboleth IdP 4.1以降では、以下の2つのファイルの変更( |
...
および
|
$IDP_HOME$/system/conf/services-system.xml
に、以下の変更を行います。id="shibboleth.AttributeFilterService"
のbean
定義の<constructor-arg name="strategy">
を以下のように変更してください:
注意 |
---|
この変更は、Shibboleth Identity Providerを再インストール(アップグレード等)する際に上書きされるため、再インストールを行った際には、再度変更を行う必要があります。 |
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
注意 |
---|
この変更は、Shibboleth Identity Providerを再インストール(アップグレード等)する際に上書きされるため、再インストールを行った際には、再度変更を行う必要があります。 |
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
$IDP_HOME$/system/flows/intercept/attribute-release-beans.xml
に、以下の変更を行います。id="IsConsentRequiredPredicate"
のbean
定義のclass
を変更してください:
注意 |
---|
この変更は、Shibboleth Identity Providerを再インストール(アップグレード等)する際に上書きされるため、再インストールを行った際には、再度変更を行う必要があります。 |
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
1.
...
6 カスタムテンプレート
テンプレートをカスタマイズしたい場合は、 テンプレートのカスタマイズ を参照してください。
少なくとも、所属機関のロゴを変更する必要があります。デフォルトではこのファイルはプレースホルダのロゴになっています。
ロゴをデフォルトのOur Identity Providerから機関のロゴに変更するには、以下の手順を行ってください。
...
少なくとも、所属機関のロゴを変更する必要があります。変更方法は以下のリンク先を参照してください。
GakuNinShare:Shibboleth IdP 3 - ロゴの変更
1.7 ログの設定
uApprove JPのログを出力するには、$IDP_HOME$/
...
conf/logback.xml
に以下を追加します:
...
パネル | |||||
---|---|---|---|---|---|
|
|
...
| |
|
...
$IDP_HOME$/messages/error-messages.properties
のidp.logo
を上記1.で配置したファイル名に変更します。なお、ファイル名は/images/
から始めます。また、idp.logo.alt-text
を変更します:
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
...
$IDP_HOME$/bin/build.sh
を実行して、$IDP_HOME$/war/idp.war
を作り直します:
書式設定済み |
---|
$ cd $IDP_HOME$
$ sudo -u tomcat env JAVA_HOME="${JAVA_HOME}" bin/build.sh
Installation Directory: [/opt/shibboleth-idp]
Rebuilding /opt/shibboleth-idp/war/idp.war ...
...done
BUILD SUCCESSFUL
Total time: 16 seconds |
1.6 ログの設定
uApprove JPのログを出力するには、$IDP_HOME$/conf/logback.xml
に以下を追加します:
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
1.
...
8 デプロイ
IdP で uApprove JP を有効にするには IdP を再デプロイする必要があります:
書式設定済みpanel |
---|
# cd $IDP_HOME$
# ./bin/build.sh
Installation Directory: [/opt/shibboleth-idp]
Rebuilding [Enter] ←入力なし Rebuilding /opt/shibboleth-idp/war/idp.war ...
...done
BUILD SUCCESSFUL
Total time: 16 seconds |
idp.war
を$CATALINA_BASE$/webapps
にコピーします:
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/ |
Tomcatを再起動しますJettyを再起動します:
書式設定済み |
---|
# servicesystemctl tomcat7restart restartjetty |
2 高度なデプロイ
この節では高度な設定についてのトピックを取り上げます。
2.1 リレーショナルデータベースを用いたユーザ同意情報の保存
リレーショナルデータベース(以下、「RDB」とします以下、「RDB」とします)を用いて、ユーザ同意情報の保存を行うことができます。
2.1.1. MySQLの設定
注意 |
---|
以下のデータベースパラメータは一例です。実際の値は必要に応じて変更してください。特にパスワードは安全なものを用意してください。 |
MySQLの設定を行います。
データベース
shibboleth
の作成
Shibboleth IdPで使用するデータベースshibboleth
を作成します:
データベース情報 rootにパスワードが設定してあってコマンドが以下のエラーで失敗する場合は、
-p
オプションを追加してください。書式設定済み ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: NO)
shibboleth
の作成
Shibboleth IdPで使用するデータベースshibboleth
を作成します:パネル borderColor silver bgColor white db$ mysql -u root
mysql>
CREATE DATABASE shibboleth;
ユーザ作成
IdPからデータベース 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が使用するテーブル eが使用するテーブルStorageRecords
を作成します:パネル borderColor silver bgColor white db$ mysql -u root
mysql>
use shibboleth;
CREATE TABLE `StorageRecords` (
`context` varchar(255) NOT NULL,
`id` `id` varchar(255) NOT NULL,
`expires` `expires` bigint(20) DEFAULT NULL,
`value` `value` longtext NOT NULL,
`version` `version` bigint(20) NOT NULL,
PRIMARY 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
配下にインストールされているので、Tomcat 配下の配下にインストールされているので、edit-webapp/
配下のlib
ディレクトリにシンボリックリンクを作成します:書式設定済みpanel #
rpm
-ql
mysql-connector-java
...(省略)
/usr/share/java/mysql-connector-java.jar
... # ln(省略)
# ln -s
/usr/share/java/mysql-connector-java.jar
$CATALINA_BASE$$IDP_HOME$/
edit-webapp/WEB-INF
/lib/- 1.8 デプロイの手順に従って再デプロイします。
2.1.4.
...
idp.consent.
...
StorageServiceの設定変更
idp.consent.StorageService
の設定をshibboleth.JPAStorageService
に変更します:
情報 |
---|
5行目の変更は3.1まで向けのものです。3.2以降では不要です(デフォルトでサーバサイドでは無制限に記憶されます)。 |
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
# Set to "shibboleth.StorageService" or custom bean for alternate storage of consent idp.consent.StorageService = shibboleth.JPAStorageService # Maximum number of consent storage records # Set to -1 for unlimited server-side storage or custom bean for alternate storage of consent
|
2.1.5. shibboleth.JPAStorageServiceの設定
2.1.4. idp.consent.StorageServiceの設定変更でidp.sesssionconsent.StorageService
に設定したshibboleth.JPAStorageService
を定義します。
id="Shibboleth.MySQLDataSource"
のbean
定義のp:url, p:username, p:password
は、2.1.1. MySQLの設定に合わせて設定します:
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
2.1.6. Tomcatの再起動
Tomcatを再起動します:
書式設定済み |
---|
# service tomcat7 restart |
2.2 テンプレート
テンプレートのカスタマイズ
$IDP_HOME$/views/
にある Velocityテンプレートファイル 、 $IDP_HOME$/edit-webapp/
にあるCSS や画像ファイルは自由にカスタマイズすることができます。 Velocity を用いているので容易にカスタマイズ出来るようになっています。
Velocity については Velocity User Guide を参照してください。
2.3 ローカライズ
カスタムメッセージ
$IDP_HOME$/messages/
に用意されているリソースバンドルは環境に合わせたり、修正することができます。
$IDP_HOME$/messages/
以下のファイルを追加、または修正した場合はTomcatの再起動が必要です。
$UAPPROVE_INSTALL$/manual/examples/messages/
に、日本語環境用のテンプレートファイルが用意されています。
|
2.1.6. Jettyの再起動
Jettyを再起動します$IDP_HOME$/messages/
にファイルをコピーすることで日本語メッセージを表示するようになります:
書式設定済み |
---|
# cp $UAPPROVE_INSTALL$/manual/examples/messages/* 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の一部を除いてこの情報が含まれています。 |
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"/> |
オプションとマークされた属性をチェックボックスつきで表示します。チェックボックスをチェックしたときだけ送信します。
...
パネル | ||||
---|---|---|---|---|
| ||||
<!-- ================================================================================== case 1: mail 属性、eduPersonPrincipalName属性、eduPersonAffiliation属性を、メタデータの 定義と照合するルールです。 メタデータでisRequired="true"が指定されている属性は、すべて必須情報になり常に 送信されます。 メタデータでisRequired="false"が指定されている属性は以下の通りです。 * mail属性は必須情報となり常に送信されます。 * eduPersonPrincipalName属性はオプション情報となります。属性選択画面ではチェック ボックスつきで表示されます。利用者がチェックボックスをチェックした場合に限り送信 されます。 * eduPersonAffiliation属性は送信されません。 メタデータにAttributeConsumingServiceをもたないSPの場合はどの属性も送信しません。 ================================================================================== --> <afp:AttributeFilterPolicy<AttributeFilterPolicy id="PolicyforSPwithAttributeConsumingService"> <afp:PolicyRequirementRule<PolicyRequirementRule xsi:type="basic:ANY" /> <afp:AttributeRule<AttributeRule attributeID="mail"> <afp:PermitValueRule<PermitValueRule xsi:type="uajpmf:AttributeInMetadata" onlyIfRequired="false" /> </afp:AttributeRule> <afp:AttributeRule<AttributeRule attributeID="eduPersonPrincipalName"> <afp:PermitValueRule<PermitValueRule xsi:type="uajpmf:AttributeInMetadata" onlyIfRequired="false" onlyIfChecked="true" /> </afp:AttributeRule> <afp:AttributeRule<AttributeRule attributeID="eduPersonAffiliation"> <afp:PermitValueRule<PermitValueRule xsi:type="uajpmf:AttributeInMetadata" /> </afp:AttributeRule> </afp:AttributeFilterPolicy> <!-- ================================================================================== case 2: メタデータに AttributeConsumingServiceがないSPに対するルールを追加したルール です。 AttributeConsumingService要素を持たないSPの場合は以下の通りです。 * mail属性は必須情報となり常に送信されます。 * eduPersonPrincipalName属性はオプション情報となります。属性選択画面ではチェック ボックスつきで表示されます。利用者がチェックボックスをチェックした場合に限り送信 されます。 * eduPersonAffiliation属性は送信されません。 AttributeConsumingService要素を持つSPの場合はcase 1と同じです。 ================================================================================== --> <afp:AttributeFilterPolicy<AttributeFilterPolicy id="PolicyforSPwithoutAttributeConsumingService"> <afp:PolicyRequirementRule<PolicyRequirementRule xsi:type="basic:ANY" /> <afp:AttributeRule<AttributeRule attributeID="mail"> <afp:PermitValueRule<PermitValueRule xsi:type="uajpmf:AttributeInMetadata" matchIfMetadataSilent="true" onlyIfRequired="false" /> </afp:AttributeRule> <afp:AttributeRule<AttributeRule attributeID="eduPersonPrincipalName"> <afp:PermitValueRule<PermitValueRule xsi:type="uajpmf:AttributeInMetadata" matchIfMetadataSilent="true" onlyIfRequired="false" onlyIfChecked="true" /> </afp:AttributeRule> <afp:AttributeRule<AttributeRule attributeID="eduPersonAffiliation"> <afp:PermitValueRule<PermitValueRule xsi:type="uajpmf:AttributeInMetadata" /> </afp:AttributeRule> </afp: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" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" 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" 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" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> ... <md:EntityDescriptor entityID="..."> <md:SPSSODescriptor> ... <md:Extensions> ... <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> |
...