目次

1. Shibboleth Identity Provider のための uApprove.jp のインストールおよび設定方法

1.1 はじめに

uApprove.jp (uApproveを機能拡張しました)は、 エンドユーザに利用するサービスに送信する属性の表示の選択を提供するアプリケーションです。

本ガイドでは Shibboleth Identity Provider (IdP)のための uApprove.jp のインストールおよび設定方法を説明します。
IdP プラグインおよび uApprove.jp viewer のインストール方法と、 ストレージとしてファイルもしくは SQL データベースを用いた設定方法を示します。

このガイドでは例として以下の設定値を使用します。

...

• Identity Provider の DNS 名

...

• uApprove.jp をインストールするディレクトリ

...

• uApprove.jp の設定ファイルのディレクトリ

...

• Shibboleth IdP のインストール時にZIPファイルを展開したディレクトリ (install.sh が存在するディレクトリ)

この文書にはuApprove Jet Pack (以下、「uApprove JP」) のインストールガイドと総合マニュアルが記されています。

uApprove JPはShibboleth Identity Provider 2.xを拡張するプラグインです。オリジナルのuApproveに独自の改修を施しています。これを利用することにより、利用者はIdentity Providerで認証する際に利用条件(ToU)を承諾するとともに、属性を選択的に送信することができます。 uApprove JPのコンセプトに関するより詳細な情報はこちらを参照してください。

本ガイドに関する注意事項:

• このガイドでは、uApprove JPはLinuxシステムにインストールされると仮定しています。Windows等の他のオペレーティングシステムにインストールすることも可能です。その場合は、いくつかのパスやコマンドを適切なものに置き換えてください。
• このガイドでは、パスやコマンドは $IDP_INSTALL$、 $IDP_HOME$、 $UAPPROVE_INSTALL$といった変数で示されます。明示的に置き換えが不要と書かれていない限りは、これらの変数は実際のパスに置き換えてください。

...

目次

想定

