simpleSAMLphp Advanced Features
===============================

<!-- 
	This file is written in Markdown syntax. 
	For more information about how to use the Markdown syntax, read here:
	http://daringfireball.net/projects/markdown/syntax
-->

  * Version: `$Id: simplesamlphp-advancedfeatures.txt 1136 2009-01-11 13:02:03Z andreassolberg@gmail.com $`


simpleSAMLphp documentation
---------------------------

This document is part of the simpleSAMLphp documentation suite.

- [List of all simpleSAMLphp documentation](http://rnd.feide.no/view/simplesamlphpdocs)


This document assumes that you already have a installation of
simpleSAMLphp running, configured and working. This is the next
step :)


Bridging between protocols
--------------------------

A bridge between two protocols is built using both an IdP and an
SP, connected together. To let a SAML 2.0 SP talk to a Shibboleth
IdP, you build a simpleSAMLphp bridge from a SAML 2.0 IdP and a
Shibboleth SP.The SAML 2.0 SP talks to the SAML 2.0 IdP, which
hands the request over to the Shibboleth 1.3 SP, which forwards it
to the Shibboleth IdP. This is configured in the IdP hosted
metadata, and is controlled by the `auth` and `authority`
parameters.

**Example&nbsp;1.&nbsp;Example of bridge configuration**

A bridge configured with a SAML 2.0 IdP and a Shibboleth 1.3 SP: In
the `saml20-idp-hosted.php` metadata you configure the
authentication to use Shibboleth 1.3 SP like this:

    'auth' => 'shib13/sp/initSSO.php',
    'authority' => 'shib13'

As no specific Shibboleth IdP is specified as parameter to the
`initSSO.php` script, the discovery service page will be shown. If
you want to connect the SAML 2.0 IdP to a specific Shibboleth 1.3
IdP, give the entity id as a parameter to the `initSSO.php`
script:

    'auth' => 'shib13/sp/initSSO.php?idpentityid=shib13idp.example.org',
    'authority' => 'shib13'


Attribute control
-----------------

Filtering, mapping, etc can be performed by using existing or create new *Authentication Processing Filters*. For more information, read:

  * [Authentication Processing Filters in SimpleSAMLphp](http://rnd.feide.no/content/authentication-processing-filters-simplesamlphp)



Automatic update of SAML 2.0 Metadata XML from HTTPS
----------------------------------------------------

simpleSAMLphp supports the SAML 2.0 Metadata XML format. There are mulitple ways of using simpleSAMLphp with SAML 2.0 Metadata XML documents, but the reccomended approach is to use the command line utility `bin/parseMetadata.php` to download and parse metadata from a HTTPS location. This script will grab the XML document from a URL and parse the content and output simpleSAMLphp flat files in a directory. In the `config.php` configuration you should configure simpleSAMLphp to read these files generated by `parseMetadata.php`.



Automated testing
-----------------

simpleSAMLphp includes a test script that can connect to a simpleSAMLphp SP, initiate login, enter some credentials. It then picks up the response to the SP and validates it, checking the output for expected attributes.

The intention of this script is to be run in system monitoring systems, like nagios or hobbit, to generate alerts when something breaks (e.g. a server is down or metadata misconfigured).

The test script is located in `bin/test.php`. The configuration file is located in `config/test.php`.

Documentation about configuration file format and more details about this test script will be added later. If you e.g. write a nagios plugin for this test script, let us know :) We will add a hobbit plugin and publish it somewhere pretty soon. Stay tuned!



Auth MemCookie
--------------

