Upgrade to new Gitlab Version 13.9 on Saturday 19th April 20:00. Expect an interruption of about 30 to 60 minutes

README 8.08 KB
Newer Older
haemmer's avatar
haemmer committed
1
Copyright (c) 2013, 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
-------------------------------------------------------------------------------
haemmer's avatar
haemmer committed
13 14
This file contains important information for this release of SWITCHwayf, 
including the installation and update instructions.
haemmer's avatar
haemmer committed
15 16 17
-------------------------------------------------------------------------------

Requirements:
18 19 20 21 22 23 24 25
- PHP 5.3 or newer
- PHP XML Parser extension is required for parsing SAML2 metadata
- The web server users must have write permissions to some files including: 
  * $backupIDPConfigFile (default 'IDProvider.conf.php')
  * $metadataIDPFile (default 'IDProvider.metadata.conf.php')
  * $metadataSPFile (default 'SProvider.metadata.conf.php')
  * $metadataLockFile (default '/tmp/wayf_metadata.lock')
  * $WAYFLogFile (default '/var/log/apache2/wayf.log')
haemmer's avatar
haemmer committed
26 27
-------------------------------------------------------------------------------

haemmer's avatar
haemmer committed
28 29 30 31
Download:
The latest release can be downloaded from:
https://forge.switch.ch/redmine/projects/wayf/files

haemmer's avatar
haemmer committed
32
Installation:
33 34
1. Unpack the SWITCHwayf_binary ${VERSION}_${DATE}.zip ZIP archive into a 
   directory on a host where Apache or IIS is installed. 
haemmer's avatar
haemmer committed
35

36 37 38 39 40 41 42
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

43 44 45 46 47 48 49
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.
50 51 52 53

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.

54
5. If Apache 2 is used, add the following statement to the Apache configugration:
haemmer's avatar
haemmer committed
55 56 57

--

58 59 60 61 62 63
Alias /SWITCHaai /#YOUR-PATH-TO#/SWITCHwayf
<Directory /#YOUR-PATH-TO#/SWITCHwayf>
    Options Indexes MultiViews
    AllowOverride None
    Order allow,deny
    Allow from all
64

65 66 67 68 69 70
    <Files WAYF>
      SetHandler php5-script
      AcceptPathInfo On
    </Files>

</Directory>
71 72 73

--

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

76 77 78
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
79 80 81 82 83

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

84 85
   For that to work, the Apache header extension must also be enabled
   with a command like:
haemmer's avatar
haemmer committed
86 87 88 89 90 91

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

92 93 94 95 96 97 98
   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
99

haemmer's avatar
haemmer committed
100 101 102 103 104 105 106

Subversion access:
Check out the latest SWITHCHwayf code with:
svn co https://subversion.switch.ch/svn/general/aai/SWITCHwayf/
Although the code in the Subversion should be always executable, it should be considered unstable and not be used for production environments without prior testing. 


haemmer's avatar
haemmer committed
107 108
-------------------------------------------------------------------------------

haemmer's avatar
haemmer committed
109
General Update Instructions:
110
1. Make a backup of the directory where the currently active version of the 
haemmer's avatar
haemmer committed
111 112 113 114 115
   SWITCHwayf is installed, e.g. with 'cp -a SWITCHwayf SWITCHwayf.bak'
2. Get the ZIP archive of the new version and move it into the same 
   parent directory where the current version is deployed.
3. Unzip the archive in the current deployment directory #DD#, 
   e.g. with the command 'unzip -d #DD# SWITCHwayf_x.y_YYYYMMDD.zip '
haemmer's avatar
haemmer committed
116 117
   This step will overwrite all files except those whose names start 
   with 'custom-'.
haemmer's avatar
haemmer committed
118 119 120
   Alternatively, create a new directory, move the ZIP archive in that directory,
   unzip it and then copy the config.php and all custom-.* files from the 
   current SWITCHwayf installation over to the new directory.
121 122
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
123 124 125 126
   Also compare your custom-.* files to the default-.* files that might have
   changed. Some features like the improved drop-down list require the WAYF
   to load additional javascripts. If your custom header file is missing these,
   the feature will not work.
haemmer's avatar
haemmer committed
127 128 129 130 131

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

Specific Update Instructions:

haemmer's avatar
haemmer committed
132 133 134 135 136 137 138 139 140 141 142 143 144 145
Updates from versions before 1.18
  The following new configuration options were introduced:
  
  - $supportContactEmail
  - $organizationLogoURL
  - $organizationURL
  - $faqURL
  - $helpURL
  - $privacyURL
  
  Have a look at config.dist.php in section 4. Appearance settings for a 
  description on these settings. The make sure to configure them to config.php
  which should contain your own configuration. Otherwise, default values
  will be set.
146 147


haemmer's avatar
haemmer committed
148 149
Updates from versions before 1.15
  The keys of the following languages strings were renamed and should be  
150
  adapted in the custom-languages.php file if it exists.
haemmer's avatar
haemmer committed
151 152
  - 'about_aai' was renamed to 'about_federation'
  - 'about_switch' was renamed to 'about_organisation'
153
  - 'switch_description' was renamed to 'additional_info'
haemmer's avatar
haemmer committed
154

155

156
Update from versions before 1.14.3:
haemmer's avatar
haemmer committed
157 158 159
  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.
160

161

haemmer's avatar
haemmer committed
162
Update from versions before 1.8:
haemmer's avatar
haemmer committed
163 164 165 166 167
  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
168 169 170

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

171
Security Notes:
haemmer's avatar
haemmer committed
172

173 174 175 176 177 178 179 180 181
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
182

183
$useSAML2Metadata = true;
184

185
and set the options:
haemmer's avatar
haemmer committed
186

187
enableDSReturnParamCheck = true;
188

189
and potentially
190

191
$useACURLsForReturnParamCheck = true;
192

193 194
in case the metadata loaded by SWITCHwayf does not include DiscoveryResponse 
elements for many Service Providers.
195 196 197

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

198 199
Troubleshooting:
Generally, if there is an error or an exception, the WAYF will log it to syslog. 
haemmer's avatar
haemmer committed
200
In case there is a problem and only a white page without any output is displayed, 
201
open config.php in a text editor, go to the bottom of the file and set:
202

203
$developmentMode = true;
haemmer's avatar
haemmer committed
204

205
This should output PHP warning messages which are otherwise supressed.
haemmer's avatar
haemmer committed
206 207 208

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

209
Documentation:
haemmer's avatar
haemmer committed
210

haemmer's avatar
haemmer committed
211
Consult the DOC file in the same directly as this file for further information 
212
on configuring and customizing the SWITCHwayf.