Examples of PySaml2 usage

doc/examples/idp.rst

@@ -0,0 +1,4 @@
+.. _idp:
+
+An extremly simple example of a SAML2 identity provider.
+========================================================

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`
+

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 <http://static.repoze.org/whodocs/narr.html>`_ 
+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.