It is possible to integrate simpleSAMLphp with [Auth MemCookie](http://authmemcookie.sourceforge.net/). This allows you to integrate simpleSAMLphp with web applications written in another language than PHP.

Auth MemCookie works by reading authentication data from a memcache server and setting environment variables based on attributes in this data. It also allows you to use the default Apache access control features to restrict access to your site.

The simpleSAMLphp Auth MemCookie module can be found in `www/authmemcookie.php` and the configuration should be stored in `config/authmemcookie.php`. You may have to copy this file from `config-template/authmemcookie.php`.

To use Auth MemCookie, you need to do the following steps:

1.  Install and configure simpleSAMLphp for running as an SP.
2.  Install and configure a memcache server.
3.  Install and configure Auth MemCookie. Go to the
    [Auth MemCookie homepage](http://authmemcookie.sourceforge.net/)
    for downloads and installation instructions. The following example
    (from `extra/auth_memcookie.conf`) may be useful when configuring
    Auth MemCookie:

        <Location />
                # This is a list of memcache servers which Auth MemCookie
                # should use. It is a ','-separated list of
                # host:port-pairs.
                # Note that this list must list the same servers as the
                # 'authmemcookie.servers'-option in config.php in the
                # configuration for simpleSAMLphp.
                Auth_memCookie_Memcached_AddrPort "127.0.0.1:11211"
        
                # This must be set to 'on' to enable Auth MemCookie for
                # this directory.
                Auth_memCookie_Authoritative on
        
                # This adjusts the maximum number of data elements in the
                # session data. The default is 10, which can be to low.
                Auth_memCookie_SessionTableSize "40"
        
                # These two commands are required to enable access control
                # in Apache.
                AuthType Cookie
                AuthName "My Login"
        
                # This command causes apache to redirect to the given
                # URL when we receive a '401 Authorization Required'
                # error. We redirect to "/simplesaml/authmemcookie.php",
                # which initializes a login to the IdP.
                ErrorDocument 401 "/simplesaml/authmemcookie.php"
        
        </Location>
        
        <Location /secret>
                # This allows all authenticated users to access the
                # directory. To learn more about the 'Require' command,
                # please look at:
                # http://httpd.apache.org/docs/2.0/mod/core.html#require
                Require valid-user
        </Location>

4. 
    Configure the simpleSAMLphp Auth MemCookie module by editing
    `config/authmemcookie.php`. You must set the `username` option to a
    valid attribute name. All other can most likely be left at their
    default values.

5. 
    Enable the simpleSAMLphp Auth MemCookie module by setting
    `enable.authmemcookie` to *`true`* in `config/config.php`.

6. 
    To test the installation, you can add the following script as your
    `/secret/index.php` directory:

        <html><body><table>
        <?php
        foreach($_SERVER as $key=>$value) {
          echo('<tr><td>' . htmlspecialchars($key) . '</td><td>' . htmlspecialchars($value) . '</td></tr>');
        }
        ?>
        </table></body></html>

    You should now be able to go to `http://yourserver/secret/` to test
    the configuration. You should be redirected to your IdP, and after
    entering your username and password you should be taken back to
    `http://yourserver/secret/`. The resulting page should list all
    environment variables set by Apache, including the ones set by Auth
    MemCookie.




Metadata signing
----------------

simpleSAMLphp supports signing of the metadata it generates. Metadata signing is configured by four options:

- `metadata.sign.enable`: Whether metadata signing should be enabled or not. Set to `TRUE` to enable metadata signing. Defaults to `FALSE`.
- `metadata.sign.privatekey`: Name of the file with the private key which should be used to sign the metadata. This file must exist in in the `cert` directory.
- `metadata.sign.privatekey_pass`: Passphrase which should be used to open the private key. This parameter is optional, and should be left out if the private key is unencrypted.
- `metadata.sign.certificate`: Name of the file with the certificate which matches the private key. This file must exist in in the `cert` directory.

These options can be configured globally in the `config/config.php`-file, or per SP/IdP by adding them to the hosted metadata for the SP/IdP. The configuration in the metadata for the SP/IdP takes precedence over the global configuration.

There is also an additional fallback for the private key and the certificate. If `metadata.sign.privatekey` and `metadata.sign.certificate` isn't configured, simpleSAMLphp will use the `privatekey`, `privatekey_pass` and `certificate` options in the metadata for the SP/IdP.




Support
-------

If you need help to make this work, or want to discuss
simpleSAMLphp with other users of the software, you are fortunate:
Around simpleSAMLphp there is a great Open source community, and
you are welcome to join! The forums are open for you to ask
questions, contribute answers other further questions, request
improvements or contribute with code or plugins of your own.

-  [simpleSAMLphp homepage (at Feide RnD)](http://rnd.feide.no/simplesamlphp)
-  [List of all available simpleSAMLphp documentation](http://rnd.feide.no/view/simplesamlphpdocs)
-  [Join the simpleSAMLphp user's mailing list](http://rnd.feide.no/content/simplesamlphp-users-mailinglist)
-  [Visit and contribute to the simpleSAMLphp wiki](https://ow.feide.no/simplesamlphp:start)




