diff --git a/docs/simplesamlphp-sp.txt b/docs/simplesamlphp-sp.txt
new file mode 100644
index 0000000000000000000000000000000000000000..98cdcc397e4ad7d5a4d0ee1a713e30f9c7001140
--- /dev/null
+++ b/docs/simplesamlphp-sp.txt
@@ -0,0 +1,754 @@
+Theming the user interface in SimpleSAMLphp
+===========================================
+
+<!--
+ 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 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. Before you continue make sure all the required
+entries in the check list at the buttom is showing green light.
+
+Introduction
+------------
+
+simpleSAMLphp can run as both a SAML 2.0 Service Provider and as a
+Shibboleth 1.3 Service Provider. Although the configuration is
+similar for the two alternatives, there are some differences in
+configuration and metadata differs somewhat, so they are treated in
+separate chapters.
+
+Selecting the desired Service Provider functionality
+----------------------------------------------------
+
+Your identity provider (IdP) may offer user authentication either
+using the SAML 2.0 protocol, or the older Shibboleth 1.3 protocol.
+
+SAML 2.0 SP functionality is enabled by default. If this is what
+you want to use, leave the default configuration unmodified.
+
+To setup a Shibboleth 1.3 SP, you must disable SAML 2.0 SP and
+enable Shib 1.3 SP in `config.php`:
+
+ 'enable.saml20-sp' => false,
+ 'enable.saml20-idp' => false,
+ 'enable.shib13-sp' => true,
+ 'enable.shib13-idp' => false,
+
+Configuring metadata for SAML 2.0 SP
+------------------------------------
+
+To set up a SAML 2.0 SP, configure two metadata files:
+`saml20-sp-hosted.php` and `saml20-idp-remote.php`. The former
+represents the SAML entity of your SP, the latter lists all the
+SAML 2.0 IdPs you trust to authenticate users, and how to connect
+to them.
+
+## Configuring SAML 2.0 SP Hosted metadata
+
+To se tup these metadata, you must know the host name of your web
+server, and select an entity ID for this server. The IdP may impose
+restrictions on your choice of entity ID.
+
+
+**Example 1. Example of metadata for hosted SAML 2.0 SP**
+
+Here is an example of the metadata file:
+
+ /*
+ * Example of a hosted SP
+ */
+ 'sp-entityid' => array(
+ 'host' => 'sp.example.org'
+ )
+
+**Example 2. Real life example**
+
+Here is a real life example from Feide:
+
+ 'urn:mace:feide.no:services:no.feide.foodle' => array(
+ 'host' => 'foodle.feide.no',
+ ),
+
+Here the service run on the host `foodle.feide.no` and have the
+entity ID `urn:mace:feide.no:services:no.feide.foodle`.
+
+You may add any number of SP definitions in the same installation
+of simpleSAMLphp. simpleSAMLphp will discover automatically which
+configuration to use in a specific scenario, by mapping current
+hostname in the URL sent by the end user client to the `host` entry
+in the metadata.
+
+Below is a description of mandatory and optional fields in the SAML
+2.0 SP hosted metadata.
+
+### Mandatory metadata fields
+
+These metadata fields are required:
+
+index in the `$metadata` array
+: The entity ID of the hosted SP entity.
+
+: simpleSAMLphp supports dynamic entityIDs that matches a URL
+ where simpleSAMLphp automatically generates metadata for the hosted
+ entity. To enable this functionality, set the index to be
+ `__DYNAMIC:1__`. The index needs to be unique, so when you have
+ multiple entries, increase the integer after the colon. When the
+ index `__DYNAMIC:1__` is used, the resulting generated entity
+ becomes something like:
+
+: https://sp.example.org/simplesaml/saml2/sp/metadata.php
+
+host
+: Host name of the server running this SP. One of your metadata
+ entries can have the value `__DEFAULT__`. A default entry will be
+ used when no other entry matches the current hostname.
+
+
+### Optional metadata fields
+
+These fields can be left out if not needed.
+
+NameIDFormat
+: The NameIDFormat in the request. If you don't know what this
+ is, or do not require a specific format, leave the default value
+ unmodified.
+
+: If you leave out this entry, the default value
+ `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` is used in
+ the authentication request. If you set the value to `null`, the
+ `samlp:NameIDPolicy` element is completely removed from the
+ request.
+
+ForceAuthn
+: Force authentication allows you to force re-authentication of
+ users even if the user has a SSO session at the IdP.
+
+AuthnContextClassRef
+: The SP can request authentication with a specific
+ authentication context class. One example of usage could be if the
+ IdP supports both username/password authentication as well as
+ software-PKI.
+
+attributemap
+: Mapping table for translating attribute names. For further
+ information, see the *Advances Features* document.
+
+attributealter
+: Table of custom functions that injects or modifies attributes.
+ For further information, see the *Advances Features* document.
+
+attributes
+: Array of attributes sent to the SP. If this field is not set,
+ the SP receives all attributes available at the IdP.
+
+IsPassive
+: IsPassive allows you to enable passive authentication by
+ default for this SP.
+
+AssertionConsumerService
+: Override the default URL for the AssertionConsumerService for
+ this SP. This is an absolute URL. The default value is
+ `<simpleSAMLphp-root>/saml2/sp/AssertionConsumerService.php`
+
+: Note that this only changes the values in the generated
+ metadata and in the messages sent to others. You must also
+ configure your webserver to deliver this URL to the correct PHP
+ page.
+
+SingleLogoutService
+: Override the default URL for the SingleLogoutService for this
+ SP. This is an absolute URL. The default value is
+ `<simpleSAMLphp-root>/saml2/sp/SingleLogoutService.php`
+
+: Note that this only changes the values in the generated
+ metadata and in the messages sent to others. You must also
+ configure your webserver to deliver this URL to the correct PHP
+ page.
+
+idpdisco.url
+: Set which IdP discovery service this SP should use. If this is
+ unset, the IdP discovery service specified in the global option
+ `idpdisco.url.saml20` in `config/config.php` will be used. If that
+ one is also unset, the builtin default discovery service will be
+ used.
+
+privatekey
+: File name of private key to be used for signing messages.
+
+certificate
+: File name of certificate corresponding to the private key. This
+ certificate will be included in generated metadata.
+
+privatekey\_pass
+: Optional field with the passphrase for the private key.
+
+
+### Fields for signing and validating messages
+
+simpleSAMLphp only signs authentication responses by default.
+Signing of authentication requests, logout requests and logout
+responses can be enabled by setting the `redirect.sign` option.
+Validation of received messages can be enabled by the
+`redirect.validate` option. Note that if you want to sign messages,
+you will need a keypair/certificate at the SP.
+
+These options set the default for this SP, but options for each IdP
+can be set in `saml20-idp-remote`.
+
+redirect.sign
+: Boolean, default `false`. To turn on signing of authentication
+ requests, logout requests and logout responses, set this flag to
+ true.
+
+: This option can be overridden by the `redirect.sign` option in
+ `saml20-idp-remote`.
+
+redirect.validate
+: Boolean, default `false`. To turn on validation of received
+ logout requests and logout responses, set this flag to true.
+
+: This option can be overridden by the `redirect.validate` option
+ in `saml20-idp-remote`.
+
+
+**Example 3. Example of configured signed messages**
+
+ 'redirect.sign' => true,
+ 'privatekey' => 'server.pem',
+
+
+## Configuring SAML 2.0 IdP Remote metadata
+
+
+The metadata file `saml20-idp-remote.php` represent the SAML 2.0
+IdPs that your service provider trust to authenticate users of your
+service.
+
+**Example 4. Example of metadata for trusted remote SAML 2.0 IdP**
+
+Here is an example of a metadata entry for a remote trusted IdP:
+
+ /*
+ * Example simpleSAMLphp SAML 2.0 IdP
+ */
+ 'idp-entity-id-simple' => array(
+ 'name' => 'Test',
+ 'description' => 'Description of this example entry',
+
+ 'SingleSignOnService' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
+ 'SingleLogoutService' => 'https://idp.example.org/simplesaml/saml2/idp/SingleLogoutService.php',
+ 'certFingerprint' => '3fa158e8abfd4b5203315b08c0b791b6ee4715f6'
+ ),
+
+**Example 5. More complex example**
+
+Here is an example with more configuration:
+
+ /*
+ * Example simpleSAMLphp SAML 2.0 IdP
+ */
+ 'idp-entity-id' => array(
+ 'name' => 'Test',
+ 'description' => 'Description of this example entry',
+
+ 'SingleSignOnService' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
+ 'SingleLogoutService' => 'https://idp.example.org/simplesaml/saml2/idp/SingleLogoutService.php',
+ 'certFingerprint' => '3fa158e8abfd4b5203315b08c0b791b6ee4715f6',
+ 'base64attributes' => true,
+
+ /*
+ * When redirect.validate is true the certificate of the IdP will be used
+ * to verify all messages received with the HTTPRedirect binding.
+ *
+ * The certificate from the IdP must be installed in the cert directory
+ * before verification can be done.
+ */
+ 'redirect.validate' => false,
+ 'certificate' => "idp.example.org.crt",
+
+ /*
+ * It is possible to relax some parts of the validation of SAML2 messages.
+ * To relax a part, add the id to the 'saml2.relaxvalidation' array.
+ *
+ * Valid ids:
+ * - 'unknowncondition' Disables errors when encountering unknown <Condition> nodes.
+ * - 'nosubject' Ignore missing <Subject> in <Assertion>.
+ * - 'noconditions' Ignore missing <Conditions> in <Assertion>.
+ * - 'noauthnstatement' Ignore missing <AuthnStatement> in <Assertion>.
+ * - 'noattributestatement' Ignore missing <AttributeStatement> in <Assertion>.
+ *
+ * Example:
+ * 'saml2.relaxvalidation' => array('unknowncondition', 'noattributestatement'),
+ *
+ * Default:
+ * 'saml2.relaxvalidation' => array(),
+ */
+ 'saml2.relaxvalidation' => array(),
+
+ ),
+
+### Mandatory metadata fields
+
+These are the required metadata fields:
+
+index in the `$metadata` array
+: Entity ID of the remote IdP.
+
+name
+: A textual name of the IdP. This can contain a string or an
+ associative array of language code => translation pairs. This name
+ is used in the SAML 2.0 discovery service.
+
+description
+: A longer description of the IdP. This can contain a string or
+ an associative array of language code => translation pairs. The
+ description is used in the SAML 2.0 discovery service.
+
+SingleSignOnService
+: Endpoint URL for sign on. You should obtain this from the IdP.
+ Your simpleSAMLphp implementation will redirected users who are not
+ yet authenticated to this URL with the AuthnRequest using
+ HTTP-REDIRECT.
+
+SingleLogoutService
+: Endpoint URL for logout. You should obtain this from the IdP.
+ Users who log out from your service is redirected to this URL with
+ the LogoutRequest using HTTP-REDIRECT.
+
+certFingerprint
+: The `sha1` checksum of the certificate used by the IdP. If you
+ don't know how to compute this, you can leave it as it is, and then
+ you'll get an error message the first time you try to login. In
+ this error message you are told what is the fingerprint of the IdP
+ certificiate, which you may copy to this metadata parameter.
+
+: It is also possible to add an array of valid fingerprints,
+ where any fingerprints in that array is accepted as valid. This can
+ be used to update the certificate of the IdP without having to
+ update every SP at that exact time. Instead, one can update the SPs
+ with the new fingerprint, and only update the certificate after
+ every SP is updated.
+
+: See
+ [Appendix A, *Calculating the fingerprint of a certificate*](#a.fingerprint "A. Calculating the fingerprint of a certificate")
+ for an example of how to calculate the fingerprint with the
+ `openssl` tool.
+
+
+### Optional metadata fields
+
+These fields can be left out if not needed.
+
+base64attributes
+: If the IdP base64 encodesattributes, you may set this parameter
+ to `true`. Base64 encoding should be avoided when not strictly
+ needed, but it allows attributes in any binary format to be
+ exchanged.
+
+: ### Warning
+
+: If you are using simpleSAMLphp at the IdP, remember to set the
+ parameter in the metadata at the IdP to be the same.
+
+SPNameQualifier
+: This corresponds to the SPNameQualifier in the SAML 2.0
+ specification. It allows to give subjects a SP specific namespace.
+ This option is rarely used, so if you don't need it, leave it out.
+ When left out, simpleSAMLphp assumes the entityID of your SP as the
+ SPNameQualifier.
+
+attributemap
+: Mapping table for translating attribute names. For further
+ information, see the *Advances Features* document.
+
+attributealter
+: Table of custom functions that injects or modifies attributes.
+ For further information, see the *Advances Features* document.
+
+certificate
+: Name of certificate file in PEM format, in the `certs`
+ directory. Used for decrypting assertions and as an alternative to
+ certFingerprint for validating signatures.
+
+: This option is also required if validating signed logout
+ requests/responses from this IdP.
+
+assertion.encryption
+: Set to true if the remote idp encrypts assertions. Encrypted
+ assertions are decrypted regardless of the value this field if the
+ neccesary certificate or key is available, but if it is set to true
+ and an unencrypted assertion is recieved an exception is raised.
+
+sharedkey
+: Used for optional symmetric decryption of assertions. Currently
+ the algorithm is hardcoded to AES128\_CBC/RIJNDAEL\_128 which uses
+ up to 128 bit for the passphrase/key. Not necessary if the idp uses
+ a sessionkey which is encrypted by the idp's private key.
+
+caFile
+: Alternative to certFingerprint. Allows you to specify a file
+ with root certificates, and responses from the service be validated
+ against these certificates. Note that simpleSAMLphp doesn't support
+ chains with any itermediate certificates between the root and the
+ certificate used to sign the response.
+
+icon
+: An icon for this IdP. This is a URL to a icon which will be
+ displayed next to this IdP in the IdP discovery service. The URL
+ can be absolute or relative. If it is relative, it will be relative
+ to the simpleSAMPphp www-directory.
+
+
+### Fields for signing and validating messages
+
+simpleSAMLphp only signs authentication responses by default.
+Signing of authentication requests, logout requests and logout
+responses can be enabled by setting the `redirect.sign` option.
+Validation of received messages can be enabled by the
+`redirect.validate` option. Note that if you want to sign messages,
+you will need a keypair/certificate at the SP.
+
+These options overrides the options set in `saml20-sp-hosted`.
+
+redirect.sign
+: Boolean, default `false`. To turn on signing of authentication
+ requests, logout requests and logout responses, set this flag to
+ true.
+
+: This option overrides the `redirect.sign` option in
+ `saml20-sp-hosted`.
+
+redirect.validate
+: Boolean, default `false`. To turn on validation of received
+ logout requests and logout responses, set this flag to true.
+
+: This option overrides the `redirect.validate` option in
+ `saml20-sp-hosted`.
+
+
+**Example 6. Example of configuration for validating messages**
+
+ 'redirect.validate' => true,
+ 'certificate' => 'server.crt'
+
+## Setting the default SAML 2.0 IdP
+
+The global configuration (`config.php`) holds a parameter to set
+the default IdP to use. Alternatively you can specify which IdP to
+use in a parameter to the initSSO.php script when you initiate
+logon in your application.
+
+Here is an example from `config.php`:
+
+ 'default-saml20-idp' => 'sam.feide.no',
+
+The configuration above will use the IdP configured in IdP Remote
+metadata with entity ID equal to `sam.feide.no`.
+
+## Using the SAML 2.0 IdP Discovery Service
+
+If you want end users to be able to select one of several specified
+entries in IdP remote metadata, set the default IdP to be null.
+simpleSAMLphp will then use its builtin IdP discovery service to
+let the user select IdP. Here is the neccessary configuration from
+`config.php`:
+
+ 'default-saml20-idp' => null,
+
+Configuring metadata for Shibboleth 1.3 SP
+------------------------------------------
+
+To set up a Shibboleth 1.3 SP, configure two metadata files.
+shib13-sp-hosted.php and shib13-idp-remote.php.The former
+represents the SAML entity of your service provider, the latter
+lists all the trusted Shibboleth 1.3 IdPs and how to connect to
+them.
+
+Note: Shibboleth 2.0 IdPs should be configured as SAML 2.0 IdPs.
+
+## Configuring Shibboleth 1.3 SP Hosted metadata
+
+Two parameters, the entity ID and the host name of the web server
+running this SP, are configured in the hosted metadata
+(`shib13-sp-hosted.php`).
+
+**Example 7. Shibboleth 1.3 SP hosted metadata**
+
+ /*
+ * Example of hosted Shibboleth 1.3 SP.
+ */
+ 'sp-provider-id' => array(
+ 'host' => 'sp.example.org'
+ )
+
+### Mandatory fields
+
+index (the index of the array)
+: The entity ID of the hosted SP entity.
+
+: simpleSAMLphp supports dynamic entityIDs that matches a URL
+ where simpleSAMLphp automatically generates metadata for the hosted
+ entity. To enable this functionality, set the index to be
+ `__DYNAMIC:1__`. The index needs to be unique, so when you have
+ multiple entries, increase the integer after the colon. When the
+ index `__DYNAMIC:1__` is used, the resulting generated entity
+ becomes something like:
+
+: https://sp.example.org/simplesaml/shib13/sp/metadata.php
+
+host
+: Host name of the server running this SP. One of your metadata
+ entries can have the value `__DEFAULT__`. A default entry will be
+ used when no other entry matches the current hostname.
+
+
+### Optional metadata fields
+
+These fields can be left out if not needed.
+
+AssertionConsumerService
+: Override the default URL for the AssertionConsumerService for
+ this SP. This is an absolute URL. The default value is
+ `<simpleSAMLphp-root>/shib13/sp/AssertionConsumerService.php`
+
+: Note that this only changes the values in the generated
+ metadata and in the messages sent to others. You must also
+ configure your webserver to deliver this URL to the correct PHP
+ page.
+
+idpdisco.url
+: Set which IdP discovery service this SP should use. If this is
+ unset, the IdP discovery service specified in the global option
+ `idpdisco.url.shib13` in `config/config.php` will be used. If that
+ one is also unset, the builtin default discovery service will be
+ used.
+
+
+## Configuring Shibboleth 1.3 IdP Remote metadata
+
+Here (`shib13-idp-remote.php`) you configure which IdPs that you
+trust to authenticate users of your service.
+
+**Example 8. Example of remote Shibboleth 1.3 IdP metadata**
+
+ 'theproviderid-of-the-idp' => array(
+ 'SingleSignOnService' => 'https://idp.example.org/shibboleth-idp/SSO',
+ 'certFingerprint' => 'c7279a9f28f11380509e072441e3dc55fb9ab864'
+ )
+
+index in the `$metadata` array
+: The `providerID` of this Shibboleth 1.3 IdP entity. In this
+ example the entity ID is set to
+ `urn:mace:switch.ch:aaitest:dukono.switch.ch`.
+
+SingleSignOnService
+: Contact the IdP to get the endpoint URL of this service. This
+ is the URL which the user is redirected with the request for
+ authentication.
+
+: ### Note
+
+: The name of this parameter changed from SingleSignOnUrl to
+ SingleSignOnService betwen simpleSAMLphp version 0.5 and 1.0.
+
+certFingerprint
+: The `sha` checksum of the certificate used by the IdP. If you
+ don't know how to compute this, you can leave it as it is, and then
+ you'll get an error message the first time you try to login. In
+ this error message you are told what is the fingerprint of the IdP
+ certificiate, which you may copy to this metadata parameter.
+
+: It is also possible to add an array of valid fingerprints,
+ where any fingerprints in that array is accepted as valid. This can
+ be used to update the certificate of the IdP without having to
+ update every SP at that exact time. Instead, one can update the SPs
+ with the new fingerprint, and only update the certificate after
+ every SP is updated.
+
+: See
+ [Appendix A, *Calculating the fingerprint of a certificate*](#a.fingerprint "A. Calculating the fingerprint of a certificate")
+ for an example of how to calculate the fingerprint with the openssl
+ tool.
+
+caFile
+: Alternative to certFingerprint. Allows you to specify a file
+ with root certificates, and responses from the service be validated
+ against these certificates. Note that simpleSAMLphp doesn't support
+ chains with any itermediate certificates between the root and the
+ certificate used to sign the response.
+
+icon
+: An icon for this IdP. This is a URL to a icon which will be
+ displayed next to this IdP in the IdP discovery service. The URL
+ can be absolute or relative. If it is relative, it will be relative
+ to the simpleSAMPphp www-directory. This field is optional.
+
+
+Exchange metadata with the IdP
+------------------------------
+
+Before you can run the test examples, you need the people running
+the IdP to load the metadata for your SP. If you run Shibboleth 1.3
+SP, you must manually create metadata for your SP and send to the
+IdP. If you use SAML 2.0, metadata can be generated automatically.
+
+## Automatic generation of SAML 2.0 SP metadata
+
+On the installation page there is a link named "Look at your SAML
+2.0 SP metadata". Click to inspect the metadata for your SP. Send
+this metadata document to the IdP and ask them to load it.
+
+
+If you are connected to Feide, and put one of Feides entity IDs as
+default IdP, you will see an additional section on this page:
+
+
+Enter your email address and click the button "Send my metadata to
+Feide". Remeber to get in contact with Feide to discuss your new
+service, and how you can be connected to Feide's test environment.
+To test your service, you must have a valid Feide login name. If
+you are not affiliated with a Feide host institution, you may
+obtain a test user identity from Feide.
+
+Test the SAML 2.0 SP examples
+-----------------------------
+
+After you have installed simpleSAMLphp, configured Apache, set up
+metadata and exchanged metadata with the IdP, you are ready to test
+the sample service included in the simpleSAMLphp distribution.
+
+The installation page of simpleSAMLphp has a link to a Shibboleth
+1.3 and a SAML 2.0 sample service. When you click the link, you
+should be automatically redirected to the IdP. Login, and you
+should be sent back and shown all the attributes sent form the
+IdP.
+
+**Figure 1. Screenshot of the status page after an user have succesfully authenticated**
+
+
+
+Integrating authentication with your own application
+----------------------------------------------------
+
+For those web resources you want to protect, you must add a few
+lines of PHP code:
+
+- Check whether the user is already authenticated.
+
+-
+ If the user is not authenticated, but should be for this resource,
+ redirect him to the `initSSO.php` script with the appropriate
+ parameters. Note particularly the `RelayState` specifying the
+ treturn URL after login.
+
+-
+ If authentication is successful, but you need to determine the
+ user's authorization, read the user attributes supplied by the IdP
+ from the session object. If you need user attributes beyond those
+ supplied by the IdP, you may maintain an exteded user description
+ in you own database, using the (authenticated) user ID as a key.
+
+
+Sample code:
+
+We start off with including a common file \_include.php. All this
+file does is to add simpleSAMLphp to the classpath. Alternately,
+this can be configured in `php.ini`, or the contents of
+`_include.php` can be included directly in the application code.
+
+
+
+ require_once('../_include.php');
+
+Including class specifications. This is for SAML 2.0; for
+Shibboleth look at the Shibboleth example in
+`www/example-simple/shib13-example.php`.
+
+ require_once('SimpleSAML/Utilities.php');
+ require_once('SimpleSAML/Session.php');
+ require_once('SimpleSAML/XHTML/Template.php');
+
+Enable PHP Sessions and load configuration with simpleSAMLphp. You
+can copy this lines into your application without changes:
+
+ /* Load simpleSAMLphp, configuration and metadata */
+ $config = SimpleSAML_Configuration::getInstance();
+ $session = SimpleSAML_Session::getInstance();
+
+Then check whether the session is valid. If not, redirect the user
+to the IdP, specifying the `initSSO.php` script (for SAML 2.0 or
+Shibboleth 1.3, respectively). adding the current URL as a
+`RelayState` parameter. The user will leave your web page
+temporarily. When he returns after successful authentication, there
+will be a valid session, and the body of the `if` statement is
+skipped.
+
+After successful athentication, user attributes supplied by the IdP
+are available in session object. To take a closer look at the
+attributes array, you may print it out...
+
+ /* Check if valid local session exists.. */
+ if (!isset($session) || !$session->isValid('saml2') ) {
+ SimpleSAML_Utilities::redirect(
+ '/' . $config->getBaseURL() .
+ 'saml2/sp/initSSO.php',
+ array('RelayState' => SimpleSAML_Utilities::selfURL())
+ );
+ }
+
+ $attributes = $session->getAttributes();
+ print_r($attributes);
+
+(Obviously, printing out all attributes this way would be done in a
+test phase only!)
+
+Each attribute name can be used as an index into $attributes to
+obtain the value. Every attribute value is an array - a
+single-valued attribute is an array of a single element.
+
+## Upgrading service integration from version 0.5 to 1.0
+
+-
+ [Wiki page describing the differences between integrating a service with simpleSAMLphp 0.5 and simpleSAMLphp 1.0.](https://ow.feide.no/simplesamlphp:spupgrade05to10)
+
+
+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)
+
+
+## A. Calculating the fingerprint of a certificate
+
+If you have obtained a certificate file, and want to calculate the
+fingerprint of the file, you can use the `openssl` command:
+
+ $ cat server.crt|openssl x509 -fingerprint
+ MD5 Fingerprint=D1:BA:B0:17:66:6D:7F:42:7B:91:1E:22:7E:3A:27:D2
+
+
+
diff --git a/docs/source/simplesamlphp-sp.xml b/docs/source/simplesamlphp-sp.xml
deleted file mode 100644
index b0492f4b5df586fc08b354f12b9e716d3f22db1c..0000000000000000000000000000000000000000
--- a/docs/source/simplesamlphp-sp.xml
+++ /dev/null
@@ -1,1147 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<article>
- <title>Using simpleSAMLphp as a Service Provider</title>
-
- <articleinfo>
- <date>2007-10-15</date>
-
- <pubdate>Sun Nov 2 14:37:37 2008</pubdate>
-
- <author>
- <firstname>Andreas Ă…kre</firstname>
-
- <surname>Solberg</surname>
-
- <email>andreas.solberg@uninett.no</email>
- </author>
- </articleinfo>
-
- <section>
- <title>simpleSAMLphp documentation</title>
-
- <para>This document is part of the simpleSAMLphp documentation
- suite.</para>
-
- <itemizedlist>
- <listitem>
- <para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
- all simpleSAMLphp documentation</ulink></para>
- </listitem>
- </itemizedlist>
-
- <para>This document assumes that you already have a installation of
- simpleSAMLphp. Before you continue make sure all the required entries in
- the check list at the buttom is showing green light.</para>
- </section>
-
- <section>
- <title>Introduction</title>
-
- <para>simpleSAMLphp can run as both a SAML 2.0 Service Provider and as a
- Shibboleth 1.3 Service Provider. Although the configuration is similar for
- the two alternatives, there are some differences in configuration and
- metadata differs somewhat, so they are treated in separate
- chapters.</para>
- </section>
-
- <section>
- <title>Selecting the desired Service Provider functionality</title>
-
- <para>Your identity provider (IdP) may offer user authentication either
- using the SAML 2.0 protocol, or the older Shibboleth 1.3 protocol.</para>
-
- <para>SAML 2.0 SP functionality is enabled by default. If this is what you
- want to use, leave the default configuration unmodified.</para>
-
- <para>To setup a Shibboleth 1.3 SP, you must disable SAML 2.0 SP and
- enable Shib 1.3 SP in <filename>config.php</filename>:</para>
-
- <programlisting>'enable.saml20-sp' => false,
-'enable.saml20-idp' => false,
-'enable.shib13-sp' => true,
-'enable.shib13-idp' => false,</programlisting>
- </section>
-
- <section>
- <title>Configuring metadata for SAML 2.0 SP</title>
-
- <para>To set up a SAML 2.0 SP, configure two metadata files:
- <filename>saml20-sp-hosted.php</filename> and
- <filename>saml20-idp-remote.php</filename>. The former represents the SAML
- entity of your SP, the latter lists all the SAML 2.0 IdPs you trust to
- authenticate users, and how to connect to them.</para>
-
- <section>
- <title>Configuring SAML 2.0 SP Hosted metadata</title>
-
- <para>To se tup these metadata, you must know the host name of your web
- server, and select an entity ID for this server. The IdP may impose
- restrictions on your choice of entity ID.</para>
-
- <note>
- <para>Feide has special rules for setting entity IDs. The rules and
- instructions on how to select an entity ID to use in Feide are
- documented in the fact sheet:</para>
-
- <itemizedlist>
- <listitem>
- <para><ulink
- url="http://docs.feide.no/fs-0051--en.html">Regulations for SAML
- 2.0 entityIDs for Feide Services</ulink> (Feide Fact Sheet
- #51)</para>
- </listitem>
- </itemizedlist>
- </note>
-
- <example>
- <title>Example of metadata for hosted SAML 2.0 SP</title>
-
- <para>Here is an example of the metadata file:</para>
-
- <programlisting>/*
- * Example of a hosted SP
- */
-'sp-entityid' => array(
- 'host' => 'sp.example.org'
-)</programlisting>
- </example>
-
- <example>
- <title>Real life example</title>
-
- <para>Here is a real life example from Feide:</para>
-
- <programlisting>'urn:mace:feide.no:services:no.feide.foodle' => array(
- 'host' => 'foodle.feide.no',
-),
-</programlisting>
-
- <para>Here the service run on the host
- <literal>foodle.feide.no</literal> and have the entity ID
- <literal>urn:mace:feide.no:services:no.feide.foodle</literal>.</para>
- </example>
-
- <para>You may add any number of SP definitions in the same installation
- of simpleSAMLphp. simpleSAMLphp will discover automatically which
- configuration to use in a specific scenario, by mapping current hostname
- in the URL sent by the end user client to the <literal>host</literal>
- entry in the metadata.</para>
-
- <para>Below is a description of mandatory and optional fields in the
- SAML 2.0 SP hosted metadata.</para>
-
- <section>
- <title>Mandatory metadata fields</title>
-
- <para>These metadata fields are required:</para>
-
- <glosslist>
- <glossentry>
- <glossterm>index in the <code>$metadata</code> array</glossterm>
-
- <glossdef>
- <para>The entity ID of the hosted SP entity.</para>
-
- <para>simpleSAMLphp supports dynamic entityIDs that matches a
- URL where simpleSAMLphp automatically generates metadata for the
- hosted entity. To enable this functionality, set the index to be
- <literal>__DYNAMIC:1__</literal>. The index needs to be unique,
- so when you have multiple entries, increase the integer after
- the colon. When the index <literal>__DYNAMIC:1__</literal> is
- used, the resulting generated entity becomes something
- like:</para>
-
- <literallayout>https://sp.example.org/simplesaml/saml2/sp/metadata.php</literallayout>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>host</glossterm>
-
- <glossdef>
- <para>Host name of the server running this SP. One of your
- metadata entries can have the value
- <literal>__DEFAULT__</literal>. A default entry will be used
- when no other entry matches the current hostname.</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </section>
-
- <section>
- <title>Optional metadata fields</title>
-
- <para>These fields can be left out if not needed.</para>
-
- <glosslist>
- <glossentry>
- <glossterm>NameIDFormat</glossterm>
-
- <glossdef>
- <para>The NameIDFormat in the request. If you don't know what
- this is, or do not require a specific format, leave the default
- value unmodified.</para>
-
- <para>If you leave out this entry, the default value
- <literal>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</literal>
- is used in the authentication request. If you set the value to
- <literal>null</literal>, the
- <literal>samlp:NameIDPolicy</literal> element is completely
- removed from the request.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>ForceAuthn</glossterm>
-
- <glossdef>
- <para>Force authentication allows you to force re-authentication
- of users even if the user has a SSO session at the IdP.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>AuthnContextClassRef</glossterm>
-
- <glossdef>
- <para>The SP can request authentication with a specific
- authentication context class. One example of usage could be if
- the IdP supports both username/password authentication as well
- as software-PKI.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>attributemap</glossterm>
-
- <glossdef>
- <para>Mapping table for translating attribute names. For further
- information, see the <emphasis>Advances Features</emphasis>
- document.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>attributealter</glossterm>
-
- <glossdef>
- <para>Table of custom functions that injects or modifies
- attributes. For further information, see the <emphasis>Advances
- Features</emphasis> document.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>attributes</glossterm>
-
- <glossdef>
- <para>Array of attributes sent to the SP. If this field is not
- set, the SP receives all attributes available at the IdP.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>IsPassive</glossterm>
-
- <glossdef>
- <para>IsPassive allows you to enable passive authentication by
- default for this SP.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>AssertionConsumerService</glossterm>
-
- <glossdef>
- <para>Override the default URL for the AssertionConsumerService
- for this SP. This is an absolute URL. The default value is
- <literal><simpleSAMLphp-root>/saml2/sp/AssertionConsumerService.php</literal></para>
-
- <para>Note that this only changes the values in the generated
- metadata and in the messages sent to others. You must also
- configure your webserver to deliver this URL to the correct PHP
- page.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>SingleLogoutService</glossterm>
-
- <glossdef>
- <para>Override the default URL for the SingleLogoutService for
- this SP. This is an absolute URL. The default value is
- <literal><simpleSAMLphp-root>/saml2/sp/SingleLogoutService.php</literal></para>
-
- <para>Note that this only changes the values in the generated
- metadata and in the messages sent to others. You must also
- configure your webserver to deliver this URL to the correct PHP
- page.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>idpdisco.url</glossterm>
-
- <glossdef>
- <para>Set which IdP discovery service this SP should use. If
- this is unset, the IdP discovery service specified in the global
- option <literal>idpdisco.url.saml20</literal> in
- <filename>config/config.php</filename> will be used. If that one
- is also unset, the builtin default discovery service will be
- used.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>privatekey</glossterm>
-
- <glossdef>
- <para>File name of private key to be used for signing
- messages.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>certificate</glossterm>
-
- <glossdef>
- <para>File name of certificate corresponding to the private key.
- This certificate will be included in generated metadata.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>privatekey_pass</glossterm>
-
- <glossdef>
- <para>Optional field with the passphrase for the private
- key.</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </section>
-
- <section>
- <title>Fields for signing and validating messages</title>
-
- <para>simpleSAMLphp only signs authentication responses by default.
- Signing of authentication requests, logout requests and logout
- responses can be enabled by setting the
- <literal>redirect.sign</literal> option. Validation of received
- messages can be enabled by the <literal>redirect.validate</literal>
- option. Note that if you want to sign messages, you will need a
- keypair/certificate at the SP.</para>
-
- <para>These options set the default for this SP, but options for each
- IdP can be set in <literal>saml20-idp-remote</literal>.</para>
-
- <glosslist>
- <glossentry>
- <glossterm>redirect.sign</glossterm>
-
- <glossdef>
- <para>Boolean, default <literal>false</literal>. To turn on
- signing of authentication requests, logout requests and logout
- responses, set this flag to true.</para>
-
- <para>This option can be overridden by the
- <literal>redirect.sign</literal> option in
- <literal>saml20-idp-remote</literal>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>redirect.validate</glossterm>
-
- <glossdef>
- <para>Boolean, default <literal>false</literal>. To turn on
- validation of received logout requests and logout responses, set
- this flag to true.</para>
-
- <para>This option can be overridden by the
- <literal>redirect.validate</literal> option in
- <literal>saml20-idp-remote</literal>.</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <example>
- <title>Example of configured signed messages</title>
-
- <programlisting> 'redirect.sign' => true,
- 'privatekey' => 'server.pem',</programlisting>
- </example>
- </section>
- </section>
-
- <section>
- <title>Configuring SAML 2.0 IdP Remote metadata</title>
-
- <para>The metadata file <filename>saml20-idp-remote.php</filename>
- represent the SAML 2.0 IdPs that your service provider trust to
- authenticate users of your service.</para>
-
- <example>
- <title>Example of metadata for trusted remote SAML 2.0 IdP</title>
-
- <para>Here is an example of a metadata entry for a remote trusted
- IdP:</para>
-
- <programlisting>/*
- * Example simpleSAMLphp SAML 2.0 IdP
- */
-'idp-entity-id-simple' => array(
- 'name' => 'Test',
- 'description' => 'Description of this example entry',
-
- 'SingleSignOnService' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
- 'SingleLogoutService' => 'https://idp.example.org/simplesaml/saml2/idp/SingleLogoutService.php',
- 'certFingerprint' => '3fa158e8abfd4b5203315b08c0b791b6ee4715f6'
-),</programlisting>
- </example>
-
- <example>
- <title>More complex example</title>
-
- <para>Here is an example with more configuration:</para>
-
- <programlisting> /*
- * Example simpleSAMLphp SAML 2.0 IdP
- */
- 'idp-entity-id' => array(
- 'name' => 'Test',
- 'description' => 'Description of this example entry',
-
- 'SingleSignOnService' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
- 'SingleLogoutService' => 'https://idp.example.org/simplesaml/saml2/idp/SingleLogoutService.php',
- 'certFingerprint' => '3fa158e8abfd4b5203315b08c0b791b6ee4715f6',
- 'base64attributes' => true,
-
- /*
- * When redirect.validate is true the certificate of the IdP will be used
- * to verify all messages received with the HTTPRedirect binding.
- *
- * The certificate from the IdP must be installed in the cert directory
- * before verification can be done.
- */
- 'redirect.validate' => false,
- 'certificate' => "idp.example.org.crt",
-
- /*
- * It is possible to relax some parts of the validation of SAML2 messages.
- * To relax a part, add the id to the 'saml2.relaxvalidation' array.
- *
- * Valid ids:
- * - 'unknowncondition' Disables errors when encountering unknown <Condition> nodes.
- * - 'nosubject' Ignore missing <Subject> in <Assertion>.
- * - 'noconditions' Ignore missing <Conditions> in <Assertion>.
- * - 'noauthnstatement' Ignore missing <AuthnStatement> in <Assertion>.
- * - 'noattributestatement' Ignore missing <AttributeStatement> in <Assertion>.
- *
- * Example:
- * 'saml2.relaxvalidation' => array('unknowncondition', 'noattributestatement'),
- *
- * Default:
- * 'saml2.relaxvalidation' => array(),
- */
- 'saml2.relaxvalidation' => array(),
-
- ),</programlisting>
- </example>
-
- <section>
- <title>Mandatory metadata fields</title>
-
- <para>These are the required metadata fields:</para>
-
- <glosslist>
- <glossentry>
- <glossterm>index in the <code>$metadata</code> array</glossterm>
-
- <glossdef>
- <para>Entity ID of the remote IdP.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>name</glossterm>
-
- <glossdef>
- <para>A textual name of the IdP. This can contain a string or an
- associative array of language code => translation pairs. This
- name is used in the SAML 2.0 discovery service.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>description</glossterm>
-
- <glossdef>
- <para>A longer description of the IdP. This can contain a string
- or an associative array of language code => translation
- pairs. The description is used in the SAML 2.0 discovery
- service.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>SingleSignOnService</glossterm>
-
- <glossdef>
- <para>Endpoint URL for sign on. You should obtain this from the
- IdP. Your simpleSAMLphp implementation will redirected users who
- are not yet authenticated to this URL with the AuthnRequest
- using HTTP-REDIRECT.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>SingleLogoutService</glossterm>
-
- <glossdef>
- <para>Endpoint URL for logout. You should obtain this from the
- IdP. Users who log out from your service is redirected to this
- URL with the LogoutRequest using HTTP-REDIRECT.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>certFingerprint</glossterm>
-
- <glossdef>
- <para>The <literal>sha1</literal> checksum of the certificate
- used by the IdP. If you don't know how to compute this, you can
- leave it as it is, and then you'll get an error message the
- first time you try to login. In this error message you are told
- what is the fingerprint of the IdP certificiate, which you may
- copy to this metadata parameter.</para>
-
- <para>It is also possible to add an array of valid fingerprints,
- where any fingerprints in that array is accepted as valid. This
- can be used to update the certificate of the IdP without having
- to update every SP at that exact time. Instead, one can update
- the SPs with the new fingerprint, and only update the
- certificate after every SP is updated.</para>
-
- <para>See <xref linkend="a.fingerprint" /> for an example of how
- to calculate the fingerprint with the <literal>openssl</literal>
- tool.</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </section>
-
- <section>
- <title>Optional metadata fields</title>
-
- <para>These fields can be left out if not needed.</para>
-
- <glosslist>
- <glossentry>
- <glossterm>base64attributes</glossterm>
-
- <glossdef>
- <para>If the IdP base64 encodesattributes, you may set this
- parameter to <literal>true</literal>. Base64 encoding should be
- avoided when not strictly needed, but it allows attributes in
- any binary format to be exchanged. <warning>
- <para>If you are using simpleSAMLphp at the IdP, remember to
- set the parameter in the metadata at the IdP to be the
- same.</para>
- </warning></para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>SPNameQualifier</glossterm>
-
- <glossdef>
- <para>This corresponds to the SPNameQualifier in the SAML 2.0
- specification. It allows to give subjects a SP specific
- namespace. This option is rarely used, so if you don't need it,
- leave it out. When left out, simpleSAMLphp assumes the entityID
- of your SP as the SPNameQualifier.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>attributemap</glossterm>
-
- <glossdef>
- <para>Mapping table for translating attribute names. For further
- information, see the <emphasis>Advances Features</emphasis>
- document.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>attributealter</glossterm>
-
- <glossdef>
- <para>Table of custom functions that injects or modifies
- attributes. For further information, see the <emphasis>Advances
- Features</emphasis> document.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>certificate</glossterm>
-
- <glossdef>
- <para>Name of certificate file in PEM format, in the
- <filename>certs</filename> directory. Used for decrypting
- assertions and as an alternative to certFingerprint for
- validating signatures.</para>
-
- <para>This option is also required if validating signed logout
- requests/responses from this IdP.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>assertion.encryption</glossterm>
-
- <glossdef>
- <para>Set to true if the remote idp encrypts assertions.
- Encrypted assertions are decrypted regardless of the value this
- field if the neccesary certificate or key is available, but if
- it is set to true and an unencrypted assertion is recieved an
- exception is raised.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>sharedkey</glossterm>
-
- <glossdef>
- <para>Used for optional symmetric decryption of assertions.
- Currently the algorithm is hardcoded to AES128_CBC/RIJNDAEL_128
- which uses up to 128 bit for the passphrase/key. Not necessary
- if the idp uses a sessionkey which is encrypted by the idp's
- private key.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>caFile</glossterm>
-
- <glossdef>
- <para>Alternative to certFingerprint. Allows you to specify a
- file with root certificates, and responses from the service be
- validated against these certificates. Note that simpleSAMLphp
- doesn't support chains with any itermediate certificates between
- the root and the certificate used to sign the response.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>icon</glossterm>
-
- <glossdef>
- <para>An icon for this IdP. This is a URL to a icon which will
- be displayed next to this IdP in the IdP discovery service. The
- URL can be absolute or relative. If it is relative, it will be
- relative to the simpleSAMPphp www-directory.</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </section>
-
- <section>
- <title>Fields for signing and validating messages</title>
-
- <para>simpleSAMLphp only signs authentication responses by default.
- Signing of authentication requests, logout requests and logout
- responses can be enabled by setting the
- <literal>redirect.sign</literal> option. Validation of received
- messages can be enabled by the <literal>redirect.validate</literal>
- option. Note that if you want to sign messages, you will need a
- keypair/certificate at the SP.</para>
-
- <para>These options overrides the options set in
- <literal>saml20-sp-hosted</literal>.</para>
-
- <glosslist>
- <glossentry>
- <glossterm>redirect.sign</glossterm>
-
- <glossdef>
- <para>Boolean, default <literal>false</literal>. To turn on
- signing of authentication requests, logout requests and logout
- responses, set this flag to true.</para>
-
- <para>This option overrides the <literal>redirect.sign</literal>
- option in <literal>saml20-sp-hosted</literal>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>redirect.validate</glossterm>
-
- <glossdef>
- <para>Boolean, default <literal>false</literal>. To turn on
- validation of received logout requests and logout responses, set
- this flag to true.</para>
-
- <para>This option overrides the
- <literal>redirect.validate</literal> option in
- <literal>saml20-sp-hosted</literal>.</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <example>
- <title>Example of configuration for validating messages</title>
-
- <programlisting>'redirect.validate' => true,
-'certificate' => 'server.crt'</programlisting>
- </example>
- </section>
- </section>
-
- <section>
- <title>Setting the default SAML 2.0 IdP</title>
-
- <para>The global configuration (<filename>config.php</filename>) holds a
- parameter to set the default IdP to use. Alternatively you can specify
- which IdP to use in a parameter to the initSSO.php script when you
- initiate logon in your application.</para>
-
- <para>Here is an example from <filename>config.php</filename>:</para>
-
- <programlisting> 'default-saml20-idp' => 'sam.feide.no',</programlisting>
-
- <para>The configuration above will use the IdP configured in IdP Remote
- metadata with entity ID equal to <literal>sam.feide.no</literal>.</para>
- </section>
-
- <section>
- <title>Using the SAML 2.0 IdP Discovery Service</title>
-
- <para>If you want end users to be able to select one of several
- specified entries in IdP remote metadata, set the default IdP to be
- null. simpleSAMLphp will then use its builtin IdP discovery service to
- let the user select IdP. Here is the neccessary configuration from
- <filename>config.php</filename>:</para>
-
- <programlisting> 'default-saml20-idp' => null,</programlisting>
- </section>
- </section>
-
- <section>
- <title>Configuring metadata for Shibboleth 1.3 SP</title>
-
- <para>To set up a Shibboleth 1.3 SP, configure two metadata files.
- shib13-sp-hosted.php and shib13-idp-remote.php.The former represents the
- SAML entity of your service provider, the latter lists all the trusted
- Shibboleth 1.3 IdPs and how to connect to them.</para>
-
- <para>Note: Shibboleth 2.0 IdPs should be configured as SAML 2.0
- IdPs.</para>
-
- <section>
- <title>Configuring Shibboleth 1.3 SP Hosted metadata</title>
-
- <para>Two parameters, the entity ID and the host name of the web server
- running this SP, are configured in the hosted metadata
- (<literal>shib13-sp-hosted.php</literal>).</para>
-
- <example>
- <title>Shibboleth 1.3 SP hosted metadata</title>
-
- <programlisting>/*
- * Example of hosted Shibboleth 1.3 SP.
- */
-'sp-provider-id' => array(
- 'host' => 'sp.example.org'
-)
-</programlisting>
- </example>
-
- <section>
- <title>Mandatory fields</title>
-
- <glosslist>
- <glossentry>
- <glossterm>index (the index of the array)</glossterm>
-
- <glossdef>
- <para>The entity ID of the hosted SP entity.</para>
-
- <para>simpleSAMLphp supports dynamic entityIDs that matches a
- URL where simpleSAMLphp automatically generates metadata for the
- hosted entity. To enable this functionality, set the index to be
- <literal>__DYNAMIC:1__</literal>. The index needs to be unique,
- so when you have multiple entries, increase the integer after
- the colon. When the index <literal>__DYNAMIC:1__</literal> is
- used, the resulting generated entity becomes something
- like:</para>
-
- <literallayout>https://sp.example.org/simplesaml/shib13/sp/metadata.php</literallayout>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>host</glossterm>
-
- <glossdef>
- <para>Host name of the server running this SP. One of your
- metadata entries can have the value
- <literal>__DEFAULT__</literal>. A default entry will be used
- when no other entry matches the current hostname.</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </section>
-
- <section>
- <title>Optional metadata fields</title>
-
- <para>These fields can be left out if not needed.</para>
-
- <glosslist>
- <glossentry>
- <glossterm>AssertionConsumerService</glossterm>
-
- <glossdef>
- <para>Override the default URL for the AssertionConsumerService
- for this SP. This is an absolute URL. The default value is
- <literal><simpleSAMLphp-root>/shib13/sp/AssertionConsumerService.php</literal></para>
-
- <para>Note that this only changes the values in the generated
- metadata and in the messages sent to others. You must also
- configure your webserver to deliver this URL to the correct PHP
- page.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>idpdisco.url</glossterm>
-
- <glossdef>
- <para>Set which IdP discovery service this SP should use. If
- this is unset, the IdP discovery service specified in the global
- option <literal>idpdisco.url.shib13</literal> in
- <filename>config/config.php</filename> will be used. If that one
- is also unset, the builtin default discovery service will be
- used.</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </section>
- </section>
-
- <section>
- <title>Configuring Shibboleth 1.3 IdP Remote metadata</title>
-
- <para>Here (<filename>shib13-idp-remote.php</filename>) you configure
- which IdPs that you trust to authenticate users of your service.</para>
-
- <example>
- <title>Example of remote Shibboleth 1.3 IdP metadata</title>
-
- <programlisting>'theproviderid-of-the-idp' => array(
- 'SingleSignOnService' => 'https://idp.example.org/shibboleth-idp/SSO',
- 'certFingerprint' => 'c7279a9f28f11380509e072441e3dc55fb9ab864'
-)</programlisting>
- </example>
-
- <glosslist>
- <glossentry>
- <glossterm>index in the <code>$metadata</code> array</glossterm>
-
- <glossdef>
- <para>The <literal>providerID</literal> of this Shibboleth 1.3 IdP
- entity. In this example the entity ID is set to
- <literal>urn:mace:switch.ch:aaitest:dukono.switch.ch</literal>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>SingleSignOnService</glossterm>
-
- <glossdef>
- <para>Contact the IdP to get the endpoint URL of this service.
- This is the URL which the user is redirected with the request for
- authentication.<note>
- <para>The name of this parameter changed from SingleSignOnUrl
- to SingleSignOnService betwen simpleSAMLphp version 0.5 and
- 1.0.</para>
- </note></para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>certFingerprint</glossterm>
-
- <glossdef>
- <para>The <literal>sha</literal> checksum of the certificate used
- by the IdP. If you don't know how to compute this, you can leave
- it as it is, and then you'll get an error message the first time
- you try to login. In this error message you are told what is the
- fingerprint of the IdP certificiate, which you may copy to this
- metadata parameter.</para>
-
- <para>It is also possible to add an array of valid fingerprints,
- where any fingerprints in that array is accepted as valid. This
- can be used to update the certificate of the IdP without having to
- update every SP at that exact time. Instead, one can update the
- SPs with the new fingerprint, and only update the certificate
- after every SP is updated.</para>
-
- <para>See <xref linkend="a.fingerprint" /> for an example of how
- to calculate the fingerprint with the openssl tool.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>caFile</glossterm>
-
- <glossdef>
- <para>Alternative to certFingerprint. Allows you to specify a file
- with root certificates, and responses from the service be
- validated against these certificates. Note that simpleSAMLphp
- doesn't support chains with any itermediate certificates between
- the root and the certificate used to sign the response.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>icon</glossterm>
-
- <glossdef>
- <para>An icon for this IdP. This is a URL to a icon which will be
- displayed next to this IdP in the IdP discovery service. The URL
- can be absolute or relative. If it is relative, it will be
- relative to the simpleSAMPphp www-directory. This field is
- optional.</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </section>
- </section>
-
- <section>
- <title>Exchange metadata with the IdP</title>
-
- <para>Before you can run the test examples, you need the people running
- the IdP to load the metadata for your SP. If you run Shibboleth 1.3 SP,
- you must manually create metadata for your SP and send to the IdP. If you
- use SAML 2.0, metadata can be generated automatically.</para>
-
- <section>
- <title>Automatic generation of SAML 2.0 SP metadata</title>
-
- <para>On the installation page there is a link named "Look at your SAML
- 2.0 SP metadata". Click to inspect the metadata for your SP. Send this
- metadata document to the IdP and ask them to load it.</para>
-
- <screenshot>
- <screeninfo>Example of automatically generated SAML 2.0
- Metadata</screeninfo>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="resources/simplesamlphp-sp/saml2metadata.png" />
- </imageobject>
- </mediaobject>
- </screenshot>
-
- <para>If you are connected to Feide, and put one of Feides entity IDs as
- default IdP, you will see an additional section on this page:</para>
-
- <screenshot>
- <screeninfo>Sending metadata to Feide</screeninfo>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="resources/simplesamlphp-sp/saml2metadata-feide.png" />
- </imageobject>
- </mediaobject>
- </screenshot>
-
- <para>Enter your email address and click the button "Send my metadata to
- Feide". Remeber to get in contact with Feide to discuss your new
- service, and how you can be connected to Feide's test environment. To
- test your service, you must have a valid Feide login name. If you are
- not affiliated with a Feide host institution, you may obtain a test user
- identity from Feide.</para>
- </section>
- </section>
-
- <section>
- <title>Test the SAML 2.0 SP examples</title>
-
- <para>After you have installed simpleSAMLphp, configured Apache, set up
- metadata and exchanged metadata with the IdP, you are ready to test the
- sample service included in the simpleSAMLphp distribution.</para>
-
- <para>The installation page of simpleSAMLphp has a link to a Shibboleth
- 1.3 and a SAML 2.0 sample service. When you click the link, you should be
- automatically redirected to the IdP. Login, and you should be sent back
- and shown all the attributes sent form the IdP.</para>
-
- <figure>
- <title>Screenshot of the status page after an user have succesfully
- authenticated</title>
-
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="resources/simplesamlphp-sp/screenshot-example.png" />
- </imageobject>
- </mediaobject>
- </screenshot>
- </figure>
- </section>
-
- <section>
- <title>Integrating authentication with your own application</title>
-
- <para>For those web resources you want to protect, you must add a few
- lines of PHP code:</para>
-
- <itemizedlist>
- <listitem>
- <para>Check whether the user is already authenticated.</para>
- </listitem>
-
- <listitem>
- <para>If the user is not authenticated, but should be for this
- resource, redirect him to the <filename>initSSO.php</filename> script
- with the appropriate parameters. Note particularly the
- <literal>RelayState</literal> specifying the treturn URL after
- login.</para>
- </listitem>
-
- <listitem>
- <para>If authentication is successful, but you need to determine the
- user's authorization, read the user attributes supplied by the IdP
- from the session object. If you need user attributes beyond those
- supplied by the IdP, you may maintain an exteded user description in
- you own database, using the (authenticated) user ID as a key.</para>
- </listitem>
- </itemizedlist>
-
- <para>Sample code:</para>
-
- <para>We start off with including a common file _include.php. All this
- file does is to add simpleSAMLphp to the classpath. Alternately, this can
- be configured in <filename>php.ini</filename>, or the contents of
- <filename>_include.php</filename> can be included directly in the
- application code.</para>
-
- <para></para>
-
- <programlisting>require_once('../_include.php');</programlisting>
-
- <para>Including class specifications. This is for SAML 2.0; for Shibboleth
- look at the Shibboleth example in
- <filename>www/example-simple/shib13-example.php</filename>.</para>
-
- <programlisting>require_once('SimpleSAML/Utilities.php');
-require_once('SimpleSAML/Session.php');
-require_once('SimpleSAML/XHTML/Template.php');
-</programlisting>
-
- <para>Enable PHP Sessions and load configuration with simpleSAMLphp. You
- can copy this lines into your application without changes:</para>
-
- <programlisting>/* Load simpleSAMLphp, configuration and metadata */
-$config = SimpleSAML_Configuration::getInstance();
-$session = SimpleSAML_Session::getInstance();</programlisting>
-
- <para>Then check whether the session is valid. If not, redirect the user
- to the IdP, specifying the <filename>initSSO.php</filename> script (for
- SAML 2.0 or Shibboleth 1.3, respectively). adding the current URL as a
- <literal>RelayState</literal> parameter. The user will leave your web page
- temporarily. When he returns after successful authentication, there will
- be a valid session, and the body of the <code>if</code> statement is
- skipped.</para>
-
- <para>After successful athentication, user attributes supplied by the IdP
- are available in session object. To take a closer look at the attributes
- array, you may print it out...</para>
-
- <programlisting>/* Check if valid local session exists.. */
-if (!isset($session) || !$session->isValid('saml2') ) {
- SimpleSAML_Utilities::redirect(
- '/' . $config->getBaseURL() .
- 'saml2/sp/initSSO.php',
- array('RelayState' => SimpleSAML_Utilities::selfURL())
- );
-}
-
-$attributes = $session->getAttributes();
-print_r($attributes);
-</programlisting>
-
- <para>(Obviously, printing out all attributes this way would be done in a
- test phase only!)</para>
-
- <para>Each attribute name can be used as an index into $attributes to
- obtain the value. Every attribute value is an array - a single-valued
- attribute is an array of a single element.</para>
-
- <section>
- <title>Upgrading service integration from version 0.5 to 1.0</title>
-
- <itemizedlist>
- <listitem>
- <para><ulink
- url="https://ow.feide.no/simplesamlphp:spupgrade05to10">Wiki page
- describing the differences between integrating a service with
- simpleSAMLphp 0.5 and simpleSAMLphp 1.0.</ulink></para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-
- <section>
- <title>Support</title>
-
- <para>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.</para>
-
- <itemizedlist>
- <listitem>
- <para><ulink url="http://rnd.feide.no/simplesamlphp">simpleSAMLphp
- homepage (at Feide RnD)</ulink></para>
- </listitem>
-
- <listitem>
- <para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
- all available simpleSAMLphp documentation</ulink></para>
- </listitem>
-
- <listitem>
- <para><ulink
- url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">Join
- the simpleSAMLphp user's mailing list</ulink></para>
- </listitem>
-
- <listitem>
- <para><ulink url="https://ow.feide.no/simplesamlphp:start">Visit and
- contribute to the simpleSAMLphp wiki</ulink></para>
- </listitem>
- </itemizedlist>
- </section>
-
- <appendix id="a.fingerprint">
- <title>Calculating the fingerprint of a certificate</title>
-
- <para>If you have obtained a certificate file, and want to calculate the
- fingerprint of the file, you can use the <literal>openssl</literal>
- command:</para>
-
- <screen>$ cat server.crt|openssl x509 -fingerprint
-MD5 Fingerprint=D1:BA:B0:17:66:6D:7F:42:7B:91:1E:22:7E:3A:27:D2
-</screen>
- </appendix>
-</article>
\ No newline at end of file