diff --git a/doc/howto/idp.rst b/doc/howto/idp.rst deleted file mode 100644 index 4f83198..0000000 --- a/doc/howto/idp.rst +++ /dev/null @@ -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 - - diff --git a/doc/howto/index.rst b/doc/howto/index.rst index 189c982..e9bf6da 100644 --- a/doc/howto/index.rst +++ b/doc/howto/index.rst @@ -25,18 +25,17 @@ But anyway, you may get my point. This is middleware stuff ! PySAML2 is built to fit into a `WSGI `_ application -There are more than one WSGI framework out there, so when I started this work -I just picked one I liked, namely `Repoze `_ . -Or to be more specific I choose to work within the context of -`Repoze.who `_. +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 diff --git a/doc/howto/sp.rst b/doc/howto/sp.rst deleted file mode 100644 index e32ccdb..0000000 --- a/doc/howto/sp.rst +++ /dev/null @@ -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 `_ - -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. -