<?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>simpleSAMLphp Installation and Configuration</title>

  <articleinfo>
    <date>2007-08-30</date>

    <pubdate>Sun Nov  2 14:45:21 2008</pubdate>

    <author>
      <firstname>Andreas Åkre</firstname>

      <surname>Solberg</surname>

      <email>andreas.solberg@uninett.no</email>
    </author>
  </articleinfo>

  <section>
    <title>simpleSAMLphp documentation</title>

    <para>This document is part of the
    <application>simpleSAMLphp</application> documentation suite.</para>

    <itemizedlist>
      <listitem>
        <para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
        all <application>simpleSAMLphp</application>
        documentation</ulink></para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>News about simpleSAMLphp</title>

    <para>To get the latest news about
    <application>simpleSAMLphp</application> you can follow this url: <ulink
    url="http://rnd.feide.no/taxonomy/term/4">http://rnd.feide.no/taxonomy/term/4</ulink>.
    It also conatins an RSS feed.</para>

    <para>Here is the <application>simpleSAMLphp</application> homepage:
    <ulink
    url="http://rnd.feide.no/simplesamlphp">http://rnd.feide.no/simplesamlphp</ulink></para>
  </section>

  <section>
    <title>Prerequisites</title>

    <para><application>PHP</application> version &gt;= 5.1.2. If you want to
    run the <emphasis>Shibboleth 1.3</emphasis> part of
    <application>simpleSAMLphp</application>, you must have
    <application>PHP</application> &gt;= 5.2.</para>

    <para>Apache or some other webserver that allows you to run PHP.</para>

    <para><application>simpleSAMLphp</application> is has been tested most
    thoroughly on different Linux versions, Unix, and Mac OS X. It also runs
    on Windows, but at the time of writing, testing has been less
    thorough.</para>
  </section>

  <section>
    <title>Download and install simpleSAMLphp</title>

    <para>The most recent relase of <application>simpleSAMLphp</application>
    is found at <ulink
    url="http://code.google.com/p/simplesamlphp/">code.google.com/p/simplesamlphp/.</ulink>
    To obtain a stable version, you may download the zipped
    <filename>simplesamlphp</filename> zip file listed under Featured
    Dowloads, or you may check out the last version includeing the most recent
    updates from the subversion repository.</para>

    <section>
      <title>Get a working copy of simpleSAMLphp from subversion</title>

      <para>Go to the directory where you want to install
      <application>simpleSAMLphp</application>:</para>

      <screen>cd /var</screen>

      <para>Then do a subversion checkout:</para>

      <screen>svn checkout http://simplesamlphp.googlecode.com/svn/trunk/ simplesamlphp</screen>

      <para>Using subversion, you can view logs and review changes to the
      files. To update the version you have checked out, enter:</para>

      <screen>cd /var/simplesamlphp
svn up</screen>
    </section>
  </section>

  <section id="sect.upgrading">
    <title>Upgrading from a previous version of
    <application>simpleSAMLphp</application></title>

    <para><emphasis>If you have downloaded a version from the subversion
    repository:</emphasis></para>

    <para>Type, while located in the root folder of your
    <application>simpleSAMLphp</application> installation:</para>

    <screen>svn update</screen>

    <para><emphasis>If you download and install the zipped version:
    </emphasis></para>

    <para><itemizedlist>
        <listitem>
          <para>Make a backup of the <filename>config</filename> and the
          <filename>metadata</filename> directories.</para>
        </listitem>

        <listitem>
          <para>Delete all files from your current simpleSAMLphp directory
          .</para>
        </listitem>

        <listitem>
          <para>Unzip the new version in the simpleSAMLphp directory.</para>
        </listitem>

        <listitem>
          <para>Install the backups of <filename>config</filename> and the
          <filename>metadata</filename> directories in the simpleSAMLphp
          directory.</para>
        </listitem>
      </itemizedlist></para>

    <para>If the format of the config files or metadata has changed from your
    previous version of <application>simpleSAMLphp</application> (check the
    revision log), you may have to update your configuration and metadata
    after updating the <application>simpleSAMLphp</application> code:</para>

    <section>
      <title>Upgrading configuration files</title>

      <para>A good approach is to run a <literal>diff</literal> between your
      preivous <filename>config.php</filename> file and the new
      <filename>config.php</filename> file located in
      <filename>config-templates/config.php</filename>, and apply relevant
      modifications to the new template. This will ensure that all new entries
      in the latest version of config.php are included, as well as preserve
      your local modifications.</para>

      <para>There is a link to a configuration check utility from the
      frontpage of your simpleSAMLphp installation page. The name of the link
      is "simpleSAMLphp configuration check". Then you will get a list of all
      configuration files in your <filename>config/</filename> directory.
      Click through the files, and you will get a report on superfluous and
      missing entries in the configuration file. What is done under the hood
      is that simpleSAMLphp looks up the
      <filename>config-templates/</filename> directory and compares to your
      real config. Although not all option is required to have in the
      configuration files, it's a good thumb rule to include them nontheless,
      so you simply see what configuration is possible.</para>
    </section>

    <section>
      <title>Upgrading metadata files</title>

      <para>Most likely the metadata format is backwards compatible. If not,
      you should receive a very clear error message at startup indicating how
      and what you need to update. You should look through the metadata in the
      metadata-templates directory after the upgrade to see whether
      recommended defaults have been changed.</para>
    </section>
  </section>

  <section>
    <title>Making configuration and metadata files</title>

    <tip>
      <para>You do not need to read this section if you are upgrading
      <application>simpleSAMLphp</application> from an earlier version, then
      see <xref linkend="sect.upgrading" />.</para>
    </tip>

    <para>Configuration and metadata files are distributed as templates; you
    should make local copies to directories <filename>config</filename> and
    <filename>metadata</filename> and edit these copies to suit your local
    requirements. When you later upgrade, through a subversion <literal>svn
    up</literal> command or by installing a new zip file, your existing
    configuration data will not not be overwritten.</para>

    <para>Here are the steps you need to do to create local configuration
    files:</para>

    <screen>cd /var/simplesamlphp