• Shibboleth Identity Provider は、 $IDP_INSTALL$ (例: /usr/local/src/shibboleth-identity-provider-#version#) に展開されているものとします。
• Shibboleth Identity Provider は、 $IDP_HOME$ (例: /opt/shibboleth-idp
  • Shibboleth IdP のインストール先
  ${CATALINA_HOME}Tomcat のインストール先 (例えば、) にインストールされているものとします。
• Tomcatは、 $CATALINA_HOME$ (例: /usr/java/tomcat) にインストールされているものとします。
• uApprove JP は、 $UAPPROVE_INSTALL$ (例: /usr/local/src/uApproveJP-#version#) にダウンロード、展開されているものとします。

1 インストール

1.

...

1 前提条件

uApprove.jp のインストールと設定の前に、以下の前提条件が揃っていることを確認してください。

共通設定

使用条件のテキストをユーザに表示するためのオプション TermsOfUseManager があります。 TermsOfUseManager を有効にしたい場合は、/opt/uApprove/conf/common.properties で定義します:

termsOfUse=/opt/uApprove/conf/terms-of-use.xml

1.4.2 IdP プラグインの設定

Shibboleth IdP の調整

IdP プラグインは Shibboleth IdP web アプリケーション /opt/shibboleth-identityprovider-2.x/src/main/webapp/WEB-INF/web.xml で有効にする必要があります:

...

• Shibboleth Identity Provider 2.34.
  • 正しく配備した Shibboleth Identity Provider が必要です。
    Java と Tomcat が動作することも含みます。
• SQL Database
  • ストレージとして SQL データベースを使用する場合は SQL サーバが必要です。
    uApprove.jp は既に MySQL 用の設定が行われていますが、他の 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 共通: ストレージ等

ファイルベース

ファイルベースストレージの設定は /opt/uApprove/conf/common.properties で行います:

...

データベース

最初にデータベースとユーザを作成します:

次に、テーブルを作成します:

...

簡単にデータベースの設定が正しいかを確認するためには、下記コマンドを利用できます:

データベースを利用する設定は /opt/uApprove/conf/common.properties で行います:

...

データベース固有の設定すべては /opt/uApprove/conf/database.properties で行います:

...

• 0 以降がインストールされている必要があります。
• MySQL 5.1 以降がインストールされている必要があります。

1.2 ライブラリのインストール

ライブラリを IdP のライブラリディレクトリにコピーします:

# cp $UAPPROVE_INSTALL$/lib/*.jar $IDP_INSTALL$/lib
# cp $UAPPROVE_INSTALL$/lib/jdbc/*.jar $IDP_INSTALL$/lib

JDBC コネクタを IdP の classpath に配置します。提供されているMySQLまたはHSQLのJDBCコネクタのいずれかを使えます:

# cp $UAPPROVE_INSTALL$/lib/jdbc/optional/#jdbc-connector#.jar $IDP_INSTALL$/lib

1.3 設定テンプレート

設定テンプレートを IdP の設定ディレクトリにコピーします:

# cp $UAPPROVE_INSTALL$/manual/configuration/uApprove.properties $IDP_HOME$/conf
# cp $UAPPROVE_INSTALL$/manual/configuration/uApprove.xml $IDP_HOME$/conf

1.4 Webapp ファイル

JSP や CSS といった web アプリケーションファイルおよび画像ファイルを IdP の webapp ディレクトリにコピーします:

# mkdir $IDP_INSTALL$/src/main/webapp/uApprove
# cp $UAPPROVE_INSTALL$/webapp/* $IDP_INSTALL$/src/main/webapp/uApprove

1.5 データベースの準備

• “uApprove” という名前のデータベースを作成します。
• ユーザ名 “uApprove” およびパスワード “secret” でデータベースのユーザを作成します。
• INSERT, SELECT, UPDATE, DELETE の各権限を作成したユーザに付与します。
• 以下のスキーマを用いて初期テーブル構造を作成します:
  
  • $UAPPROVE_INSTALL$/manual/storage/terms-of-use-schema.sql
  • $UAPPROVE_INSTALL$/manual/storage/attribute-release-schema.sql
  • $UAPPROVE_INSTALL$/manual/storage/service-access-data-schema.sql

2 基本的なデプロイ

2.1 Web アプリケーションデプロイメントデスクリプタ

IdP の Web アプリケーションデプロイメントデスクリプタ  ($IDP_INSTALL$/src/main/webapp/WEB-INF/web.xml)  を修正します。以下に示すように、実際のファイルを反映してください。

• contextConfigLocation コンテキストパラメータに $IDP_HOME$/conf/uApprove.xml を追加します。 $IDP_HOME$ の部分は変更せずにこのまま記述してください。後で行いますIdPの再デプロイの際に自動的に置き換えられます。
• 以下に示す必要となるフィルタおよびサーブレットを追加します。

<web-app ...>

    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>$IDP_HOME$/conf/internal.xml; $IDP_HOME$/conf/service.xml; $IDP_HOME$/conf/uApprove.xml;</param-value>
    </context-param>

    <!-- IdP Listeners, Filters and Servlets -->
    <!-- ...                                 -->
    
    <!-- uApprove Filter and Servlets -->

    <filter>
        <filter-name>uApprove</filter-name>
        <filter-class>ch.SWITCH.aai.uApprove.Intercepter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>uApprove</filter-name>
        <url-pattern>/profile/Shibboleth/SSO</url-pattern>
        <url-pattern>/profile/SAML1/SOAP/AttributeQuery</url-pattern>
        <url-pattern>/profile/SAML1/SOAP/ArtifactResolution</url-pattern>
        <url-pattern>/profile/SAML2/POST/SSO</url-pattern>
        <url-pattern>/profile/SAML2/POST-SimpleSign/SSO</url-pattern>
        <url-pattern>/profile/SAML2/Redirect/SSO</url-pattern>
        <url-pattern>/profile/SAML2/Unsolicited/SSO</url-pattern>
        <url-pattern>/Authn/UserPassword</url-pattern>
    </filter-mapping>

    <servlet>
        <servlet-name>uApprove - Terms Of Use</servlet-name>
        <servlet-class>ch.SWITCH.aai.uApprove.

tou.

ToUServlet</

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/.*

属性の順序とブラックリストの作成

attributeList=/opt/uApprove/conf/attribute-list

# 属性の順序を定義
surname
givenName
postalAddress
...

# 隠す属性
!persistentId
!transientId

その他の設定

データベースを使用する場合は各プロバイダのアクセスに対して記録を残すことが可能で、 これはすべての属性の送信がデータベースに保存されていることを意味します。
IdP プラグイン は monitoring only mode で実行することも可能で、 これはすべてのプロバイダのアクセスを記録しますが、ユーザの同意のためのやりとりは行いません。
viewer web アプリケーションを使用する場合、 IdP プラグインは viewer web アプリケーションのデプロイ先を知っている必要があります。
IdP プラグインに、isPassiveリクエストに関して考慮の必要があることを伝えることができます。
設定は /opt/uApprove/conf/idp-plugin.properties で行います:

1.4.3 Viewer 設定

uApprove.jp webapp のための tomcat のデプロイの記述を ${CATALINA_HOME}/conf/Catalina/localhost/uApprove.xml で定義します:

servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>uApprove - Terms Of Use</servlet-name>
        <url-pattern>/uApprove/TermsOfUse</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>uApprove - Attribute Release</servlet-name>
        <servlet-class>ch.SWITCH.aai.uApprove.ar.AttributeReleaseServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>uApprove - Attribute Release</servlet-name>
        <url-pattern>/uApprove/AttributeRelease</url-pattern>
    </servlet-mapping>

</web-app>

2.2 設定のカスタマイズ

$IDP_HOME$/conf/internal.xml にて以下の変更を行います。 id="shibboleth.OpensamlConfig" の Bean 定義の <constructor-arg> に、 id="uajpMetadataExtensions" の Bean 定義を追加してください:

<bean id="shibboleth.OpensamlConfig" class="edu.internet2.middleware.shibboleth.common.config.OpensamlConfigBean"
         depends-on="shibboleth.LogbackLogging">
    ...
    <constructor-arg>
        <list>
            <bean id="shibMetadataExtensions" class="org.opensaml.util.resource.ClasspathResource">
                <constructor-arg value="/shibboleth-saml-ext-config.xml"/>
            </bean>
            <bean id="uajpMetadataExtensions" class="org.opensaml.util.resource.ClasspathResource">
                <constructor-arg value="/uApprove-jp-metadata-config.xml"/>
            </bean>
        </list>
    </constructor-arg>
    <property name="parserPool" ref="shibboleth.ParserPool"/>
    ...

$IDP_HOME$/conf/uApprove.xml にて以下の変更を行います:

変更前:

<context:property-placeholder location="classpath:/configuration/uApprove.properties" />

変更後:

<context:property-placeholder location="file:$IDP_HOME$/conf/uApprove.properties" />

$IDP_HOME$ は実際のパス (例: /opt/shibboleth-idp) にしてください(その結果、値全体は file:/opt/shibboleth-idp/conf/uApprove.properties のようになります)。

正しいIdPのメタデータを$IDP_HOME$/metadata/idp-metadata.xmlに配置してください。そのうえで$IDP_HOME$/metadata/idp-metadata.xmlを読み込むように$IDP_HOME$/conf/relying-party.xmlを編集します:

    <!-- ========================================== -->
    <!--      Metadata Configuration                -->
    <!-- ========================================== -->
    <!-- MetadataProvider the combining other MetadataProviders -->
    <metadata:MetadataProvider id="ShibbolethMetadata" xsi:type="metadata:ChainingMetadataProvider">
    
        <!-- Load the IdP's own metadata.  This is necessary for artifact support. -->
        <metadata:MetadataProvider id="IdPMD" xsi:type="metadata:FilesystemMetadataProvider"
                                   metadataFile="$IDP_HOME$/metadata/idp-metadata.xml"
                                   maxRefreshDelay="P1D" />

データベースおよび必要な機能に応じて $IDP_HOME$/conf/uApprove.properties をカスタマイズします。設定オプションについては uApprove.properties のインライン文書を参照してください。

"Terms of Use" モジュールを有効にする場合(デフォルトで有効になっています)、所属組織に適した文書を設定する必要があります。

"Terms of Use" の HTML ファイルは、 $UAPPROVE_INSTALL$/manual/examples/terms-of-use.html に例があります。

• $UAPPROVE_INSTALL$/manual/examples/terms-of-use.html を $IDP_HOME$/conf/terms-of-use.html にコピーします:

  No Format
  # cp $UAPPROVE_INSTALL$/manual/examples/terms-of-use.html $IDP_HOME$/conf/terms-of-use.html

• $IDP_HOME$/conf/terms-of-use.html を適切に修正します。

• それに従って、 $IDP_HOME$/conf/uApprove.properties の中の tou.resource を適切に修正します:

  No Format
  tou.resource = file:$IDP_HOME$/conf/terms-of-use.html

2.3 カスタムテンプレート

テンプレートをカスタマイズしたい場合は、 テンプレートのカスタマイズ を参照してください。

少なくとも、所属機関のロゴを $IDP_INSTALL$/src/main/webapp/uApprove/logo.png にコピーする必要があります。デフォルトではこのファイルはプレースホルダのロゴになっています。
さらに、フェデレーションのロゴを $IDP_INSTALL$/src/main/webapp/uApprove/federation-logo.png にコピーすることもできます(デフォルトでは空のプレースホルダのロゴになっています)。

2.4 デプロイ

IdP で uApprove JP を有効にするには IdP を再デプロイする必要があります:

# cd $IDP_INSTALL$
# ./install.sh

idp.war を $CATALINA_HOME$/webapps にコピーします:

# cp $IDP_HOME$/war/idp.war $CATALINA_HOME$/webapps/

Tomcat を再起動します:

# service tomcat6 restart

3 アップグレード

3.1 uApprove.jp 2.2.1 からのアップグレード

本節では、すでに uApprove.jp 2.2.1 / 2.2.1a / 2.2.1b / 2.2.1c をインストール・運用しているIdPにおいて、uApprove JP 2.5.0 にアップグレードする手順を示します。

• デプロイされている uApprove.jp-2.2.1 を削除します。

• 設定ファイルは新しい設定ファイルを使用し、カスタマイズします。

  Tip
  新しいToUはカスタマイズ可能なHTMLファイルであり、uApprove.jp 2.2.1 の ToU XML からプレーンな HTML ファイルにコピーするだけで使用できます。

• uajpmf:AttributeUapprove マッチングルールは使用できません。
  uajpmf:AttributeInMetadata を使用したルールに書き換えてください。4.7 AttributeInMetadataマッチングルールを参照してください。

  Expand
  title 書き換えのヒント...
  Tip メタデータに <RequstedAttribute> として宣言されている属性は isRequired 属性に従い、 true の場合は必須、 false の場合はオプショナルに、<RequstedAttribute> として宣言されてない属性およびそもそもメタデータに <AttributeConsumingService> がない場合は非表示とするルールは下記の通り書き換えできます。 uApprove.jp 2.2.1   uApprove JP 2.5.0 <PermitValueRule xsi:type="uajpmf:AttributeUapprove"                 isApproved="true" requestedOnly="true" /> ⇒ <PermitValueRule xsi:type="uajpmf:AttributeInMetadata" onlyIfChecked="true"                  onlyIfRequired="false" matchIfMetadataSilent="false" /> メタデータに <RequstedAttribute> として宣言されている属性は isRequired 属性に従い、 true の場合は必須、 false の場合はオプショナルに、メタデータに <AttributeConsumingService> がない場合もオプショナルとするルールは下記の通り書き換えできます。ただし、メタデータに <AttributeConsumingService> があるがその中で <RequstedAttribute> として宣言されていない属性は、 uajpmf:AttributeUapprove ではオプショナルとなりますが uajpmf:AttributeInMetadata では非表示となります。 uApprove.jp 2.2.1   uApprove JP 2.5.0 <PermitValueRule xsi:type="uajpmf:AttributeUapprove"                  isApproved="true" requestedOnly="false" /> ⇒ <PermitValueRule xsi:type="uajpmf:AttributeInMetadata" onlyIfChecked="true"                  onlyIfRequired="false" matchIfMetadataSilent="true" /> メタデータに <AttributeConsumingService> が含まれる場合に適用するポリシーは一対一の書き換えができないため、 <PolicyRequirementRule> は <basic:ANY> として、各ルールでは <AttributeConsumingService> が含まれない場合の挙動も考慮し matchIfMetadataSilent に反映させてください。 uApprove.jp 2.2.1   uApprove JP 2.5.0 <PolicyRequirementRule xsi:type="uajpmf:AttributeUapprove" /> ⇒ <PolicyRequirementRule xsi:type="basic:ANY" /> <PermitValueRule xsi:type="uajpmf:AttributeUapprove"                  isApproved="true" requestedOnly="false" /> かつ他のルールで <AttributeConsumingService> が含まれない場合に非表示としている場合 ⇒ <PermitValueRule xsi:type="uajpmf:AttributeInMetadata" onlyIfChecked="true"                  onlyIfRequired="false" matchIfMetadataSilent="false" /> ※ただし2.の場合と同じく、<AttributeConsumingService>が存在しかつ同要素中に<RequstedAttribute>として宣言されていない属性に対する挙動が変化する（オプショナル→非表示）ことにご注意ください。 <PermitValueRule xsi:type="uajpmf:AttributeUapprove"                 isApproved="true" requestedOnly="true" /> かつ他のルールで <AttributeConsumingService> が含まれない場合に非表示としている場合 ⇒ <PermitValueRule xsi:type="uajpmf:AttributeInMetadata" onlyIfChecked="true"                  onlyIfRequired="false" matchIfMetadataSilent="false" /> <PermitValueRule xsi:type="uajpmf:AttributeUapprove"                 isApproved="true" requestedOnly="true" /> かつ他のルールで <AttributeConsumingService> が含まれない場合にオプショナルとしている場合 ⇒ <PermitValueRule xsi:type="uajpmf:AttributeInMetadata" onlyIfChecked="true"                  onlyIfRequired="false" matchIfMetadataSilent="true" /> <PermitValueRule xsi:type="uajpmf:AttributeUapprove"                 isApproved="true" requestedOnly="true" /> かつ他のルールで <AttributeConsumingService> が含まれない場合に必須としている場合 ⇒ <PermitValueRule xsi:type="uajpmf:AttributeInMetadata" onlyIfChecked="false"                  onlyIfRequired="false" matchIfMetadataSilent="true" /> ※ただしisRequired="false"の属性に対する挙動が変化する（オプショナル→必須）ことにご注意ください。 ※上記の場合の挙動を非表示にするには onlyIfRequied="true" としてください。 Info 上記表の斜体の属性はデフォルト値であるため実際の設定では記載していないことが多い。

• JSP は新しい JSP ファイルを使用します。
  4.1 属性送信の同意のリセットの機能を使用している場合は、 login.jsp を修正します。
• データベースのマイグレーションはできません。

4 高度なデプロイ

この節では高度な設定についてのトピックを取り上げます。

4.1 属性送信の同意のリセット

利用者がログインのフローの際に属性送信の同意をクリア ¹ できる機能を提供する場合は、 $IDP_INSTALL$/src/main/webapp/login.jsp にチェックボックスを追加します:

<form action="<%=request.getAttribute("actionUrl")%>" method="post">
  ...
  <input id="uApprove.consent-revocation" type="checkbox" name="uApprove.consent-revocation" value="true"/>
  <label for="uApprove.consent-revocation">Clear my attribute release consent</label>
  ...
</form>

<form action="<%=request.getAttribute("actionUrl")%>" method="post">
  ...
  <section>
    <input id="uApprove.consent-revocation" type="checkbox" name="uApprove.consent-revocation" value="true"/>
    <label for="uApprove.consent-revocation" style="position: relative; left: 0px;">Clear my attribute release consent</label>
  </section>
  ...
</form>

¹ クリアとは、アクセスして来たRelying Partyの属性送信の同意のすべての削除が行われた際に一般的な合意も削除することを意味します。

4.2 ストレージ

ファイルのみのストレージ

シンプルなデプロイのために、ファイルのみのデータベースを使うことができます。HSQL はそのようなオプションを提供します。
uApprove.properties にデータベースプロパティを定義します。

database.driver             = org.hsqldb.jdbcDriver
database.url        

...

        = jdbc:hsqldb:file:/var/opt/uApprove/

...

hsql.db
database.username           = SA
database.password        

   = 

必要であれば、ロゴやナビゲーションメニューを変更します。 ロゴは/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">
  <br>
  <span class="switchaai"><a href="http://www.gakunin.jp/" class="switchaai">About GakuNin</a></span>

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) から取得します。ローカライズされた属性名や説明は変更や追加ができます:

...

提供されているスキーマを用いてデータベースを初期化します:

echo "SHUTDOWN;" > /tmp/shutdown
java -jar $HSQLDB_HOME$/lib/sqltool.jar \
  --inlineRC=url=jdbc:hsqldb:file:/var/opt/uApprove/hsql.db,user=SA,password= \
  $UAPPROVE_INSTALL$/manual/storage/terms-of-use-schema.sql /tmp/shutdown
java -jar $HSQLDB_HOME$/lib/sqltool.jar \
  --inlineRC=url=jdbc:hsqldb:file:/var/opt/uApprove/hsql.db,user=SA,password= \
  $UAPPROVE_INSTALL$/manual/storage/attribute-relase-schema.sql /tmp/shutdown
java -jar $HSQLDB_HOME$/lib/sqltool.jar \
  --inlineRC=url=jdbc:hsqldb:file:/var/opt/uApprove/hsql.db,user=SA,password= \
  $UAPPROVE_INSTALL$/manual/storage/service-access-data-schema.sql /tmp/shutdown

SQL文のカスタマイズ

1. $UAPPROVE_INSTALL$/manual/storage/sql-statements.properties を $IDP_HOME$/conf/uApprove.sql-statements.properties にコピーします。
2. $IDP_HOME$/conf/uApprove.sql-statements.properties をカスタマイズします。

3. カスタマイズした sql-statements.properties を $IDP_HOME/conf/uApprove.xml で有効化します:

   Code Block
   language xml
   <bean id="uApprove.touModule" class="ch.SWITCH.aai.uApprove.tou.ToUModule" ...> <!-- ... --> <property name="storage"> <bean class="ch.SWITCH.aai.uApprove.tou.storage.JDBCStorage" ... p:sqlStatements="file:/$IDP_HOME$/conf/uApprove.sql-statements.properties" ... /> </property> </bean> <!-- ... --> <bean id="uApprove.attributeReleaseModule" class="ch.SWITCH.aai.uApprove.ar.AttributeReleaseModule" ...> <!-- ... --> <property name="storage"> <bean class="ch.SWITCH.aai.uApprove.ar.storage.JDBCStorage" ... p:sqlStatements="file:/$IDP_HOME$/conf/uApprove.sql-statements.properties" ... /> </property> </bean>

JDBCコネクションの緩やかな扱い

JDBC ストレージは、データベースの一時的な問題(接続できない等)の場合に緩やかに扱うように設定することができます。通常は、例外を許さずエラーページを表示し、継続的な動作は行われません。
以前の ToU の承諾や属性送信の同意に関わらず、利用者は再度承諾/同意を行わなければならない(既に行っていた場合)か、次回のログインの際に行わなければなりません(最初の場合)。

この設定は、 $IDP_HOME$/conf/uApprove.xml の中で定義されています:

<bean id="uApprove.touModule" class="ch.SWITCH.aai.uApprove.tou.ToUModule" ...>
    <!-- ... -->
    <property name="storage">
        <bean class="ch.SWITCH.aai.uApprove.tou.storage.JDBCStorage" ...
            p:graceful="true" ... />
    </property>
</bean>

<!-- ... -->

<bean id="uApprove.attributeReleaseModule" class="ch.SWITCH.aai.uApprove.ar.AttributeReleaseModule" ...>
    <!-- ... -->
    <property name="storage">
        <bean class="ch.SWITCH.aai.uApprove.ar.storage.JDBCStorage" ...
           p:graceful="true" ... />
    </property>
</bean>

JDBCコネクションプールのチューニング

この設定は、 $IDP_HOME$/conf/uApprove.xml の中で定義されています:

<bean id="uApprove.dataSource" class="com.mchange.v2.c3p0.ComboPooledDataSource" ...
    

...

.

...

.

...

.

...

    p:idleConnectionTestPeriod="

...

300" 

...

... />

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)内に このプラグインのためにネームスペース宣言を追加する必要があります。以下のように行います:

1. <ProfileHandlerGroup> ルート要素のxmlns:xsi 属性の前に xmlns:uajpph="http://www.gakunin.jp/ns/uapprove-jp/profile-handler" 属性を追加
2. 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プロファイルハンドラを変更する必要があります。以下のように行います:

1. xsi:type 属性の値を ph:SAML1AttributeQuery から uajpph:SAML1AttributeQueryUApprove に変更
2. 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)内に このプラグインのためにネームスペース宣言を追加する必要があります。以下のように行います:

