# CONTENTS
* Summary
* Checklist
* Installation
* Contact

# SUMMARY
SURFconext Drupal module enables federated authentication on the SURFcontext
service based on the SAML standard. It does not, however, replace the Drupal
login like other SimpleSAML modules.

# CHECKLIST
1. SURFconext Drupal module (http://drupal.org/surfconext). This is the Drupal module that will enable SURFcontext logins.
2. SimpleSAMLphp library. Download the 3rdparty SimpleSAMLphp library (http://simplesamlphp.org/download). We have tested our software with SimpleSAMLphp v1.8.x and v1.9.
3. SURFconext certificates. You need to apply for SP (Service Provider) to connect to the SURFconext infrastructure. For more information, send email to [email protected] or visit https://wiki.surfnetlabs.nl/display/surfconextdev/


# INSTALLATION
1. Install SimpleSAMLphp library. The SimpleSAMLphp can not use phpsessions for its session storage, as it will conflict with the Drupal sessions. One of the alternatives is SQL or memcache.
Its wise to test the SimpleSAML login before continuing installing the Drupal module.
For more information; http://simplesamlphp.org/docs/1.8/simplesamlphp-install
For technical information to install and test SURFconext, look under section 'Setting up an SP' on page
https://wiki.surfnetlabs.nl/display/surfconextdev/My+First+SP+-+PHP

2. Setup a working Drupal 7 website.
For more information; http://drupal.org/start.
Make sure you enable the cron functionality of Drupal, as regular cron runs are required by the module.

3. Setup private files under Drupal file system. We need the private storage for file under Drupal for storing our generated metadata file.
See page http://your.drupal.install/admin/config/media/file-system
Configure the 'Private file system path', default value is 'sites/default/files/private'. You can also setup this directory under '/var/private' (or any other location) as long Drupal has write access.

4. Enable the Drupal module.
Enabling the module does *not* activate the SimpleSAML login.

5. Configure the module.
See page http://your.drupal.install/admin/config/people/surfconext
The default settings should work fine. Do *not* turn on the master switch yet.

6. Check the Drupal status page.
See page http://your.drupal.install/admin/reports/status
There should be no RED parts on your status page.

7. The metadata file generated by Drupal is stored at the location specified in
the configuration form of step 5, under section 'SURFconext IdP metadata file
location'. By default this path will translate to 'sites/default/files/private/saml20-idp-remote.php'. This directory will be protected against download by Drupal; it will create a .htaccess file. However, remember that apache will use this file, other webservers like nginx will not. If you use other webservers than Apache, please make sure that this directory is protected again download / listing. Other solution is putting the metadata file in another directory where your webserver can read/write to which is
outside the webroot. To let SimpleSAMLphp library able to access this file, create an symbolic link
to the file. Location of the link should be /var/simplesamlphp/metadata/saml20-idp-remote.php and must replace the existing file 'saml20-idp-remote.php' at /var/simplesamlphp/metadata/.

8. Enable the login.
You can enable the login on the SURFconext configuration page (at the bottom).

9. Test the login.
See page http://your.drupal.install/user/login/surfconext

# TROUBLESHOOTING

# FAQ

# CONTACT
Current maintainers:
* Robert Blanker - http://drupal.org/user/1980740

Official website:
http://www.surfconext.nl (Dutch / English)


# Copyright
Copyright (C) 2012 SURFnet BV (http://www.surfnet.nl)

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, you can find it at:
http://www.gnu.org/licenses/old-licenses/gpl-2.0.html