196 lines
9.4 KiB
Plaintext
196 lines
9.4 KiB
Plaintext
Connecting SimpleSAMLphp SP to UK Access Federation and InCommon
|
||
================================================================
|
||
|
||
<!--
|
||
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-ukaccess.txt 3126 2012-06-28 08:39:33Z olavmrk $`
|
||
|
||
<!-- {{TOC}} -->
|
||
|
||
This guide will describe how to configure simpleSAMLphp as a service provider (SP) supporting SAML 1.1 (shib1.3) and SAML 2.0 connecting it to a federation such as **UK Access Federation** or **InCommon**.
|
||
|
||
You should previously have installed simpleSAMLphp as described in [the simpleSAMLphp installation instructions](simplesamlphp-install).
|
||
|
||
|
||
Configuring the SP
|
||
------------------
|
||
|
||
The SP is configured by an entry in `config/authsources.php`. If you copy the `authsources.php` configuration from `config-templates`, it contains a decent default setup.
|
||
|
||
Further details on configuring an SP:
|
||
|
||
* [Service Provider QuickStart](simplesamlphp-sp)
|
||
* [Configuration Reference](./saml:sp)
|
||
|
||
### Enabling a certificate for your Service Provider
|
||
|
||
UK Access Federation and InCommon probably requires that you enable a certificate for your SP. Other federations do not always require that you do.
|
||
|
||
If you enable a certificate for your Service Provider, it may be able to sign requests and response sent to the Identity Provider, as well as receiving encrypted responses.
|
||
|
||
Create a self-signed certificate in the `cert/` directory.
|
||
|
||
cd cert
|
||
openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem
|
||
|
||
|
||
Then edit your `authsources.php` entry, and add references to your certificate:
|
||
|
||
'default-sp' => array(
|
||
'saml:SP',
|
||
'privatekey' => 'saml.pem',
|
||
'certificate' => 'saml.crt',
|
||
),
|
||
|
||
|
||
|
||
Consuming Federation Metadata
|
||
-----------------------------
|
||
|
||
In order to enable the functionality to automatically download and parse metadata from a remote URL, enable the `metarefresh` and `cron` modules:
|
||
|
||
touch modules/metarefresh/enable
|
||
cp modules/metarefresh/config-templates/*.php config/
|
||
touch modules/cron/enable
|
||
cp modules/cron/config-templates/*.php config/
|
||
|
||
Create a directory to cache the downloaded federation metadata:
|
||
|
||
mkdir metadata/metarefresh-ukaccess
|
||
chmod go+rw metadata/metarefresh-ukaccess
|
||
|
||
The module `metarefresh` is responsible for getting metadata from a preconfigured URL, and then parse and validate it and cache it for use with the SAML SP module.
|
||
|
||
Edit the `config/config-metarefresh.php`:
|
||
|
||
|
||
<?php
|
||
$config = array(
|
||
'sets' => array(
|
||
'uk' => array(
|
||
'cron' => array('hourly'),
|
||
'sources' => array(
|
||
array(
|
||
'src' => 'http://metadata.ukfederation.org.uk/ukfederation-metadata.xml',
|
||
'validateFingerprint' => 'D0:E8:40:25:F0:B1:2A:CC:74:22:ED:C3:87:04:BC:29:BB:7B:9A:40',
|
||
),
|
||
),
|
||
'expireAfter' => 60*60*24*4, // Maximum 4 days cache time.
|
||
'outputDir' => 'metadata/metarefresh-ukaccess/',
|
||
'outputFormat' => 'serialize',
|
||
),
|
||
),
|
||
);
|
||
|
||
The example above is from **UK Access Federation**. If you instead would like to get metadata from **InCommon**, use the following URL and fingerprint:
|
||
|
||
'src' => 'http://wayf.incommonfederation.org/InCommon/InCommon-metadata.xml',
|
||
'validateFingerprint' => '74278f967cf1bfcaaa1b41afb6336448a2150eb4',
|
||
|
||
|
||
* [Updated information about access endpoints and trust anchors for InCommon](http://www.incommonfederation.org/metadata.html)
|
||
|
||
|
||
Notice that the configuration points the `outputDir` to the directory we created earlier. Now, we configure the SAML SP to use the cached `outputDir` as one of its metadata sources. Edit `config.php`:
|
||
|
||
'metadata.sources' => array(
|
||
array('type' => 'flatfile'),
|
||
array('type' => 'serialize', 'directory' => 'metadata/metarefresh-ukaccess'),
|
||
),
|
||
|
||
Now, go to the frontpage of your simpleSAMLphp installation, and:
|
||
|
||
1. **Configuration** › **Cron module information page**.
|
||
2. You then would need to enter that admin password that you did set in `config.php` during installation.
|
||
3. **Run cron [hourly]**
|
||
|
||
Then the page should load for a while and show no errors, only a white page. (These URLs are meant to run from *cron*, hence no output). If this operation seems to run fine, navigate to the **SimpleSAMLphp Front page** › **Federation**. Here you should see a list of all trusted Identity Providers. The Identity Providers that are downloaded are listed with information about the valid cache duration, such as *(expires in 96.0 hours)*.
|
||
|
||
For more details on how to configure automated metadata:
|
||
|
||
* [Automated Metadata Management](simplesamlphp-automated_metadata)
|
||
|
||
For information on how to configure *remote metadata* manually (possibly in combination with automated metadata as described here):
|
||
|
||
* [Service Provider QuickStart](simplesamlphp-sp)
|
||
|
||
|
||
|
||
|
||
|
||
Exchange metadata with the Federation
|
||
-------------------------------------
|
||
|
||
In order to connect your Service Provider to the IdPs of the federations, the IdPs will need to trust your Service Provider. The prodecure for managing trust in federations differ, but the common part is that you would need to prepare *SAML 2.0 metadata for your SP*, and register that with the federation administration.
|
||
|
||
SimpleSAMLphp will automatically suggest metadata for your SP. Go to the **SimpleSAMLphp Front page** › **Federation**. Here you will see an entry with *SAML 2.0 SP Metadata*. If you follow the link **[ Show metadata ]**, you will see a page listing metadata for your entity. You may copy and paste the SAML 2.0 metadata document, or send a link to this page to the federation administration.
|
||
|
||
|
||
|
||
Test the SP
|
||
-----------
|
||
|
||
After the metadata is is configured on the IdP, you should be able to test your SP.
|
||
|
||
Go to the **SimpleSAMLphp Front Page** › **Authentication** › **Test configured authentication sources**. You will then see a list of authentication sources that you may test. Select the authentication source ID for your SAML 2.0 SP. If you have not modified the `authsources.php` template, the ID is `default-sp`. When you click that link you should see a discovery service list of all Identity Providers.
|
||
|
||
For a better looking more advanced Discovery Service with tabs and live search, you should use the `discopower` module in simpleSAMLphp that is part of the official simpleSAMLphp release.
|
||
|
||
* [Blog entry about the DiscoPower module](https://rnd.feide.no/content/improved-discovery-service-live-search)
|
||
* Dedicated documentation for DiscoPower module, TBD.
|
||
|
||
|
||
Integrating authentication with your own application
|
||
----------------------------------------------------
|
||
|
||
|
||
* [Service Provider QuickStart](simplesamlphp-sp)
|
||
|
||
|
||
Caveat
|
||
------
|
||
|
||
In federations like UK Access Federations different aspects of the SAML protocol is in use, and here follows some information about what should work with SimpleSAMLphp and what will not work.
|
||
|
||
SimpleSAMLphp SP supports *SAML 1.1*, compatible with Shibboleth 1.3:
|
||
|
||
* SimpleSAMLphp supports Shibboleth Binding for authentication request.
|
||
* SimpleSAMLphp does not support SAML 1.1 Attribute Queries, but it supports attribute push (embedded attributes in Response).
|
||
* SimpleSAMLphp supports SAML 1.1 Artifact Binding for Response.
|
||
|
||
SimpleSAMLphp SP supports *SAML 2.0*, compatible with Shibboleth 2.X:
|
||
|
||
* SimpleSAMLphp uses the SAML 2.0 HTTP-REDIRECT binding for authentication request.
|
||
* SimpleSAMLphp by default sends unsigned authentication request, may be enabled by configuring a certificate.
|
||
* SimpleSAMLphp supports the SAML 2.0 HTTP-POST binding for Response.
|
||
* SimpleSAMLphp does not support the SAML 2.0 Artifact binding for Response. Estimated to be available in SimpleSAMLphp 1.6.
|
||
* SimpleSAMLphp supports SAML 2.0 Attribute Queries, but these are not sent automatically during SSO.
|
||
* SimpleSAMLphp supports receiving and decrypting EncryptedAssertions.
|
||
* SimpleSAMLphp supports receiving and decrypting NameID, as enabled by default by Shibboleth 2.0 - 2.1.
|
||
* SimpleSAMLphp supports SAML 2.0 Single Logout Profile using HTTP-REDIRECT binding. Warning: not yet supported by Shibboleth 2.x IdP.
|
||
|
||
**Important about certificates**: SimpleSAMLphp as an SP requires that Identity Providers have embedded certificates in metadata. Most federations use emebedded certificates, and others are migrating to use embedded certificates. Some federations though are using PKI, relying on a list of trusted CAs and no embedded certificates in metadata - this setup is *not* supported by simpleSAMLphp.
|
||
|
||
|
||
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://simplesamlphp.org/docs/)
|
||
- [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)
|
||
|
||
More information about the federations:
|
||
|
||
- [UK Access Federation](http://www.ukfederation.org.uk/)
|
||
- [InCommon](http://www.incommonfederation.org/)
|
||
|
||
If your questions are not related to simpleSAMLphp, but instead procedures on how to deal with a specific federation, visit the support channels specific for that federation.
|
||
|