1. <AttributeFilterPolicyGroup> ルート要素のxmlns:xsi 属性の前に xmlns:uajpmf="http://www.gakunin.jp/ns/uapprove-jp/afp/mf" 属性を追加
2. xsi:schemaLocation 属性の値のリストの最後に下記を追加
   http://www.gakunin.jp/ns/uapprove-jp/afp/mf classpath:/schema/shibboleth-2.0-afp-mf-uapprovejp.xsd

4.3 テンプレート

テンプレートのカスタマイズ

$DP_INSTALL$/src/main/webapp/uApprove/ にある JSP 、 CSS や画像ファイルは自由にカスタマイズすることができます。 JSTL を用いているので容易にカスタマイズ出来るようになっています。

JSTL については JSTL reference を参照してください。

4.4 ローカライズ

カスタムメッセージ

$UAPPROVE_INSTALL$/manual/examples/messages に用意されているリソースバンドルは環境に合わせたり、修正することができます。修正後のファイルを IdP の classpath(例えば $IDP_INSTALL$/src/main/webapp/WEB-INF/classes/uApprove/messages)にコピーすることで利用可能となります。
バンドルのベースを $IDP_HOME$/conf/uApprove.xml で以下のように定義します:

<bean id="uApprove.viewHelper" class="ch.SWITCH.aai.uApprove.ViewHelper" ...
    p:messagesBase="uApprove.messages" />

