SimpleSAMLphp Identity Provider QuickStart
===========================================

<!-- 
	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-idp.txt 1400 2009-03-12 09:56:50Z andreassolberg $`

This guide will describe how to configure simpleSAMLphp as an identity provider (IdP). You should previously have installed simpleSAMLphp as described in [the simpleSAMLphp installation instructions](http://rnd.feide.no/content/installing-simplesamlphp)


Enabling the Identity Provider functionality
--------------------------------------------

The first that must be done is to enable the identity provider functionality. This is done by editing `config/config.php`. The options `enable.saml20-idp` and `enable.shib13-idp` controls whether SAML 2.0 and Shibboleth 1.3 support is enabled. Enable one or both of those by assigning `true` to them:

    'enable.saml20-sp'  => false,
    'enable.saml20-idp' => true,
    'enable.shib13-sp'  => false,
    'enable.shib13-idp' => true,


Authentication module
---------------------

The next step is to configure the way users authenticate on your IdP. Various modules in the `modules/` directory provides methods for authenticating your users. This is an overview of those that are included in the simpleSAMLphp distribution:

[`authfacebook:Facebook`](https://rnd.feide.no/content/using-facebook-authentication-source)
: Authenticate with a Facebook ID.

`authYubiKey:YubiKey`
: Authenticate with an YubiKey.

`exampleauth:UserPass`
: Authenticate against a list of usernames and passwords.

`exampleauth:Static`
: Automatically log in as a user with a set of attributes.

[`InfoCard:ICAuth`](http://rnd.feide.no/content/simplesamlphp-infocard-module-usage)
: Authenticate with an InfoCard.

[`ldap:LDAP`](https://rnd.feide.no/content/configuring-simplesamlphp-ldap-authentication-source)
: Authenticates an user to a LDAP server.

[`ldap:LDAPMulti`](https://rnd.feide.no/content/configuring-simplesamlphp-ldap-authentication-source)
: Authenticates an user to one of several LDAP server.
  The user can choose the LDAP server from a dropdown list.

`openid:OpenIDConsumer`
: Authenticate against an OpenID provider.

`saml2:SP`
: Authenticate against a SAML 2.0 IdP.

`sqlauth:SQL`
: Authenticate an user against a database.

In this guide, we will use the `exampleauth:UserPass` authentication
module. This module does not have any dependencies, and is therefore
simple to set up.


Configuring the authentication module
-------------------------------------

The `exampleauth:UserPass` authentication module is part of the `exampleauth` module. This module isn't enabled by default, so you will have to enable it. This is done by creating a file named `enable` in `modules/exampleauth/`.

On unix, this can be done by running (from the simpleSAMLphp
installation directory):

    touch modules/exampleauth/enable

The next step is to create an authentication source with this module. An authentication source is an authentication module with a specific configuration. Each authentication source has a name, which is used to refer to this specific configuration in the IdP configuration. Configuration for authentication sources can be found in `config/authsources.php`.

In this setup, this file should contain a single entry:

	<?php
	$config = array(
		'example-userpass' => array(
			'exampleauth:UserPass',
			'student:studentpass' => array(
				'uid' => array('student'),
				'eduPersonAffiliation' => array('member', 'student'),
			),
			'employee:employeepass' => array(
				'uid' => array('employee'),
				'eduPersonAffiliation' => array('member', 'employee'),
			),
		),
	);
	?>

This configuration creates two users - `student` and `employee`, with the passwords `studentpass` and `employeepass`. The username and password is stored in the array index (`student:studentpass` for the `student`-user. The attributes for each user is configured in the array referenced by the index. For the student user, these are:

	array(
		'uid' => array('student'),
		'eduPersonAffiliation' => array('member', 'student'),
	),

The attributes will be returned by the IdP when the user logs on.


Configuring the IdP
-------------------

The IdP is configured by the metadata stored in
`metadata/saml20-idp-hosted.php` and `metadata/shib13-idp-hosted.php`.
This is a minimal configuration of a SAML 2.0 IdP:

	<?php
	$metadata = array(
		'__DYNAMIC:1__' => array(
			/*
			 * The hostname for this IdP. This makes it possible to run multiple
			 * IdPs from the same configuration. '__DEFAULT__' means that this one
			 * should be used by default.
			 */
			'host' => '__DEFAULT__',

			/*
			 * The private key and certificate to use when signing responses.
			 * These are stored in the cert-directory.
			 */
			'privatekey' => 'server.pem',
			'certificate' => 'server.crt',

			/*
			 * The authentication source which should be used to authenticate the
			 * user. This must match one of the entries in config/authsources.php.
			 */
			'auth' => 'example-userpass',
		),
	);
	?>

For more information about available options in the idp-hosted metadata
files, see the [IdP hosted reference](https://rnd.feide.no/content/idp-hosted-metadata-reference).


Adding SPs to the IdP
---------------------

The identity provider you are configuring needs to know about the service providers you are going to connect to it. This is configured by metadata stored in `metadata/saml20-sp-remote.php` and `metadata/shib13-sp-remote.php`. This is a minimal example of a `metadata/saml20-sp-remote.php` metadata file:

	<?php
	$metadata = array(
		'sp.example.org' => array(
			'AssertionConsumerService' => 'https://sp.example.org/simplesaml/saml2/sp/AssertionConsumerService.php',
			'SingleLogoutService'      => 'https://sp.example.org/simplesaml/saml2/sp/SingleLogoutService.php',
		),
	);
	?>

If you have the metadata of the remote SP as an XML file, you can use the built-in XML to simpleSAMLphp metadata converter, which by default is available as `/admin/metadata-converter.php` in your simpleSAMLphp installation.

For more information about available options in the sp-remote metadata files, see the [SP remote reference](https://rnd.feide.no/content/sp-remote-metadata-reference).


Creating a SSL self signed certificate
--------------------------------------

For test purposes, you can skip this section, and use the certificate
included in the simpleSAMLphp distribution.

Here is an example of `openssl`-commands which can be used to generate
a new private key key and the corresponding self-signed certificate.
This key and certificate can be used to sign SAML messages:

    openssl genrsa -out example.org.pem 1024
    openssl req -new -key example.org.pem -out example.org.csr
    openssl x509 -req -days 9999 -in example.org.csr -signkey example.org.pem -out example.org.crt
    rm example.org.csr

The certificate above will be valid for 9999 days.


### Note ###

simpleSAMLphp will only work with RSA certificates. DSA certificates
are not supported.


### Warning ###

The certificate that is included in 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.


Adding this IdP to other SPs
----------------------------

The method for adding this IdP to a SP varies between different types of SPs. In general, most SPs need some metadata from the IdP. This should be available from `/saml2/idp/metadata.php` and `/shib13/idp/metadata.php`.


Testing the IdP
---------------

The simplest way to test the IdP is to configure a simpleSAMLphp SP
on the same machine. See the instructions for
[configuring simpleSAMLphp as an SP](http://rnd.feide.no/content/using-simplesamlphp-service-provider).


### Note ###

When running a simpleSAMLphp IdP and a simpleSAMLphp SP on the same computer, the SP and IdP **MUST** be configured with different hostnames. This prevents cookies from the SP to interfere with cookies from the IdP.


Support
-------

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

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



A. IdP-first setup
------------------

If you do not want to start the SSO flow at the SP, you may use the IdP-first setup. To do this, redirect the user to the SSOService endpoint on the IdP with one parameter `spentityid` that match the SP EntityId that the user should be logged into.

Here is an example of such an url:

	https://idp.example.org/simplesaml/saml2/idp/SSOService.php?spentityid=sp.example.org

When the IdP-first flow is used an extra parameter is needed in the `saml20-sp-hosted` metadata. This is the `RelayState` parameter that tells the SP which URL to redirect the user to after the user is successfully authenticated. This typically is the frontpage of your application. An example of this can be:

	'RelayState' => '/',

