Upgrade auf Shibboleth IdP 5.x

Dies ist eine alte Version des Dokuments!

Die vorliegende Dokumentation wurde unter Debian Linux erstellt. Sie beschreibt das Upgrade ausgehend von folgendem Ausgangszustand:

Betriebssystem: Debian 12
Servlet-Container: Tomcat 9
Java: OpenJDK 11
Shibboleth IdP 4.3.2

Wir raten, wenn möglich, die Pakete Ihrer Distribution bzw. Ihres Betriebssystems zu installieren! Nicht-paketierte Software erfordert einen ungleich höheren Wartungsaufwand.

Wenn Sie nicht wissen, wann der Shibboleth IdP in Ihrem Hause zuletzt neu aufgesetzt wurden, können die folgenden Gegebenheiten Indizien für eine mitgeschleifte Konfiguration von vor 4.1.x sein:

Die Attribute Registry ist zwar vorhanden, aber noch nicht in Betrieb. Das ist der Fall, wenn die folgenden Zeilen in conf/services.xml durch Kommentarzeichen noch deaktiviert sind:

/opt/shibboleth-idp/conf/services.xml

    <!--
    <util:list id ="shibboleth.AttributeRegistryResources">
        <value>%{idp.home}/conf/attribute-registry.xml</value>
        <value>%{idp.home}/conf/attributes/default-rules.xml</value>
        <value>%{idp.home}/conf/attribute-resolver.xml</value>
    </util:list>
    -->

Es existiert noch ein Ordner /opt/shibboleth-idp/system.

Es sind diverse Module aktiviert, die Sie nicht aktiviert haben und die Sie nicht benötigen.

root@idp:~# ./bin/module.sh -l
Module: idp.authn.Duo [ENABLED]
Module: idp.authn.External [ENABLED]
Module: idp.authn.Function [ENABLED]
Module: idp.authn.IPAddress [ENABLED]
Module: idp.authn.MFA [ENABLED]
Module: idp.authn.Password [ENABLED]
Module: idp.authn.RemoteUser [ENABLED]
Module: idp.authn.RemoteUserInternal [ENABLED]
Module: idp.authn.SPNEGO [ENABLED]
Module: idp.authn.X509 [DISABLED]
Module: idp.authn.Demo [DISABLED]
Module: idp.admin.Hello [ENABLED]
Module: idp.admin.UnlockKeys [DISABLED]
Module: idp.intercept.Consent [ENABLED]
Module: idp.intercept.ContextCheck [ENABLED]
Module: idp.intercept.ExpiringPassword [ENABLED]
Module: idp.intercept.Impersonate [ENABLED]
Module: idp.intercept.Warning [DISABLED]
Module: idp.profile.CAS [ENABLED]

Im Ordner conf/authn liegen Konfigurationsdateien für Login-Flows, die Sie noch nie verwendet haben. Beispiel:

root@idp:~# ls /opt/shibboleth-idp/conf/authn/
authn-comparison.xml   duo.properties.idpnew             ipaddress-authn-config.xml         mfa-authn-config.xml                  remoteuser-internal-authn-config.xml.idpnew
authn-events-flow.xml  external-authn-config.xml         ipaddress-authn-config.xml.idpnew  password-authn-config.xml             saml-authn-config.xml
authn.properties       external-authn-config.xml.idpnew  jaas-authn-config.xml              password-authn-config.xml.idpnew      spnego-authn-config.xml
discovery-config.xml   function-authn-config.xml         jaas.config                        remoteuser-authn-config.xml           spnego-authn-config.xml.idpnew
duo-authn-config.xml   function-authn-config.xml.idpnew  krb5-authn-config.xml              remoteuser-authn-config.xml.idpnew    x509-authn-config.xml
duo.properties         general-authn.xml                 ldap-authn-config.xml              remoteuser-internal-authn-config.xml  x509-internal-authn-config.xml

Die Zeitstempel der Dateien in den Ordnern conf, messages und edit-webapp können eventuell Aufschluss darüber geben, wann der IdP aufgesetzt wurde. Hier sind die Zeitstempel der Dateien am interessantesten, die wahrscheinlich seit der Installation nicht mehr bearbeitet wurden. In einer Standard-Installation könnten das z.B. conf/cas-protocol.xml, conf/errors.xml oder auch edit-webapp/WEB-INF/web.xml sein.

→ Dokumentation

Die Datenbank-Verbindung wird im IdP 5.x nicht mehr über den JPA Storage Service hergestellt, sondern über den JDBC Storage Service. Mit folgenden Schritten stellen Sie den IdP um:

Sicherstellen, dass mindestens die Spalten context und id in der Tabelle StorageRecords case-sensitive behandelt werden.

Prüfen Sie die COLLATION. Eine Collation, deren Name auf _ci endet, ist case-insensitive,_cs steht für case-sensitive, utf8_bin ist ebenfalls case-sensitive. Ab MariaDB heißt es utf8_mb3 statt utf8.

root@idp:~# show create table StorageRecords\G;
*************************** 1. row ***************************
Table: StorageRecords
Create Table: 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
1 row in set (0.000 sec)