日本語のメッセージを修正する場合は、文字コードが UTF-8 のファイル #view#_ja-UTF8.properties を編集してください。編集したファイルを native2ascii コマンドで変換したうえで$IDP_INSTALL$/src/main/webapp/WEB-INF/classes/uApprove/messages にコピーしてください。 

attribute-release.jsp のメッセージを修正する手順は以下のようになります:

# cd $UAPPROVE_INSTALL$/manual/examples/messages
(attribute-release_ja-UTF8.properties を編集する)
# native2ascii attribute-release_ja-UTF8.properties attribute-release_ja.properties
# cp attribute-release_ja.properties $IDP_INSTALL$/src/main/webapp/WEB-INF/classes/uApprove/messages/

属性の名前と説明

ローカライズされた属性名および説明の設定方法については、 $UAPPROVE_INSTALL$/manual/examples/attribute-descriptions.xml を参照してください。

Relying Partyの名前と説明

現状では、ローカライズされた Relying Party の名前と説明を取得する際には、メタデータのうち <AttributeConsumingService> 要素および <mdui:UIInfo> 要素がサポートされています。

この名前と説明を使用する場合は、SPのメタデータを以下のように記述します:

<EntityDescriptor entityID="https://sp.example.org/shibboleth">
    <!-- ... -->
    <SPSSODescriptor>
        <Extensions>
            <mdui:UIInfo xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui">
                <mdui:DisplayName xml:lang="en">Example SP</mdui:DisplayName>
                <!-- Service names in other languages -->
                <mdui:Description xml:lang="en">Some description of Example SP</mdui:Description>
                <!-- Service descriptions in other languages -->
            </mdui:UIInfo>
        </Extensions>
        <!-- ... -->
        <AttributeConsumingService index="1">
            <ServiceName xml:lang="en">Example SP</ServiceName>
            <!-- Service names in other languages -->
            <ServiceDescription xml:lang="en">Some description of Example SP</ServiceDescription>
            <!-- Service descriptions in other languages -->
        </AttributeConsumingService>
    </SPSSODescriptor>
