Add some documentaion and some light cleanup.

Author: jeffFranklin

README.md

@@ -1,3 +1,63 @@
 # uw-saml
 
-A UW-specific adapter to the python3-saml package.
+A UW-specific adapter to the
+[python3-saml](https://github.com/onelogin/python3-saml) package. This package
+was built to federate with other IdPs, but the default case is to use the UW
+Identity Provider. It can be used against any framework. For a django-specific
+package, also consider
+[uw-django-saml2](https://github.com/uw-it-aca/uw-django-saml2).
+
+# Installation
+
+```bash
+pip install uw-saml
+```
+
+# Example login endpoint using flask
+
+In this example you've gone to
+[SP Registry](https://iam-tools.u.washington.edu/spreg) and registered an
+Entity ID of https://samldemo.iamdev.s.uw.edu/saml, with an ACS endpoint of
+https://samldemo.iamdev.s.uw.edu/saml/login. GETs will return a
+redirect to the IdP for authentication, and POSTs will try to process a SAML
+Response.
+
+```python
+from flask import request, session, redirect
+
+@app.route('/saml/login', methods=['GET', 'POST'])
+def login():
+    session.clear()
+    args = {
+        'entity_id': 'https://samldemo.iamdev.s.uw.edu/saml',
+        'acs_url': 'https://samldemo.iamdev.s.uw.edu/saml/login'
+    }
+    if request.method == 'GET':
+        args['return_to'] = request.args.get('url', None)
+        return redirect(uw_saml2.login_redirect(**args))
+
+    attributes = uw_saml2.process_response(request.form, **args)
+    session['userid'] = attributes['uwnetid']
+    session['groups'] = attributes.get('groups', [])
+
+    relay_state = request.form.get('RelayState')
+    if relay_state and relay_state.startswith('/'):
+        return redirect(urljoin(request.url_root, request.form['RelayState']))
+
+    return 'Welcome ' + session['userid']
+```
+
+# Considerations
+
+Give some consideration to session lifetime. The session in this example lives as a
+signed cookie. Ideally the cookie would expire at browser close, along with
+some time limit appropriate for your application. An example again with flask
+for a ten minute limit...
+
+```python
+from datetime import timedelta
+
+app.config.update(
+    PERMANENT_SESSION_LIFETIME=timedelta(minutes=10)
+)
+```

uw_saml2/auth.py

@@ -1,32 +1,66 @@
 """UW-specific adapter for the python3-saml package."""
 from onelogin.saml2.auth import OneLogin_Saml2_Auth
 from .idp.uw import UwIdp
-from .sp import Config
+from .sp import Config, TWO_FACTOR_CONTEXT
 from .idp import attribute
 from logging import getLogger
 logger = getLogger(__name__)
 
 
-def login_redirect(entity_id='', acs_url='', return_to='/', force_authn=False,
-                   idp=UwIdp, two_factor=False):
+def login_redirect(entity_id=None, acs_url=None, return_to='/',
+                   force_authn=False, idp=UwIdp, two_factor=False):
+    """
+    Return a SAML request URL for redirecting to the Identity Provider (IdP).
+
+    entity_id - The Service Provider (SP) Entity ID.
+    acs_url - The SP endpoint the Identity Provider will post back to, known
+        technically as the Assertion Consumer Service. This endpoint along
+        with the Entity Id are registered with the IdP.
+    force_authn - whether to force authentication even if the user has already
+        authenticated against the IdP.
+    idp - which IdP to use, defaulting to UW's IdP. Other IdPs of type
+        uw_saml2.idp.IdpConfig can be added.
+    two_factor - whether to ask for two-factor authentication. Asking for it
+        doesn't mean you get it back on the response. You'll need to check
+        there as well.
+    """
     sp = Config(entity_id, acs_url)
     config = sp.config(idp, two_factor=two_factor)
     auth = OneLogin_Saml2_Auth(sp.request(), old_settings=config)
     return auth.login(return_to=return_to, force_authn=force_authn)
 
 
-def process_response(post, entity_id, acs_url, idp=UwIdp, two_factor=False):
+def process_response(post, entity_id=None, acs_url=None, idp=UwIdp,
+                     two_factor=False):
+    """
+    Validate a SAML Response posted by the Identity Provider (IdP) and return
+    its attributes as a dict.
+
+    post - The post data to process.
+    entity_id - The Service Provider (SP) Entity ID.
+    acs_url - The SP endpoint the IdP posted back to. At this point entity_id
+        and acs_url are used to validate a SAML Response.
+    idp - The IdP to validate against.
+    two_factor - whether we expect a 2FA response or not. If True then
+        non-2FA authentication will raise a SamlResponseError. Another
+        technique would be to leave this False and check the attribute we
+        add to the attribute data returned.
+    """
     sp = Config(entity_id, acs_url)
     config = sp.config(idp, two_factor=two_factor)
     auth = OneLogin_Saml2_Auth(sp.request(post), old_settings=config)
     auth.process_response()
     errors = auth.get_errors()
     if errors:
-        raise SamlResponseException(auth.get_last_error_reason())
+        raise SamlResponseError(auth.get_last_error_reason())
     attribute_data = dict(attribute.map(auth.get_attributes(), idp=idp))
+
+    authn_contexts = auth.get_last_authn_contexts()
+    attribute_data['two_factor'] = TWO_FACTOR_CONTEXT in authn_contexts
+
     logger.info(attribute_data)
     return attribute_data
 
 
-class SamlResponseException(Exception):
+class SamlResponseError(Exception):
     """Exception to raise when a SAMLResponse can't be validated."""

uw_saml2/idp/attribute.py

@@ -27,6 +27,19 @@ def map(self, values):
         return values[:]
 
 
+class UWGroups(List):
+    """An attribute that splits out the common UW Groups prefix."""
+    prefix = 'urn:mace:washington.edu:groups:'
+
+    def map(self, values):
+        results = []
+        for value in values:
+            if value.startswith(self.prefix):
+                value = value.split(self.prefix)[1]
+            results.append(value)
+        return results
+
+
 class NestedNameid(Attribute):
     """An attribute that's an object of a NameId structure."""
     def map(self, values):

uw_saml2/idp/uw.py

@@ -33,7 +33,11 @@ class UwIdp(IdpConfig):
         'urn:oid:1.3.6.1.4.1.5923.1.1.1.6': 'eppn',
         'urn:oid:0.9.2342.19200300.100.1.1': 'uwnetid',
         'urn:oid:1.3.6.1.4.1.5923.1.1.1.1': attribute.List('affiliations'),
-        'urn:oid:1.3.6.1.4.1.5923.1.5.1.1': attribute.List('groups'),
+        'urn:oid:1.3.6.1.4.1.5923.1.5.1.1': attribute.UWGroups('groups'),
         'urn:oid:1.3.6.1.4.1.5923.1.1.1.9': attribute.List(
             'scoped_affiliations')
     }
+
+
+class UwIdpTwoFactor(UwIdp):
+    two_factor = True

uw_saml2/sp.py

@@ -1,15 +1,21 @@
 """Service Provider configuration."""
 from urllib.parse import urlparse
-CERT = ''
-KEY = ''
+import os
+TWO_FACTOR_CONTEXT = 'https://refeds.org/profile/mfa'
 
 
 class Config(object):
-    def __init__(self, entity_id, acs_url, cert=CERT, key=KEY):
-        self.entity_id = entity_id
-        self.acs_url = acs_url
-        self.cert = cert
-        self.key = key
+    entity_id = ''
+    acs_url = ''
+    cert_file = ''
+    key_file = ''
+    _file_store = {}  # cache files we've read
+
+    def __init__(self, entity_id=None, acs_url=None):
+        if entity_id:
+            self.entity_id = entity_id
+        if acs_url:
+            self.acs_url = acs_url
 
     def request(self, post=None):
         post = post or {}
@@ -21,6 +27,24 @@ def request(self, post=None):
             'post_data': post
         }
 
+    def _read_file(self, filename):
+        if filename in self._file_store:
+            return self._file_store[filename]
+        if os.path.isfile(filename):
+            with open(filename) as fd:
+                filedata = fd.read()
+            self._file_store[filename] = filedata
+            return filedata
+        return ''
+
+    @property
+    def cert(self):
+        return self._read_file(self.cert_file)
+
+    @property
+    def key(self):
+        return self._read_file(self.key_file)
+
     def config(self, idp, two_factor=False):
         """Return config in a way that makes sense to OneLogin_Saml2_Auth."""
         data = {
@@ -43,9 +67,9 @@ def config(self, idp, two_factor=False):
                 'privateKey': self.key
             }
         }
-        if two_factor:
+        if two_factor or getattr(idp, 'two_factor', False):
             data.update({'security': {
-                'requestedAuthnContext': ['https://refeds.org/profile/mfa'],
+                'requestedAuthnContext': [TWO_FACTOR_CONTEXT],
                 'failOnAuthnContextMismatch': True
             }})
-        return data
+        return data