diff --git a/docs/simplesamlphp-idp.txt b/docs/simplesamlphp-idp.txt
new file mode 100644
index 0000000000000000000000000000000000000000..e68824a68a153f08e0e5c2c801ab28f89f7e49af
--- /dev/null
+++ b/docs/simplesamlphp-idp.txt
@@ -0,0 +1,808 @@
+SimpleSAMLphp as an Identity Provider
+===========================================
+
+<!--
+ 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 bottom is showing green light.
+
+Enabling the Identity Provider functionality
+--------------------------------------------
+
+Edit `config.php`, and enable either the SAML 2.0 IdP or the Shib
+1.3 IdP, depending on your needs. By default, SAML 2.0 SP IdP
+functionality is enabled. Here is an example of SAML 2.0 IdP
+enabled:
+
+ 'enable.saml20-sp' => false,
+ 'enable.saml20-idp' => true,
+ 'enable.shib13-sp' => false,
+ 'enable.shib13-idp' => false,
+
+Authentication modules
+----------------------
+
+In the `www/auth` directory, each file represents an authentication
+module. The IdP hosted metadata configuration specifies which
+authentication module to use for that specific IdP. You can
+implement your own authentication module, see
+[Appendix A, *Writing your own authentication module*](#sect.customauth).
+
+These authentication modules are included:
+
+auth/login.php
+: This is the standard LDAP backend authentication module. It
+ uses LDAP configuration from the `config.php` file.
+
+auth/login-ldapmulti.php
+: This authentication module lets you connect to multiple LDAPs
+ depending on the home organization selected by the user.
+
+auth/login-feide.php
+: A multi-LDAP module which looks up the users in LDAP, first
+ searching for `eduPersonPrincipalName`.
+
+auth/login-radius.php
+: This authentication module will authenticate users against an
+ RADIUS server instead of LDAP.
+
+auth/login-auto.php
+: This module will automatically login the user with some test
+ details. You can use this to test the IdP functionality if you do
+ not have
+
+: This module is not completed yet. Work in progress.
+
+auth/login-cas-ldap.php
+: Authentication via CAS, followed by attribute lookup in LDAP.
+
+auth/login-tlsclient.php
+: Authentication via client certificates. (using the apache SSL
+ module)
+
+
+## Configuring the LDAP authentication module
+
+The LDAP module is found in `auth/login.php`.
+
+If you want to perform local authentication using this server,
+using the LDAP authentication plugin, the following parameters
+should be configured in `config/ldap.php`:
+
+-
+ `auth.ldap.dnpattern`: Which DN to bind to. `%username%` is
+ replaced with the user name typed in.
+
+- `auth.ldap.hostname`: Host name of the LDAP server
+
+-
+ `auth.ldap.attributes`: Search parameter to LDAP. List of
+ attributes to be extracted. Set this option to `null` to retrieve
+ all attributes available.
+
+-
+ `auth.ldap.enable_tls`: Will perform `ldap_start_tls()` after
+ creation the connectino to the LDAP server.
+
+
+### Searching for the user's DN
+
+It is possible to search for the DN of the user by matching the
+username provided by the user against one or more attributes. This
+feature is configured by the following options in
+`config/ldap.php`:
+
+-
+ `auth.ldap.search.enable`: Whether searching for the user's DN
+ should be enabled. Set this to `TRUE` to enable searching.
+
+-
+ `auth.ldap.search.base`: The DN we should search for the user in.
+
+-
+ `auth.ldap.search.attributes`: The attributes we shoule match the
+ username against. This can be a single attribute, in which case it
+ should be a string, or multiple attributes, in which case it should
+ be an array of strings.
+
+ If this is multiple attributes, they will be joined into a search
+ query with the following form:
+ `(|(<attr1>=<username>)(<attr2>=<username>)...)`
+
+-
+ `auth.ldap.search.username`: The user we should authenticate to the
+ LDAP server as before searching. Leave this as `NULL` if it isn't
+ necessary to authenticate to the server before searching.
+
+-
+ `auth.ldap.search.password`: The password for the user selected
+ with the `auth.ldap.search.username` option.
+
+
+**Example 1. Configuring LDAP for searching**
+
+ $config = array (
+ 'auth.ldap.hostname' => 'ldap.example.org',
+ 'auth.ldap.attributes' => NULL,
+ 'auth.ldap.enable_tls' => FALSE,
+
+ /* Enable searching. */
+ 'auth.ldap.search.enable' => TRUE,
+
+ /* The base DN for the search. */
+ 'auth.ldap.search.base' => 'cn=users,dc=example,dc=org',
+
+ /* The user can authenticate using the uid or the email address. */
+ 'auth.ldap.search.attributes' => array('uid', 'mail'),
+
+ 'auth.ldap.search.username' => 'uid=authsearch,cn=server,dc=example,dc=org',
+ 'auth.ldap.search.password' => 'secret',
+ );
+
+## Configure the tlsclient authenticaiton module
+
+Configure apache like this:
+
+ SSLEngine On
+ SSLCertificateFile /etc/ssl/private/bridge.pem
+ SSLCertificateKeyFile /etc/ssl/private/bridge.key
+ SSLCertificateChainFile /etc/ssl/certs/sureserverEDU.pem
+ SSLOptions +StdEnvVars +ExportCertData
+ KeepAliveTimeout 60
+ SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
+
+ SSLCACertificateFile "/etc/ssl/private/tlsclienttest-ca.crt"
+ SSLVerifyClient optional
+ SSLVerifyDepth  1
+
+And, then configure the identity provider to use the authentication
+module: `auth/login-tlsclient.php`.
+
+## Configuring the multi-LDAP authenticaiton module
+
+The module is found in `auth/login-ldapmulti.php`.
+
+## Note
+
+Documentation will be added later. For now, contact the author.
+
+## Configuring the 'login-CAS-LDAP' module for authentication
+
+If you want to connect your identity provider using either CAS or
+CAS in combination with LDAP (for attribute retrieval), you may use
+the login-cas-ldap module. It is found in
+`auth/login-cas-ldap.php`.
+
+The following parameters should be configured in
+config/cas-ldap.php:
+
+-
+ make an entry for each identity provider using the identity ID as
+ key
+
+-
+ you should make a sub entry with 'cas' as key and the following
+ parameters:
+
+ login
+ : the url of the login service of the CAS server
+
+
+
+We recomment you always use 'renew=true'v to be able to comply with
+a SAML2 'force-auth' request. In addition you may configure either
+a 'validate' or a 'serviceValdate' (simpleSAMLphp supports both CAS
+ver.1 and ver.2).
+
+'validate' is the CAS ver.1 YES/NO\\r\<username>style validation
+which only returns a user name to simpleSAMLphp and which requires
+subsequent use of LDAP to retrieve the attributes. The value of
+this parameter is the url of the validate service of the CAS
+server.
+
+'serviceValidate' is the url of the CAS servers' ver.2 validation.
+In some cases the CAS server returns attributes in non-standard XML
+format. The login-cas-ldap module allows you to map a list of
+attribute names to Xpath expressions which are returned to
+simpleSAMLphp from the auth-module. The list is named 'attributes'
+(see example for further information).
+
+If you want to use LDAP for retrieving attributes you should make
+sub entry with 'ldap' as key and the following parameters:
+
+servers
+: a space separated list of urls in OpelLDAP format (see
+ example)
+
+starttls
+: (set to true to secure (encrypt) the LDAP connection)
+
+searchbase
+: the starting point for the LDAP search (simpleSAMLphp always
+ uses sub-tree search)
+
+searchattributes
+: an array of attribute names to search for (when used in this
+ combination with CAS only one value is needed)
+
+dnpattern
+: a pattern for a dn for the user where %username% is replaced
+ with the actual user name for constructing the dn of the users'
+ entry. If used no search for the user is performed and the
+ constructed dn is used in stead.
+
+attributes
+: the list of attributes retrieved from the users' entry
+
+priv\_user\_dn (optional)
+: the dn of a priviliged user who is allowed to search and read
+ the whole LDAP sub-tree for the user if anonynous search and read
+ is not allowed
+
+priv\_user\_pw (optional)
+: the password of the priviiliged user
+
+
+Samle configuration:
+
+ $casldapconfig = array (
+ 'idpentityid.example.org' => array(
+ 'cas' => array(
+ 'login' => 'https://idpentityid.example.org/cas/login',
+ 'validate' => 'https://idpentityid.example.org/cas/validate',
+ ),
+ 'ldap' => array(
+ 'servers' => 'idpentityid.example.org',
+ 'enable_tls' => false,
+ 'searchbase' => 'dc=example,dc=org',
+ 'searchattributes' => 'uid',
+ 'attributes' => array('cn', 'mail'),
+ ),
+ ),
+ 'idpentityid2.example.org' => array(
+ 'cas' => array(
+ 'login' => 'https://idpentityid2.example.org/login',
+ 'validate' => 'https://idpentityid2.example.org/validate',
+ ),
+ 'ldap' => array(
+ 'servers' => 'ldap://idpentityid2.example.org',
+ 'enable_tls' => false,
+ 'searchbase' => 'ou=users,dc=example,dc=org',
+ 'searchattributes' => array('uid', 'mail'), # array for being able to login with either uid or mail.
+ 'attributes' => null,
+ 'priv_user_dn' => 'uid=admin,ou=users,dc=example,dc=org',
+ 'priv_user_pw' => 'xxxxx',
+ ),
+ ),
+
+ );
+
+
+Setting up an SSL signing certificate
+------------------------------------
+
+For test purposes, you can skip this section, and use the
+certificate included in the simpleSAMLphp distribution.
+
+For a production system, you must generate a new certificate for
+your IdP.
+
+## Warning
+
+The certificate that follows the simpleSAMLphp distribution must
+*NEVER* be used in production, as the private key is also included
+in the package and can be downloaded by anyone.
+
+Here is an examples of openssl commands to generate a new key and a
+selfsigned certificate to use for signing SAML messages:
+
+ openssl genrsa -des3 -out server2.key 1024
+ openssl rsa -in server2.key -out server2.pem
+ openssl req -new -key server2.key -out server2.csr
+ openssl x509 -req -days 60 -in server2.csr -signkey server2.key -out server2.crt
+
+The certificate above will be valid for 60 days.
+
+## Note
+
+simpleSAMLphp will only work with RSA and not DSA certificates.
+
+
+Configuring metadata for an SAML 2.0 IdP
+----------------------------------------
+
+To setup a SAML 2.0 IdP you must configure two metadata files:
+`saml20-idp-hosted.php` and `saml20-sp-remote.php`.
+
+## Configuring SAML 2.0 IdP Hosted metadata
+
+This is the configuration of the IdP itself. Here is some example
+config:
+
+ // The SAML entity ID is the index of this config.
+ 'idp.example.org' => array(
+
+ // The hostname of the server (VHOST) that this SAML entity will use.
+ 'host' => 'sp.example.org',
+
+ // X.509 key and certificate. Relative to the cert directory.
+ 'privatekey' => 'server.pem',
+ 'certificate' => 'server.crt',
+
+ // Authentication plugin to use. login.php is the default one that uses LDAP.
+ 'auth' => 'auth/login.php',
+ 'authority' => 'login',
+ ),
+
+Parameter details:
+
+### Mandatory metadata fields
+
+index in the `$metadata` array
+: The entity ID of the IdP. In this example: `idp.example.org`.
+
+: 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/idp/metadata.php
+
+host
+: Host name of the server running this IdP. One of your metadata
+ entries can have the value `__DEFAULT__`. A default entry will be
+ used when no other entry matches the current hostname.
+
+privatekey
+: Name of private key file in PEM format, in the `certs`
+ directory.
+
+certificate
+: Name of certificate file in PEM format, in the `certs`
+ directory.
+
+auth
+: Which authentication module to use. Default:
+ `auth/login.php,`the LDAP authentication module.
+
+
+### Optional metadata fields
+
+privatekey\_pass
+: Passphrase for the private key.
+
+requireconsent
+: Set to true if you want to require user's consent each time
+ attributes are sent to an SP.
+
+authority
+: Who is authorized to create sessions for this IdP. Can be
+ `login` for LDAP login module, or `saml2` for SAML 2.0 SP.
+ Specifying this parameter is highly recommended.
+
+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.
+
+userid.attribute
+: The attribute name of an attribute which uniquely identifies
+ the user. This attribute is used if simpleSAMLphp needs to generate
+ a persistent unique identifier for the user. This option can be set
+ in both the IdP-hosted and the SP-remote metadata. The value in the
+ sp-remote metadata has the highest priority. The default value is
+ `eduPersonPrincipalName`.
+
+AttributeNameFormat
+: What value will be set in the Format field of attribute
+ statements. This parameter can be configured multiple places, and
+ the actual value used is fetched from metadata by the following
+ priority:
+
+: 1. SP Remote Metadata
+
+ 2. IdP Hosted Metadata
+
+ 3.
+ Default value:
+ `urn:oasis:names:tc:SAML:2.0:attrname-format:basic`
+
+
+: Some examples of values specified in the SAML 2.0 Core
+ Specification:
+
+: - `urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified`
+
+ -
+ `urn:oasis:names:tc:SAML:2.0:attrname-format:uri` (Used as default
+ in Shibboleth 2.0)
+
+ -
+ `urn:oasis:names:tc:SAML:2.0:attrname-format:basic` (Used as
+ default in Sun Access Manager)
+
+ - You can define your own value.
+
+
+SingleSignOnService
+: Override the default URL for the SingleSignOnService for this
+ IdP. This is an absolute URL. The default value is
+ `<simpleSAMLphp-root>/saml2/idp/SSOService.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
+ IdP. This is an absolute URL. The default value is
+ `<simpleSAMLphp-root>/saml2/idp/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.
+
+privacypolicy
+: This is an absolute URL for where an user can find a
+ privacypolicy. If set, this will be shown on the consent page.
+ `%SPENTITYID%` in the URL will be replaced with the entity id of
+ the service the user is accessing.
+
+
+### Fields for signing and validating messages
+
+simpleSAMLphp only signs authentication responses by default.
+Signing of 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.
+
+These options set the default for this IdP, but options for each SP
+can be set in `saml20-sp-remote`.
+
+redirect.sign
+: Boolean, default `false`. To turn on signing of logout requests
+ and logout responses, set this flag to true.
+
+: This option can be overridden by the `redirect.sign` option in
+ `saml20-sp-remote`.
+
+redirect.validate
+: Boolean, default `false`. To turn on validation of received
+ authentication requests, logout requests and logout responses, set
+ this flag to true.
+
+: This option can be overridden by the `redirect.validate` option
+ in `saml20-sp-remote`.
+
+
+**Example 2. Example of configuration for signed messages**
+
+ 'redirect.sign' => true,
+
+## Configuring SAML 2.0 SP Remote metadata
+
+In the file `saml20-sp-remote.php`, you configure all SPs that you
+trust. Here is an example:
+
+ /*
+ * Example simpleSAMLphp SAML 2.0 SP
+ */
+ 'saml2sp.example.org' => array(
+ 'AssertionConsumerService' => 'https://saml2sp.example.org/simplesaml/saml2/sp/AssertionConsumerService.php',
+ 'SingleLogoutService' => 'https://saml2sp.example.org/simplesaml/saml2/sp/SingleLogoutService.php',
+
+ 'attributes' => array('email', 'eduPersonPrincipalName'),
+ 'name' => 'Example service provider',
+ ),
+
+Parameter details:
+
+### Mandatory metadata fields
+
+index in the `$metadata` array
+: Entity ID of the given SP. Here: `saml2sp.example.org`.
+
+AssertionConsumerService
+: URL of this SAML 2.0 endpoint. Ask the SP if you are uncertain.
+ You may find the endpoint URL in SAML 2.0 metadata received from
+ the SP.
+
+
+### Optional metadata fields
+
+SingleLogoutService
+: URL of this SAML 2.0 endpoint. Ask the SP if you are uncertain.
+ You may find the endpoint URL in SAML 2.0 metadata received from
+ the SP.
+
+NameIDFormat
+: Set it to the default: `transient`.
+
+SPNameQualifier
+: SP NameQualifier for this SP. If not set, the IdP will set the
+ SPNameQualifier to be the SP entity ID.
+
+AttributeNameFormat
+: What value will be set in the Format field of attribute
+ statements. This parameter can be configured multiple places, and
+ the actual value used is fetched from metadata by the following
+ priority:
+
+: 1. SP Remote Metadata
+
+ 2. IdP Hosted Metadata
+
+ 3.
+ Default value:
+ `urn:oasis:names:tc:SAML:2.0:attrname-format:basic`
+
+
+: Some examples of values specified in the SAML 2.0 Core
+ Specification:
+
+: - `urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified`
+
+ -
+ `urn:oasis:names:tc:SAML:2.0:attrname-format:uri` (Used as default
+ in Shibboleth 2.0)
+
+ -
+ `urn:oasis:names:tc:SAML:2.0:attrname-format:basic` (Used as
+ default in Sun Access Manager)
+
+ - You can define your own value.
+
+
+base64attributes
+: Boolean, default `false`: Perform base64 encoding of attributes
+ sent to this SP. This parameter must be set according to what the
+ SP expects.
+
+simplesaml.nameidattribute
+: If the `NameIDFormat` is set to `email`, then the email address
+ is extracted from the attribute with this name. E.g. if
+ `simplesaml.nameidattribute` is set to uid, and the authentcation
+ module provides an attribute named `uid`, this attribute value is
+ set as the NameID.
+
+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.
+
+simplesaml.attributes
+: Boolean, default `true`: Send an attribute statement to the
+ SP.
+
+name
+: A descriptive name of the SP. This can be a string, or an
+ associative array with language code => translation pairs.
+
+description
+: A longer description of the SP. This can be a string, or an
+ associative array with language code => translation pairs.
+
+certificate
+: Name of certificate file for verifying the signature when
+ `redirect.validate` is set to `true`.
+
+ForceAuthn
+: Set this `true` to force authentication when receiving
+ authentication requests from this SP. The default is `false`.
+
+assertion.enctyption
+: Boolean, default `false`. Defines whether this IdP shoul
+ encrypt assertions to this SP.
+
+sharedkey
+: Used for optional symmetric encryption of assertions. Currently
+ the algorithm is hardcoded to AES128\_CBC/RIJNDAEL\_128 which uses
+ up to 128 bit for the passphrase/key. If you want to use a
+ sessionkey which is encrypted by this idp's private key do not
+ specify a sharedkey.
+
+userid.attribute
+: The attribute name of an attribute which uniquely identifies
+ the user. This attribute is used if simpleSAMLphp needs to generate
+ a persistent unique identifier for the user. This option can be set
+ in both the IdP-hosted and the SP-remote metadata. The value in the
+ sp-remote metadata has the highest priority. The default value is
+ `eduPersonPrincipalName`.
+
+signresponse
+: The default behaviour of simpleSAMLphp is to sign the Assertion
+ element in the SAML 2.0 response sent to SPs. This option allows
+ you to override this behaviour on a per SP basis. Set this to
+ `TRUE` to sign the Response element. `FALSE` will make the SP sign
+ the Assertion. If this option is unset, the value from
+ `saml2.signresponse` in `config.php` will be used. That value is
+ `FALSE` by default.
+
+privacypolicy
+: This is an absolute URL for where an user can find a
+ privacypolicy for this SP. If set, this will be shown on the
+ consent page. `%SPENTITYID%` in the URL will be replaced with the
+ entity id of this service provider.
+
+
+### Fields for signing and validating messages
+
+simpleSAMLphp only signs authentication responses by default.
+Signing of 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.
+
+These options overrides the options set in `saml20-idp-hosted`.
+
+redirect.sign
+: Boolean, default `false`. To turn on signing of logout requests
+ and logout responses, set this flag to true.
+
+: This option overrides the `redirect.sign` option in
+ `saml20-idp-hosted`.
+
+redirect.validate
+: Boolean, default `false`. To turn on validation of received
+ authentication requests, logout requests and logout responses, set
+ this flag to true.
+
+: This option overrides the `redirect.validate` option in
+ `saml20-idp-hosted`.
+
+
+**Example 3. Example of configuration for validating messages**
+
+ 'redirect.validate' => true,
+ 'certificate' => 'server.crt'
+
+
+
+Configuring metadata for a Shibboleth 1.3 IdP
+---------------------------------------------
+
+In the file `shib13-idp-hosted.php`, you configure metadata for the
+Shibboleth 1.3 IdP. In the file `shib13-sp-remote.php`, you
+configurethe list of trusted SPs using the Shibboleth 1.3 protocol.
+This configuration is very similar to configuring SAML 2.0
+metadata; please find information in the previous chapter.
+
+## Scoped attributes
+
+It is possible to configure some attributes to be scoped, and
+include the Scope-attribute on the attribute values. This is
+enabled by setting the `scopedattributes`-option in either
+`shib13-sp-remote.php` or `shib13-idp-hosted.php`. If both are
+defined, the SP configuration is used.
+
+This option is an array of the names of attributes which should be
+treated as scoped. The matching is case-sensitive. A scoped
+attribute will be split on the first `@`-sign, and the first part
+will be used as the attribute value, while the last part will be
+used as the scope.
+
+ /*
+ * Example of scopedattributes option. Will use scoped attribute for eduPersonPrincipalName.
+ */
+ 'scopedattributes' => array('eduPersonPrincipalName'),
+
+Test IdP
+--------
+
+To test the IdP, it is best to configure two hosts with
+simpleSAMLphp, and use the SP demo example to test the IdP.
+
+## Tip
+
+To make the initial test up and running with minimal hassle, use
+the login-auto if you do not want to setup a user storage, and use
+the included certificate so you do not need to create a new one.
+
+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. Writing your own authentication module
+----------------------------------------------
+
+You can write your own authentication module. Just copy one of the
+files in the www/auth directory and play with it, then configure an
+IdP to use that module with the auth parameter in the metadata. The
+file must support incoming URL parameters, massage the session
+object with login state information and return to the RelayState,
+and that is all you need to do!
+
+## Tip
+
+Instead of changing the code of the builtin authentication module,
+copy it into a new file and edit that. That way, your module will
+not be replaced or in conflict when you upgrade simpleSAMLphp to a
+newer version.
+
+## Authentication API
+
+The authentication plugin should be placed in the `auth`
+directory.
+
+The following parameters must be accepted in the incoming URL:
+
+-
+ `RelayState`: URL where the user is sent after authentication
+ within the plugin.
+
+- `RequestID`: ID of an incoming request.
+
+
+The initSSO.php takes in addition the following parameters:
+
+-
+ `idpentityid`: This is the entityid of the IdP to authenticate
+ with. This parameter is optional, if not set the default for this
+ host will be used.
+
+-
+ `spentityid`: This is which SP config to use. This parameter is
+ optional, if not set the default for this host will be used.
+
+
+In hosted IdP metadata there is a config parameter auth that will
+tell simpleSAML which authentication plugin that can beu sed.
+
+## Tip
+
+The authentication API is pretty basic. The easiest way to
+understand how it works is to look at one of the existing plugins
+that is located in the auth directory of your installation.
+
+
+
diff --git a/docs/source/simplesamlphp-idp.xml b/docs/source/simplesamlphp-idp.xml
deleted file mode 100644
index 909de27b3474fa428d6cf9c4996460145fd842fd..0000000000000000000000000000000000000000
--- a/docs/source/simplesamlphp-idp.xml
+++ /dev/null
@@ -1,1264 +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 an identity provider</title>
-
- <articleinfo>
- <date>2007-10-15</date>
-
- <pubdate>Sun Nov 2 14:35:35 2008</pubdate>
-
- <author>
- <firstname>Andreas Ă…kre</firstname>
-
- <surname>Solberg</surname>
-
- <email>andreas.solberg@uninett.no</email>
- </author>
-
- <author>
- <firstname>Mads</firstname>
-
- <surname>Freek</surname>
- </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 bottom is showing green light.</para>
- </section>
-
- <section>
- <title>Enabling the Identity Provider functionality</title>
-
- <para>Edit <filename>config.php</filename>, and enable either the SAML 2.0
- IdP or the Shib 1.3 IdP, depending on your needs. By default, SAML 2.0 SP
- IdP functionality is enabled. Here is an example of SAML 2.0 IdP
- enabled:</para>
-
- <programlisting>'enable.saml20-sp' => false,
-'enable.saml20-idp' => true,
-'enable.shib13-sp' => false,
-'enable.shib13-idp' => false,</programlisting>
- </section>
-
- <section>
- <title>Authentication modules</title>
-
- <para>In the <filename>www/auth</filename> directory, each file represents
- an authentication module. The IdP hosted metadata configuration specifies
- which authentication module to use for that specific IdP. You can
- implement your own authentication module, see <xref
- linkend="sect.customauth" />.</para>
-
- <para>These authentication modules are included:</para>
-
- <para><glosslist>
- <glossentry>
- <glossterm>auth/login.php</glossterm>
-
- <glossdef>
- <para>This is the standard LDAP backend authentication module. It
- uses LDAP configuration from the <filename>config.php</filename>
- file.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>auth/login-ldapmulti.php</glossterm>
-
- <glossdef>
- <para>This authentication module lets you connect to multiple
- LDAPs depending on the home organization selected by the
- user.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>auth/login-feide.php</glossterm>
-
- <glossdef>
- <para>A multi-LDAP module which looks up the users in LDAP, first
- searching for <literal>eduPersonPrincipalName</literal>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>auth/login-radius.php</glossterm>
-
- <glossdef>
- <para>This authentication module will authenticate users against
- an RADIUS server instead of LDAP.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>auth/login-auto.php</glossterm>
-
- <glossdef>
- <para>This module will automatically login the user with some test
- details. You can use this to test the IdP functionality if you do
- not have</para>
-
- <para>This module is not completed yet. Work in progress.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>auth/login-cas-ldap.php</glossterm>
-
- <glossdef>
- <para>Authentication via CAS, followed by attribute lookup in
- LDAP.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>auth/login-tlsclient.php</glossterm>
-
- <glossdef>
- <para>Authentication via client certificates. (using the apache
- SSL module)</para>
- </glossdef>
- </glossentry>
- </glosslist></para>
-
- <section>
- <title>Configuring the LDAP authentication module</title>
-
- <para>The LDAP module is found in
- <filename>auth/login.php</filename>.</para>
-
- <para>If you want to perform local authentication using this server,
- using the LDAP authentication plugin, the following parameters should be
- configured in <filename>config/ldap.php</filename>:</para>
-
- <itemizedlist>
- <listitem>
- <para><literal>auth.ldap.dnpattern</literal>: Which DN to bind to.
- <literal>%username%</literal> is replaced with the user name typed
- in.</para>
- </listitem>
-
- <listitem>
- <para><literal>auth.ldap.hostname</literal>: Host name of the LDAP
- server</para>
- </listitem>
-
- <listitem>
- <para><literal>auth.ldap.attributes</literal>: Search parameter to
- LDAP. List of attributes to be extracted. Set this option to
- <literal>null</literal> to retrieve all attributes available.</para>
- </listitem>
-
- <listitem>
- <para><literal>auth.ldap.enable_tls</literal>: Will perform
- <code>ldap_start_tls()</code> after creation the connectino to the
- LDAP server.</para>
- </listitem>
- </itemizedlist>
-
- <section>
- <title>Searching for the user's DN</title>
-
- <para>It is possible to search for the DN of the user by matching the
- username provided by the user against one or more attributes. This
- feature is configured by the following options in
- <filename>config/ldap.php</filename>:</para>
-
- <itemizedlist>
- <listitem>
- <para><literal>auth.ldap.search.enable</literal>: Whether
- searching for the user's DN should be enabled. Set this to
- <literal>TRUE</literal> to enable searching.</para>
- </listitem>
-
- <listitem>
- <para><literal>auth.ldap.search.base</literal>: The DN we should
- search for the user in.</para>
- </listitem>
-
- <listitem>
- <para><literal>auth.ldap.search.attributes</literal>: The
- attributes we shoule match the username against. This can be a
- single attribute, in which case it should be a string, or multiple
- attributes, in which case it should be an array of strings.</para>
-
- <para>If this is multiple attributes, they will be joined into a
- search query with the following form:
- <literal>(|(<attr1>=<username>)(<attr2>=<username>)...)</literal></para>
- </listitem>
-
- <listitem>
- <para><literal>auth.ldap.search.username</literal>: The user we
- should authenticate to the LDAP server as before searching. Leave
- this as <literal>NULL</literal> if it isn't necessary to
- authenticate to the server before searching.</para>
- </listitem>
-
- <listitem>
- <para><literal>auth.ldap.search.password</literal>: The password
- for the user selected with the
- <literal>auth.ldap.search.username</literal> option.</para>
- </listitem>
- </itemizedlist>
-
- <example>
- <title>Configuring LDAP for searching</title>
-
- <programlisting>$config = array (
- 'auth.ldap.hostname' => 'ldap.example.org',
- 'auth.ldap.attributes' => NULL,
- 'auth.ldap.enable_tls' => FALSE,
-
- /* Enable searching. */
- 'auth.ldap.search.enable' => TRUE,
-
- /* The base DN for the search. */
- 'auth.ldap.search.base' => 'cn=users,dc=example,dc=org',
-
- /* The user can authenticate using the uid or the email address. */
- 'auth.ldap.search.attributes' => array('uid', 'mail'),
-
- 'auth.ldap.search.username' => 'uid=authsearch,cn=server,dc=example,dc=org',
- 'auth.ldap.search.password' => 'secret',
-);</programlisting>
- </example>
- </section>
- </section>
-
- <section>
- <title>Configure the tlsclient authenticaiton module</title>
-
- <para>Configure apache like this:</para>
-
- <programlisting> SSLEngine On
- SSLCertificateFile /etc/ssl/private/bridge.pem
- SSLCertificateKeyFile /etc/ssl/private/bridge.key
- SSLCertificateChainFile /etc/ssl/certs/sureserverEDU.pem
- SSLOptions +StdEnvVars +ExportCertData
- KeepAliveTimeout 60
- SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
-
- SSLCACertificateFile "/etc/ssl/private/tlsclienttest-ca.crt"
- SSLVerifyClient optional
- SSLVerifyDepth  1</programlisting>
-
- <para>And, then configure the identity provider to use the
- authentication module:
- <filename>auth/login-tlsclient.php</filename>.</para>
- </section>
-
- <section>
- <title>Configuring the multi-LDAP authenticaiton module</title>
-
- <para>The module is found in
- <filename>auth/login-ldapmulti.php</filename>.</para>
-
- <note>
- <para>Documentation will be added later. For now, contact the
- author.</para>
- </note>
- </section>
-
- <section>
- <title>Configuring the 'login-CAS-LDAP' module for
- authentication</title>
-
- <para>If you want to connect your identity provider using either CAS or
- CAS in combination with LDAP (for attribute retrieval), you may use the
- login-cas-ldap module. It is found in
- <filename>auth/login-cas-ldap.php</filename>.</para>
-
- <para>The following parameters should be configured in
- config/cas-ldap.php:</para>
-
- <itemizedlist>
- <listitem>
- <para>make an entry for each identity provider using the identity ID
- as key</para>
- </listitem>
-
- <listitem>
- <para>you should make a sub entry with 'cas' as key and the
- following parameters:</para>
-
- <glosslist>
- <glossentry>
- <glossterm>login</glossterm>
-
- <glossdef>
- <para>the url of the login service of the CAS server</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </listitem>
- </itemizedlist>
-
- <para>We recomment you always use 'renew=true'v to be able to comply
- with a SAML2 'force-auth' request. In addition you may configure either
- a 'validate' or a 'serviceValdate' (simpleSAMLphp supports both CAS
- ver.1 and ver.2).</para>
-
- <para>'validate' is the CAS ver.1 YES/NO\r<username>style
- validation which only returns a user name to simpleSAMLphp and which
- requires subsequent use of LDAP to retrieve the attributes. The value of
- this parameter is the url of the validate service of the CAS
- server.</para>
-
- <para>'serviceValidate' is the url of the CAS servers' ver.2 validation.
- In some cases the CAS server returns attributes in non-standard XML
- format. The login-cas-ldap module allows you to map a list of attribute
- names to Xpath expressions which are returned to simpleSAMLphp from the
- auth-module. The list is named 'attributes' (see example for further
- information).</para>
-
- <para>If you want to use LDAP for retrieving attributes you should make
- sub entry with 'ldap' as key and the following parameters:</para>
-
- <glosslist>
- <glossentry>
- <glossterm>servers</glossterm>
-
- <glossdef>
- <para>a space separated list of urls in OpelLDAP format (see
- example)</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>starttls</glossterm>
-
- <glossdef>
- <para>(set to true to secure (encrypt) the LDAP connection)</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>searchbase</glossterm>
-
- <glossdef>
- <para>the starting point for the LDAP search (simpleSAMLphp always
- uses sub-tree search)</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>searchattributes</glossterm>
-
- <glossdef>
- <para>an array of attribute names to search for (when used in this
- combination with CAS only one value is needed)</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>dnpattern</glossterm>
-
- <glossdef>
- <para>a pattern for a dn for the user where %username% is replaced
- with the actual user name for constructing the dn of the users'
- entry. If used no search for the user is performed and the
- constructed dn is used in stead.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>attributes</glossterm>
-
- <glossdef>
- <para>the list of attributes retrieved from the users'
- entry</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>priv_user_dn (optional)</glossterm>
-
- <glossdef>
- <para>the dn of a priviliged user who is allowed to search and
- read the whole LDAP sub-tree for the user if anonynous search and
- read is not allowed</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>priv_user_pw (optional)</glossterm>
-
- <glossdef>
- <para>the password of the priviiliged user</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <para>Samle configuration:</para>
-
- <programlisting>$casldapconfig = array (
- 'idpentityid.example.org' => array(
- 'cas' => array(
- 'login' => 'https://idpentityid.example.org/cas/login',
- 'validate' => 'https://idpentityid.example.org/cas/validate',
- ),
- 'ldap' => array(
- 'servers' => 'idpentityid.example.org',
- 'enable_tls' => false,
- 'searchbase' => 'dc=example,dc=org',
- 'searchattributes' => 'uid',
- 'attributes' => array('cn', 'mail'),
- ),
- ),
- 'idpentityid2.example.org' => array(
- 'cas' => array(
- 'login' => 'https://idpentityid2.example.org/login',
- 'validate' => 'https://idpentityid2.example.org/validate',
- ),
- 'ldap' => array(
- 'servers' => 'ldap://idpentityid2.example.org',
- 'enable_tls' => false,
- 'searchbase' => 'ou=users,dc=example,dc=org',
- 'searchattributes' => array('uid', 'mail'), # array for being able to login with either uid or mail.
- 'attributes' => null,
- 'priv_user_dn' => 'uid=admin,ou=users,dc=example,dc=org',
- 'priv_user_pw' => 'xxxxx',
- ),
- ),
-
-);</programlisting>
- </section>
- </section>
-
- <section>
- <title>Setting up a SSL signing certificate</title>
-
- <para>For test purposes, you can skip this section, and use the
- certificate included in the simpleSAMLphp distribution.</para>
-
- <para>For a production system, you must generate a new certificate for
- your IdP.</para>
-
- <warning>
- <para>The certificate that follows the simpleSAMLphp distribution must
- <emphasis>NEVER</emphasis> be used in production, as the private key is
- also included in the package and can be downloaded by anyone.</para>
- </warning>
-
- <para>Here is an examples of openssl commands to generate a new key and a
- selfsigned certificate to use for signing SAML messages:</para>
-
- <screen>openssl genrsa -des3 -out server2.key 1024
-openssl rsa -in server2.key -out server2.pem
-openssl req -new -key server2.key -out server2.csr
-openssl x509 -req -days 60 -in server2.csr -signkey server2.key -out server2.crt</screen>
-
- <para>The certificate above will be valid for 60 days.</para>
-
- <note>
- <para>simpleSAMLphp will only work with RSA and not DSA
- certificates.</para>
- </note>
- </section>
-
- <section>
- <title>Configuring metadata for an SAML 2.0 IdP</title>
-
- <para>To setup a SAML 2.0 IdP you must configure two metadata files:
- <filename>saml20-idp-hosted.php</filename> and
- <filename>saml20-sp-remote.php</filename>.</para>
-
- <section>
- <title>Configuring SAML 2.0 IdP Hosted metadata</title>
-
- <para>This is the configuration of the IdP itself. Here is some example
- config:</para>
-
- <programlisting>// The SAML entity ID is the index of this config.
-'idp.example.org' => array(
-
- // The hostname of the server (VHOST) that this SAML entity will use.
- 'host' => 'sp.example.org',
-
- // X.509 key and certificate. Relative to the cert directory.
- 'privatekey' => 'server.pem',
- 'certificate' => 'server.crt',
-
- // Authentication plugin to use. login.php is the default one that uses LDAP.
- 'auth' => 'auth/login.php',
- 'authority' => 'login',
-),</programlisting>
-
- <para>Parameter details:</para>
-
- <section>
- <title>Mandatory metadata fields</title>
-
- <glosslist>
- <glossentry>
- <glossterm>index in the <code>$metadata</code> array</glossterm>
-
- <glossdef>
- <para>The entity ID of the IdP. In this example:
- <literal>idp.example.org</literal>.</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/idp/metadata.php</literallayout>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>host</glossterm>
-
- <glossdef>
- <para>Host name of the server running this IdP. 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>
-
- <glossentry>
- <glossterm>privatekey</glossterm>
-
- <glossdef>
- <para>Name of private key file in PEM format, in the
- <filename>certs</filename> directory.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>certificate</glossterm>
-
- <glossdef>
- <para>Name of certificate file in PEM format, in the
- <filename>certs</filename> directory.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>auth</glossterm>
-
- <glossdef>
- <para>Which authentication module to use. Default:
- <filename>auth/login.php, </filename>the LDAP authentication
- module.</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </section>
-
- <section>
- <title>Optional metadata fields</title>
-
- <glosslist>
- <glossentry>
- <glossterm>privatekey_pass</glossterm>
-
- <glossdef>
- <para>Passphrase for the private key.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>requireconsent</glossterm>
-
- <glossdef>
- <para>Set to true if you want to require user's consent each
- time attributes are sent to an SP.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>authority</glossterm>
-
- <glossdef>
- <para>Who is authorized to create sessions for this IdP. Can be
- <literal>login</literal> for LDAP login module, or
- <literal>saml2</literal> for SAML 2.0 SP. Specifying this
- parameter is highly recommended.</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>userid.attribute</glossterm>
-
- <glossdef>
- <para>The attribute name of an attribute which uniquely
- identifies the user. This attribute is used if simpleSAMLphp
- needs to generate a persistent unique identifier for the user.
- This option can be set in both the IdP-hosted and the SP-remote
- metadata. The value in the sp-remote metadata has the highest
- priority. The default value is
- <literal>eduPersonPrincipalName</literal>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>AttributeNameFormat</glossterm>
-
- <glossdef>
- <para>What value will be set in the Format field of attribute
- statements. This parameter can be configured multiple places,
- and the actual value used is fetched from metadata by the
- following priority:</para>
-
- <orderedlist>
- <listitem>
- <para>SP Remote Metadata</para>
- </listitem>
-
- <listitem>
- <para>IdP Hosted Metadata</para>
- </listitem>
-
- <listitem>
- <para>Default value:
- <literal>urn:oasis:names:tc:SAML:2.0:attrname-format:basic</literal></para>
- </listitem>
- </orderedlist>
-
- <para>Some examples of values specified in the SAML 2.0 Core
- Specification:</para>
-
- <itemizedlist>
- <listitem>
- <para><literal>urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified</literal></para>
- </listitem>
-
- <listitem>
- <para><literal>urn:oasis:names:tc:SAML:2.0:attrname-format:uri</literal>
- (Used as default in Shibboleth 2.0)</para>
- </listitem>
-
- <listitem>
- <para><literal>urn:oasis:names:tc:SAML:2.0:attrname-format:basic</literal>
- (Used as default in Sun Access Manager)</para>
- </listitem>
-
- <listitem>
- <para>You can define your own value.</para>
- </listitem>
- </itemizedlist>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>SingleSignOnService</glossterm>
-
- <glossdef>
- <para>Override the default URL for the SingleSignOnService for
- this IdP. This is an absolute URL. The default value is
- <literal><simpleSAMLphp-root>/saml2/idp/SSOService.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 IdP. This is an absolute URL. The default value is
- <literal><simpleSAMLphp-root>/saml2/idp/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>privacypolicy</glossterm>
-
- <glossdef>
- <para>This is an absolute URL for where an user can find a
- privacypolicy. If set, this will be shown on the consent page.
- <literal>%SPENTITYID%</literal> in the URL will be replaced with
- the entity id of the service the user is accessing.</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </section>
-
- <section>
- <title>Fields for signing and validating messages</title>
-
- <para>simpleSAMLphp only signs authentication responses by default.
- Signing of 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.</para>
-
- <para>These options set the default for this IdP, but options for each
- SP can be set in <literal>saml20-sp-remote</literal>.</para>
-
- <glosslist>
- <glossentry>
- <glossterm>redirect.sign</glossterm>
-
- <glossdef>
- <para>Boolean, default <literal>false</literal>. To turn on
- signing of 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-sp-remote</literal>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>redirect.validate</glossterm>
-
- <glossdef>
- <para>Boolean, default <literal>false</literal>. To turn on
- validation of received authentication requests, 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-sp-remote</literal>.</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <example>
- <title>Example of configuration for signed messages</title>
-
- <programlisting> 'redirect.sign' => true,</programlisting>
- </example>
- </section>
- </section>
-
- <section>
- <title>Configuring SAML 2.0 SP Remote metadata</title>
-
- <para>In the file <filename>saml20-sp-remote.php</filename>, you
- configure all SPs that you trust. Here is an example:</para>
-
- <programlisting>/*
- * Example simpleSAMLphp SAML 2.0 SP
- */
-'saml2sp.example.org' => array(
- 'AssertionConsumerService' => 'https://saml2sp.example.org/simplesaml/saml2/sp/AssertionConsumerService.php',
- 'SingleLogoutService' => 'https://saml2sp.example.org/simplesaml/saml2/sp/SingleLogoutService.php',
-
- 'attributes' => array('email', 'eduPersonPrincipalName'),
- 'name' => 'Example service provider',
-),</programlisting>
-
- <para>Parameter details:</para>
-
- <section>
- <title>Mandatory metadata fields</title>
-
- <glosslist>
- <glossentry>
- <glossterm>index in the <code>$metadata</code> array</glossterm>
-
- <glossdef>
- <para>Entity ID of the given SP. Here:
- <literal>saml2sp.example.org</literal>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>AssertionConsumerService</glossterm>
-
- <glossdef>
- <para>URL of this SAML 2.0 endpoint. Ask the SP if you are
- uncertain. You may find the endpoint URL in SAML 2.0 metadata
- received from the SP.</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </section>
-
- <section>
- <title>Optional metadata fields</title>
-
- <glosslist>
- <glossentry>
- <glossterm>SingleLogoutService</glossterm>
-
- <glossdef>
- <para>URL of this SAML 2.0 endpoint. Ask the SP if you are
- uncertain. You may find the endpoint URL in SAML 2.0 metadata
- received from the SP.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>NameIDFormat</glossterm>
-
- <glossdef>
- <para>Set it to the default:
- <literal>transient</literal>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>SPNameQualifier</glossterm>
-
- <glossdef>
- <para>SP NameQualifier for this SP. If not set, the IdP will set
- the SPNameQualifier to be the SP entity ID.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>AttributeNameFormat</glossterm>
-
- <glossdef>
- <para>What value will be set in the Format field of attribute
- statements. This parameter can be configured multiple places,
- and the actual value used is fetched from metadata by the
- following priority:</para>
-
- <orderedlist>
- <listitem>
- <para>SP Remote Metadata</para>
- </listitem>
-
- <listitem>
- <para>IdP Hosted Metadata</para>
- </listitem>
-
- <listitem>
- <para>Default value:
- <literal>urn:oasis:names:tc:SAML:2.0:attrname-format:basic</literal></para>
- </listitem>
- </orderedlist>
-
- <para>Some examples of values specified in the SAML 2.0 Core
- Specification:</para>
-
- <itemizedlist>
- <listitem>
- <para><literal>urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified</literal></para>
- </listitem>
-
- <listitem>
- <para><literal>urn:oasis:names:tc:SAML:2.0:attrname-format:uri</literal>
- (Used as default in Shibboleth 2.0)</para>
- </listitem>
-
- <listitem>
- <para><literal>urn:oasis:names:tc:SAML:2.0:attrname-format:basic</literal>
- (Used as default in Sun Access Manager)</para>
- </listitem>
-
- <listitem>
- <para>You can define your own value.</para>
- </listitem>
- </itemizedlist>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>base64attributes</glossterm>
-
- <glossdef>
- <para>Boolean, default <literal>false</literal>: Perform base64
- encoding of attributes sent to this SP. This parameter must be
- set according to what the SP expects.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>simplesaml.nameidattribute</glossterm>
-
- <glossdef>
- <para>If the <code>NameIDFormat</code> is set to
- <literal>email</literal>, then the email address is extracted
- from the attribute with this name. E.g. if
- <code>simplesaml.nameidattribute</code> is set to uid, and the
- authentcation module provides an attribute named
- <code>uid</code>, this attribute value is set as the
- NameID.</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>simplesaml.attributes</glossterm>
-
- <glossdef>
- <para>Boolean, default <literal>true</literal>: Send an
- attribute statement to the SP.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>name</glossterm>
-
- <glossdef>
- <para>A descriptive name of the SP. This can be a string, or an
- associative array with language code => translation
- pairs.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>description</glossterm>
-
- <glossdef>
- <para>A longer description of the SP. This can be a string, or
- an associative array with language code => translation
- pairs.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>certificate</glossterm>
-
- <glossdef>
- <para>Name of certificate file for verifying the signature when
- <literal>redirect.validate</literal> is set to
- <literal>true</literal>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>ForceAuthn</glossterm>
-
- <glossdef>
- <para>Set this <literal>true</literal> to force authentication
- when receiving authentication requests from this SP. The default
- is <literal>false</literal>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>assertion.enctyption</glossterm>
-
- <glossdef>
- <para>Boolean, default <literal>false</literal>. Defines whether
- this IdP shoul encrypt assertions to this SP.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>sharedkey</glossterm>
-
- <glossdef>
- <para>Used for optional symmetric encryption of assertions.
- Currently the algorithm is hardcoded to AES128_CBC/RIJNDAEL_128
- which uses up to 128 bit for the passphrase/key. If you want to
- use a sessionkey which is encrypted by this idp's private key do
- not specify a sharedkey.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>userid.attribute</glossterm>
-
- <glossdef>
- <para>The attribute name of an attribute which uniquely
- identifies the user. This attribute is used if simpleSAMLphp
- needs to generate a persistent unique identifier for the user.
- This option can be set in both the IdP-hosted and the SP-remote
- metadata. The value in the sp-remote metadata has the highest
- priority. The default value is
- <literal>eduPersonPrincipalName</literal>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>signresponse</glossterm>
-
- <glossdef>
- <para>The default behaviour of simpleSAMLphp is to sign the
- Assertion element in the SAML 2.0 response sent to SPs. This
- option allows you to override this behaviour on a per SP basis.
- Set this to <literal>TRUE</literal> to sign the Response
- element. <literal>FALSE</literal> will make the SP sign the
- Assertion. If this option is unset, the value from
- <literal>saml2.signresponse</literal> in
- <literal>config.php</literal> will be used. That value is
- <literal>FALSE</literal> by default.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>privacypolicy</glossterm>
-
- <glossdef>
- <para>This is an absolute URL for where an user can find a
- privacypolicy for this SP. If set, this will be shown on the
- consent page. <literal>%SPENTITYID%</literal> in the URL will be
- replaced with the entity id of this service provider.</para>
- </glossdef>
- </glossentry>
- </glosslist>
- </section>
-
- <section>
- <title>Fields for signing and validating messages</title>
-
- <para>simpleSAMLphp only signs authentication responses by default.
- Signing of 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.</para>
-
- <para>These options overrides the options set in
- <literal>saml20-idp-hosted</literal>.</para>
-
- <glosslist>
- <glossentry>
- <glossterm>redirect.sign</glossterm>
-
- <glossdef>
- <para>Boolean, default <literal>false</literal>. To turn on
- signing of logout requests and logout responses, set this flag
- to true.</para>
-
- <para>This option overrides the <literal>redirect.sign</literal>
- option in <literal>saml20-idp-hosted</literal>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>redirect.validate</glossterm>
-
- <glossdef>
- <para>Boolean, default <literal>false</literal>. To turn on
- validation of received authentication requests, logout requests
- and logout responses, set this flag to true.</para>
-
- <para>This option overrides the
- <literal>redirect.validate</literal> option in
- <literal>saml20-idp-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>
-
- <section>
- <title>Configuring metadata for a Shibboleth 1.3 IdP</title>
-
- <para>In the file <filename>shib13-idp-hosted.php</filename>, you
- configure metadata for the Shibboleth 1.3 IdP. In the file
- <filename>shib13-sp-remote.php</filename>, you configurethe list of
- trusted SPs using the Shibboleth 1.3 protocol. This configuration is very
- similar to configuring SAML 2.0 metadata; please find information in the
- previous chapter.</para>
-
- <section>
- <title>Scoped attributes</title>
-
- <para>It is possible to configure some attributes to be scoped, and
- include the Scope-attribute on the attribute values. This is enabled by
- setting the <literal>scopedattributes</literal>-option in either
- <filename>shib13-sp-remote.php</filename> or
- <filename>shib13-idp-hosted.php</filename>. If both are defined, the SP
- configuration is used.</para>
-
- <para>This option is an array of the names of attributes which should be
- treated as scoped. The matching is case-sensitive. A scoped attribute
- will be split on the first <literal>@</literal>-sign, and the first part
- will be used as the attribute value, while the last part will be used as
- the scope.</para>
-
- <programlisting>/*
- * Example of scopedattributes option. Will use scoped attribute for eduPersonPrincipalName.
- */
-'scopedattributes' => array('eduPersonPrincipalName'),</programlisting>
- </section>
- </section>
-
- <section>
- <title>Test IdP</title>
-
- <para>To test the IdP, it is best to configure two hosts with
- simpleSAMLphp, and use the SP demo example to test the IdP.</para>
-
- <tip>
- <para>To make the initial test up and running with minimal hassle, use
- the login-auto if you do not want to setup a user storage, and use the
- included certificate so you do not need to create a new one.</para>
- </tip>
- </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>
- <title id="sect.customauth">Writing your own authentication module</title>
-
- <para>You can write your own authentication module. Just copy one of the
- files in the www/auth directory and play with it, then configure an IdP to
- use that module with the auth parameter in the metadata. The file must
- support incoming URL parameters, massage the session object with login
- state information and return to the RelayState, and that is all you need
- to do!</para>
-
- <tip>
- <para>Instead of changing the code of the builtin authentication module,
- copy it into a new file and edit that. That way, your module will not be
- replaced or in conflict when you upgrade simpleSAMLphp to a newer
- version.</para>
- </tip>
-
- <section>
- <title>Authentication API</title>
-
- <para>The authentication plugin should be placed in the
- <filename>auth</filename> directory.</para>
-
- <para>The following parameters must be accepted in the incoming
- URL:</para>
-
- <itemizedlist>
- <listitem>
- <para><literal>RelayState</literal>: URL where the user is sent
- after authentication within the plugin.</para>
- </listitem>
-
- <listitem>
- <para><literal>RequestID</literal>: ID of an incoming
- request.</para>
- </listitem>
- </itemizedlist>
-
- <para>The initSSO.php takes in addition the following parameters:</para>
-
- <itemizedlist>
- <listitem>
- <para><literal>idpentityid</literal>: This is the entityid of the
- IdP to authenticate with. This parameter is optional, if not set the
- default for this host will be used.</para>
- </listitem>
-
- <listitem>
- <para><literal>spentityid</literal>: This is which SP config to use.
- This parameter is optional, if not set the default for this host
- will be used.</para>
- </listitem>
- </itemizedlist>
-
- <para>In hosted IdP metadata there is a config parameter auth that will
- tell simpleSAML which authentication plugin that can beu sed.</para>
-
- <tip>
- <para>The authentication API is pretty basic. The easiest way to
- understand how it works is to look at one of the existing plugins that
- is located in the auth directory of your installation.</para>
- </tip>
- </section>
- </appendix>
-</article>
\ No newline at end of file