openstack/deb-python-pysaml2
Code Issues Proposed changes

shuffled doc files

Browse Source
This commit is contained in:
Roland Hedberg
2011-03-14 12:55:45 +01:00
parent 2ce0359704
commit 5b4ab566d1
3 changed files with 7 additions and 207 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
doc/howto/idp.rst
View File

@@ -1,73 +0,0 @@
.. _howto_idp:
How to make a SAML2 identity provider.
======================================
To make an SAML2 identity provider is a bit tricker than doing a service
provider, mainly because you have to divide the functionality between
the application and the plugins.
Now, to do that you have to understand how repoze.who works.
Basically on every request; the ingress plugins first gets to do their stuff,
then the application and finally the egress plugins.
So in broad terms this is what happens:
1. A GET request is received for where ever the IdP is supposted to be listing.
1.1 Identifiers are checked on ingress and none of them will be able to
identify the user since no login has been done.
1.2 After the ingress plugins have had their turn, the control is passed
to the application, which must state that a 401 reponse should be
returned if a user tries to access the IdP without an identification.
1.3 On a 401 response the egress challenger, in this case the plugin 'form',
is activated.
The configuration of this plugin is::
[plugin:form]
use = s2repoze.plugins.formswithhidden:make_plugin
login_form_qs = __do_login
rememberer_name = auth_tkt
What's special with this form plugin is that the form carries the
query part of the original GET request in hidden fields.
1.4 The form is displayed, the user enters the user name and password and
submits the form.
2. The log in form reply is received by the server
2.1 The ingress identifier gets the form and extracts login and password
and passes it on to the authentication plugin. It will also extract
the query parameters from the hidden fields and store them in an
environment variable ('s2repoze.qinfo').
If the login and password was correct a cookie is issued. If there is
a mdprovider plugin defined it will now add extra information about
the individual from some external source.
After this the control is passed on to the application.
2.2 The function that is bound to the path of the IdP now gets to act.
This is just the main outline:
* It finds the query parameters in the
environment and parses it::
query = environ["s2repoze.qinfo"]
(consumer, identifier, name_id_policy,
spid) = IDP.parse_authn_request(query["SAMLRequest"][0])
* then for the user information::
identity = environ["repoze.who.identity"]["user"]
userid = environ["repoze.who.identity"]['repoze.who.userid']
* and finally build the response::
authn_resp = IDP.authn_response(identity, identifier, consumer,
spid, name_id_policy, userid)
IDP is assumed to be an instance of saml2.server.Server

15
doc/howto/index.rst
View File

@@ -25,18 +25,17 @@ But anyway, you may get my point. This is middleware stuff !
PySAML2 is built to fit into a
`WSGI <http://www.python.org/dev/peps/pep-0333/>`_ application
There are more than one WSGI framework out there, so when I started this work
I just picked one I liked, namely `Repoze <http://repoze.org/>`_ .
Or to be more specific I choose to work within the context of
`Repoze.who <http://static.repoze.org/whodocs/>`_.
But it can be used in a non-WSGI environment too.
So the descriptions in the following chapters are based on the usage of
pySAML2 together with repoze.who .
So you will find descriptions of both cases here.
The configuration is the same disregarding whether you are using PySAML2 in a
WSGI or non-WSGI environment.
.. toctree::
:maxdepth: 1
config
sp
idp
wsgi/index
nonwsgi/index

126
doc/howto/sp.rst
View File

@@ -1,126 +0,0 @@
.. _howto_sp:
How to make a SAML2 service provider (SP).
==========================================
How it works
------------
A SP handles authentication, by the use of an Identity Provider, and possibly
attribute aggregation.
Both of these functions can be seen as parts of the normal Repoze.who
setup. Namely the Challenger, Identifier and MetadataProvider parts so that
is also how it is implemented.
Normal for Repoze.who Identifier and MetadataProvider plugins are that
they place the information, they gather, in environment variables. The convention is
to place identity information in the environment under the key
*repoze.who.identity*.
The information is structured as a dictionary with keys like *login*, and
*repoze.who.userid*.
This SP follows this pattern and places the information gathered from
the Identity Provider that handled the authentication and possible extra
information received from attribute authorities in the above mentioned
dictionary under the key *user*.
To summaries: in environ["repoze.who.identity"]["user"] you will find a
dictionary with attributes and values describing the identity of a subject,
the attribute names used depends on what's returned from the Identity
Provider and possible Attribute Authorities.
Accessing the information from an application is done by doing something
like this::
user_info = environ["repoze.who.identity"]["user"]
If a WAYF is going to be used, then the pattern is the following:
unauthenticated user + no IdP selected
In this case, if there is a WAYF page specified in the
SP part of the repoze.who configuration file,
the user is redirected to that page. If no WAYF page is known an exception
is raised.
unauthenticated user + selected IdP
This is after the WAYF has been used, the entity ID of the selected IdP
is expected to be in the environment variable *s2repose.wayf_selected*.
If so the user is redirected to that IdP.
The set-up
----------
There are two configuration files you have to deal with, first the
pySAML2 configuration file which you can read more about here
:ref:`howto_config` and secondly the repoze.who configuration file.
And it is the later one I will deal with here.
The **sp** plugin configuration has the following arguments
use
Which module to use and which factory function in that module that should
be run to initiate the plugin.
rememberer_name
Which plugin to use for remembering users
saml_conf
Where the pySAML2 configuration file can be found
virtual_organization
Which virtual organization this SP belongs to, can only be none or one.
debug
Debug state, an integer. Presently just on (!= 0)/off (0) is supported.
cache
If no cache file is defined, an in-memory cache will be used to
remember information received from IdPs and AAs. If a file name
is given that file will be used for persistent storage of the cache.
wayf
The webpage where the WAYF service is situated.
An example::
[plugin:saml2sp]
use = s2repoze.plugins.sp:make_plugin
saml_conf = sp.conf
rememberer_name = auth_tkt
debug = 1
sid_store = outstanding
identity_cache = identities
wayf = wayf.html
Once you have configured the plugin you have to tell the server to use the
plugin in different ingress and egress operations as specified in
`Middleware responsibilities <http://docs.repoze.org/who/narr.html>`_
A typical SP configuration would be to use it in all aspects::
[identifiers]
plugins =
saml2sp
auth_tkt
[authenticators]
plugins = saml2sp
[challengers]
plugins = saml2sp
[mdproviders]
plugins = saml2sp
Other information
-----------------
The SP keeps tabs on all outstanding authentication requests it has.
This is kept in the datastore pointed to by *sid_store*.
Presently if an authentication reponse is received that does not match an
outstanding request the reponse is ignored. This is going to change in the
future.
The format of *sid_store* is a dictionary with the outstanding session IDs as
keys.