In der Dokumentation Ihrer Datenbank-Software finden Sie die Umstellungsmöglichkeiten und Hinweise, was ggf. bzgl. der Länge der Werte zu beachten ist (hier etwa für MariaDB).
Um die Collation für die ganze Tabelle StorageRecords umzustellen, gehen Sie wie folgt vor:
```
MariaDB[idp]> ALTER TABLE StorageRecords CONVERT TO CHARACTER SET utf8 COLLATE utf8_bin;
```

Installation des JDBC-Plugins (ab 4.2):

root@idp:~# /opt/shibboleth-idp/bin/plugin.sh -I net.shibboleth.plugin.storage.jdbc

Änderung der Konfiguration in conf/global.xml:

    <!-- VORHER -->										      |	    <!-- NACHHER -->
        <bean id="shibboleth.MySQLDataSource"								        <bean id="shibboleth.MySQLDataSource"
              class="%{mysql.class}"									              class="%{mysql.class}"
              p:driverClassName="org.mariadb.jdbc.Driver"						              p:driverClassName="org.mariadb.jdbc.Driver"
              p:url="%{mysql.url}"									              p:url="%{mysql.url}"
              p:username="%{mysql.username}"								              p:username="%{mysql.username}"
              p:password="%{mysql.password}"								              p:password="%{mysql.password}"
              p:maxWait="15000"										              p:maxWait="15000"
              p:testOnBorrow="true"									              p:testOnBorrow="true"
              p:maxActive="100"										              p:maxActive="100"
              p:maxIdle="100"										              p:maxIdle="100"
              p:validationQuery="select 1"								              p:validationQuery="select 1"
              p:validationQueryTimeout="5" />								              p:validationQueryTimeout="5" />
 
        <bean id="shibboleth.JPAStorageService"							      |	        <bean id="JDBCStorageService"
              class="org.opensaml.storage.impl.JPAStorageService"				      |	              parent="shibboleth.JDBCStorageService"
              p:cleanupInterval="%{idp.storage.cleanupInterval:PT10M}"					              p:cleanupInterval="%{idp.storage.cleanupInterval:PT10M}"
              c:factory-ref="shibboleth.JPAStorageService.EntityManagerFactory" />		      |		      p:dataSource-ref="shibboleth.MySQLDataSource" />
 
        <bean id="shibboleth.JPAStorageService.EntityManagerFactory"				      <
              class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">	      <
            <property name="packagesToScan" value="org.opensaml.storage.impl"/>			      <
            <property name="dataSource" ref="shibboleth.MySQLDataSource"/>			      <
            <property name="jpaVendorAdapter" ref="shibboleth.JPAStorageService.JPAVendorAdapter"/>   <
            <property name="jpaDialect">							      <
                <bean class="org.springframework.orm.jpa.vendor.HibernateJpaDialect" />		      <
            </property>										      <
        </bean>											      <
												      <
        <bean id="shibboleth.JPAStorageService.JPAVendorAdapter"				      <
              class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter"		      <
              p:generateDdl="true"								      <
              p:database="MYSQL"								      <
              p:databasePlatform="org.hibernate.dialect.MySQL5Dialect" />			      <
    												      <

Falls in Ihrer conf/idp.properties noch shibboleth.JPAStorageService vorkommt, ersetzen Sie die Stellen durch JDBCStorageService.
```
idp.session.StorageService = JDBCStorageService
idp.consent.StorageService = JDBCStorageService
```
Wenn Sie darüber hinaus das OIDC-Plugin auf Ihrem IdP nutzen, kann es sein, dass Sie den String shibboleth.JPAStorageService auch in den Dateien conf/oidc.properties…
```
idp.oidc.dynreg.StorageService = JDBCStorageService
```
… und/oder conf/oidc-clientinfo-resolvers.xml ersetzen müssen.
```
<bean id="StorageClientInformationResolver" parent="shibboleth.oidc.StorageClientInformationResolver"
        p:storageService-ref="JDBCStorageService" />
```

JDK 17 erforderlich

Dieser Schritt kann erst auf einem Server mit JDK 17 erfolgen.

Eine Voraussetzung für den Betrieb des IdP 5.x ist JDK 17. Ab dem Java Development Kit 15 wird die Javascript Scripting Engine Nashorn nicht mehr mit ausliefert. Der IdP benötigt sie jedoch, um ggf. die Javascript-Anteile bei der Definition von Scripted Attributes in conf/attribute-resolver.xml auszuführen. Sie können die Funktionalität über das Nashorn-Plugin ergänzen. Es muss lediglich installiert, aber nicht konfiguriert werden (ab 4.2):

root@idp:~# /opt/shibboleth-idp/bin/plugin.sh -I net.shibboleth.idp.plugin.nashorn

idp5

Upgrade auf Shibboleth IdP 5.x

Wurde der IdP vor oder nach 4.1.x neu aufgesetzt?

Mitpflegen der Konfiguration in den 4.x-IdPs

JDBC-Plugin

Nashorn-Plugin

JDK 17 erforderlich