<?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>Tue Mar 11 21:00:08 2008</pubdate>

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

      <surname>Solberg</surname>

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

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

    <para>To get the latest news about simpleSAMLphp 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 simpleSAMLphp homepage: <ulink
    url="http://rnd.feide.no/simplesamlphp">http://rnd.feide.no/simplesamlphp</ulink></para>
  </section>

  <section>
    <title>Prerequisites</title>

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

    <para>Apache or some other webserver.</para>

    <para>simpleSAMLphp is mostly tested on different Linux, Unix, and Mac OS
    X, but someone has also made it work on Windows.</para>
  </section>

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

    <para>You can go to <ulink
    url="http://code.google.com/p/simplesamlphp/">code.google.com/p/simplesamlphp/</ulink>
    to find the most recent release of simpleSAMLphp. Download the zipped
    file, and unzip it on your webserver. However I hightly reccomend running
    from a subversion checkout instead.</para>

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

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

      <screen>cd /var</screen>

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

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

      <para>If you know subversion you know how to 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 simpleSAMLphp</title>

    <para>If you run a the subversion version, you can just type in:</para>

    <screen>svn update</screen>

    <para>in the root folder of your simpleSAMLphp installation. If you did
    download and install the zipped version, you should take backup of the
    config and the metadata directories, and then replace your simpleSAMLphp
    directory with the new version.</para>

    <para>After updating from subversion or from a newer release as a zip
    file, you will need to update your configuration and metadata. This is
    only neccessary if the format of the config files or metadata has changed
    between the version you ran and the one you are upgrading to.</para>

    <section>
      <title>Upgrading config.php</title>

      <para>A good approach is to run a diff between your preivous config.php
      file and the new config.php file located in config-templates/config.php,
      and apply your modifications to the new template. Then you make sure
      that all new entries in the latest version of config.php are included,
      as well as your local modifications are preserved.</para>
    </section>

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

      <para>Most likely the metadata format is backward compatible. Otherwise
      it should give a very clear error message about how and what you need to
      update. Still, it is reccomended to take a look at the metadata in the
      metadata-templates directory after the upgrade, and see if the
      reccomended defaults are 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
      simpleSAMLphp from an earlier version, then see <xref
      linkend="sect.upgrading" />.</para>
    </tip>

    <para>Configuration and metadata files are stored in a template format,
    you need to copy them to have your local copies. The reason why it is done
    this way, is that when you upgrade you can do svn up in subversion or just
    copy the whole directory over your installation, without replacing your
    existing configuration. When you are updating, you should investigate
    whether the config format is changed, this should be documented in the
    changelog.</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>
    <title>Configuring apache</title>

    <para>In this example simpleSAMLphp is located in
    <filename>/var/simplesamlphp</filename>, that is the default location. If
    you want to modify this location, you can do so freely, but then you need
    to update the path in a few files. <link linkend="sect.altlocations">I
    wrote a separate chapter about that, read on</link>.</para>

    <para>Of the folders inside simpleSAMLphp, only the www folder needs to be
    accessible from the web. There are several ways of putting the
    simpleSAMLphp 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 that you
    want to run simpleSAML on. 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>What is special is the <literal>Alias</literal> directive. That
    directive will give control to simpleSAMLphp for all urls that matches
    <literal>http(s)://service.example.com/simplesaml/*</literal>.
    simpleSAMLphp will need to have several SAML interfaces available on the
    web, and all these interfaces are included in the <filename>www</filename>
    subdirectory of your simpleSAMLphp installation. You can set the alias to
    whatever you want, but this alias must be set 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>:</para>

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

  <section>
    <title>simpleSAMLphp configuration: config.php</title>

    <para>placeholder. will add more text.</para>
  </section>

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

    <para>When you have installed simpleSAMLphp, 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 in example:</para>

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

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

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

    <para>Here is an example screenshot of what the simpleSAMLphp 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>On the bottom of the installation page there is some green lights.
      simpleSAML runs some tests to see whether required and reccomended
      prerequisites are met. If you see some red lights, there might be
      neccessary to add some extensions or modules to PHP. In example you
      would need PHP LDAP extension to use the LDAP authentication
      module.</para>
    </section>
  </section>

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

    <para>You have now successfully installed simpleSAMLphp, and the next
    steps depends on whether you want to setup a service provider, to protect
    a website with authentication or if you want to setup an identity provider
    and connect it to a user storage. We will also provide documentation on
    bridging federation protocols 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 have problems to get this work, or want to discuss
    simpleSAMLphp with other users of the software you are lucky! Around
    simpleSAMLphp there is a great Open source community, and you are welcome
    to join! Both for asking question, answer other questions, request
    improvements or contribute with code or plugins of your own.</para>

    <itemizedlist>
      <listitem>
        <para><ulink url="http://rnd.feide.no/simplesamlphp">simpleSAMLphp
        homepage (at Feide RnD)</ulink></para>
      </listitem>

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

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

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

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

    <para>You can spit the <literal>www</literal> folder in simpleSAMLphp from
    the installation directory. You need to set the path of the installation
    directory in the <filename>config.php</filename> file:</para>

    <programlisting> 'basedir' =&gt; '/usr/local/simplesaml/simplesamlphp',</programlisting>

    <para>And you also need to modify the Alias directive in the apache
    configuration:</para>

    <programlisting> Alias /simplesaml /usr/local/simplesaml/simplesamlphp/www</programlisting>

    <para>You also need to change the path of the <literal>require_once(...
    _include.php )</literal> line in the examples and in your integration
    code.</para>

    <para>Normally you would not want to do it this way, but one example is if
    you must install simpleSAMLphp in your home directory, and you would like
    the following directory structure:</para>

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

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