Dies ist eine alte Version des Dokuments!


Upgrade

Ein Upgrade von IdP Version 2.x auf 3.4.x auf ein und demselben Host wird von den Entwicklern nicht empfohlen, da sich die Konfigurationen zu sehr unterscheiden und es keine automatische Konvertierung gibt.

Um Ihren IdP 2.x in der DFN-AAI ohne Downtime auf 3.4.x zu migrieren, empfehlen wir daher folgende Vorgehensweise, in der beide IdP-Versionen während der Migration parallel betrieben werden:

  • Lassen Sie den produktiven IdP 2.x zunächst unverändert weiter laufen.
  • Installieren Sie den aktuellsten IdP 3.4.x auf einem (neuen) Testsystem von Grund auf wie in diesem Wiki beschrieben.
  • Testen Sie damit ausführlich in der DFN-AAI-Test, bis Sie gut mit der Konfiguration vertraut sind:
    • Konfigurieren Sie attribut-resolver.xml und attribut-filter.xml analog zu Ihrem IdP 2.x und überzeugen Sie sich mithilfe unserer Test-SPs, dass die Attribute so übermittelt werden, wie es Ihr IdP 2.x tut.
    • Bitte bauen Sie in diesem Zuge auch die Syntax von attribute-resolver.xml um! Die Syntax von Shibboleth IdP 2.x mit den zahlreichen Namespaces wird ab Shibboleth 4.x nicht mehr unterstützt. Hiermit legen Sie eine wichtige Grundlage für das Upgrade auf die 4er-Version. Beispiele finden Sie in der mitgelieferten Datei conf/attribute-resolver.xml bzw. hier im Wiki.
    • Übrigens gibt es in der DFN-AAI keine SPs mehr, die ausschließlich den veralteten SAML1-Standard sprechen. Daher können Sie aus der conf/attribute-resolver.xml alle SAML1-Direktiven entfernen.
      ./conf/attribute-resolver.xml
      <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:mail" encodeType="false" />

      Die SAML2-Encodings brauchen Sie selbstverständlich noch!

    • Migrieren Sie die bestehende persistentId-Datenbank vom IdP 2.x auf die Testinstallation und verifizieren Sie, dass die IDs unverändert geblieben sind. Achten Sie hierbei darauf, dass Quellattribut(e) und Salt gleich bleiben! Die persistentIds müssen unverändert bleiben, damit Ihre Nutzer*innen bei den Service Providern wiedererkannt werden!
  • Wir empfehlen Ihnen, diesen Test-IdP zu behalten. So haben Sie für künftige Upgrades ein funktionierendes Testsystem, das Sie bei Bedarf einfach wieder in die Testföderation aufnehmen können.
  • Installieren Sie den IdP 3.4.x so auf einem neuen Produktivsystem, dass die Metadaten identisch zu Ihrem IdP 2.x sind, indem Sie bei der Installation den gleichen DNS-Namen wählen wie auf Ihrem bestehenden 2.x-System!
    • Die entityID des IdP 3.4.x entspricht damit der des IdP 2.x.
    • Die Kommunikations-URLs in den Metadaten bleiben unverändert.
    • Ersetzen Sie auf dem IdP 3.4.x die automatisch generierten private-Key- und Zertifikatsdateien durch die entsprechenden Dateien vom IdP 2.x (Dokumentation zu conf/idp.properties).
  • Die Metadaten des IdP 3.4.x sind jetzt identisch zum IdP 2.x. Es muss nichts in der DFN-AAI-Metadatenverwaltung eingetragen oder geändert werden. Insbesondere ist dort nach wie vor nur ein produktiver IdP eingetragen!
  • Übernehmen Sie die Attribute-, NameID-, Datenbank- und sonstige Konfigurationen von Ihrer 3.4.x Testinstallation auf das neue Produktiv-System.
  • Ersetzen Sie in Ihrem DNS-Server die IP des alten IdP 2.x durch die IP des neuen IdP 3.4.x.
  • Lassen Sie den IdP 2.x noch so lange laufen, bis sich die DNS-Änderung weltweit verbreitet hat.
  • Wenn Sie sehen, dass am IdP 2.x keine Zugriffe mehr erfolgen, können Sie ihn abschalten.

(Siehe hierzu auch diese Präsentation)

https://wiki.shibboleth.net/confluence/display/IDP30/Upgrading. Etwas ausführlicher ist die Anleitung von SWITCH.

Unter Linux ist insbesondere darauf zu achten, dass beim Upgrade die Schreib-/Leseberechtigungen korrekt gesetzt werden (Parameter -Didp.conf.filemode=644 beim Aufruf von ./bin/install.sh). Siehe hierzu auch die Anleitung von SWITCH unter 8.2. Common upgrade instructions for the Shibboleth IdP 3.

Für den Fall, dass die deutsche Übersetzung danach fehlt, stellen Sie sicher, dass die Sprachdatei unter dem Pfad <installationspfad>/system/messages/messages_de.properties (meist: /opt/shibboleth-idp/system/messages/messages_de.properties) liegt.