</EntityDescriptor>

4.5 厳密な比較

利用条件の内容の比較

デフォルトの設定では、利用者がToUを承諾したかどうかは ToU のバージョンの比較のみで行われます。 ToU の内容の比較を有効にしたい場合は、 $IDP_HOME$/conf/uApprove.xml にて以下のように設定します:

<bean id="uApprove.touModule" ... p:compareContent="true" ... />

4.6 監査ロギング

uApprove JP は、(IdP の監査ロギング機能を使用して) $IDP_HOME$/logs/idp-audit.log への監査ロギングを行うことができます。

利用条件の監査ロギングの有効化

ToU の監査ロギングを有効にしたい場合は、 $IDP_HOME$/conf/uApprove.xml にて以下のように設定します:

<bean id="uApprove.touModule" ... p:auditLogEnabled="true" ... />

ログ出力例:

20120101T010000Z|ch.SWITCH.aai.uApprove|||tou.acceptance|null|null|null|student1||1.0,5b2ee897c08c79a09cd57e8602d605bf8c52db17de9793677c36b5c78644b2b3,|

属性の送信の監査ロギングの有効化

属性の送信の監査ロギングを有効にしたい場合は、 $IDP_HOME$/conf/uApprove.xml にて以下のように設定します:

<bean id="uApprove.attributeReleaseModule" ... p:auditLogEnabled="true" ... />

