Skip to content
Snippets Groups Projects
Commit 0033a24a authored by Jaime Pérez Crespo's avatar Jaime Pérez Crespo
Browse files

Removing the simplesamlphp-ukaccess page in documentation. Improving docs on... 

Removing the simplesamlphp-ukaccess page in documentation. Improving docs on automated metadata management. Issue #608.

git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@3334 44740490-163a-0410-bde0-09ae8108e29a
parent 74f1033f
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/index.txt
+ 0
− 1
View file @ 0033a24a
......@@ -14,7 +14,6 @@ SimpleSAMLphp Documentation
* [Using simpleSAMLphp as a SAML Service Provider](simplesamlphp-sp)
* [Hosted SP Configuration Reference](./saml:sp)
* [IdP remote reference](simplesamlphp-reference-idp-remote)
* [Connecting SimpleSAMLphp as a SP to UK Access Federation or InCommon](simplesamlphp-ukaccess)
* [Upgrading - migration to use the SAML authentication source](simplesamlphp-sp-migration)
* [Configuring HTTP-Artifact](./simplesamlphp-artifact-sp)
* [Using scoping](./simplesamlphp-scoping)
......
docs/simplesamlphp-automated_metadata.txt
+ 112
− 107
View file @ 0033a24a
......@@ -14,11 +14,11 @@ Automated Metadata Management
Introduction
------------
If you want to connect an Identity Provider, or a Service Provider to a **federation**, you need to setup metadata for the entries that you trust. In many federation, in particular federations based upon the Shibboleth software, it is normal to setup automated distributed metadata using the SAML 2.0 Metadata XML Format.
If you want to connect an Identity Provider, or a Service Provider to a **federation**, you need to setup metadata for the entries that you trust. In many federations, in particular federations based upon the Shibboleth software, it is normal to setup automated distribution of metadata using the SAML 2.0 Metadata XML Format.
Some central administration or authority, provides a URL with a SAML 2.0 document including metadata for all entities in the federation.
This document explains how to setup automated downloading and parsing of a metadata document on a specific URL.
The present document explains how to setup automated downloading and parsing of a metadata document on a specific URL.
......@@ -30,11 +30,11 @@ You need to enable the following modules:
1. cron
2. metarefresh
The cron module allows you to do tasks regularly, by setting up a cronjob that calls a hook in simpleSAMLphp.
The cron module allows you to do tasks regularly, by setting up a cron job that calls a hook in simpleSAMLphp.
The metarefresh module will download and parse the metadata document and store it in cached local metadata files.
The metarefresh module will download and parse the metadata document and store it in metadata files cached locally.
You also need to copy the `config-templates` files from the two modules above, into the global `config/` directory.
First, you will need to copy the `config-templates` files of the two modules above into the global `config/` directory.
[root@simplesamlphp] cd /var/simplesamlphp
[root@simplesamlphp simplesamlphp] touch modules/cron/enable
......@@ -44,69 +44,17 @@ You also need to copy the `config-templates` files from the two modules above, i
Testing to parse the metadata document
--------------------------------------
Testing it manually
-------------------
We'll use the SWITCH AAI Test Federation as an example in this document. This federation provides metadata on this URL:
http://metadata.aai.switch.ch/metadata.aaitest.xml
I reccomend to first test on the command line to parse the metadata URL.
It is often useful to verify that the metadata sources we want to use can be parsed and verified by metarefresh, before actually
configuring it. We can do so in the command line, by invoking metarefresh with the URL of the metadata set we want to check. For
instance, if we want to configure the metadata of the SWITCH AAI Test Federation:
cd modules/metarefresh/bin
./metarefresh.php -s http://metadata.aai.switch.ch/metadata.aaitest.xml
We use the `-s` option to send output to console (for testing purposes). If the output makes sense, continue. If you get a lot of error messages, send an e-mail to the simpleSAMLphp list and ask for advice.
Below is the documentation provided by Nuno Gonçalves <nuno@fccn.pt>
Configuring the cron module
---------------------------
At `/var/simplesamlphp/config`
[root@simplesamlphp-teste config]# vi module_cron.php
edit:
$config = array (
'key' => 'kb10fu2sao',
'allowed_tags' => array('daily', 'hourly', 'frequent'),
'debug_message' => TRUE,
'sendemail' => TRUE,
);
Then: With your browser go to => https://simplesamlphp_machine/simplesaml/module.php/cron/croninfo.php
And copy the cron's sugestion:
-------------------------------------------------------------------------------------------------------------------
Cron is a way to run things regularly on unix systems.
Here is a suggestion for a crontab file:
# Run cron [daily]
02 0 * * * curl --silent "https://simplesamlphp-teste.fccn.pt/simplesaml/module.php/cron/cron.php?key=kb10fu2sao&tag=daily" > /dev/null 2>&1
# Run cron [hourly]
01 * * * * curl --silent "https://simplesamlphp-teste.fccn.pt/simplesaml/module.php/cron/cron.php?key=kb10fu2sao&tag=hourly" > /dev/null 2>&1
# Run cron [frequent]
XXXXXXXXXX curl --silent "https://simplesamlphp-teste.fccn.pt/simplesaml/module.php/cron/cron.php?key=kb10fu2sao&tag=frequent" > /dev/null 2>&1
Click here to run the cron jobs:
Run cron [daily]
Run cron [hourly]
Run cron [frequent]
-------------------------------------------------------------------------------------------------------------------
Add to CRON with
[root@simplesamlphp config]# crontab -e
The `-s` option sends the output to the console (for testing purposes). If the output makes sense, continue. If you get a lot of error messages, try to read them and fix the problems that might be causing them. If you are having problems and you can't figure out the cause, you can always send an e-mail to the simpleSAMLphp mailing list and ask for advice.
......@@ -114,53 +62,62 @@ Configuring the metarefresh module
----------------------------------
At `/var/simplesamlphp/config/`
Now we are going to proceed to configure the metarefresh module. First, edit the appropriate configuration file:
[root@simplesamlphp config]# vi config-metarefresh.php
edit:
[root@simplesamlphp simplesamlphp]# vi config/config-metarefresh.php
$config = array( 'sets' => array(
Here's an example of a possible configuration for both the Kalmar Federation and UK Access Management Federation:
'kalmar' => array(
'cron' => array('hourly'),
'sources' => array(
array(
'src' => 'https://kalmar.feide.no/simplesaml/module.php/aggregator/?id=kalmarcentral&mimetype=text/plain&exclude=norway',
'validateFingerprint' => '591d4b4670463eeda91fcc816dc0af2a092aa801',
'template' => array(
'tags' => array('kalmar'),
'authproc' => array(
51 => array('class' => 'core:AttributeMap', 'oid2name'),
$config = array(
'sets' => array(
'kalmar' => array(
'cron' => array('hourly'),
'sources' => array(
array(
'src' => 'https://kalmar.feide.no/simplesaml/module.php/aggregator/?id=kalmarcentral&mimetype=text/plain&exclude=norway',
'validateFingerprint' => '591d4b4670463eeda91fcc816dc0af2a092aa801',
'template' => array(
'tags' => array('kalmar'),
'authproc' => array(
51 => array('class' => 'core:AttributeMap', 'oid2name'),
),
),
),
),
'expireAfter' => 60*60*24*4, // Maximum 4 days cache time.
'outputDir' => 'metadata/metarefresh-kalmar/',
'outputFormat' => 'flatfile',
),
'expireAfter' => 60*60*24*4, // Maximum 4 days cache time.
'outputDir' => 'metadata/federation/',
/*
* Which output format the metadata should be saved as.
* Can be 'flatfile' or 'serialize'. 'flatfile' is the default.
*/
'outputFormat' => 'flatfile',
),
));
'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',
),
)
);
TEMPLATE FILE : /var/simplesamlphp/modules/metarefresh/config-templates/config-metarefresh.php
The configuration consists of one or more metadata sets. Each metadata set has its own configuration, representing a metadata set of sources.
Some federations will provide you with detailed instructions on how to configure metarefresh to fetch their metadata automatically, like,
for instance, [the InCommon federation in the US](https://spaces.internet2.edu/x/eYHFAg). Whenever a federation provides you with specific
instructions to configure metarefresh, be sure to use them from the authoritative source.
The configuration consists of one or more metadata sets. Each metadata
set has its own configuration. The following options are available:
The metarefresh module supports the following configuration options:
`cron`
: Which of the cron tags will refresh this metadata set.
: Which cron tags will refresh this metadata set.
`sources`
: An array of metadata sources which will be included in this
metadata set. The contents of this option will be described in more
detail later.
: An array of metadata sources that will be included in this
metadata set. The contents of this option will be described later in more detail.
`expireAfter`
: The maximum number of seconds a metadata entry will be valid.
......@@ -184,28 +141,76 @@ Each metadata source has the following options:
on the metadata.
`template`
: This is an array which will be combined with the fetched metadata to
: This is an array which will be combined with the metadata fetched to
generate the final metadata array.
After you have configured the metadata source, you need to give the
web-server write access to the output directory. Depending on the
platform, this may be done by a command similar to:
After you have configured the metadata sources, you need to give the
web-server write access to the output directories. Following the previous example:
chown www-data /var/simplesamlphp/metadata/metadata-federation/
chown www-data /var/simplesamlphp/metadata/metarefresh-kalmar/
chown www-data /var/simplesamlphp/metadata/metarefresh-ukaccess/
Then configure your simpleSAMLphp installation to use the generated metadata:
In config.php:
Now you can configure simpleSAMLphp to use the metadata fetched by metarefresh. Edit the main
config.php file, and modify the `metadata.sources` directive accordingly:
'metadata.sources' => array(
array('type' => 'flatfile'),
array('type' => 'flatfile', 'directory' => 'metadata/federation'),
array('type' => 'flatfile', 'directory' => 'metadata/metarefresh-kalmar'),
array('type' => 'serialize', 'directory' => 'metadata/metarefresh-ukaccess'),
),
Remember that the `type` parameter here must match the `outputFormat` in the configuration of the module.
Configuring the cron module
---------------------------
Once we have configured metarefresh, we can edit the configuration file for the cron module:
[root@simplesamlphp simplesamlphp]# vi config/module_cron.php
The configuration should look similar to this:
$config = array (
'key' => 'RANDOM_KEY',
'allowed_tags' => array('daily', 'hourly', 'frequent'),
'debug_message' => TRUE,
'sendemail' => TRUE,
);
Bear in mind that the key is used as a security feature, to restrict access to your cron. Therefore, you need to make sure that the string here is a random key available to no one but you. Additionally, make sure that you include here the appropriate tags that you previously told metarefresh
to use in the `cron` directive.
Next, use your web browser to go to `https://YOUR_SERVER/simplesaml/module.php/cron/croninfo.php`. Make sure to properly set your server's address, as well as use HTTP or HTTPS accordingly, and also to specify the correct path to the root of your simpleSAMLphp installation.
Now, copy the cron configuration suggested:
# Run cron [daily]
02 0 * * * curl --silent "https://YOUR_SERVER/simplesaml/module.php/cron/cron.php?key=RANDOM_KEY&tag=daily" > /dev/null 2>&1
# Run cron [hourly]
01 * * * * curl --silent "https://YOUR_SERVER/simplesaml/module.php/cron/cron.php?key=RANDOM_KEY&tag=hourly" > /dev/null 2>&1
Finally, add it to your crontab by going back to the terminal, and editing with:
[root@simplesamlphp config]# crontab -e
This will open up your favourite editor. If an editor different than the one you use normally appears, exit, and configure the `EDITOR` variable
to tell the command line which editor it should use:
[root@simplesamlphp config]# export EDITOR=emacs
If you want to force the metadata to be refreshed manually, you can do so by going back to the cron page in the web interface. Then, just follow
the appropriate links to execute the cron jobs you want. The page will take a while loading, and eventually show a blank page. It is so because
the commands are intended to be run from cron, and therefore they produce no output. If this operation seems to run fine, navigate to the **SimpleSAMLphp Front page** › **Federation**. Here you will see a list of all the Identity Providers trusted. They will be listed with information about the maximum duration of their cached version, such as *(expires in 96.0 hours)*.
Metadata cacheDuration
----------------------
Metadata duration
-----------------
SAML metadata may supply a cacheDuration attribute which indicates the maxium time to cache metadata. Because this module is run from cron, it cannot influence how often it is run and enfore this attribute by itself. Take care that you run metarefresh from cron at least as often as the shortest cacheDuration in your metadata sources.
SAML metadata may supply a `cacheDuration` attribute which indicates the maximum time to keep metadata cached. Because this module is run from cron, it cannot decide how often it is run and enforce this duration on its own. Make sure to run metarefresh from cron at least as often as the shortest `cacheDuration` in your metadata sources.
docs/simplesamlphp-sp.txt
+ 10
− 1
View file @ 0033a24a
......@@ -130,11 +130,15 @@ The textfields for AssertionConsumerService and SingleLogoutService should conta
After checking your metadata, give your SP a proper name and description and click 'save'.
The procedure for managing trust in federations differ, but the common part is that you would need to provide the *SAML 2.0 metadata
of your SP*, and register that with the federation administration.
Test the SP
-----------------------------
After the metadata is is configured on the IdP, you should be able to test the configuration.
After the metadata is configured on the IdP, you should be able to test the configuration.
The installation page of simpleSAMLphp has a link to test authentication sources.
When you click the link, you should receive a list of authentication sources, including the one you have created for the SP.
......@@ -144,6 +148,11 @@ The test page should contain a list of your attributes:
![Screenshot of the status page after an user have succesfully authenticated](http://rnd.feide.no/files/screenshot-example.png)
For a better looking, more advanced Discovery Service with tabs and live search, you may want to use the `discopower` module
in simpleSAMLphp. Take a look at the following blog entry for more information:
* [Blog entry about the DiscoPower module](https://rnd.feide.no/content/improved-discovery-service-live-search)
Integrating authentication with your own application
----------------------------------------------------
......
docs/simplesamlphp-ukaccess.txt deleted 100644 → 0
+ 0
− 195
View file @ 74f1033f
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$`
<!-- {{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.
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