この文書にはuApprove Jet Pack 3.2(以下、「uApprove JP」) のインストールガイドと総合マニュアルが記されています。
uApprove JPはShibboleth Identity Provider 3を拡張するプラグインです。uApprove Jet Pack 2.5で提供していた機能の一部をShibboleth Identity Provider 3でも利用できるようにすることを目的としています。これを利用することにより、利用者はIdentity Providerで認証する際に、属性を選択的に送信することができます。 uApprove JPのコンセプトに関するより詳細な情報はこちらを参照してください。
本ガイドに関する注意事項:
$IDP_HOME$
、$UAPPROVE_INSTALL$
といった変数で示されます。明示的に置き換えが不要と書かれていない限りは、これらの変数は実際のパスに置き換えてください。$IDP_HOME$
(例: /opt/shibboleth-idp
) にインストールされているものとします。$CATALINA_HOME$
(例: /usr/java/tomcat
) にインストールされているものとし、$CATALINA_BASE$
(例: $CATALINA_HOME$
)にIdPインスタンスの設定がされているものとします。$UAPPROVE_INSTALL$
(例: /usr/local/src/uApproveJP-#version#
) にダウンロード、展開されているものとします。ライブラリをIdPのライブラリディレクトリにコピーします:
# cp $UAPPROVE_INSTALL$/lib/*.jar $IDP_HOME$/edit-webapp/WEB-INF/lib/ |
|
属性選択画面用のVelocityテンプレートファイルをIdPのviews
ディレクトリに上書きコピーします:
# cp $UAPPROVE_INSTALL$/manual/examples/views/intercept/* $IDP_HOME$/views/intercept/ 以下のメッセージが表示される場合がありますが、y を入力してください。 cp: `/opt/shibboleth-idp/views/intercept/attribute-release.vm' を上書きしますか? |
CSSファイルをIdPのedit-webapp
ディレクトリにコピーします:
# cp $UAPPROVE_INSTALL$/manual/examples/edit-webapp/css/* $IDP_HOME$/edit-webapp/css/ |
$IDP_HOME$/conf/idp.properties
に、以下の変更を行います。idp.consent.allowPerAttribute
とidp.consent.compareValues
の値をtrue
に設定してください:
|
$IDP_HOME$/conf/global.xml
に、以下の属性選択画面で使用するbean
定義を追加します:
挿入する場所に制限はありませんが、よく分からなければ末尾の行に |
...
|
$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を再インストール(アップグレード等)する際に上書きされるため、再インストールを行った際には、再度変更を行う必要があります。 |
class="jp.gakunin.idp.consent.logic.impl.IsConsentRequiredPredicate" />
|
テンプレートをカスタマイズしたい場合は、 テンプレートのカスタマイズ を参照してください。
少なくとも、所属機関のロゴを変更する必要があります。デフォルトではこのファイルはプレースホルダのロゴになっています。
ロゴをデフォルトのOur Identity Providerから機関のロゴに変更するには、以下の手順を行ってください。
ロゴファイル organization-logo.png
を$IDP_HOME$/edit-webapp/images/
以下に配置します:
$ ls $IDP_HOME$/edit-webapp/images/ dummylogo-mobile.png dummylogo.png organization-logo.png |
$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 |
uApprove JPのログを出力するには、$IDP_HOME$/conf/logback.xml
に以下を追加します:
|
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/ |
Tomcatを再起動します:
CentOS 7の場合は以下のコマンドで再起動してください。
|
# service tomcat7 restart |
この節では高度な設定についてのトピックを取り上げます。
リレーショナルデータベース(以下、「RDB」とします)を用いて、ユーザ同意情報の保存を行うことができます。
以下のデータベースパラメータは一例です。実際の値は必要に応じて変更してください。特にパスワードは安全なものを用意してください。 |
MySQLの設定を行います。
データベース shibboleth
の作成
Shibboleth IdPで使用するデータベース shibboleth
を作成します:
rootにパスワードが設定してあってコマンドが以下のエラーで失敗する場合は、
|
|
ユーザ作成
IdPからデータベース shibboleth
にアクセスするためのユーザ shibboleth
を作成し、データベース shibboleth
への権限を付与します:
|
StorageRecords
テーブル作成
JPAStorageServic
eが使用するテーブル StorageRecords
を作成します:
|
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$/ |
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 idp.consent.maxStoredRecords = -1 |
2.1.4. idp.consent.StorageServiceの設定変更でidp.sesssion.StorageService
に設定したshibboleth.JPAStorageService
を定義します。
id="Shibboleth.MySQLDataSource"
のbean
定義のp:url, p:username, p:password
は、2.1.1. MySQLの設定に合わせて設定します:
|
2.1.6. Tomcatの再起動
Tomcatを再起動します:
CentOS 7の場合は以下のコマンドで再起動してください。
|
# service tomcat7 restart |
$IDP_HOME$/views/
にある Velocityテンプレートファイル 、 $IDP_HOME$/edit-webapp/
にあるCSS や画像ファイルは自由にカスタマイズすることができます。 Velocity を用いているので容易にカスタマイズ出来るようになっています。
Velocity については Velocity User Guide を参照してください。
以下の記述はShibboleth IdP 3.2.1およびそれ未満向けです。3.3.0およびそれ以降では次のリンク先を参照してください。 |
$IDP_HOME$/messages/
に用意されているリソースバンドルは環境に合わせたり、修正することができます。
$IDP_HOME$/messages/
以下のファイルを追加、または修正した場合はTomcatの再起動が必要です。
$UAPPROVE_INSTALL$/manual/examples/messages/
に、日本語環境用のテンプレートファイルが用意されています。
$IDP_HOME$/messages/
にファイルをコピーすることで日本語メッセージを表示するようになります:
# cp $UAPPROVE_INSTALL$/manual/examples/messages/* $IDP_HOME$/messages/ # service tomcat7 restart |
現状では、ローカライズされた Relying Party の名前と説明を取得する際には、メタデータのうち<AttributeConsumingService>
要素および<mdui:UIInfo>
要素がサポートされています。
この名前と説明を使用する場合は、SPのメタデータを以下のように記述します:
|
両方記載されている場合には 学認のSPについても海外SPの一部を除いてこの情報が含まれています。 |
このルールは、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の場合はどの属性も送信しません。 ================================================================================== --> <afp:AttributeFilterPolicy id="PolicyforSPwithAttributeConsumingService"> <afp:PolicyRequirementRule xsi:type="basic:ANY" /> <afp:AttributeRule attributeID="mail"> <afp:PermitValueRule xsi:type="uajpmf:AttributeInMetadata" onlyIfRequired="false" /> </afp:AttributeRule> <afp:AttributeRule attributeID="eduPersonPrincipalName"> <afp:PermitValueRule xsi:type="uajpmf:AttributeInMetadata" onlyIfRequired="false" onlyIfChecked="true" /> </afp:AttributeRule> <afp:AttributeRule attributeID="eduPersonAffiliation"> <afp:PermitValueRule xsi:type="uajpmf:AttributeInMetadata" /> </afp:AttributeRule> </afp:AttributeFilterPolicy> <!-- ================================================================================== case 2: メタデータに AttributeConsumingServiceがないSPに対するルールを追加したルール です。 AttributeConsumingService要素を持たないSPの場合は以下の通りです。 * mail属性は必須情報となり常に送信されます。 * eduPersonPrincipalName属性はオプション情報となります。属性選択画面ではチェック ボックスつきで表示されます。利用者がチェックボックスをチェックした場合に限り送信 されます。 * eduPersonAffiliation属性は送信されません。 AttributeConsumingService要素を持つSPの場合はcase 1と同じです。 ================================================================================== --> <afp:AttributeFilterPolicy id="PolicyforSPwithoutAttributeConsumingService"> <afp:PolicyRequirementRule xsi:type="basic:ANY" /> <afp:AttributeRule attributeID="mail"> <afp:PermitValueRule xsi:type="uajpmf:AttributeInMetadata" matchIfMetadataSilent="true" onlyIfRequired="false" /> </afp:AttributeRule> <afp:AttributeRule attributeID="eduPersonPrincipalName"> <afp:PermitValueRule xsi:type="uajpmf:AttributeInMetadata" matchIfMetadataSilent="true" onlyIfRequired="false" onlyIfChecked="true" /> </afp:AttributeRule> <afp:AttributeRule attributeID="eduPersonAffiliation"> <afp:PermitValueRule xsi:type="uajpmf:AttributeInMetadata" /> </afp:AttributeRule> </afp:AttributeFilterPolicy> |
ERROR
ないしWARN
メッセージについては、$IDP_HOME$/logs/idp-process.log
をチェックしてください。
$CATALINA_BASE$/logs
にあるTomcatのログファイルにエラーメッセージがないかチェックしてください。
DEBUG
ないしTRACE
ログレベルを有効にしたい場合は、$IDP_HOME$/conf/idp.properties
にて以下を追加します:
idp.loglevel.uApproveJP = DEBUG |
SP管理者はSPのメタデータに属性の使用用途を記述することで、SPの利用者に属性の使用用途 (例えば、プロファイルの初期値として使用) をuApprove JPで表示することができます。
属性使用用途通知機能は、<RequestedAttribute>
にuajpmd:description
属性を追加する、または、<SPSSODescriptor>
の<Extensions>
に<uajpmd:RequestedAttributeExtension>
を追加することで利用できます。
<uajpmd:RequestedAttributeExtension>
は多言語に対応しています。また、一つの属性に両方が設定されている場合は、<uajpmd:RequestedAttributeExtension>
が優先されます。
この属性は<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:
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> |