From bac5a0bd45451aee61171a018d2452e9e5ff002d Mon Sep 17 00:00:00 2001 From: Ivan Kanakarakis Date: Sun, 3 Nov 2019 21:23:39 +0200 Subject: Fix warnings from docs generation Signed-off-by: Ivan Kanakarakis --- docs/examples/idp.rst | 6 ++++-- docs/examples/sp.rst | 47 ++++++++++++++++++++++++----------------------- docs/howto/config.rst | 2 +- docs/sp_test/internal.rst | 6 +++--- 4 files changed, 32 insertions(+), 29 deletions(-) diff --git a/docs/examples/idp.rst b/docs/examples/idp.rst index cb990dde..01b78705 100644 --- a/docs/examples/idp.rst +++ b/docs/examples/idp.rst @@ -6,8 +6,10 @@ An extremly simple example of a SAML2 identity provider. There are 2 example IDPs in the project's example directory: * idp2 has a static definition of users: - * user attributes are defined in idp_user.py - * the password is defined in the PASSWD dict in idp.py + + * user attributes are defined in idp_user.py + * the password is defined in the PASSWD dict in idp.py + * idp2_repoze is using repoze.who middleware to perform authentication and attribute retrieval Configuration diff --git a/docs/examples/sp.rst b/docs/examples/sp.rst index 7d392257..3990d3e1 100644 --- a/docs/examples/sp.rst +++ b/docs/examples/sp.rst @@ -1,6 +1,6 @@ .. _example_sp: -An extremely simple example of a SAML2 service provider. +An extremely simple example of a SAML2 service provider ======================================================= How it works @@ -15,12 +15,12 @@ they place information in environment variables. The convention is to place identity information in environ["repoze.who.identity"]. This is a dictionary with keys like 'login', and 'repoze.who.userid'. -The SP follows this pattern and places the information gathered from +The SP follows this pattern and places the information gathered from the IdP that handled the authentication and possible extra information received from attribute authorities in the above mentioned dictionary under the key 'user'. -So in environ["repoze.who.identity"] you will find a dictionary with +So in environ["repoze.who.identity"] you will find a dictionary with attributes and values, the attribute names used depends on what's returned from the IdP/AA. If there exists both a name and a friendly name, for instance, the friendly name is used as the key. @@ -47,6 +47,7 @@ sp_conf.py is configured to run on localhost on port 8087. If you want to you co **sp-repoze:** * Go to the folder: + [your path]/pysaml2/example/sp-repoze * Take the file named sp_conf.py.example and rename it sp_conf.py @@ -61,11 +62,11 @@ sp_conf.py is configured to run on localhost on port 8087. If you want to you co Important files: sp_conf.py - The SPs configuration - + The SPs configuration + who.ini The repoze.who configuration file - + Inside the folder named pki there are two files with certificates, mykey.pem with the private certificate and mycert.pem with the public part. @@ -83,15 +84,15 @@ it line by line:: "service": ["sp"], Tells the software what type of services the software is supposed to -supply. It is used to check for the +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" +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", @@ -101,11 +102,11 @@ 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 ? :: @@ -122,7 +123,7 @@ 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/", + "url":"http://www.example.com/", }, Information about the organization that is behind this SP, only used when @@ -144,12 +145,12 @@ 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. +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 - + who.ini @@ -157,7 +158,7 @@ who.ini The file named ``who.ini`` is the ``sp-repoze`` folder I'm not going through the INI file format here. You should read -`Middleware Responsibilities `_ +`Middleware Responsibilities `_ to get a good introduction to the concept. The configuration of the pysaml2 part in the applications middleware are @@ -170,10 +171,10 @@ first the special module configuration, namely:: 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 +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 +("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:: @@ -182,7 +183,7 @@ After this, the plugin is referenced in a couple of places:: plugins = saml2auth auth_tkt - + [authenticators] plugins = saml2auth @@ -216,10 +217,10 @@ The application The app is, as said before, extremely simple. The only thing that is connected to the PySaml2 configuration is at the bottom, namely where the server is. -You have to ascertain that this coincides with what is specified in the -PySaml2 configuration. Apart from that there really is nothing 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 +You have to ascertain that this coincides with what is specified in the +PySaml2 configuration. Apart from that there really is nothing 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. diff --git a/docs/howto/config.rst b/docs/howto/config.rst index 1aee086c..0ae9487d 100644 --- a/docs/howto/config.rst +++ b/docs/howto/config.rst @@ -674,7 +674,7 @@ Example:: } want_assertions_or_response_signed -"""""""""""""""""""" +"""""""""""""""""""""""""""""""""" Indicates that *either* the Authentication Response *or* the assertions contained within the response to this SP must be signed. diff --git a/docs/sp_test/internal.rst b/docs/sp_test/internal.rst index bea43336..6720742f 100644 --- a/docs/sp_test/internal.rst +++ b/docs/sp_test/internal.rst @@ -22,7 +22,7 @@ These files should be stored outside the saml2test package to have a clean separ :::::::::::::::::::::::::::::: Client (sp_test/__init__.py) -......................... +............................ Its life cycle is responsible for following activities: - read config files and command line arguments (the test driver's config is "json_config") - initialize the test driver IDP @@ -49,7 +49,7 @@ Sequence - Example: see "sequence" item in operation dict Test (in the context of an operation) -.... +..................................... - class to be executed as part of an operation, either before ("pre") or after ("post") the sequence or in between a SAML request and response ("mid"). There are standard tests with the Request class (VerifyAuthnRequest) and operation-specific tests. - Example for an operation-specific "mid" test: VerifyIfRequestIsSigned @@ -66,7 +66,7 @@ Flow * flow[3]: Check (optional - can be None. E.g. check the response if a correct error status was raised when sending a broken response) Check (and subclasses) -..... +...................... - An optional class that is executed on receiving the SP's HTTP response(s) after the SAML response. If there are redirects, it will be called for each response. - Writes a structured test report to conv.test_output - It can check for expected errors, which do not cause an exception but in contrary are reported as a success -- cgit v1.2.1