ログ出力例:

20120101T010000Z|ch.SWITCH.aai.uApprove||https://sp.example.org/shibboleth|ar.consent|null|null|null|student1||uid,surname,givenName,|
20120101T010000Z|ch.SWITCH.aai.uApprove||https://sp.example.org/shibboleth|ar.clearConsent|null|null|null|student1|||
20120101T010000Z|ch.SWITCH.aai.uApprove|||ar.generalConsent|null|null|null|student1|||

4.7 AttributeInMetadataマッチングルール

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 classpath:/schema/shibboleth-2.0-afp-mf-uapprovejp.xsd

ルールの定義

このルールは <PermitValueRule xsi:type="uajpmf:AttributeInMetadata"> のように記述します。以下のオプショナルな属性を使用できます: 

...

Attribute RuleのPermit/Deny Value Rule

...

ルールの定義

uApprove.jpはPolicy RequirementルールとAttribute RulesのPermit/Deny Valueルールを拡張します:

...

• このルールは<afp:PolicyRequirementRule xsi:type="uajpmf:AttributeUapprove"> 要素によって定義されます。 そして、SPのメタデータ内に<AttributeConsumingService> 要素が存在する場合に適用されます。

AttributeInMetadata マッチファンクションを使用した <PermitValueRule> の書き方は下記のようになります:

<PermitValueRule xsi:type="uajpmf:

...

isApproved (オプショナル)

...

AttributeInMetadata" onlyIfRequired="false"
                 onlyIfChecked="true"

...

requestedOnly (オプショナル)

• SPのメタデータで定義された属性のみを表示するか否かを示すブーリアン値です。
  デフォルト値: false

xsi:type="uajpmf:AttributeUapprove" を持たない許可された属性は必須属性として扱われます。

uajpmf:AttributeUapprove Matchファンクションを用いたPermit Valueルールの例を示します:

>

オプションとマークされた属性をチェックボックスつきで表示します。チェックボックスをチェックしたときだけ送信します。

AttributeInMetadata マッチファンクションを使用した <PermitValueRule> の設定例を示します:

<!--    ==================================================================================
case 1: メタデータ内にmail AttributeConsumingService属性、eduPersonPrincipalName 要素を持つSPにマッチします。属性、eduPersonAffiliation 属性を、メタデータの
       eduPersonPrincipalName 属性はオプショナル属性で、ユーザは送信するか否かを選択できます。 定義と照合するルールです。

        メタデータで isRequired="true" が指定されている属性は、すべて必須情報になり常に
        送信されます。

        メタデータで isRequired="false" が指定されている属性は以下の通りです。
        * mail 属性は必須情報となり常に送信されます。
        * eduPersonPrincipalName 属性はオプション情報となります。属性選択画面ではチェック
          ボックスつきで表示されます。利用者がチェックボックスをチェックした場合に限り送信
          されます。
        * eduPersonAffiliation 属性は必須属性で、常に送信されます。属性は送信されません。

        メタデータに AttributeConsumingService をもたない SP の場合はどの属性も送信しません。
        ================================================================================== -->
<afp:AttributeFilterPolicy id="PolicyforSPwithAttributeConsumingService">
    <afp:PolicyRequirementRule xsi:type="uajpmfbasic:AttributeUapproveANY" />

    <afp:AttributeRule attributeID="eduPersonPrincipalNamemail">
        <afp:PermitValueRule xsi:type="uajpmf:AttributeUapprove" AttributeInMetadata"
                             onlyIfRequired="false" />
    </afp:AttributeRule>

    <afp:AttributeRule attributeID="eduPersonAffiliationeduPersonPrincipalName">
        <afp:PermitValueRule xsi:type="basicuajpmf:ANY" 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にマッチします。がない SP に対するルールを追加したルール
      eduPersonPrincipalName 属性 および eduPersonAffiliation 属性共に必須属性です。  です。

        AttributeConsumingService 要素を持たない SP の場合は以下の通りです。
        * mail 属性は必須情報となり常に送信されます。
        * eduPersonPrincipalName 属性はオプション情報となります。属性選択画面ではチェック
          ボックスつきで表示されます。利用者がチェックボックスをチェックした場合に限り送信
          されます。
        * eduPersonAffiliation 属性は送信されません。

        AttributeConsumingService 要素を持つ SP の場合は case 1 と同じです。
        ================================================================================== -->
<afp:AttributeFilterPolicy id="PolicyforSPwithoutAttributeConsumingService">
    <afp:PolicyRequirementRule xsi:type="basic:NOTANY" />

    <afp:AttributeRule attributeID="mail">
 <basic:Rule       <afp:PermitValueRule xsi:type="uajpmf:AttributeUapproveAttributeInMetadata"/>
    </afp:PolicyRequirementRule>      <afp:AttributeRule attributeID="eduPersonPrincipalName">                   matchIfMetadataSilent="true"
        <afp:PermitValueRule xsi:type="basic:ANY                     onlyIfRequired="false" />
    </afp:AttributeRule>

    <afp:AttributeRule attributeID="eduPersonAffiliationeduPersonPrincipalName">
        <afp:PermitValueRule xsi:type="basicuajpmf:ANYAttributeInMetadata"
