README 6.44 KB
Newer Older
haemmer's avatar
haemmer committed
1
Copyright 2012 SWITCH - Serving Swiss Universities. 
haemmer's avatar
haemmer committed
2 3
See LICENSE file for details.

haemmer's avatar
haemmer committed
4
-------------------------------------------------------------------------------
haemmer's avatar
haemmer committed
5
SWITCHwayf
haemmer's avatar
haemmer committed
6
Contact: aai@switch.ch or go to http://www.switch.ch/aai/wayf
7
Version: See head of file 'WAYF' in the same directory
haemmer's avatar
haemmer committed
8 9
Project web site: https://forge.switch.ch/redmine/projects/wayf
Bug reports/feature requests: https://forge.switch.ch/redmine/projects/wayf/issues
haemmer's avatar
haemmer committed
10 11
-------------------------------------------------------------------------------

12
-------------------------------------------------------------------------------
13 14
This file contains important information relevant to this release and general
information.
haemmer's avatar
haemmer committed
15 16 17
-------------------------------------------------------------------------------

Requirements:
haemmer's avatar
haemmer committed
18
- The web server must support PHP5
haemmer's avatar
haemmer committed
19 20 21
- 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.
22
- PHP XML Parser extension for parsing SAML2 metadata
haemmer's avatar
haemmer committed
23 24 25
-------------------------------------------------------------------------------

Installation:
26 27
1. Unpack the Zip archive into a directory on a host where Apache 
  (IIS also should work) is deployed. 
haemmer's avatar
haemmer committed
28

29 30 31 32 33 34 35
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

36 37 38 39 40 41 42
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.
43 44 45 46

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.

47
5. If Apache 2 is used, add the following statement to the Apache configugration:
haemmer's avatar
haemmer committed
48 49 50 51 52 53 54

--
<Location /path/to/WAYF>
  SetHandler php5-script
</Location>
--

55
   In some clustered environments with FastCGI it may be necessary to use 
56
   something like:
57 58 59 60 61 62 63 64 65 66 67

--
Options +FollowSymLinks

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteRule ^WAYF/(.*)$ WAYF.php/$1 [QSA,L]
  RewriteRule ^WAYF$ WAYF.php [QSA,L]
</IfModule>
--

68
   Alternatively, one also could rename the file 'WAYF' to 'WAYF.php'.
haemmer's avatar
haemmer committed
69

70 71 72
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:
haemmer's avatar
haemmer committed
73 74 75 76 77

--
Header set P3P "CP=\"NOI CUR DEVa OUR IND COM NAV PRE\""
--

78 79
   For that to work, the Apache header extension must also be enabled
   with a command like:
haemmer's avatar
haemmer committed
80 81 82 83 84 85

--
a2enmod headers
/etc/init.d/apache2 reload
--

86 87 88 89 90 91 92
   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.
haemmer's avatar
haemmer committed
93 94 95

-------------------------------------------------------------------------------

haemmer's avatar
haemmer committed
96
General Update Instructions:
97 98 99 100 101 102 103 104 105 106
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.

haemmer's avatar
haemmer committed
107 108 109 110 111 112 113

-------------------------------------------------------------------------------

Specific Update Instructions:

Updates from versions before 1.15
  The keys of the following languages strings were renamed and should be  
114
  adapted in the custom-languages.php file if it exists.
haemmer's avatar
haemmer committed
115 116
  - 'about_aai' was renamed to 'about_federation'
  - 'about_switch' was renamed to 'about_organisation'
117
  - 'switch_description' was renamed to 'additional_info'
haemmer's avatar
haemmer committed
118

119
Update from versions before 1.14.3:
haemmer's avatar
haemmer committed
120 121 122
  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.
123

haemmer's avatar
haemmer committed
124
Update from versions before 1.8:
haemmer's avatar
haemmer committed
125 126 127 128 129
  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.
haemmer's avatar
haemmer committed
130 131 132

-------------------------------------------------------------------------------

133 134 135 136 137 138 139 140 141 142
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 <idpdisc:DiscoveryResponse> 
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
haemmer's avatar
haemmer committed
143

144
$useSAML2Metadata = true;
145

146
and set the options:
haemmer's avatar
haemmer committed
147

148
enableDSReturnParamCheck = true;
149

150
and potentially
151

152
$useACURLsForReturnParamCheck = true;
153

154 155
in case the metadata loaded by SWITCHwayf does not include DiscoveryResponse 
elements for many Service Providers.
156 157 158

-------------------------------------------------------------------------------

159 160 161 162
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:
163

164
$developmentMode = true;
haemmer's avatar
haemmer committed
165

166
This should output PHP warning messages which are otherwise supressed.
haemmer's avatar
haemmer committed
167 168 169

-------------------------------------------------------------------------------

170
Documentation:
haemmer's avatar
haemmer committed
171

172 173
Consult the DOC file in the same directly like this file for further information 
on configuring and customizing the SWITCHwayf.