Authentic - Installation Instructions
=====================================

.. note:: there is an administrator guide covering installation and much more
   available in doc/en/ (French translation in doc/fr/)

Prerequisites
-------------

- Lasso 0.6.1 <http://lasso.entrouvert.org>
- Quixote 2.0 <http://www.mems-exchange.org/software/quixote/>


Installation
------------

Authentic uses the standard distutils Python package; just run::

  python setup.py install

and you're done.

.. note:: if you are using Debian, there are packages available, add ``deb
   http://deb.entrouvert.org sarge`` in your ``sources.list``.
     


Configuration
-------------

Authentic has been tested with Quixote configured through mod_python or through
SCGI, both with Apache 1.3 and 2.  The recommended configuration is to use
SCGI (version 1.8 or later is recommended since they have SCGIMount directive).

An example configuration (mod_python, Apache 2) looks like this::

  <VirtualHost www.example.com:80>
      ServerAdmin webmaster@locahost
      ServerName www.example.com
      DocumentRoot /usr/share/authentic/web/
      <LocationMatch "^/authentic(/|$)">
          SetHandler python-program
          PythonHandler quixote.server.mod_python_handler
          PythonOption quixote-publisher-factory authentic.create_publisher
      </LocationMatch>
  </VirtualHost>

An other example configuration (SCGI, Apache 1.3)::

  <VirtualHost *:80>
    ServerAdmin webmaster@locahost
    ServerName www.example.com
    DocumentRoot /usr/share/authentic/web/

    RedirectMatch permanent ^/authentic$ /authentic/
    <Location /authentic/>
      SCGIServer 127.0.0.1 3002
      SCGIHandler On
    </Location>
  </VirtualHost>

SCGI usage requires an additional server to run, authentic_scgi_server.py,
the Debian package installs a init.d script automatically.

It is also possible to have it configured to run at the root of the website,
with something like:

  <LocationMatch "^/($|admin|liberty|login|logout|theme|qo|change_password|register|forgot_password)">
    SCGIServer 127.0.0.1 3002
    SCGIHandler On
  </LocationMatch>

This is the situation where SCGIMount is really useful; the previous
configuration snippet would then be:

  SCGIMount / 127.0.0.1:3002
  <LocationMatch "^/(css|images|js)/.*">
    SCGIHandler off
  </LocationMatch>



First Use
=========

Point your browser to http://www.example.com/authentic/admin (with whatever
hostname or path you decided to use, and possibly https).

- Identity Management
  - New
    - Name, username, password, fill them as you want.
    - Don't forget to give admin rights to this first user.
- You have now been kicked out, log on with the username/password you entered.
- Settings
  - Identity Provider
    - Provider ID: whatever
    - Base URL: probably ok as is
    - Organization Name: whatever
    - Private & Public Keys: generate them with OpenSSL or grab some from
      another project (<http://lasso.entrouvert.org/souk> has many of them).
  - Save metadata from "Identity Provider Metadata"
  - Service Providers
    - New
      - Metadata file from the service provider
      - Public key from the service provider
- Configure you service provider to use authentic metadata file and public key.