Ab IdP v3.4.0 werden Konfigurationsparameter als veraltet geloggt, die in Version 4.x nicht mehr vorkommen werden. An dieser Stelle sammeln wir fortlaufend die wichtigsten Änderungen. Das erklärte Ziel der Shibboleth-Entwickler*innen ist es, dass eine mitgepflegte Konfiguration nach einem Upgrade auf IdP v4.x fehlerfrei startet. Die jeweiligen vollständigen Release Notes sind wie immer im Shibboleth-Wiki. Dort finden Sie ebenfalls eine vollständige Übersicht über abgekündigte Konfigurationsdirektiven (DeprecatedIdPV4).

  1. Sicherstellen, dass idp.cookie.secure = true gesetzt ist (es sei denn, es soll explizit nicht so sein):
    idp.cookie.secure = true
    [...]
  2. Änderung der folgenden zwei Direktiven:
    • idp.consent.userStorageKey ersetzen durch idp.consent.attribute-release.userStorageKey und idp.consent.terms-of-use.userStorageKey
    • idp.consent.userStorageKeyAttribute ersetzen durch idp.consent.attribute-release.userStorageKeyAttribute und idp.consent.terms-of-use.userStorageKeyAttribute
      conf/idp.properties
      # Beispiel:
      [...]
      idp.consent.attribute-release.userStorageKey = shibboleth.consent.PrincipalConsentStorageKey
      idp.consent.attribute-release.userStorageKeyAttribute = %{idp.persistentId.sourceAttribute}
      idp.consent.terms-of-use.userStorageKey = shibboleth.consent.PrincipalConsentStorageKey
      idp.consent.terms-of-use.userStorageKeyAttribute = %{idp.persistentId.sourceAttribute}
      [...]

Der LegacyPrincipalConnector wird entfernt (oder zumindest auskommentiert):

conf/c14n/subject-c14n.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" /> -->
[...]
  1. Im Attribute Resolver wird die Dependency-Direktive ersetzt.
    • Wenn die Dependency sich auf einen Data Connector bezieht, wird ab IdP v3.4.2 stattdessen InputDataConnector verwendet. Bei jedem InputDataConnector muss das zu holende Attribut mit attributeNames mit angegeben werden. Damit wird die sourceAttributeID ersetzt.
      conf/attribute-resolver.xml
      # bis IdP v3.3.x:
          [...]
          <AttributeDefinition id="mail" xsi:type="Simple" sourceAttributeID="mail">
              <Dependency ref="myLDAP" />
                  <DisplayName xml:lang="en">E-mail</DisplayName>
                  <DisplayName xml:lang="de">E-Mail</DisplayName>
                  <DisplayDescription xml:lang="en">E-Mail address</DisplayDescription>
                  <DisplayDescription xml:lang="de">E-Mail Adresse</DisplayDescription>
              <AttributeEncoder xsi:type="SAML2String" name="urn:oid:0.9.2342.19200300.100.1.3" friendlyName="mail" encodeType="false" />
          </AttributeDefinition>
          [...]
       
      # ab IdP v3.4.x:
          [...]
          <AttributeDefinition id="mail" xsi:type="Simple">
              <InputDataConnector ref="myLDAP" attributeNames="mail"/>
              <DisplayName xml:lang="en">E-mail</DisplayName>
              <DisplayName xml:lang="de">E-Mail</DisplayName>
              <DisplayDescription xml:lang="en">E-Mail address</DisplayDescription>
              <DisplayDescription xml:lang="de">E-Mail Adresse</DisplayDescription>
              <AttributeEncoder xsi:type="SAML2String" name="urn:oid:0.9.2342.19200300.100.1.3" friendlyName="mail" encodeType="false"/>
          </AttributeDefinition>
          [...]
    • Wenn die Dependency sich auf ein anderes Attribut bezieht, das in conf/attribute-resolver.xml definiert wird, wird stattdessen InputAttributeDefinition verwendet.
      conf/attribute-resolver.xml
          [...]
          <AttributeDefinition id="uid" xsi:type="PrincipalName">
              <DisplayName xml:lang="en">User Name</DisplayName>
              <DisplayName xml:lang="de">Nutzerkennung</DisplayName>
              <DisplayDescription xml:lang="en">Local User Id</DisplayDescription>
              <DisplayDescription xml:lang="de">Nutzerkennung der Heimateinrichtung</DisplayDescription>
              <AttributeEncoder xsi:type="SAML2String" name="urn:oid:0.9.2342.19200300.100.1.1" friendlyName="uid" encodeType="false"/>
          </AttributeDefinition>
       
          <AttributeDefinition id="eduPersonPrincipalName" xsi:type="Scoped" scope="%{idp.scope}">
              <InputAttributeDefinition ref="uid" />
              <DisplayName xml:lang="en">Principal name</DisplayName>
              <DisplayName xml:lang="de">Netz-Id</DisplayName>
              <DisplayDescription xml:lang="en">A unique identifier for a person, mainly for inter-institutional user identification</DisplayDescription>
              <DisplayDescription xml:lang="de">Eindeutige, einrichtungsübergreifende Nutzerkennung</DisplayDescription>
              <AttributeEncoder xsi:type="SAML2ScopedString" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" friendlyName="eduPersonPrincipalName" encodeType="false" />
          </AttributeDefinition>
          [...]

Ab Shib IdP v3.4.x steht nach einer Neuinstallation ein Ablaufdatum in den IdP-Metadaten (metadata/idp-metadata.xml), das entfernt werden muss. Im folgenden Beispiel muss validUntil=„2019-05-22T11:01:10.621Z“ gelöscht werden.

metadata/idp-metadata.xml
<?xml version="1.0" encoding="UTF-8"?>
<!--
     This is example metadata only. Do *NOT* supply it as is without review,
     and do *NOT* provide it in real time to your partners.
 
     This metadata is not dynamic - it will not change as your configuration changes.
-->
<EntityDescriptor  xmlns="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:xml="http://www.w3.org/XML/1998/namespace" xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui" xmlns:req-attr="urn:oasis:names:tc:SAML:protocol:ext:req-attr" validUntil="2019-05-22T11:01:10.621Z" entityID="https://localhost.localdomain/idp/shibboleth">
 
[...]
  • Zuletzt geändert: vor 3 Monaten