cp -r config-templates/*.php config/
cp -r metadata-templates/*.php metadata/
</screen>
  </section>

  <section id="sect.apacheconfig">
    <title>Configuring Apache</title>

    <para>Examples below assume that <application>simpleSAMLphp</application>
    is installed in the default location,
    <filename>/var/simplesamlphp</filename>. You may choose another location,
    but this requires a path update in a few files. <link
    linkend="sect.altlocations">See Appendix A for details</link>.</para>

    <para>The only subdirectories of <filename>simpleSAMLphp</filename> that
    needs to be accessible from the web is <filename>www</filename>. There are
    several ways of putting the <application>simpleSAMLphp</application>
    depending on the way web sites are structured on your apache web server.
    Here is what I believe is the best configuration.</para>

    <para>Find the Apache configuration file for the virtual hosts where you
    want to run <application>simpleSAMLphp</application>. The configuration
    may look like this:</para>

    <programlisting>&lt;VirtualHost *&gt;
        ServerName service.example.com
        DocumentRoot /var/www/service.example.com

        Alias /simplesaml /var/simplesamlphp/www
&lt;/VirtualHost&gt;
</programlisting>

    <para>Note the <literal>Alias</literal> directive, which gives control to
    <application>simpleSAMLphp</application> for all urls matching
    <literal>http(s)://service.example.com/simplesaml/*</literal>.
    <application>simpleSAMLphp</application> makes several SAML interfaces
    available on the web; all of them are included in the
    <filename>www</filename> subdirectory of your
    <application>simpleSAMLphp</application> installation. You can name the
    alias whatever you want, but the name must be specified in the
    <filename>config.php</filename> file of simpleSAML as described in <xref
    linkend="sect.config" />. Here is an example of how this configuration may
    look like in <filename>config.php</filename>:h</para>

    <programlisting>$config = array (
[...]
        'baseurlpath'                   =&gt; 'simplesaml/',</programlisting>
  </section>

  <section id="sect.config">
    <title>simpleSAMLphp configuration: config.php</title>

    <para>There is a few steps that you should edit in the main configuration
    file, <filename>config.php</filename>, right away:</para>

    <itemizedlist>
      <listitem>
        <para>Set a administrator password. This is needed to access some of
        the pages in your simpleSAMLphp installation web interface.</para>

        <programlisting>	'auth.adminpassword'		=&gt; 'setnewpasswordhere',</programlisting>
      </listitem>

      <listitem>
        <para>Set a secret salt. This should be a random string. Some parts of
        the simpleSAMLphp needs this salt to generate cryptographically secure
        hashes. SimpleSAMLphp will give an error if the salt is not changed
        from the default value. The command below can help you to generated a
        random string on (some) unix systems:</para>

        <programlisting>tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' &lt;/dev/urandom | dd bs=32 count=1 2&gt;/dev/null;echo</programlisting>

        <para>Here is an example of the config option:</para>

        <programlisting>	'secretsalt' =&gt; 'randombytesinsertedhere',</programlisting>
      </listitem>

      <listitem>
        <para>Set technical contact information. This information will be
        available in the generated metadata. The e-mail address will also be
        used for receiving error reports sent automatically by simpleSAMLphp.
        Here is an example:</para>

        <programlisting>	'technicalcontact_name'     =&gt; 'Andreas Åkre Solberg',
	'technicalcontact_email'    =&gt; 'andreas.solberg@uninett.no',</programlisting>
      </listitem>

      <listitem>
        <para>If you use simpleSAMLphp in a country where english is not
        widespread, you may want to change the default language from english
        to something else:</para>

        <programlisting>	'language.default'		=&gt; 'no',</programlisting>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Configure PHP to be able to send e-mails</title>

    <para>Some parts of simpleSAMLphp will allow you to send e-mails. In
    example sending error reports to technical admin, as well as sending in
    metadata to the federation administrators. If you want to make use of this
    functionality, you should make sure your PHP installation is configured to
    be able to send e-mails. It's a common problem that PHP is not configured
    to send e-mails properly. The configuration differs from system to system.
    On UNIX, PHP is using sendmail, on Windows SMTP. </para>
  </section>

  <section>
    <title>Enable modules</title>

    <para>If you want to enable some of the modules that are installed with
    simpleSAMLphp, but are disabled by default, you should create an empty
    file in the module directory named <filename>enable</filename>.</para>

    <programlisting># Enabling the consent module
cd modules
ls -l
cd consent
touch enable
</programlisting>

    <para>If you later want to disable the module, rename the
    <filename>enable</filename> file to <filename>disable</filename>.</para>

    <programlisting>cd modules/consent
mv enable disable
</programlisting>
  </section>

  <section>
    <title>The simpleSAMLphp installation webpage</title>

    <para>After installing <application>simpleSAMLphp</application>, you can
    access the homepage of your installation, which contains some information
    and a few links to the test services. The url of an installation can be
    e.g.:</para>

    <literallayout>https://service.example.com/simplesaml/</literallayout>

    <para>The exact link depends on how you set it up with Apache, and off
    course on your hostname.</para>

    <warning>
      <para>Don't click on any of the links yet, because they require you to
      either have setup <application>simpleSAMLphp</application> as an Service
      Provider or as an Identity Provider.</para>
    </warning>

    <para>Here is an example screenshot of what the
    <application>simpleSAMLphp</application> page looks like:</para>

    <figure>
      <title>Screenshot of the simpleSAMLphp installation page.</title>

      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="resources/simplesamlphp-install/screenshot-installationpage.png" />
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure>

    <section>
      <title>Check your PHP environment</title>

      <para>At the bottom of the installation page are some green lights.
      simpleSAML runs some tests to see whether required and recommended
      prerequisites are met. If any of the lights are red, you may have to add
      some extensions or modules to <application>PHP</application>, e.g. you
      need the PHP LDAP extension to use the LDAP authentication
      module.</para>
    </section>
  </section>

  <section>
    <title>Next steps</title>

    <para>You have now successfully installed
    <application>simpleSAMLphp</application>, and the next steps depends on
    whether you want to setup a service provider, to protect a website by
    authentication or if you want to setup an identity provider and connect it
    to a user catalog. Documentation on bridging between federation protocols
    is found in a separate document.</para>

    <itemizedlist>
      <listitem>
        <para><ulink
        url="http://rnd.feide.no/content/using-simplesamlphp-service-provider">Setting
        up simpleSAMLphp as a service provider</ulink></para>
      </listitem>

      <listitem>
        <para><ulink
        url="http://rnd.feide.no/content/using-simplesamlphp-identity-provider">Setting
        up simpleSAMLphp as an identity provider</ulink></para>
      </listitem>

      <listitem>
        <para><ulink
        url="http://rnd.feide.no/content/simplesamlphp-idp-google-apps-education">Setting
        up simpleSAMLphp with Google Apps for Eduation</ulink></para>
      </listitem>

      <listitem>
        <para><ulink
        url="http://rnd.feide.no/content/simplesamlphp-advanced-features">Advanced
        simpleSAMLphp features</ulink></para>
      </listitem>

      <listitem>
        <para><ulink
        url="http://rnd.feide.no/content/simplesamlphp-maintenance-and-configuration">simpleSAMLphp
        maintenance and configuration</ulink></para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Support</title>

    <para>If you need help to make this work, or want to discuss
    <application>simpleSAMLphp</application> with other users of the software,
    you are fortunate: Around <application>simpleSAMLphp</application> 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"><application>simpleSAMLphp</application>
        homepage (at Feide RnD)</ulink></para>
      </listitem>

      <listitem>
        <para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
        all available <application>simpleSAMLphp</application>
        documentation</ulink></para>
      </listitem>

      <listitem>
        <para><ulink
        url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">Join
        the <application>simpleSAMLphp</application> user's mailing
        list</ulink></para>
      </listitem>

      <listitem>
        <para><ulink url="https://ow.feide.no/simplesamlphp:start">Visit and
        contribute to the <application>simpleSAMLphp</application>
        wiki</ulink></para>
      </listitem>
    </itemizedlist>
  </section>

  <appendix id="sect.altlocations">
    <title>Installing simpleSAMLphp in alternative locations</title>

    <para>There may be several reasons why you want to install simpleSAMLphp
    in an alternative way.</para>

    <orderedlist>
      <listitem>
        <para>You are installing simpleSAMLphp in a hosted environment where
        you do not have root access, and cannot change Apache configuration.
        Still you can install simpleSAMLphp - keep on reading.</para>
      </listitem>

      <listitem>
        <para>You have full permissions to the server, but cannot edit Apache
        configuration for some reason, polictics, policy or whatever.</para>
      </listitem>
    </orderedlist>

    <para>The SimpleSAMLphp code contains one folder named
    <filename>simplesamlphp</filename>. In this folder there are a lot of
    subfolders for library, metadata, configuration and much more. One of
    these folders is named <filename>www</filename>. This and <emphasis>only
    this</emphasis> folder should be exposed on the web. The reccomended
    configuration is to put the whole <filename>simplesamlphp</filename>
    folder outside the webroot, and then link in the <filename>www</filename>
    folder by using the <literal>Alias</literal> directive, as described in
    <xref linkend="sect.apacheconfig" />. But this is not the only possible
    way.</para>

    <para>As an example, let's see how you can install simpleSAMLphp in your
    home directory on a shosted server.</para>

    <para>Check out simpleSAMLphp in your home directory, and move or symlink
    the www folder into the <filename>public_html</filename> folder.</para>

    <screen>cd ~
svn checkout [snipp] simplesamlphp
</screen>

    <para>Then you can try to make a symlink into the public_html
    directory.</para>

    <screen>cd ~/public_html
ln -s ../simplesamlphp/www simplesaml
</screen>

    <tip>
      <para>Symlinking may fail, because some apache configurations do not
      allow you to link in files from outside the public_html folder. If so,
      move the folder instead of symlinking:</para>

      <screen>cd ~/public_html
mv ../simplesamlphp/www simplesaml</screen>
    </tip>

    <para>Now you have the following directory structure.</para>

    <itemizedlist>
      <listitem>
        <para><filename>~/simplesamlphp</filename></para>
      </listitem>

      <listitem>
        <para><filename>~/public_html/simplesaml</filename> where
        <filename>simplesaml</filename> is the <filename>www</filename>
        directory from the <filename>simplesamlphp</filename> installation
        directory, either moved or a symlink.</para>
      </listitem>
    </itemizedlist>

    <para>Now, we need to make a few configuration changes. First, let's edit
    <filename>~/public_html/simplesaml/_include.php</filename>:</para>

    <para>Change the two lines from:</para>

    <programlisting>require_once(dirname(dirname(__FILE__)) . '/lib/_autoload.php');
$path_extra = dirname(dirname(__FILE__)) . '/lib';</programlisting>

    <para>to something like:</para>

    <programlisting>require_once('/home/andreas/simplesamlphp/lib/_autoload.php');
$path_extra = '/home/andreas/simplesamlphp/lib';</programlisting>

    <para>And then at the end of the file, you need to change another line
    from:</para>

    <programlisting>$configdir = dirname(dirname(__FILE__)) . '/config';</programlisting>

    <para>to:</para>

    <programlisting>$configdir = '/home/andreas/simplesamlphp/config';</programlisting>

    <note>
      <para>In a future version of simpleSAMLphp we'll make this a bit easier,
      and let you only change the path one place, instead of three as
      described above.</para>
    </note>

    <para>Next, you need to update the configuration of paths in
    <filename>simplesamlphp/config/config.php</filename>:</para>

    <para>Set the <literal>basedir</literal> parameter to the path of your
    simplesamlphp folder:</para>

    <programlisting>	'basedir' =&gt; '/home/andreas/simplesamlphp/',</programlisting>

    <para>And, then we need to set the <literal>baseurlpath</literal>
    parameter to match the base path of the URLs to the content of your
    <filename>www</filename> folder:</para>

    <programlisting>	'baseurlpath'           =&gt; '~andreas/simplesaml/',</programlisting>

    <para>Now, you can go to the URL of your installation and check if things
    work:</para>

    <literallayout>http://yourcompany.com/~andreas/simplesaml/</literallayout>
  </appendix>
</article>