feat: idp hinting

- IdP hinting in HTTP-REDIRECT and HTTP-POST
- README, added idp hinting section
- small code refactor

Author: peppelinux

README.rst

@@ -164,13 +164,36 @@ Idp's like Okta require a signed logout response to validate and logout a user.
 
 Discovery Service
 -----------------
-If you want to use a SAML Discovery Service, all you need is adding:
+If you want to use a SAML Discovery Service, all you need is adding::
 
   SAML2_DISCO_URL = 'https://your.ds.example.net/'
 
 Of course, with the real URL of your preferred Discovery Service.
 
 
+Idp hinting
+-----------
+If the SP uses an AIM Proxy it is possible to suggest the authentication IDP by adopting the _idphint_ parameter. The name of the `idphint` parameter is default, but it can also be changed using this parameter::
+
+  SAML2_IDPHINT_PARAM = 'idphint'
+
+This will ensure that the user will not get a possible discovery service page for the selection of the IdP to use for the SSO.
+When Djagosaml2 receives an HTTP request at the resource, web path, configured for the saml2 login, it will detect the presence of the `idphint` parameter. If this is present, the authentication request will report this URL parameter within the http request relating to the SAML2 SSO binding.
+
+For example::
+
+  import requests
+  import urllib
+  idphint = {'idphint': [
+               urllib.parse.quote_plus(b'https://that.idp.example.org/metadata'),
+               urllib.parse.quote_plus(b'https://another.entitydi.org')]
+            }
+  param = urllib.parse.urlencode(idphint)
+  # param is "idphint=%5B%27https%253A%252F%252Fthat.idp.example.org%252Fmetadata%27%2C+%27https%253A%252F%252Fanother.entitydi.org%27%5D"
+  requests.get(f'http://djangosaml2.sp.fqdn.org/saml2/login/?{param}')
+
+see AARC Blueprint specs `here <https://zenodo.org/record/4596667/files/AARC-G061-A_specification_for_IdP_hinting.pdf>`_.
+
 Changes in the urls.py file
 ---------------------------
 

djangosaml2/utils.py

@@ -12,18 +12,23 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 import base64
+import logging
 import re
 import urllib
 import zlib
 from typing import Optional
 
 from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured
+from django.http import HttpResponseRedirect
 from django.utils.http import is_safe_url
 from saml2.config import SPConfig
 from saml2.s_utils import UnknownSystemEntity
 
 
+logger = logging.getLogger(__name__)
+
+
 def get_custom_setting(name: str, default=None):
     return getattr(settings, name, default)
 
@@ -106,3 +111,52 @@ def get_session_id_from_saml2(saml2_xml):
 def get_subject_id_from_saml2(saml2_xml):
     saml2_xml = saml2_xml if isinstance(saml2_xml, str) else saml2_xml.decode()
     re.findall('">([a-z0-9]+)</saml:NameID>', saml2_xml)[0]
+
+def add_param_in_url(url:str, param_key:str, param_value:str):
+    params = list(url.split('?'))
+    params.append(f'{param_key}={param_value}')
+    new_url = params[0] + '?' +''.join(params[1:])
+    return new_url
+
+def add_idp_hinting(request, http_response) -> bool:
+    idphin_param = getattr(settings, 'SAML2_IDPHINT_PARAM', 'idphint')
+    params = urllib.parse.urlencode(request.GET)
+
+    if idphin_param not in request.GET.keys():
+        return False
+
+    idphint = request.GET[idphin_param]
+    # validation : TODO -> improve!
+    if idphint[0:4] != 'http':
+        logger.warning(
+            f'Idp hinting: "{idphint}" doesn\'t contain a valid value.'
+            'idphint paramenter ignored.'
+        )
+        return False
+
+    if http_response.status_code in (302, 303):
+        # redirect binding
+        # urlp = urllib.parse.urlparse(http_response.url)
+        new_url = add_param_in_url(http_response.url,
+                                   idphin_param, idphint)
+        return HttpResponseRedirect(new_url)
+
+    elif http_response.status_code == 200:
+        # post binding
+        res = re.search(r'action="(?P<url>[a-z0-9\:\/\_\-\.]*)"',
+                        http_response.content.decode(), re.I)
+        if not res:
+            return False
+        orig_url = res.groupdict()['url']
+        #
+        new_url = add_param_in_url(orig_url, idphin_param, idphint)
+        content = http_response.content.decode()\
+                               .replace(orig_url, new_url)\
+                               .encode()
+        return HttpResponse(content)
+
+    else:
+        logger.warning(
+            f'Idp hinting: cannot detect request type [{http_response.status_code}]'
+        )
+    return False

djangosaml2/views.py

@@ -52,7 +52,7 @@
 from .conf import get_config
 from .exceptions import IdPConfigurationMissing
 from .overrides import Saml2Client
-from .utils import (available_idps, get_custom_setting,
+from .utils import (add_idp_hinting, available_idps, get_custom_setting,
                     get_idp_sso_supported_bindings, get_location,
                     validate_referral_url)
 
@@ -307,7 +307,10 @@ def get(self, request, *args, **kwargs):
             f'Saving the session_id "{oq_cache.__dict__}" '
             'in the OutstandingQueries cache',
         )
-        return http_response
+
+        # idp hinting support, add idphint url parameter if present in this request
+        response = add_idp_hinting(request, http_response) or http_response
+        return response
 
 
 @method_decorator(csrf_exempt, name='dispatch')

setup.py

@@ -24,7 +24,7 @@ def read(*rnames):
 
 setup(
     name='djangosaml2',
-    version='1.0.7',
+    version='1.1.0',
     description='pysaml2 integration for Django',
     long_description=read('README.rst'),
     classifiers=[