Commit 3fbdfb26 authored by haemmer's avatar haemmer
Browse files

Applied Markdown syntax

parent 1b556bf3
......@@ -2,170 +2,176 @@ Copyright (c) 2013, SWITCH - Serving Swiss Universities
See LICENSE file for details.
-------------------------------------------------------------------------------
SWITCHwayf
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
SWITCHwayf Changes
==================
Find below the changes for past releases of the SWITCHwayf and in the credits
sections the people who contributed to the SWITCHwayf.
-------------------------------------------------------------------------------
Version Number Policy:
**This document is written in the markdown syntax**
Releases with a 0version number X.Y.Z usually are bug fix releases, typo
corrections and graphical changes.
Releases with a version number X.Y usually are minor releases that introduce
new functionality. Few adapations in the configuration might be necessary to
upgrade to minor releases.
-------------------------------------------------------------------------------
Version Number Policy
---------------------
Releases with a version number 'X.Y.Z' are bug fix releases correcting
small bugs, typos and graphical issues.
Releases with a version number 'X.Y' are minor releases that introduce
new functionality of fix non-trivial bugs. Few adaptions in the configuration
might be necessary to upgrade to minor releases.
Releases with a version number X are major releases that will require major
changes in the configuration files. Therefore, a clean instalation might be
necessary for such releases.
-------------------------------------------------------------------------------
SWITCHwayf Changes and Version History:
1.18 - Changed default SessionInitiator of the Embedded WAYF to
/Login because this has been the default SessionInitiator in
Shibboleth for quite some time now.
- Corrected viewport meta tag separator of default header as suggested
by Andrew Sokolov from Saint Petersburg State University
- Fixed a bug in the IdP preselection of the embedded wayf when
additional IdPs where added
- Removed as many SWITCH-specific graphics and texts as possible.
- Introduced configuration options to allow easier customization.
- Fixed a few small bugs
- Added some optimizations to the drop-down list search-as-you type
feature
- The log file now logs - if possible - also the SP entityID/providerId
- Some small styling changes/CSS improvements
- Added Japanese locales from the GakuNin version of the WAYF
Issues: https://forge.switch.ch/redmine/projects/wayf/versions/62
Please read the specific update instructions in the README file, as some
new configuration options were introduced that should be revised.
1.17.1 Release date: 14. June 2012
- Fixed a bug occuring when wayf_sp_samlDSURL contains GET arguments
Bug reported with a patch by Takeshi Nishimura from NII (Japan)
- Fixed typo in configuration otpion useImprovedDropDownList
- Added Javascripts required for improved drop down list
Issues: https://forge.switch.ch/redmine/projects/wayf/versions/55
1.17 Release date: 18. May 2012
- Added CSS styles for mobile view
- Embedded WAYF now reads 'entityID' and 'return' GET arguments.
They get precedence over the values configured for the Embedded WAYF.
- Embedded WAYF logged in message now contains a link to target URL
Issues: https://forge.switch.ch/redmine/projects/wayf/versions/45
1.16 Release date: 19. January 2012
- Added an improved version of the drop down list to the WAYF
Inspired by code from Takeshi Nishimura from NII (Japan)
Uses modified ImprovedDropdown JQuery library by John Fuex
See LICENSE file for further information
- Added cookieSecurity option to set and transmit cookies securely
Code contributed by Takeshi Nishimura from NII (Japan)
- Added additional data protection feature that uses the referer to
decide whether or not to preselect an Identity Provider in the
Embedded WAYF.
Code contributed by Takeshi Nishimura from NII (Japan)
- If the Discovery Feed feature is activated only those IdPs are shown
that are contained in the feed. Others will be hidden automatically.
- Added Keywords property to format of IDP entries to allow users to
search Identity Providers using a keyword.
Issues: https://forge.switch.ch/redmine/projects/wayf/versions/40
1.15 Release date: 21. October 2011
- A default and custom CSS file can now be used
- Graphical design now is based new SWITCH harmos elements
- Adapted JSON output to use format used by Shibboleth SP
- Renamed some string keys to make them independent from SWITCH
###################################################################
Please review the 'Specific Update Instructions' in the README file
###################################################################
- Added support for the Shibboleth SP 2.4 Discovery Feed JSON output
in Embedded WAYF
- Focus on submit button works better with different browsers
- Invalid values for width and height are now defaulted to auto for
Embedded WAYF
- Fixed a URL composing bug that resulted in a wrong return URL to
the Service Provider if the return parameter did not contain any GET
arguments. Reported by Tom Scavo
- Made implementation behave according to the Discovery Service protocol
specification when it comes to the return parameter. This parameter
is optional in case the DS knows the SP Discovery URL.
Reported by Tom Scavo.
Issues: https://forge.switch.ch/redmine/projects/wayf/versions/26
1.14.3 Release date: 4. March 2011
- Fixed a race condition. Thanks go to Robert Basch from MIT for
reporting the issue and providing a patch.
Issues: https://forge.switch.ch/redmine/projects/wayf/versions/32
1.14.2 Release date: 15. December 2010
- IDProvider.conf.php and config.php are not overwritten anymore by upgrades
- Logging to syslog now works properly and is more consistent
- Access log now properly locks file
- Unknown category is not shown anymore when there is no other category
- Namespaces are now taken properly into account when parsing SAML2
metadata. Thanks go to Olivier Salaün for reporting this issue and
submitting a patch.
- Improved installation instructions
Issues: https://forge.switch.ch/redmine/projects/wayf/versions/25
1.14.1 Release date: 12. November 2010
- Fixed an encoding bug that affected non-ASCII characters in
JavaScripts. Thanks to Prof. Kazutsuna Yamaji for reporting this issue.
- Corrected behaviour of $enableDSReturnParamCheck and
$useACURLsForReturnParamCheck. There won't be an error anymore if an SP
has no <idpdisc:DiscoveryResponse> extension defined. In such a case
there will only be a check if $useACURLsForReturnParamCheck is enabled.
- Fixed a bug in readMetadata.php that prevented CLI execution
- Changed the default configuration option to generate the Embedded WAYF
to false due to some concerns regarding phishing attacks
- Added proper copyright statements to all source code files
Issues: https://forge.switch.ch/redmine/projects/wayf/versions/21
1.14 Release date: 9. November 2010
- Added the configuration option wayf_force_remember_for_session to
the Embedded WAYF on request of Wolgang Lierz. This
option allows setting the remember for session checkbox to true
- The 'return' parameter of a Discovery Service request can now be
checked using the idp-discovery-protocol extension or using the FQDN
of all the Service Provider's assertion consumer URLs. The latter
alternative is less secure but still offers better security against
phising attacks. Have a look at config.dist.php and the README for
more detailed explanations on these feature.
- Metadata parsing now uses DOM XML for PHP5 instead of Simple XML
- Fixed a minor HTML error in template for Embedded WAYF
- Sorting within categories works now correctly if SAML2 metadata is
used to generate Identity Provider drop-down list.
Thanks to Prof. Kazutsuna Yamaji
Informatics (NII) for reporting this issue.
- Fixed a minor bug in templates.php that cause PHP warnings to show up
in case an invalid IdP was stored in the cookie.
- Fixed a bug affecting the Kerberos authentication.
Thanks to Robert Basch for reporting these bugs and for
submitting patches.
- Fixed a bug where hidden IdPs would still be shown in Embedded WAYF
Issues: https://forge.switch.ch/redmine/projects/wayf/versions/17
SWITCHwayf Version History
--------------------------
* Version 1.18 - Release date: 5. August 2013
- Changed default SessionInitiator of the Embedded WAYF to
/Login because this has been the default SessionInitiator in
Shibboleth for quite some time now.
- Corrected viewport meta tag separator of default header as suggested
by Andrew Sokolov from Saint Petersburg State University
- Fixed a bug in the IdP preselection of the embedded wayf when
additional IdPs where added
- Removed as many SWITCH-specific graphics and texts as possible.
- Introduced configuration options to allow easier customization.
- Fixed a few small bugs
- Added some optimizations to the drop-down list search-as-you type
feature
- The log file now logs - if possible - also the SP entityID/providerId
- Some small styling changes/CSS improvements
- Added Japanese locales from the GakuNin version of the WAYF
Issues: <https://forge.switch.ch/redmine/projects/wayf/versions/62>
Please read the specific update instructions in the README file, as some
new configuration options were introduced that should be revised.
* Version 1.17.1 - Release date: 14. June 2012
- Fixed a bug occuring when wayf_sp_samlDSURL contains GET arguments
Bug reported with a patch by Takeshi Nishimura
- Fixed typo in configuration otpion useImprovedDropDownList
- Added Javascripts required for improved drop down list
Issues: <https://forge.switch.ch/redmine/projects/wayf/versions/55>
* Version 1.17 Release date: 18. May 2012
- Added CSS styles for mobile view
- Embedded WAYF now reads 'entityID' and 'return' GET arguments.
They get precedence over the values configured for the Embedded WAYF.
- Embedded WAYF logged in message now contains a link to target URL
Issues: <https://forge.switch.ch/redmine/projects/wayf/versions/45>
* Version 1.16 - Release date: 19. January 2012
- Added an improved version of the drop down list to the WAYF
Inspired by code from Takeshi Nishimura from NII (Japan)
Uses modified ImprovedDropdown JQuery library by John Fuex
See LICENSE file for further information
- Added cookieSecurity option to set and transmit cookies securely
Code contributed by Takeshi Nishimura from NII (Japan)
- Added additional data protection feature that uses the referer to
decide whether or not to preselect an Identity Provider in the
Embedded WAYF.
Code contributed by Takeshi Nishimura from NII (Japan)
- If the Discovery Feed feature is activated only those IdPs are shown
that are contained in the feed. Others will be hidden automatically.
- Added Keywords property to format of IDP entries to allow users to
search Identity Providers using a keyword.
Issues: <https://forge.switch.ch/redmine/projects/wayf/versions/40>
* Version 1.15 - Release date: 21. October 2011
- A default and custom CSS file can now be used
- Graphical design now is based new SWITCH harmos elements
- Adapted JSON output to use format used by Shibboleth SP
- Renamed some string keys to make them independent from SWITCH
**Please review the 'Specific Update Instructions' in the README file**
- Added support for the Shibboleth SP 2.4 Discovery Feed JSON output
in Embedded WAYF
- Focus on submit button works better with different browsers
- Invalid values for width and height are now defaulted to auto for
Embedded WAYF
- Fixed a URL composing bug that resulted in a wrong return URL to
the Service Provider if the return parameter did not contain any GET
arguments. Reported by Tom Scavo
- Made implementation behave according to the Discovery Service protocol
specification when it comes to the return parameter. This parameter
is optional in case the DS knows the SP Discovery URL.
Reported by Tom Scavo.
Issues: <https://forge.switch.ch/redmine/projects/wayf/versions/26>
* Version 1.14.3 - Release date: 4. March 2011
- Fixed a race condition.
Thanks go to Robert Basch for reporting the issue and providing a patch.
Issues: <https://forge.switch.ch/redmine/projects/wayf/versions/32>
* Version 1.14.2 - Release date: 15. December 2010
- IDProvider.conf.php and config.php are not overwritten anymore by upgrades
- Logging to syslog now works properly and is more consistent
- Access log now properly locks file
- Unknown category is not shown anymore when there is no other category
- Namespaces are now taken properly into account when parsing SAML2
metadata. Thanks go to Olivier Salaün for reporting this issue and
submitting a patch.
- Improved installation instructions
Issues: <https://forge.switch.ch/redmine/projects/wayf/versions/25>
* Version 1.14.1 - Release date: 12. November 2010
- Fixed an encoding bug that affected non-ASCII characters in JavaScripts.
Thanks to Prof. Kazutsuna Yamaji for reporting this issue.
- Corrected behaviour of $enableDSReturnParamCheck and
$useACURLsForReturnParamCheck. There won't be an error anymore if an SP
has no <idpdisc:DiscoveryResponse> extension defined. In such a case
there will only be a check if $useACURLsForReturnParamCheck is enabled.
- Fixed a bug in readMetadata.php that prevented CLI execution
- Changed the default configuration option to generate the Embedded WAYF
to false due to some concerns regarding phishing attacks
- Added proper copyright statements to all source code files
Issues: <https://forge.switch.ch/redmine/projects/wayf/versions/21>
* Version 1.14 - Release date: 9. November 2010
- Added the configuration option wayf_force_remember_for_session to
the Embedded WAYF on request of Wolgang Lierz. This
option allows setting the remember for session checkbox to true
- The 'return' parameter of a Discovery Service request can now be
checked using the idp-discovery-protocol extension or using the FQDN
of all the Service Provider's assertion consumer URLs. The latter
alternative is less secure but still offers better security against
phising attacks. Have a look at config.dist.php and the README for
more detailed explanations on these feature.
- Metadata parsing now uses DOM XML for PHP5 instead of Simple XML
- Fixed a minor HTML error in template for Embedded WAYF
- Sorting within categories works now correctly if SAML2 metadata is
used to generate Identity Provider drop-down list.
Thanks to Prof. Kazutsuna Yamaji for reporting this issue.
- Fixed a minor bug in templates.php that cause PHP warnings to show up
in case an invalid IdP was stored in the cookie.
- Fixed a bug affecting the Kerberos authentication.
Thanks to Robert Basch for reporting these bugs and for
submitting patches.
- Fixed a bug where hidden IdPs would still be shown in Embedded WAYF
Issues: <https://forge.switch.ch/redmine/projects/wayf/versions/17>
The revision history of older versions, can be found on the SWITCHwayf web page:
https://forge.switch.ch/redmine/projects/wayf/wiki/Changes
<https://forge.switch.ch/redmine/projects/wayf/wiki/Changes>
-------------------------------------------------------------------------------
Credits:
Credits
-------
Find below the list of people who have contributed to code, either because they
found bugs, suggested improvements or contributed code. Have a look at the
version history in order to see the individual contributions. The list is sorted
......
This diff is collapsed.
......@@ -2,19 +2,28 @@ Copyright (c) 2013, SWITCH - Serving Swiss Universities
See LICENSE file for details.
-------------------------------------------------------------------------------
SWITCHwayf
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 for this release of SWITCHwayf,
This document contains important information for this release of SWITCHwayf,
including the installation and update instructions.
* Version: 1.18
* Project web site: <https://forge.switch.ch/redmine/projects/wayf>
* Bug reports/feature requests: <https://forge.switch.ch/redmine/projects/wayf/issues>
* Contact: aai@switch.ch or go to <http://www.switch.ch/aai/wayf>
-------------------------------------------------------------------------------
Requirements:
**This document is written in the markdown syntax**
-------------------------------------------------------------------------------
Requirements
------------
- 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:
......@@ -23,13 +32,18 @@ Requirements:
* $metadataSPFile (default 'SProvider.metadata.conf.php')
* $metadataLockFile (default '/tmp/wayf_metadata.lock')
* $WAYFLogFile (default '/var/log/apache2/wayf.log')
-------------------------------------------------------------------------------
Download:
Download
--------
The latest release can be downloaded from:
https://forge.switch.ch/redmine/projects/wayf/files
<https://forge.switch.ch/redmine/projects/wayf/files>
Installation:
-------------------------------------------------------------------------------
Installation
------------
1. Unpack the SWITCHwayf_binary ${VERSION}_${DATE}.zip ZIP archive into a
directory on a host where Apache or IIS is installed.
......@@ -40,13 +54,13 @@ Installation:
This file contains the list of Identity Providers that that can be
configured by hand
3. Make sure that permissions for the files:
3. Enure 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.
permissions for them.
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.
......@@ -89,62 +103,83 @@ a2enmod headers
/etc/init.d/apache2 reload
--
See http://www.w3.org/P3P/ for more details on P3P.
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
<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.
Subversion access:
-------------------------------------------------------------------------------
Subversion access
-----------------
Check out the latest SWITHCHwayf code with:
svn co https://subversion.switch.ch/svn/general/aai/SWITCHwayf/
`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.
-------------------------------------------------------------------------------
General Update Instructions:
General Update Instructions
---------------------------
1. Make a backup of the directory where the currently active version of the
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 '
directory as the WAYF script of the currently deployed version.
Download from: <https://forge.switch.ch/redmine/projects/wayf/files>
3. Unzip the archive, e.g. with the command
'unzip -d #DD# SWITCHwayf_x.y_YYYYMMDD.zip '
This step will overwrite all files except those whose names start
with 'custom-'.
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.
4. Have a look at config.dist.php and compare this file with your current
config.php in order to identify new configuration options.
## Since version 1.18 the script 'update-config.php' can be used to
## merge an existing configuration (from config.php) with the default
## configuration (config.dist.php) into a new configuration file
## (config.new.php). This allows easily getting a clean configuration file
## while keeping the current settings. Run the script with:
## php update-config.php
## Ensure that the user has the necessary write privileges to create
> Since version 1.18 the script 'update-config.php' can be used to
> merge an existing configuration (from config.php) with the default
> configuration (config.dist.php) into a new configuration file
> (config.new.php). This allows easily getting a clean configuration file
> while keeping the current settings.
> Run the script with: `php update-config.php`
> Ensure that the user has the necessary write privileges to create the
> file config.new.php. Also note that all comments you might have
> added in the current.php will not be copied over.
Also compare the 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 a custom header file is missing these,
to load additional javascripts. If a custom header file is missing them,
the feature will not work.
5. If SAML2 metadata is used by SWITCHwayf, you might have to run the following
command to bootstrap the metadata reading process again.
$ php readMetadata.php
5. Ensure 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 them.
6. If SAML2 metadata is used by SWITCHwayf, you might have to run the following
command to bootstrap the metadata reading process again:
`php readMetadata.php`
-------------------------------------------------------------------------------
Specific Update Instructions:
Specific Update Instructions
----------------------------
Updates from versions before 1.18
* Updates from versions before 1.18
The following new configuration options were introduced:
- $supportContactEmail
......@@ -168,7 +203,7 @@ Updates from versions before 1.18
larger logo.
Updates from versions before 1.15
* 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'
......@@ -176,13 +211,13 @@ Updates from versions before 1.15
- 'switch_description' was renamed to 'additional_info'
Update from versions before 1.14.3:
* 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:
* 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
......@@ -191,10 +226,10 @@ Update from versions before 1.8:
-------------------------------------------------------------------------------
Security Notes:
Security Notes
--------------
The Discovery Service protocol as defined in
http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-idp-discovery.pdf
<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
......@@ -203,22 +238,23 @@ 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;
* $useSAML2Metadata = true;
and set the options:
enableDSReturnParamCheck = true;
* enableDSReturnParamCheck = true;
and potentially
$useACURLsForReturnParamCheck = true;
* $useACURLsForReturnParamCheck = true;
in case the metadata loaded by SWITCHwayf does not include DiscoveryResponse
elements for many Service Providers.
-------------------------------------------------------------------------------
Troubleshooting:
Troubleshooting
---------------
Generally, if there is an error or an exception, the WAYF will log it to syslog.
In case there is a problem and only a white page without any output is displayed,
open config.php in a text editor, go to the bottom of the file and set:
......@@ -229,7 +265,7 @@ This should output PHP warning messages which are otherwise supressed.
-------------------------------------------------------------------------------
Documentation:
Documentation
-------------
Consult the DOC file in the same directly as this file for further information
on configuring and customizing the SWITCHwayf.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment