Merge pull request #151 from sbc100/doc_fixes

Doc fixes

Author: pitbulk

README.md

@@ -7,31 +7,30 @@
 ![Python versions](https://img.shields.io/pypi/pyversions/python-saml.svg)
 
 Add SAML support to your Python software using this library.
-Forget those complicated libraries and use that open source library provided
+Forget those complicated libraries and use the open source library provided
 and supported by OneLogin Inc.
 
-This version supports Python2, exists an alternative version compatible with Python 3: [python3-saml](https://github.com/onelogin/python3-saml)
+This version supports Python2. There is a separate version that supports
+Python3: [python3-saml](https://github.com/onelogin/python3-saml).
 
 #### Warning ####
 
 Update python-saml to 2.1.9, this version includes a security patch that contains extra validations that will prevent signature wrapping attacks.
 
 python-saml < v2.1.6 is vulnerable and allows signature wrapping!
 
-
 #### Security Guidelines ####
 
 If you believe you have discovered a security vulnerability in this toolkit, please report it at https://www.onelogin.com/security with a description. We follow responsible disclosure guidelines, and will work with you to quickly find a resolution.
 
-
 Why add SAML support to my software?
 ------------------------------------
 
 SAML is an XML-based standard for web browser single sign-on and is defined by
-the OASIS Security Services Technical Committee. The standard has been around 
+the OASIS Security Services Technical Committee. The standard has been around
 since 2002, but lately it is becoming popular due its advantages:
 
- * **Usability** - One-click access from portals or intranets, deep linking, 
+ * **Usability** - One-click access from portals or intranets, deep linking,
    password elimination and automatically renewing sessions make life
    easier for the user.
  * **Security** - Based on strong digital signatures for authentication and
@@ -44,21 +43,21 @@ since 2002, but lately it is becoming popular due its advantages:
  * **IT Friendly** - SAML simplifies life for IT because it centralizes
    authentication, provides greater visibility and makes directory
    integration easier.
- * **Opportunity** - B2B cloud vendor should support SAML to facilitate the 
+ * **Opportunity** - B2B cloud vendor should support SAML to facilitate the
    integration of their product.
 
 General description
 -------------------
 
-OneLogin's SAML Python toolkit let you build a SP (Service Provider) over
-your Python application and connect it to any IdP (Identity Provider).
+OneLogin's SAML Python toolkit lets you turn you Python application into an SP
+(Service Provider) that can connect to a IdP (Identity Provider).
 
 Supports:
 
  * SSO and SLO (SP-Initiated and IdP-Initiated).
  * Assertion and nameId encryption.
- * Assertion signature.
- * Message signature: AuthNRequest, LogoutRequest, LogoutResponses.
+ * Assertion signatures.
+ * Message signatures: AuthNRequest, LogoutRequest, LogoutResponses.
  * Enable an Assertion Consumer Service endpoint.
  * Enable a Single Logout Service endpoint.
  * Publish the SP metadata (which can be signed).
@@ -68,7 +67,7 @@ Key features:
  * **saml2int** - Implements the SAML 2.0 Web Browser SSO Profile.
  * **Session-less** - Forget those common conflicts between the SP and
    the final app, the toolkit delegate session in the final app.
- * **Easy to use** - Programmer will be allowed to code high-level and 
+ * **Easy to use** - Programmer will be allowed to code high-level and
    low-level programming, 2 easy to use APIs are available.
  * **Tested** - Thoroughly tested.
  * **Popular** - OneLogin's customers use it. Add easy support to your django/flask/bottle web projects.
@@ -77,7 +76,7 @@ Key features:
 Installation
 ------------
 
-### Dependences ###
+### Dependencies ###
 
  * python 2.7
  * [dm.xmlsec.binding](https://pypi.python.org/pypi/dm.xmlsec.binding)  Cython/lxml based binding for the XML security library (depends on python-dev libxml2-dev libxmlsec1-dev)
@@ -87,13 +86,14 @@ Installation
 
 Review the setup.py file to know the version of the library that python-saml is using
 
-### OSX Dependences ###
+### OSX Dependencies ###
+
  * python 2.7
  * libxmlsec1
- 
+
 ```sh
- # using brew
- brew install libxmlsec1
+# using brew
+$ brew install libxmlsec1
 ```
 
 
@@ -106,15 +106,15 @@ The toolkit is hosted on github. You can download it from:
  * Lastest release: https://github.com/onelogin/python-saml/releases/latest
  * Master repo: https://github.com/onelogin/python-saml/tree/master
 
-Copy the core of the library (src/onelogin/saml2 folder) and merge the setup.py inside the python application. (each application has its structure so take your time to locate the Python SAML toolkit in the best place). 
+Copy the core of the library (src/onelogin/saml2 folder) and merge the setup.py inside the python application. (each application has its structure so take your time to locate the Python SAML toolkit in the best place).
 
 #### Option 2. Download from pypi ####
 
 The toolkit is hosted in pypi, you can find the python-saml package at https://pypi.python.org/pypi/python-saml
 
 You can install it executing:
 ```
- pip install python-saml
+$ pip install python-saml
 ```
 
 If you want to know how a project can handle python packages review this [guide](https://packaging.python.org/en/latest/tutorial.html) and review this [sampleproject](https://github.com/pypa/sampleproject)
@@ -123,7 +123,7 @@ If you want to know how a project can handle python packages review this [guide]
 Security warning
 ----------------
 
-In production, the **strict** parameter MUST be set as **"true"**. Otherwise 
+In production, the **strict** parameter MUST be set as **"true"**. Otherwise
 your environment is not secure and will be exposed to attacks.
 
 
@@ -217,7 +217,7 @@ This is the settings.json file:
 
 ```javascript
 {
-    // If strict is True, then the Python Toolkit will reject unsigned 
+    // If strict is True, then the Python Toolkit will reject unsigned
     // or unencrypted messages if it expects them to be signed or encrypted.
     // Also it will reject the messages if the SAML standard is not strictly
     // followed. Destination, NameId, Conditions ... are validated too.
@@ -236,11 +236,11 @@ This is the settings.json file:
             // URL Location where the <Response> from the IdP will be returned
             "url": "https://<sp_domain>/?acs",
             // SAML protocol binding to be used when returning the <Response>
-            // message. OneLogin Toolkit supports this endpoint for the 
+            // message. OneLogin Toolkit supports this endpoint for the
             // HTTP-POST binding only.
             "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
         },
-        // If you need to specify requested attributes, set a 
+        // If you need to specify requested attributes, set a
         // attributeConsumingService. nameFormat, attributeValue and
         // friendlyName can be omitted
         "attributeConsumingService": {
@@ -257,7 +257,7 @@ This is the settings.json file:
                 ]
         },
         // Specifies info about where and how the <Logout Response> message MUST be
-        // returned to the requester, in this case our SP. 
+        // returned to the requester, in this case our SP.
         "singleLogoutService": {
             // URL Location where the <Response> from the IdP will be returned
             "url": "https://<sp_domain>/?sls",
@@ -282,7 +282,7 @@ This is the settings.json file:
         "entityId": "https://app.onelogin.com/saml/metadata/<onelogin_connector_id>",
         // SSO endpoint info of the IdP. (Authentication Request protocol)
         "singleSignOnService": {
-            // URL Target of the IdP where the Authentication Request Message 
+            // URL Target of the IdP where the Authentication Request Message
             // will be sent.
             "url": "https://app.onelogin.com/trust/saml2/http-post/sso/<onelogin_connector_id>",
             // SAML protocol binding to be used when returning the <Response>
@@ -302,16 +302,16 @@ This is the settings.json file:
         // Public x509 certificate of the IdP
         "x509cert": "<onelogin_connector_cert>"
         /*
-         *  Instead of use the whole x509cert you can use a fingerprint in order to 
+         *  Instead of using the whole x509cert you can use a fingerprint in order to
          *  validate a SAMLResponse, but you will need it to validate LogoutRequest and LogoutResponse using the HTTP-Redirect binding.
-         * 
+         *
          *  (openssl x509 -noout -fingerprint -in "idp.crt" to generate it,
          *  or add for example the -sha256 , -sha384 or -sha512 parameter)
          *
          *  If a fingerprint is provided, then the certFingerprintAlgorithm is required in order to
          *  let the toolkit know which algorithm was used. Possible values: sha1, sha256, sha384 or sha512
          *  'sha1' is the default value.
-         * 
+         *
          *  Notice that if you want to validate any SAML Message sent by the HTTP-Redirect binding, you
          *  will need to provide the whole x509cert.
          */
@@ -321,7 +321,7 @@ This is the settings.json file:
 }
 ```
 
-In addition to the required settings data (idp, sp), there is extra information that could be defined at advanced_settings.json
+In addition to the required settings data (idp, sp), extra settings can be defined in `advanced_settings.json`:
 
 ```javascript
 {
@@ -334,15 +334,15 @@ In addition to the required settings data (idp, sp), there is extra information
         // will be encrypted.
         "nameIdEncrypted": false,
 
-        // Indicates whether the <samlp:AuthnRequest> messages sent by this SP 
+        // Indicates whether the <samlp:AuthnRequest> messages sent by this SP
         // will be signed.  [Metadata of the SP will offer this info]
         "authnRequestsSigned": false,
 
-        // Indicates whether the <samlp:logoutRequest> messages sent by this SP 
+        // Indicates whether the <samlp:logoutRequest> messages sent by this SP
         // will be signed.
         "logoutRequestSigned": false,
 
-        // Indicates whether the <samlp:logoutResponse> messages sent by this SP 
+        // Indicates whether the <samlp:logoutResponse> messages sent by this SP
         // will be signed.
         "logoutResponseSigned": false,
 
@@ -368,7 +368,7 @@ In addition to the required settings data (idp, sp), there is extra information
         // elements received by this SP to be encrypted.
         'wantAssertionsEncrypted' => false,
 
-        // Indicates a requirement for the NameID element on the SAMLResponse 
+        // Indicates a requirement for the NameID element on the SAMLResponse
         // received by this SP to be present.
         "wantNameId": true,
 
@@ -428,7 +428,7 @@ In addition to the required settings data (idp, sp), there is extra information
 }
 ```
 
-In the security section, you can set the way that the SP will handle the messages and assertions. Contact the admin of the IdP and ask him what the IdP expects, and decide what validations will handle the SP and what requirements the SP will have and communicate them to the IdP's admin too.
+In the security section, you can set the way that the SP will handle the messages and assertions. Contact the admin of the IdP and ask them what the IdP expects, and decide what validations will handle the SP and what requirements the SP will have and communicate them to the IdP's admin too.
 
 Once we know what kind of data could be configured, let's talk about the way settings are handled within the toolkit.
 
@@ -557,7 +557,7 @@ auth.get_last_request_id()
 
 #### The SP Endpoints ####
 
-Related to the SP there are 3 important endpoints: The metadata view, the ACS view and the SLS view. 
+Related to the SP there are 3 important endpoints: The metadata view, the ACS view and the SLS view.
 The toolkit provides examples of those views in the demos, but lets see an example.
 
 ***SP Metadata***
@@ -580,7 +580,7 @@ The get_sp_metadata will return the metadata signed or not based on the security
 
 Before the XML metadata is exposed, a check takes place to ensure that the info to be provided is valid.
 
-Instead of use the Auth object, you can directly use
+Instead of using the Auth object, you can directly use
 ```
 saml_settings = OneLogin_Saml2_Settings(settings=None, custom_base_path=None, sp_validation_only=True)
 ```
@@ -598,7 +598,7 @@ errors = auth.get_errors()
 if not errors:
     if auth.is_authenticated():
         request.session['samlUserdata'] = auth.get_attributes()
-        if 'RelayState' in req['post_data'] and 
+        if 'RelayState' in req['post_data'] and
           OneLogin_Saml2_Utils.get_self_url(req) != req['post_data']['RelayState']:
             auth.redirect_to(req['post_data']['RelayState'])
         else:
@@ -636,7 +636,7 @@ If we execute print attributes we could get:
     "mail": ["Doe"],
     "groups": ["users", "members"]
 }
-``` 
+```
 
 Each attribute name can be used as a key to obtain the value. Every attribute is a list of values. A single-valued attribute is a listy of a single element.
 
@@ -679,7 +679,7 @@ if not logout_response.is_valid(self.__request_data, request_id):
 elif logout_response.get_status() != OneLogin_Saml2_Constants.STATUS_SUCCESS:
     self.__errors.append('logout_not_success')
 elif not keep_local_session:
-    OneLogin_Saml2_Utils.delete_local_session(delete_session_cb)  
+    OneLogin_Saml2_Utils.delete_local_session(delete_session_cb)
 ```
 
 If the SLS endpoints receives an Logout Request, the request is validated, the session is closed and a Logout Response is sent to the SLS endpoint of the IdP.
@@ -723,7 +723,7 @@ In order to send a Logout Request to the IdP:
 
 The Logout Request will be sent signed or unsigned based on the security info of the advanced_settings.json ('logoutRequestSigned').
 
-The IdP will return the Logout Response through the user's client to the Single Logout Service of the SP. 
+The IdP will return the Logout Response through the user's client to the Single Logout Service of the SP.
 
 We can set a 'return_to' url parameter to the logout function and that will be converted as a 'RelayState' parameter:
 
@@ -734,7 +734,7 @@ auth.logout(return_to=target_url)
 
 Also there are 2 optional parameters that can be set:
 
-* name_id. That will be used to build the LogoutRequest. If not name_id parameter is set and the auth object processed a 
+* name_id. That will be used to build the LogoutRequest. If not name_id parameter is set and the auth object processed a
 SAML Response with a NameId, then this NameId will be used.
 * session_index. SessionIndex that identifies the session of the user.
 
@@ -758,21 +758,21 @@ auth = OneLogin_Saml2_Auth(req)             # Initialize the SP SAML instance
 
 if 'sso' in request.args:                   # SSO action (SP-SSO initited).  Will send an AuthNRequest to the IdP
     return redirect(auth.login())
-elif 'sso2' in request.args:                       # Another SSO init action 
+elif 'sso2' in request.args:                       # Another SSO init action
     return_to = '%sattrs/' % request.host_url      # but set a custom RelayState URL
     return redirect(auth.login(return_to))
 elif 'slo' in request.args:                     # SLO action. Will sent a Logout Request to IdP
     return redirect(auth.logout())
 elif 'acs' in request.args:                 # Assertion Consumer Service
     auth.process_response()                     # Process the Response of the IdP
     errors = auth.get_errors()              # This method receives an array with the errors
-    if len(errors) == 0:                    # that could took place during the process 
+    if len(errors) == 0:                    # that could took place during the process
         if not auth.is_authenticated():         # This check if the response was ok and the user
             msg = "Not authenticated"           # data retrieved or not (user authenticated)
         else:
             request.session['samlUserdata'] = auth.get_attributes()     # Retrieves user data
             self_url = OneLogin_Saml2_Utils.get_self_url(req)
-            if 'RelayState' in request.form and self_url != request.form['RelayState']:   
+            if 'RelayState' in request.form and self_url != request.form['RelayState']:
                 return redirect(auth.redirect_to(request.form['RelayState']))   # Redirect if there is a relayState
             else:                           # If there is user data we save that to print it later.
                 msg = ''
@@ -875,7 +875,7 @@ SAML 2 Logout Response class
 * ***get_status*** Gets the Status of the Logout Response.
 * ***is_valid*** Determines if the SAML LogoutResponse is valid
 * ***build*** Creates a Logout Response object.
-* ***get_response*** Returns a Logout Response object. 
+* ***get_response*** Returns a Logout Response object.
 * ***get_error*** After execute a validation process, if fails this method returns the cause.
 
 
@@ -915,7 +915,7 @@ Configuration of the OneLogin Python Toolkit
 
 A class that contains functionality related to the metadata of the SP
 
-* ***builder*** Generates the metadata of the SP based on the settings. 
+* ***builder*** Generates the metadata of the SP based on the settings.
 * ***sign_metadata*** Signs the metadata with the key/cert provided.
 * ***add_x509_key_descriptors*** Adds the x509 descriptors (sign/encriptation) to the metadata
 
@@ -1039,7 +1039,7 @@ The flask project contains:
 
 ####SP setup####
 
-The Onelogin's Python Toolkit allows you to provide the settings info in 2 ways: settings files or define a setting dict. In the demo-flask it used the first method. 
+The Onelogin's Python Toolkit allows you to provide the settings info in 2 ways: settings files or define a setting dict. In the demo-flask it used the first method.
 
 In the index.py file we define the app.config['SAML_PATH'], that will target to the 'saml' folder. We require it in order to load the settings files.
 
@@ -1079,7 +1079,7 @@ To run the demo you need to install the requirements first. Load your
 virtualenv  and execute:
 ```
  pip install -r demo-django/requirements.txt
-``` 
+```
 This will install django and its dependences. Once it has finished, you have to complete the configuration of the toolkit.
 
 Later, with the virtualenv loaded, you can run the demo like this:
@@ -1112,9 +1112,9 @@ The django project contains:
 
 ####SP setup####
 
-The Onelogin's Python Toolkit allows you to provide the settings info in 2 ways: settings files or define a setting dict. In the demo-django it used the first method. 
+The Onelogin's Python Toolkit allows you to provide the settings info in 2 ways: settings files or define a setting dict. In the demo-django it used the first method.
 
-After set the SAML_FOLDER in the demo/settings.py, the settings of the python toolkit will be loaded on the django web. 
+After set the SAML_FOLDER in the demo/settings.py, the settings of the python toolkit will be loaded on the django web.
 
 First we need to edit the saml/settings.json, configure the SP part and  review the metadata of the IdP and complete the IdP info.  Later edit the saml/advanced_settings.json files and configure the how the toolkit will work. Check the settings section of this document if you have any doubt.
 

demo-flask/index.py

@@ -121,7 +121,7 @@ def metadata():
         resp = make_response(metadata, 200)
         resp.headers['Content-Type'] = 'text/xml'
     else:
-        resp = make_response(errors.join(', '), 500)
+        resp = make_response(', '.join(errors), 500)
     return resp