PRE-REQUISITES
==============
To use the "saml2idp" app, you must download and install these libraries:
- M2Crypto @ http://chandlerproject.org/bin/view/Projects/MeTooCrypto


UBUNTU Packages
===============
M2Crypto is also available as a system package for Ubuntu (at least on 9.10).
The name is 'python-m2crypto'. You can use the "Synaptic Package Manager" or
the "apt-get" command-line program to install it.


RUNNING THE SAMPLE PROJECT
==========================
This project comes with a working sample Django project called "idptest".
You can download it and run it as-is, using standard Django commands:

$ svn co https://django-saml2-idp.googlecode.com/svn/trunk django-saml2-idp-readonly
$ cd django-saml2-idp-readonly/idptest
$ python manage.py syncdb
$ python manage.py runserver


INCLUDING THE SAML2IDP APP IN A DJANGO PROJECT
==============================================

Enable the Django Auth system
-----------------------------
For existing projects, you will also need to:
- Enable the Django auth system. (http://docs.djangoproject.com/en/dev/topics/auth/)
- If you haven't set up login templates, you can just reuse the ones from this
  project under "templates/registration".

Get the code for the saml2idp app
---------------------------------
- Download and install the "saml2idp" app from this project site:

$ svn co https://django-saml2-idp.googlecode.com/svn/trunk/idptest/saml2idp
$ cd saml2idp
$ sudo python setup.py install

Configure the URLs
------------------
- Add this line to your top-level urlpatterns (in urls.py usually):

    urlpatterns = patterns('',
    ...
        (r'^idp/', include('saml2idp.urls')),
    ...
    )

Set appropriate settings
------------------------
- SAML2IDP_CONFIG - REQUIRED. See SETTINGS_AND_METADATA.txt.

- SAML2IDP_REMOTES - REQUIRED. See SETTINGS_AND_METADATA.txt.

- INSTALLED_APPS - OPTIONAL.
    Add 'saml2idp' If you want to include the saml2idp tests, add 'saml2idp'
    to the INSTALLED_APPS list in settings.py.


OpenSSL Key and Certificate Files
=================================
OpenSSL signing requires creation of a key and a certificate file. The "keys"
folder contains the "mk_keys.sh" Bash Script, which will walk you through the
process.  (Sorry, I don't have any help for non-linux users, but I would be
happy to include it, if someone contributes it.)

You can turn on the "signing" feature by adding this entry to your settings.py:

    SAML2IDP_CONFIG = {
        ...
        'signing': True,
        'private_key_file': '/absolute/path/to/private-key.pem',
        'certificate_file': '/absolute/path/to/certificate.pem',
        ...
    }

When signing is enabled, the "saml2idp" views will be signed with the key and
the certificate; in other words, this Identity Provider will identify itself
much more securely.

Certificates
------------
The sample certificate and private key files are located at:

/idptest/keys/sample/sample-certificate.pem
/idptest/keys/sample/sample-private-key.pem

You can use these for testing, but DO NOT USE THESE IN PRODUCTION.