/>     </afp:AttributeRule>      ... </afp:AttributeFilterPolicy>  <!--    ==================================================================================
case 3: 全てのSPにマッチします。           matchIfMetadataSilent="true"
           eduPersonPrincipalName 属性 および eduPersonAffiliation 属性はオプショナル属性です。         ================================================================================== --> <afp:AttributeFilterPolicy id   onlyIfRequired="PolicyforAnyonefalse">
    <afp:PolicyRequirementRule xsi:type="basic:ANY" />      <afp:AttributeRule attributeID="eduPersonPrincipalName">         <afp:PermitValueRule xsi:type="uajpmf:AttributeUapprove       onlyIfChecked="true" />
    </afp:AttributeRule>

    <afp:AttributeRule attributeID="eduPersonAffiliation">
        <afp:PermitValueRule xsi:type="uajpmf:AttributeUapproveAttributeInMetadata" />
    </afp:AttributeRule>

    ...
</afp:AttributeFilterPolicy>

1.4.6 Reset-approvals 設定

オプションである reset-approvals は以下の二通りの方法で操作可能です:

• In-flow モード
  • ユーザがログイン手続きにおいてリセット可能であることを意味します。 たとえばログインフォームのチェックボックスを使用するといった方法です。
• Standalone モード
  • JSP などを直接呼ぶ操作です。

In-flow モード

In-Flow の reset-approvals アプリケーションを有効にするには、Shibboleth の UsernamePassword ログインフォーム ${CATALINA_HOME}/webapps/idp/login.jsp にチェックボックスの追加で対応可能です。

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 設定

オプションである list-approvals はStandalone モードで使用します。 REMOTE_USER を提供するShibboleth Service Provider で JSP が保護されている必要があります。

SPの設定

...

/etc/shibboleth/shibboleth2.xmlで uid を REMOTE_USERに設定します。

...

4.8 AttributeQuery プロファイルハンドラの変更

uApprove JP は Attribute Query の SAML 応答メッセージの属性のリストを利用者の同意内容に応じて生成します。

プロファイルハンドラの設定

名前空間の定義

プロファイルハンドラファイル(例えば、$IDP_HOME$/conf/handler.xml) 内にこのプラグインの名前空間の定義を追加する必要があります。以下のように行います:

1. <ProfileHandlerGroup> ルートの xmlns:xsi 属性の前に xmlns:uajpph="http://www.gakunin.jp/ns/uapprove-jp/profile-handler" 属性を追加
2. xsi:schemaLocation 属性の値のリストの最後に下記を追加
   http://www.gakunin.jp/ns/uapprove-jp/profile-handler classpath:/schema/shibboleth-2.0-idp-profile-handler-uapprovejp.xsd

...
<ph:ProfileHandlerGroup
        xmlns:ph="urn:mace:shibboleth:2.0:idp:profile-handler"
        xmlns:uajpph="http://www.gakunin.jp/ns/uapprove-jp/profile-handler"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:mace:shibboleth:2.0:idp:profile-handler classpath:/schema/shibboleth-2.0-idp-profile-handler.xsd
                            http://www.gakunin.jp/ns/uapprove-jp/profile-handler classpath:/schema/shibboleth-2.0-idp-profile-handler-uapprovejp.xsd">
... 

プロファイルハンドラ定義の変更

Attribute Query プロファイルハンドラを変更する必要があります。以下のように行います:

1. xsi:type 属性の値を ph:SAML1AttributeQuery から uajpph:SAML1AttributeQueryUApprove に変更
2. xsi:type 属性の値を ph:SAML2AttributeQuery から uajpph:SAML2AttributeQueryUApprove に変更

...
    <ph:ProfileHandler xsi:type="uajpph:SAML1AttributeQueryUApprove" inboundBinding="urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding"
                       outboundBindingEnumeration="urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding">
        <ph:RequestPath>/SAML1/SOAP/AttributeQuery</ph:RequestPath>
    </ph:ProfileHandler>
...
    <ph:ProfileHandler xsi:type="uajpph:SAML2AttributeQueryUApprove" inboundBinding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
                       outboundBindingEnumeration="urn:oasis:names:tc:SAML:2.0:bindings:SOAP">
        <ph:RequestPath>/SAML2/SOAP/AttributeQuery</ph:RequestPath>
    </ph:ProfileHandler>
... 

SPがブラックリストに登録されている場合の挙動について

uApprove.properitesのservices.blacklistプロパティが true の場合、services プロパティは SP のブラックリストになります。services プロパティに正規表現を記述すると、エンティティIDがマッチした SP には uApprove を使用せずに接続します。このとき、属性の送信情報はストレージに保存しません。

uApprove JP の AttribureQuery プロファイルハンドラを設定すると、ブラックリストに登録されている SP からの AttribureQuery には、属性情報を応答しません。ただし、SP がブラックリストに登録される前に属性の送信に同意していた場合は、「今回は情報を送信することに同意します。次のログイン時に再度チェックします」で同 意した場合をのぞき、同意済みの情報を応答します。

4.9 属性送信済み SP の一覧

Shibboleth SPのインストールと設定

属性送信済み SP の一覧のWebページは REMOTE_USER を提供する Shibboleth SP  で保護されている必要があります。

IdP サーバに Shibboleth SP をインストールし、以下の設定をしてください。

REMOTE_USER の設定

/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.ac.jp/shibboleth-sp"
                         REMOTE_USER="uid

...

">
...

SSO の設定

同じマシン上の IdP に接続するため、 /etc/shibboleth/shibboleth2.xml で SSO から DS の設定を削除します:

...
            <SSO entityID="https://idp.example.ac.jp/idp/shibboleth">
              SAML2 SAML1
            </SSO>
...

IdP のメタデータ設定

