{"type":"doc","content":[{"type":"panel","attrs":{"panelType":"success"},"content":[{"type":"paragraph","content":[{"text":"TL, DR; Refer to the ","type":"text"},{"text":"ReleaseNotes","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/SP3/pages/2065335693"}}]},{"text":" for the important information about the 3.0 release.","type":"text"}]},{"type":"paragraph","content":[{"text":"If your configuration is extremely old and dates to V2.3 or earlier, it will not be suitable for use. It may work at least in part, but it will contain a huge amount of unnecessary configuration and complexity and you should either redo it when upgrading to V3 by starting from scratch, or consider modernizing it prior to upgrading by comparing it against the default distribution file.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The upgrade process is designed to be seamless and is functionally the same as upgrading V2 in the past. Depending on the platform and how you've installed V2, upgrading to V3 should be done in the same fashion (yum update, port upgrade, Windows Installer, make install, etc.) and the result should be a functional system, with the logs indicating that the software and library versions are updated and warnings about the detection of the older configuration namespace.","type":"text"}]},{"type":"paragraph","content":[{"text":"The essential information you need is found on the ","type":"text"},{"text":"ReleaseNotes","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/SP3/pages/2065335693"}}]},{"text":" page, in which you will find a list of changes and altered behavior, and an explanation of how the configuration format has been \"forked\" to distinguish between older installations and a fresh install. An upgraded system is expected to initially run on the older configuration and the software will adjust its behavior accordingly, with some limited exceptions that are discussed in the notes.","type":"text"}]},{"type":"paragraph","content":[{"text":"One issue to highlight is that if you haven't ever modified the ","type":"text"},{"text":"attribute-map.xml","type":"text","marks":[{"type":"em"}]},{"text":" file, an RPM upgrade will replace it with the new default version, and an old mapping for an incorrect version of eduPersonTargetedID was removed in this release, so this could impact a system still making use of that broken attribute form. Just edit the file with a comment before upgrading to prevent this.","type":"text"}]},{"type":"paragraph","content":[{"text":"Once a system is upgraded and stable, carve out a small amount of time to review the warnings in the log for any deprecated settings or features, and establish a testing environment configured as a mirror of production. You can clean up your configuration in one of two ways:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The simplest thing in most cases is just to update your ","type":"text"},{"text":"shibboleth2.xml","type":"text","marks":[{"type":"em"}]},{"text":" and ","type":"text"},{"text":"security-policy.xml","type":"text","marks":[{"type":"em"}]},{"text":" files in place by changing the namespace declaration at the top of the file from ","type":"text"},{"text":"urn:mace:shibboleth:2.0:native:sp:config","type":"text","marks":[{"type":"code"}]},{"text":" to ","type":"text"},{"text":"urn:mace:shibboleth:3.0:native:sp:config","type":"text","marks":[{"type":"code"}]},{"text":" (there are usually two mentions of the namespace in the root element). ","type":"text"},{"text":"Note the difference there, the 2.0→ 3.0 in the string.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Be sure to review all \"MetadataProvider\" elements in the ","type":"text"},{"text":"shibboleth2.xml","type":"text","marks":[{"type":"em"}]},{"text":" file for \"file\" and \"uri\" attributes. These attribute names are no longer valid in the 3.0 namespace and must be replaced with the \"path\" and \"url\" attribute names. Examples below.","type":"text"}]},{"type":"paragraph","content":[{"text":"Old MetadataProvider","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n \n\n\n\n","type":"text"}]},{"type":"paragraph","content":[{"text":"New MetadataProvider","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n \n\n\n\n","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Alternatively you can start with the default ","type":"text"},{"text":"shibboleth2.xml.dist","type":"text","marks":[{"type":"em"}]},{"text":" file and transfer your settings to a new copy of ","type":"text"},{"text":"shibboleth2.xml","type":"text","marks":[{"type":"em"}]},{"text":", but that has a tendency to break things because it's hard to reproduce complex settings accurately.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The V3 default filename remains \"shibboleth2.xml\" to facilitate the upgrade process. Any settings that are flagged with warnings may be removed from the updated XML schema and prevent the system from loading the file if the namespace is updated, so they should be corrected as part of the process and once the system is operating with the new file you're done.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the warning doesn't explicitly mention how to replace a setting or what the alternative syntax should be, we will eventually capture that information on this page.","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that as of V3.1, the ","type":"text"},{"text":"XMLAttributeFilter","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/SP3/pages/2072543324"}}]},{"text":" configuration syntax has been updated to align with the IdP software, and the \"basic\" and \"saml\" XML namespaces are now deprecated. Use of those namespaces will emit warnings (usually quite a few of them).","type":"text"}]}],"version":1}