Copyright 2011 SWITCH - Serving Swiss Universities. See LICENSE file for details. ------------------------------------------------------------------------------- SWITCH WAYF Contact: aai@switch.ch or go to http://www.switch.ch/aai/wayf Version: See head of file 'WAYF' in the same directory Project web site: https://forge.switch.ch/redmine/projects/wayf Bug reports/feature requests: https://forge.switch.ch/redmine/projects/wayf/issues ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- This file contains important information relevant to this release and general information. ------------------------------------------------------------------------------- Requirements: - The web server must support PHP5 - If the configuration and the backup configuration differ, you have to make sure the user that runs the php script has write access for the configuration files. - PHP XML Parser extension for parsing SAML2 metadata ------------------------------------------------------------------------------- Installation: 1. Unpack the Zip archive into a directory on a host where Apache (IIS also should work) is deployed. 2. Make a copy of the *.dist.php files - Copy the file config.dist.php and name it config.php This is the main configuration file of the SWITCHwayf - Copy the file IDProvider.conf.dist.php and name it IDProvider.conf.php This file contains the list of Identity Providers that you configure by hand 3. Make sure that permissions for the files: - SProvider.metadata.php - IDProvider.metadata.php - metadata.lock - $WAYFLogFile (typically /var/log/apache2/wayf.log) are set such that the web server user (e.g. www-data, www or httpd) has write permissions for these two files. 4. Adapt the SWITCHwayf configuration in config.php. There are comments in that file that should help you make suitable choices for your use case. 5. If Apache 2 is used, add the following statement to the Apache configugration: -- SetHandler php5-script -- In some clustered environments with FastCGI it may be necessary to use something like: -- Options +FollowSymLinks RewriteEngine On RewriteRule ^WAYF/(.*)$ WAYF.php/$1 [QSA,L] RewriteRule ^WAYF$ WAYF.php [QSA,L] -- Alternatively, one also could rename the file 'WAYF' to 'WAYF.php'. 6. When using the embedded WAYF feature it might be necessary to add a line to the Apache configuration like below in order to prevent certain web browsers from not displaying the Embedded WAYF or parts of it: -- Header set P3P "CP=\"NOI CUR DEVa OUR IND COM NAV PRE\"" -- For that to work, the Apache header extension must also be enabled with a command like: -- a2enmod headers /etc/init.d/apache2 reload -- See http://www.w3.org/P3P/ for more details on P3P. 7. Test access by calling the WAYF with a URL like: https://your.host.com/path/to/WAYF Use this URL as Location for your Shibboleth configuration. The WAYF will automatically be able to detect whether it receives a Shibboleth authentication request or a Discovery Service request. ------------------------------------------------------------------------------- General Update Instructions: 1. Make a backup of the directory where the currently active version of the SWITCHwayf is installed 2. Get the compressed archive of the new version and move it into the directory of the currently deployed version 3. Unpack the archive with zip or tar This step will overwrite some existing files. Files whose name starts with 'custom-' will not be overwritten. 4. Have a look at config.dist.php and compare this file with your current config.php in order to identify new configuration options. ------------------------------------------------------------------------------- Specific Update Instructions: Updates from versions before 1.15 The keys of the following languages strings were renamed and should be adapted in the custom-languages.php file if it exists. - 'about_aai' was renamed to 'about_federation' - 'about_switch' was renamed to 'about_organisation' - 'switch_description' was renamed to 'additional_info' Update from versions before 1.14.3: The new setting '$metadataLockFile' was introduced in config.php. It allows configuring the location of the lock file. When the SWITCHwayf is used in a Windows environment, the path to this file probably has to be adapted. Update from versions before 1.8: This version has a slightly different structure than previous versions. Therefore, it is recommended to start with a clean installation. However, you should be able to take over most of your old config.php functions and use them in the new template.php file again to keep your customized look and feel. ------------------------------------------------------------------------------- Security Notes: The Discovery Service protocol as defined in http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-idp-discovery.pdf states that the protocol creates opportunities for phishing attacks as do all SSO protocols that make use of redirection. The specification states that an implementation "SHOULD" examine the 'return' parameter used in a Discovery Service request and match it against the extension in SAML metadata. Since version 1.14 the SWITCHwayf supports this feature. In order to activate it, the SWITCHwayf has to use the SAML 2 metadata parsing features by using $useSAML2Metadata = true; and set the options: enableDSReturnParamCheck = true; and potentially $useACURLsForReturnParamCheck = true; in case the metadata loaded by SWITCHwayf does not include DiscoveryResponse elements for many Service Providers. ------------------------------------------------------------------------------- Troubleshooting: Generally, if there is an error or an exception, the WAYF will log it to syslog. In case there is a problem and you see only a white page without any output, open config.php in a text editor, go to the bottom of the file and set: $developmentMode = true; This should output PHP warning messages which are otherwise supressed. ------------------------------------------------------------------------------- Documentation: Consult the DOC file in the same directly like this file for further information on configuring and customizing the SWITCHwayf.