/etc/shibboleth/shibboleth2.xml で同じマシン上の IdP のメタデータの読み込むための設定を追加します:

...
        <!-- Example of locally maintained metadata. -->
        <MetadataProvider type="XML" file="$IDP_HOME$/metadata/idp-metadata.xml" />
...

uid の受信設定

/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 で以下のように設定します。

...

</Attributes>

shibd を再起動してください。（なお、httpd の再起動は本節の最後でまとめて行います）

IdP の設定

SP のメタデータ設定

$IDP_HOME$/conf/relying-party.xml で同一マシンの SP のメタデータを読み込むための設定を追加します:

...

...

        <!-- Load the local SP's metadata. -->
        <metadata:MetadataProvider id="LocalSPMD" xsi:type="metadata:FilesystemMetadataProvider"
                                   metadataFile="$IDP_HOME$/metadata/sp-metadata.xml"
                                   maxRefreshDelay="P1D" />
...

...

...

下記のように実行します。

...

1.5 実行

Tomcat を再起動してください:

/sbin/service tomcat6 stop && sleep 10 && /sbin/service tomcat6 start

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">
 <appender-ref ref="IDP_PROCESS"/>
</logger>
<logger name="jp.gakunin.shibboleth" level="DEBUG">
 <appender-ref ref="IDP_PROCESS"/>
</logger>
...

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 (希望する)。

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> 要素の例を下記に示します:

attribute-resolver.xml の設定

$IDP_HOME$/conf/attribute-resolver.xml に uid の定義を追加します:

<resolver:AttributeDefinition xsi:type="ad:Simple" id="uid" sourceAttributeID="uid">
    <resolver:Dependency ref="myLDAP" />
    <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:mace:dir:attribute-def:uid" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:0.9.2342.19200300.100.1.1" friendlyName="uid" />
</resolver:AttributeDefinition>

attribute-filter.xml の設定

$IDP_HOME$/conf/attribute-filter.xml で uid のみを送出するように設定します:

<afp:AttributeFilterPolicy id="PolicyforLocalSP">
    <afp:PolicyRequirementRule xsi:type="basic:AttributeRequesterString"
                               value="https://idp.example.ac.jp/shibboleth-sp" />
    <afp:AttributeRule attributeID="uid">
        <afp:PermitValueRule xsi:type="basic:ANY"/>
    </afp:AttributeRule>
</afp:AttributeFilterPolicy>

uApprove.properies の設定

IdP 上で動作する SP なので、uApprove JPによる同意をスキップするために以下の設定を推奨します。

• services にエンティティ ID の正規表現を追加します。
• services.blacklist は true を設定します。

services                    = ^https://idp\.example\.ac\.jp/shibboleth-sp$
services.blacklist          = true

Web アプリケーションデプロイメントデスクリプタ に ListApprovalsServlet サーブレットについての設定を追加します:

<web-app ...>

    ...
    <servlet>
        <servlet-name>ListConsentedSP - List of consented SP</servlet-name>
        <servlet-class>jp.gakunin.uApprovejp.lcsp.ListApprovalsServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>ListConsentedSP - List of consented SP</servlet-name>
        <url-pattern>/uApprove/ListConsentedSP</url-pattern>
    </servlet-mapping>

</web-app>

IdP の再デプロイが必要です。2.4 デプロイを参照してください。

httpd の設定

/etc/httpd/conf.d/ssl.conf で以下のように設定します:

...
<Location /idp/uApprove/ListConsentedSP>
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  require valid-user
</Location>
...

httpd を再起動してください。

属性送信済み SP の一覧の URL

属性送信済み SP の一覧のURLは以下のようになります:

https://idp.example.ac.jp/idp/uApprove/ListConsentedSP

終了ページの設定

終了ボタンを押すと、https://idp.example.ac.jp/idp/uApprove/list-approvals-exit.html に移動します。移動先は uApprove.properties の lcsp.returnURL に URL を記述して変更できます。

設定例:

lcsp.returnURL = https://idp.exmaple.ac.jp/your-made-page.html

5 トラブルシューティング

5.1 トラブルシューティング

• ERROR ないし WARN メッセージについては、 $IDP_HOME$/logs/idp-process.log をチェックしてください。
• $CATALINA_HOME$/logs にある Tomcat のログファイルにエラーメッセージがないかチェックしてください。

5.2 詳細なログ設定

DEBUG ないし TRACE ログレベルを有効にしたい場合は、 $IDP_HOME$/conf/logging.xml にて以下のように設定します:

<logger name="ch.SWITCH.aai.uApprove" level="DEBUG"/>
<logger name="jp.gakunin.shibboleth" level="DEBUG"/>
<logger name="jp.gakunin.uApprovejp" level="DEBUG"/>

A SPでの属性使用用途通知

SP 管理者は SP のメタデータに属性の使用用途を記述することで、SP の利用者に属性の使用用途 (例えば、プロファイルの初期値として使用) を uApprove JP 内で通知することができます。

A.1 設定

属性使用用途通知機能は、 <RequestedAttribute> に uajpmd:description 属性を追加する、または、 <SPSSODescriptor> の <Extensions> に <uajpmd:RequestedAttributeExtension> を追加することで利用できます。

<uajpmd:RequestedAttributeExtension> は多言語に対応しています。また、一つの属性に両方が設定されている場合は、 <uajpmd:RequestedAttributeExtension> が優先されます。

uajpmd:description

この属性は <ResquestedAttribute> にて定義します:

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:Description> には属性の使用用途を記述します。<uajpmd:RequestedAttributeExtension> は以下の必須属性と共に設定します:

<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>

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の以前のバージョンでは以下の要素が無かったようですので、この部分に特にご注意ください。

    <dispatcher>REQUEST</dispatcher>
    <dispatcher>FORWARD</dispatcher> 

    ...
  </md:EntityDescriptor>
  ...
</md:EntitiesDescriptor>