From e28f08f640e2f3fff24d8496d0dc7c9080109703 Mon Sep 17 00:00:00 2001 From: Roland Hedberg Date: Mon, 9 Nov 2009 16:51:26 +0100 Subject: [PATCH] Examples of PySaml2 usage --- doc/examples/idp.rst | 4 + doc/examples/index.rst | 23 ++++++ doc/examples/sp.rst | 161 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 188 insertions(+) create mode 100644 doc/examples/idp.rst create mode 100644 doc/examples/index.rst create mode 100644 doc/examples/sp.rst diff --git a/doc/examples/idp.rst b/doc/examples/idp.rst new file mode 100644 index 0000000..9e69e2d --- /dev/null +++ b/doc/examples/idp.rst @@ -0,0 +1,4 @@ +.. _idp: + +An extremly simple example of a SAML2 identity provider. +======================================================== diff --git a/doc/examples/index.rst b/doc/examples/index.rst new file mode 100644 index 0000000..a0a2741 --- /dev/null +++ b/doc/examples/index.rst @@ -0,0 +1,23 @@ +.. _example_index: + +These are examples of the usage of pysaml2! +=========================================== + +:Release: |version| +:Date: |today| + +Contents: + +.. toctree:: + :maxdepth: 1 + + sp + idp + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/examples/sp.rst b/doc/examples/sp.rst new file mode 100644 index 0000000..ba54395 --- /dev/null +++ b/doc/examples/sp.rst @@ -0,0 +1,161 @@ +.. _sp: + +An extremly simple example of a SAML2 service provider. +======================================================= + +I you look in the example/sp directory of the distribution you will see +the necessary files: + +application.py + which is the web application. In this case it will just print the + information provided by the IdP in a table. + +sp_conf.py + The SPs configuration + +who.ini + The repoze.who configuration file + +And then there are two files with certificates, mykey.pem with the private +certificate and mycert.pem with the public part. + +I'll go through these step by step. + +SP configuration +---------------- + +The configuration is written as a Python dictionary. It means among other +things that it's easily testable as to the correct syntax. + +You can see the whole file in example/sp/sp_conf.py, here I will go through +it line by line:: + + "service": ["sp"], + +Tells the software what type of services the software are suppost to +supply. It is used to check for the +completeness of the configuration and also when constructing metadata from +the configuration. More about that later. Allowed values are: "sp" +(service provider), "idp" (identity provider) and "aa" (attribute authority). +:: + + "entityid" : "urn:mace:example.com:saml:sp", + "service_url" : "http://example.com:8087/", + +The ID of the entity and the URL on which it is listening.:: + + "idp_url" : "https://example.com/saml2/idp/SSOService.php", + +Since this is a very simple SP it only need to know about one IdP, therefor there +is really no need for a metadata file or a WAYF-function or anything like that. +It needs the URL of the IdP and that's all.:: + + "my_name" : "My first SP", + +This is just for informal purposes, not really needed but nice to do:: + + "debug" : 1, + +Well, at this point in time you'd really like to have as much information +as possible as to what's going on, right ? :: + + "key_file" : "./mykey.pem", + "cert_file" : "./mycert.pem", + +The necessary certificates.:: + + "xmlsec_binary" : "/opt/local/bin/xmlsec1", + +Right now the software is built to use xmlsec binaries and not the python +xmlsec package. There are reasons for this but I won't go into them here.:: + + "organization": { + "name": "Example Co", + #display_name + "url":"http://www.example.com/", + }, + +Information about the organization that is behind this SP, only used when +building metadata. :: + + "contact": [{ + "given_name":"John", + "sur_name": "Smith", + "email_address": "john.smith@example.com", + #contact_type + #company + #telephone_number + }] + +Another piece of information that only is matters if you build and distribute +metadata. + +So, now to that part. In order to allow the IdP to talk to you you may have +to provide the one running the IdP with a metadata file. +If you have a SP configuration file similar to the one I've walked you +through here, but with your information. You can make the metadata file +by running the make_metadata script you can find in the tools directory. + +Change directory to where you have the configuration file and do :: + + make_metadata.py sp_conf.py > metadata.xml + + + +Repoze configuration +-------------------- + +I'm not going through the INI file format here. You should read +`Middleware Responsibilities `_ +to get a good introduction to the concept. + +The configuration of the pysaml2 part in the applications middleware are +first the special module configuration, namely:: + + [plugin:saml2auth] + use = s2repoze.plugins.sp:make_plugin + saml_conf = sp_conf.py + rememberer_name = auth_tkt + debug = 1 + path_logout = .*/logout.* + +Which contains a specification ("use") of which function in which module +should be used to initialize the part. After that comes the name of the +file ("saml_conf") that contains the PySaml2 configuration. The third line +("rememberer_name") points at the plugin that should be used to +remember the user information. + +After this, the plugin is referenced in a couple of places:: + + [identifiers] + plugins = + saml2auth + auth_tkt + + [authenticators] + plugins = saml2auth + + [challengers] + plugins = saml2auth + + [mdproviders] + plugins = saml2auth + +Which means that the plugin is used in all phases. + +The application +--------------- + +Is as said before extremly simple. The only thing that is connected to +the PySaml2 configuration are at the bottom, namely where the server are. +You have to ascertain that this coincides with what is specified in the +PySaml2 configuration. Apart from that there really are no thing in +application.py that demands that you use PySaml2 as middleware. If you +switched to using the LDAP or CAS plugins nothing would change in the +application. In the application configuration yes! But not in the application. +And that is really how it should be done. + +There is one assumption and that is that the middleware plugin that gathers +information about the user places the extra information in as value on the +"user" property in the dictionary found under the key "repoze.who.identity" +in the environment.