ヒント |
---|
Shibboleth SPのアップデートに関してはこちらをご覧ください。⇒SPv3アップデートに関する情報 |
注意 |
---|
Shibboleth IdPバージョン5がすでにリリースされております。V5へのアップデートに関してはこちらをご覧ください。⇒IdPv5アップデートに関する情報 |
ヒント |
V3内のアップデートに関してはこちらをご覧ください。⇒IdPバージョン3アップデートに関する情報 |
目次 |
---|
バージョン共通
アップデートの手順
shibboleth-identity-provider-※ 4.x0.xxから4.tar.gzパッケージを展開したディレクトリで、以下のコマンドで設定ファイルの変更点を確認し、適宜反映した上で、アップデートを実行します。2.xにアップデートするような場合、途中のバージョンの注意点にも有効なものがありますので確認するようにしてください
バージョン共通
アップデートの手順
アップデート時には設定ファイルの変更点を手動で反映させなければならない場合があります。以下の注意事項をご確認ください。
情報 |
---|
反映しない場合、旧来の機能は変わらず動作することが保証されますが、新バージョン以降の新機能が(基盤となる機能がデフォルトで有効な場合でも、手動で有効化した場合でもいずれも)正しく動作することが保証されません。このため、将来的な新機能利用も見据えて、アップデート後でもかまいませんのでなるべく早く反映するようにしてください。 edit-webapp/ については扱いが特殊で、この配下のファイルについては dist/webapp/ 配下の変更点に従って更新してください。また、*.jarなど edit-webapp/ に元々存在しないファイルは反映する必要がありません。基本的に差分のあるもののみ edit-webapp/ に配置されます。逆に、dist/webapp/ 配下のファイルと同一内容の edit-webapp/ のファイルについては、将来的な更新に備えて配置されたものとなります。edit-webapp/ 上のファイルを削除しても問題なく動作しますが、将来のアップデート時に動作しなくなる原因となりますので、削除しないようご注意ください。dist/webapp/ 上で削除されたファイルについては、他のファイルを更新する前提で安全に削除できます。 特に、edit-webapp/WEB-INF/web.xmlは頻繁に更新されていますので、当該ファイルが存在する場合はweb.xmlの変遷を参照の上必要な変更を反映してください。( |
ヒント | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
uApproveJPをインストールしている場合は
ただし、4.1.0以降ではファイルがライブラリの中に入っております。下記の手順で展開したディレクトリの webapp/WEB-INF/lib/idp-conf-impl-4.1.x.jarの中にある当該設定ファイルを更新してJARファイルを上書きしてください。
|
まず、プラグインを使用している場合にはそちらの最新版を確認し、あればそちらを先にアップデートしてください。
shibboleth-identity-provider-4.x.x.tar.gz
パッケージを展開してそのディレクトリに移動します。
パネル |
---|
|
配布物の設定ファイルについて旧バージョンからの変更点を確認し、/opt/shibboleth-idp/ に既に存在するファイルについて適宜変更点を反映してください。もしくは、出力を任意のファイルに保存しておき、後日変更点を反映してください。まず、配布物として旧バージョンからの変更点を確認します。
パネル |
---|
|
情報 |
---|
4.1以降モジュール化された一部の設定ファイルはこのコマンドでは変更点が出力されません。後述のようにアップデート後、*.idpnewもしくは*.idpsaveというファイル名のファイルから差分を確認してください。 |
Jettyを停止後、インストールスクリプトを実行することでアップデートを行います。Jettyを停止後、インストールスクリプトを実行します。
パネル |
---|
|
...
パネル |
---|
|
情報 |
---|
アップデートが完了しましたら、後日でもかまいませんので各種設定ファイルを最新版の書式に更新することをご検討ください。
※ *.idpnewはモジュール化された設定ファイルに関するものしか生成されませんので、非モジュールの設定ファイルの差分は上述の従来通りの方法で dist/ 配下のものとの差分をご確認ください。 |
IdP 4.2.x から IdP 4.2.x へアップデートする場合の注意点
...
古いJetty 10には高負荷時のメモリリークの問題があるようですので、該当する場合には10.0.11以降を使用することをお勧めします。https://shibboleth.atlassian.net/browse/IDP-1969
...
再びlogbackライブラリの問題ですが、Jetty 9.4.46以降にバージョンアップすると再びlogbackおよびSLF4Jライブラリの問題ですが、Jettyをバージョンアップすると
書式設定済み |
---|
java.security.PrivilegedActionException: java.lang.ClassNotFoundException: ch.qos.logback.access.jetty.RequestLogImpl |
...
コード ブロック | ||
---|---|---|
| ||
@@ -6,3 +6,8 @@ # This seems to be needed in some cases to get early logging output. -Dlogback.configurationFile=resources/logback.xml + +# Override logback version pinned in jetty-home/modules/logback-impl.mod +#logbacklogback.version=1.2.6 +# Override SLF4J version pinned in jetty-home/modules/slf4j-api.mod +slf4j.version=1.7.32 |
...
どのバージョンから提供された機能か不明ですが、アカウントロックアウト機能が提供するAPIにアクセスできるようにするにはbeanの移動が必要です。(アカウントロックアウトを有効化するだけでAPIは不要の場合は移動は不要と思われます)
移動が必要な場合は、conf/authn/password-authn-config.xml に定義されている id="shibboleth.authn.Password.AccountLockoutManager" のbeanを conf/global.xml に移動させてください。
詳細: https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1294074654/AccountLockoutManagement
...
このバージョンに限ったことではありませんが、以前の3.xから運用していて4.xにバージョンアップした場合、secrets.propertiesファイルが存在しない状態となります。起動ごとにwarningが出ますが動作に支障はありません。もしV4の新書式へ移行しsecrets.propertiesファイルの利用を希望する場合は以下のページをご参照ください。
⇒credentials/secrets.propertiesの生成
IdP 4.1.x から IdP 4.2.x へアップデートする場合の注意点
...
詳細はリリースノート原文および開発者からの月例お知らせをご参照ください。
遅れての情報提供ですが、アサーション内の属性の格納方法が正規化されました。これまで同一属性の複数属性値についてばらばらに格納される場合がありましたが、4.2.0以降同一XML要素内に記載されます。これによる影響はないはずですが、実装に問題のあるSPによっては挙動に違いが発生することが考えられます。
IdP 4.1.x から IdP 4.1.x へアップデートする場合の注意点
このバージョンに限ったことではありませんが、Windows MSI installerを使っている場合アップデート時に最大メモリ設定が変更されるという情報があります。Windowsをお使いの場合はアップデート後にチェックするようにしてください。
詳細: (Shibboleth Wiki) WindowsInstallation の"Always Check"
こちらもこのバージョンに限ったことではありませんが、Jettyを9.4.44以降に更新する場合、logbackライブラリのコンフリクトでバージョン違いで従来の/opt/jetty-base/では以下のエラーで起動できません。
書式設定済み |
---|
java.security.PrivilegedActionException: java.lang.ClassNotFoundException: ch.qos.logback.access.jetty.RequestLogImpl |
このエラーで起動できない場合は、以下で提供されております /opt/jetty-base/ に更新してお使いください。
https://build.shibboleth.net/maven/snapshots/net/shibboleth/idp/idp-jetty-base/9.4.1-SNAPSHOT/idp-jetty-base-9.4.1-20211028.163025-766.tar.gzもしくは、/opt/jetty-base/lib/logback/ 以下の3つのファイルを、上記パッケージで提供されているもので置き換えてください。
こちらもこのバージョンに限ったことではありませんが、技術ガイドでご案内しているようにsystemdでJettyの起動や停止を行っている場合、かなり低い確率で起動時に以下のエラーが出て起動できない場合があるという報告があります。こちらもこのバージョンに限ったことではありませんが、技術ガイドでご案内しているようにsystemdでJettyの起動や停止を行っている場合、かなり低い確率で起動時に以下のエラーが出て起動できない場合があるという報告があります。(これはJetty 9.4の問題でJetty 10にはこの問題はありません)
書式設定済み |
---|
Job for jetty.service failed because the control process exited with error code. See "systemctl status jetty.service" and "journalctl -xe" for details. |
...
4.1からはidp.propertiesの記述が別の複数のファイルに分割記述されるようになりました(例: authn/authn.properties)。ただし4.0.x以前からのアップデートの場合はそれらの記述は適切に無視されます。4.1流にプロパティを分散記述する場合は、idp.propertiesにある重複を排除した上でidp.searchForPropertiesをtrueに設定してください。詳しくは dist/conf/idp.properties の冒頭のコメントを参照してください。
4.1の書式に書き換える例: https://shibboleth.atlassian.net/wiki/spaces/KB/pages/1469908146/Example+4.1+Upgrade
...
4.1から新たにプロパティで指定できるようになった設定が多数ありますが、古い設定ファイルが邪魔をして適切に反映されない場合があります。適切にプロパティの値を反映させたい場合は、対応する .idpnew が末尾に付くファイルを探し、元のファイルの変更点を確認し *.idpnew のファイルで置き換えた上で、適切に変更点を反映させてください。1から新たにプロパティで指定できるようになった設定が多数ありますが、古い設定ファイルが邪魔をしてプロパティで指定しても適切に反映されない場合があります。適切にプロパティの値を反映させたい場合は、アップデート手順にあるように設定ファイルの更新を適切に反映させてください。
...
4.0.1までには属性値ハッシュ計算の問題で属性値が複数ある場合変更されていないのに再同意を求める問題(idp.consent.compareValues=trueの場合の問題)があるようです。本運用環境を移行する場合にはご注意ください。4.1.0で修正されました。
https://issues.shibboleth.net/jira/browse/IDP-1660
...
LDAPを使った属性取得の例が conf/examples/ の下に移動しました。(conf/examples/attribute-resolver-ldap.xml)
...
4.1以降では conf/session-manager.xml ファイルは不要になりました。もし当該ファイルの shibboleth.ClientStorageServices
beanをカスタマイズして使っている場合は、当該beanを conf/global.xml に移したのち、conf/session-manager.xml を削除してください。
IdP 3.x.x から IdP 4.x.x へアップグレードする場合の注意点
...
名前空間のフラット化が強制され、プレフィックスありの(v2由来の名前空間を使用した)設定ファイルが使用できなくなります
IdP v3.4ではフラット化していない場合、DEPRECATEDのwarningとしてログに出力されます
- 3.4.0以降も細かい改善が続けられていますので、v3.4系の最新版で確認してください
静的に解析しているものと動的に解析しているものがあり、3.4系の最新版でしばらく動かして一通り認証フローの動作確認を行ってみることが必要です
- フラット化の対応手順はこちら
⇒https://meatwiki.nii.ac.jp/confluence/x/F4Z7AQ
- その他にも、DEPRECATEDのwarningとなる対象が複数あります
- 影響の大きいものとして、<Dependency>要素はDEPRECATEDです
内容によって<InputAttributeDefinition>もしくは<InputDataConnector>で置き換えてください。例えば
コード ブロック language xml <resolver:Dependency ref="myLDAP" />
は(myLDAPがDataConnectorとして定義されていると仮定して)以下で置き換えます。attributeNamesには使用する属性名を(複数ある場合はスペース区切りで)列挙してください:
コード ブロック language xml <InputDataConnector ref="myLDAP" attributeNames="..." />
また、
コード ブロック language xml <resolver:Dependency ref="eduPersonAffiliation" />
は(eduPersonAffiliationがAttributeDefinitionで定義されていると仮定して)以下で置き換えます:
コード ブロック language xml <InputAttributeDefinition ref="eduPersonAffiliation" />
LegacyPrincipalConnector
以下のwarningが出る場合は書式設定済み WARN [DEPRECATED:118] - Spring bean 'c14n/LegacyPrincipalConnector', (c14n/subject-c14n.xml): This will be removed in the next major version of this software; replacement is <remove>
conf/c14n/subject-c14n.xml の以下の部分を削除してください。
コード ブロック language xml <!-- This is installed to support the old mechanism of using PrincipalConnectors in the attribute resolver to map SAML Subjects back into principals. If you don't use those (or this is a new install) you can remove this. --> <ref bean="c14n/LegacyPrincipalConnector" />
フラット化への対応により<PrincipalConnector>は削除されているはずですので、当該部分を削除しても問題ありません。
- 詳細はShibbolethの本家の情報を参照してください。
- 変更のある要素への置き換え方法へのリンクを含めて記載されています
- Shibboleth IdP V4への準備として、V3.4系最新版(3.4.8)にてwarningが出なくなるまで設定ファイルを修正することを推奨します
- 影響の大きいものとして、<Dependency>要素はDEPRECATEDです
- すでにフラット化とDEPRECATED対応済みの学認テンプレートを配布中ですのでこちらも参考にしていただけます。ただし最新版attribute-resolver.xmlテンプレートにはV4向けのAttribute Registry対応も入っておりますので、本ページ(V3からのアップグレード)の文脈では参考にしないでください。具体的に言うと、
<AttributeEncoder>
の行は消さないでください。あくまでフラット化とDEPRECATEDな要素・属性の置き換えの参考として参照してください。 - LDAP周りで、使用するライブラリがJNDIからUnboundIDに変更になることにより以下の通り設定によってはV4への移行後にエラーになる可能性が若干ございます。
- LDAPのURL(ldap.propertiesの
idp.authn.LDAP.ldapURL
)がスラッシュ(/)で終わる場合はうまく動作しませんのでスラッシュを除去してください。 - 検索フィルタ(ldap.propertiesの
idp.attribute.resolver.LDAP.searchFilter
)に空白が含まれるとActive Directory等との連携に問題が発生する場合がございますので、空白を除去してください。 - LDAPConnectorもしくはJAASAuthnConfigurationにてJNDI特有のプロパティを使っている場合問題が発生します。プロパティ名に"jndi"を含むものもしくは下記"binary"にご注意ください。代替のものに置き換えてください。
- 特にバイナリ属性(objectGUID等)については3.4.5よりLDAPConnectorにて
<BinaryAttributes>
要素がサポートされておりますのでこれで代替してください。プロパティ名は"java.naming.ldap.attributes.binary"となっております。 JNDI特有のプロパティとは、例えば、attribute-resolver.xmlの<DataConnector>に以下のような指定がある場合該当します。
コード ブロック language xml <LDAPProperty name="com.sun.jndi.ldap.connect.timeout" value="500"/>
その他、IdPのディレクトリの中やJavaのディレクトリの中に
jndi.properties
というファイルが存在しその中で指定しているという場合があるようですのでご注意ください。
- 特にバイナリ属性(objectGUID等)については3.4.5よりLDAPConnectorにて
- 上記問題の対象の場合は、V3.4系最新版で以下に記載されている手順でUnboundIDを使うようにして動作確認することを推奨します
V3.4.4以降で以下の行をldap.propertiesに追加すればJNDIでなくUnboundIDを使うようになります。
コード ブロック idp.ldaptive.provider=org.ldaptive.provider.unboundid.UnboundIDProvider
V3系でUnboundIDが使われていることの確認は、idp.propertiesに
コード ブロック idp.loglevel.ldap=INFO
を追加してログレベルを変更の上再起動し、下記のように"Setting ldap provider to"が UnboundIDProvider になっていることを確認してください。
コード ブロック 2020-03-02 09:46:50,446 - - INFO [org.ldaptive.DefaultConnectionFactory:192] - Setting ldap provider to org.ldaptive.provider.unboundid.UnboundIDProvider 2020-03-02 09:46:50,453 - - INFO [org.ldaptive.DefaultConnectionFactory:192] - Setting ldap provider to org.ldaptive.provider.unboundid.UnboundIDProvider 2020-03-02 09:46:50,453 - - INFO [org.ldaptive.DefaultConnectionFactory:192] - Setting ldap provider to org.ldaptive.provider.unboundid.UnboundIDProvider
確認後、idp.propertiesに追加した行を削除してログレベルを元に戻してください。
- 詳細はこちら: LDAPonJava (v4) および LDAPonJava>8 (v3)
- LDAPのURL(ldap.propertiesの
...