<?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'  =&gt; false,
'enable.saml20-idp' =&gt; true,
'enable.shib13-sp'  =&gt; false,
'enable.shib13-idp' =&gt; 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>(|(&lt;attr1&gt;=&lt;username&gt;)(&lt;attr2&gt;=&lt;username&gt;)...)</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' =&gt; 'ldap.example.org',
  'auth.ldap.attributes' =&gt; NULL,
  'auth.ldap.enable_tls' =&gt; FALSE,

  /* Enable searching. */
  'auth.ldap.search.enable' =&gt; TRUE,

  /* The base DN for the search. */
  'auth.ldap.search.base' =&gt; 'cn=users,dc=example,dc=org',

  /* The user can authenticate using the uid or the email address. */
  'auth.ldap.search.attributes' =&gt; array('uid', 'mail'),

  'auth.ldap.search.username' =&gt; 'uid=authsearch,cn=server,dc=example,dc=org',
  'auth.ldap.search.password' =&gt; '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&lt;username&gt;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' =&gt; array(
		'cas' =&gt; array(
			'login' =&gt; 'https://idpentityid.example.org/cas/login',
			'validate' =&gt; 'https://idpentityid.example.org/cas/validate',
		),
		'ldap' =&gt; array(
			'servers' =&gt; 'idpentityid.example.org',
			'enable_tls' =&gt; false,
			'searchbase' =&gt; 'dc=example,dc=org',
			'searchattributes' =&gt; 'uid',
			'attributes' =&gt; array('cn', 'mail'),
		),
	),
	'idpentityid2.example.org' =&gt; array(
		'cas' =&gt; array(
			'login' =&gt; 'https://idpentityid2.example.org/login',
			'validate' =&gt; 'https://idpentityid2.example.org/validate',
		),
		'ldap' =&gt; array(
			'servers' =&gt; 'ldap://idpentityid2.example.org',
			'enable_tls' =&gt; false,
			'searchbase' =&gt; 'ou=users,dc=example,dc=org',
			'searchattributes' =&gt; array('uid', 'mail'), # array for being able to login with either uid or mail.
			'attributes' =&gt; null,
			'priv_user_dn' =&gt; 'uid=admin,ou=users,dc=example,dc=org',
			'priv_user_pw' =&gt; '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' =&gt; array(

 // The hostname of the server (VHOST) that this SAML entity will use.
 'host'            =&gt; 'sp.example.org',
 
 // X.509 key and certificate. Relative to the cert directory.
 'privatekey'      =&gt; 'server.pem',
 'certificate'     =&gt; 'server.crt',
 
 // Authentication plugin to use. login.php is the default one that uses LDAP.
 'auth'             =&gt; 'auth/login.php',
 'authority'        =&gt; '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>&lt;simpleSAMLphp-root&gt;/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>&lt;simpleSAMLphp-root&gt;/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' =&gt; 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' =&gt; array(
 'AssertionConsumerService' =&gt; 'https://saml2sp.example.org/simplesaml/saml2/sp/AssertionConsumerService.php', 
 'SingleLogoutService'      =&gt; 'https://saml2sp.example.org/simplesaml/saml2/sp/SingleLogoutService.php',
 
 'attributes'               =&gt; array('email', 'eduPersonPrincipalName'),
 'name'                     =&gt; '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 =&gt; 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 =&gt; 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' =&gt; true,
'certificate' =&gt; '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' =&gt; 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 incomming
      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 incomming
          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>