README

moonshot
========
A python module usable in a Moonshot environment to allow a freeradius server
to fetch information about a user from a SAML2 Attribute Authority (AA) or
Identity Provider (IdP).
There are some things you have to do disregarding how you want the SP to
talk to the IdP/AA. So I take those first.

Dependency
----------

This package is dependent on pySAML2.
You should get PySAML2 from Launchpad, the version that is at PyPI is not
enough up-to-date.

bzr co bzr+ssh://bazaar.launchpad.net/%2Bbranch/pysaml2/

should get you the latest version.

Basic Installing
----------

A couple of changes to the freeradius configuration are necessary.
This is one way of doing it. How you chose to do it depends on your local
preferences.

1) create raddb/modules/python

You can use one of the provided 'template/modules_python_aa' or
'template/modules_python_ecp' files as they are. Which one depends of your
choice of using ECP or AA. Rename of copy the one you want to use to
'template/modules_python' and copy it to raddb/modules.

Regarding the configuration of outer/inner tunnel this is still a bit
undecided. The extension module can be use in either.

2) Edit raddb/sites-available/default
To the 'post-auth' section add one line referencing the python module.
You can see how it can be done in
'template/sites-available_default".

3) Edit raddb/sites-available/inner-tunnel.
To the 'post-auth' section add one line referencing the python module.
You can see how it can be done in
'template/sites-available_inner-tunnel".


Now, you should have the basic freeradius setup.
To get it working you have to do a couple of more things:


I) Get the SAML2 metadata for the AA or IDP you want to use. Rename it to
metadata.xml and place it in the 'etc' directory.


II) Chose one of the configuration files for the extension you want to use.
There are two choices (etc/aa_config.py and etc/ecp_config.py).
Rename (or copy) the one you want to use to config.py and edit it.

You must change the value of ATTRIBUTE_AUTHORITY/IDP_ENTITYID so it is the
identifier (entityID) of the SAML2 AA/IdP you want to use.


III) Change the pysaml2 configuration file 'etc/pysaml_config.py'.
A couple of things:

BASE : This is the identifier of the SP (=this module) you are running.

organization: Information about the organization running this service

contact_person: Information about a person people can contact to ask about
    this service

xmlsec_binary: where the xmlsec1 binaries are located. This is only needed if
these binaries are somewhere outside the normal PATH.

IV) Create your own key pair.

A key and certificate can be created using the openssl tool:
$ openssl genrsa 1024 > ssl.key
$ openssl req -new -x509 -nodes -sha1 -days 365 -key ssl.key > ssl.cert
$ sudo mv ssl.key ssl.cert /usr/local/etc/moonshot/pki

If you chose other names for you key and cert you have to change
pysaml_config.py accordingly.


V)

Now you can install the package:

python setup.py install

should place everything in it's place.
One thing that might happen is that a new directory is created.
/usr/local/etc/moonshot
You may have to change the premissions on this directory to make it possible
for the freeradius extension to access the information in the directory.

VI) Create the metadata file for your SP.

$ cd etc
$ make_metadata.py pysaml_config.py > sp.xml

This file you have to give to the person/organization that runs the AA/IdP you
want to get information from.

!!! That should be it !!!