Configurable memoization of IdP selection when using MDQ

This commit introduces four optional configuration parameters that can be used
to modify the default SATOSA behaviour:

- CONTEXT_STATE_DELETE
- remember_selected_idp_from_disco
- use_disco_when_forceauthn
- mirror_saml_forceauthn

By default, SATOSA deletes the context state when it receives an
authentication response from an identity provider. The first configuration
option, CONTEXT_STATE_DELETE, allows us disable this behaviour and thus
keeping state across different authentication flows, when the user uses
the same browser.

The second configuration option, remember_selected_idp_from_disco,
controls whether SATOSA will remember and reuse the IdP that is returned
from a discovery service. If ForceAuthn is set in the authentication
request, then the user will then the user the IdP will be redirected to
the discovery service (if it is configured) and ForceAuthn will be set
in the authentication request towards the selected IdP.

These two options together allow us to modify the current behaviour so
that within a given session, a user will select only once the identity
provider and then SATOSA will store this information in the state
cookie. When the cookie expires, the user will be redirected again to
the discovery service.

The third configuration option, use_disco_when_forceauthn, controls
whether SATOSA will redirect the use to the discovery service, even when
remember_selected_idp_from_disco is true and for the current session
there is the entity id of an IdP stored in the cookie state. This
behaviour provides a way for SPs that need to force a new IdP selection
(e.g. for account linking purposes) to use ForceAuthn to achieve this.

The fourth configuration option, mirror_saml_forceauthn, adds configuration
option to mirror ForceAuthn. By default, when the SATOSA SAML frontend
receives a SAML authentication request with ForceAuthn set to `True`, this
information is not mirrored in the SAML authentication request that is
generated by the SATOSA SAML backend towards the upstream identity provider.
If the configuration parameter `mirror_saml_forceauthn` is set to `True`,
then the default behaviour changes and the SATOSA SAML backend will set
ForceAuthn to true when it proxies a SAML authentication request with
ForceAuthn set to `True`.

The default values of these configuration options are tuned so that the
default behaviour of SATOSA is not changed.

Signed-off-by: Ivan Kanakarakis <[email protected]>

Author: skanct

doc/README.md

@@ -37,6 +37,7 @@ in the [example directory](../example).
 | -------------- | --------- | ------------- | ----------- |
 | `BASE` | string | `https://proxy.example.com` | base url of the proxy |
 | `COOKIE_STATE_NAME` | string | `satosa_state` | name of cooke SATOSA uses for preserving state between requests |
+| `CONTEXT_STATE_DELETE` | bool | `True` | controls whether SATOSA will delete the state after receiving the authentication response from the upstream IdP|
 | `STATE_ENCRYPTION_KEY` | string | `52fddd3528a44157` | key used for encrypting the state cookie, will be overriden by the environment variable `SATOSA_STATE_ENCRYPTION_KEY` if it is set |
 | `INTERNAL_ATTRIBUTES` | string | `example/internal_attributes.yaml` | path to attribute mapping
 | `CUSTOM_PLUGIN_MODULE_PATHS` | string[] | `[example/plugins/backends, example/plugins/frontends]` | list of directory paths containing any front-/backend plugin modules |
@@ -322,6 +323,45 @@ config:
     disco_srv: http://disco.example.com
 ```
 
+##### Remember the IdP provided in the discovery service
+
+The `remember_selected_idp_from_disco` parameter controls whether the user will have to always select a
+target provider when a discovery service is configured. If the parameter is set to `True` and ForceAutn is not set,
+SATOSA will remember and reuse the selected target provider for the duration that context.state is valid.
+The default behaviour is `False`.
+
+```yaml
+config:
+  sp_config: [...]
+    remember_selected_idp_from_disco: True
+```
+
+##### Use the configured discovery service if ForceAuthn is set to true
+
+The `use_disco_when_forceauthn` parameter controls whether the user will be redirected to the configured
+discovery service when the SP sends a SAML authentication request with `ForceAuthn` set to `True`.  The
+default behaviour is `False`.
+
+```yaml
+config:
+  sp_config: [...]
+    use_disco_when_forceauthn: True
+```
+
+##### Mirror the SAML ForceAuthn option
+
+By default when the SATOSA SAML frontend receives a SAML authentication request with ForceAuthn set to `True`,
+this information is not mirrored in the SAML authentication request that is generated by the SATOSA SAML backend
+towards the upstream identity provider. If the configuration parameter `mirror_saml_forceauthn` is set to `True`,
+then the default behaviour changes and the SATOSA SAML backend will set ForceAuthn to true when it proxies a SAML
+authentication request with ForceAuthn set to `True`. The default behaviour is `False`.
+
+```yaml
+config:
+  sp_config: [...]
+    mirror_saml_forceauthn: True
+```
+
 ### <a name="openid_plugin" style="color:#000000">OpenID Connect plugins</a>
 
 #### Backend

example/plugins/backends/saml2_backend.yaml.example

@@ -3,6 +3,7 @@ name: Saml2
 config:
   idp_blacklist_file: /path/to/blacklist.json
   sp_config:
+    remember_selected_idp_from_disco: False
     key_file: backend.key
     cert_file: backend.crt
     organization: {display_name: Example Identities, name: Example Identities Org., url: 'http://www.example.com'}

example/proxy_conf.yaml.example

@@ -2,6 +2,7 @@
 BASE: https://example.com
 INTERNAL_ATTRIBUTES: "internal_attributes.yaml"
 COOKIE_STATE_NAME: "SATOSA_STATE"
+CONTEXT_STATE_DELETE: False
 STATE_ENCRYPTION_KEY: "asdASD123"
 CUSTOM_PLUGIN_MODULE_PATHS:
   - "plugins/backends"

src/satosa/backends/saml2.py

@@ -43,6 +43,10 @@ class SAMLBackend(BackendModule, SAMLBaseModule):
     KEY_SAML_DISCOVERY_SERVICE_URL = 'saml_discovery_service_url'
     KEY_SAML_DISCOVERY_SERVICE_POLICY = 'saml_discovery_service_policy'
     KEY_SP_CONFIG = 'sp_config'
+    KEY_SELECTED_IDP_FROM_DISCO = 'selected_idp_from_disco'
+    KEY_REMEMBER_SELECTED_IDP_FROM_DISCO = 'remember_selected_idp_from_disco'
+    KEY_USE_DISCO_WHEN_FORCEAUTHN = 'use_disco_when_forceauthn'
+    KEY_MIRROR_SAML_FORCEAUTHN = 'mirror_saml_forceauthn'
     VALUE_ACR_COMPARISON_DEFAULT = 'exact'
 
     def __init__(self, outgoing, internal_attributes, config, base_url, name):
@@ -67,6 +71,11 @@ def __init__(self, outgoing, internal_attributes, config, base_url, name):
         sp_config = SPConfig().load(copy.deepcopy(config[self.KEY_SP_CONFIG]), False)
         self.sp = Base(sp_config)
 
+        # If use_disco_when_forceauthn is not set in the SP config,
+        # then False is the default behaviour
+        if self.KEY_USE_DISCO_WHEN_FORCEAUTHN not in self.config['sp_config']:
+            self.config['sp_config'][self.KEY_USE_DISCO_WHEN_FORCEAUTHN] = False
+
         self.discosrv = config.get(self.KEY_DISCO_SRV)
         self.encryption_keys = []
         self.outstanding_queries = {}
@@ -85,26 +94,76 @@ def __init__(self, outgoing, internal_attributes, config, base_url, name):
             with open(p) as key_file:
                 self.encryption_keys.append(key_file.read())
 
-    def start_auth(self, context, internal_req):
+    def get_idp_entity_id(self, context):
         """
-        See super class method satosa.backends.base.BackendModule#start_auth
         :type context: satosa.context.Context
-        :type internal_req: satosa.internal.InternalData
-        :rtype: satosa.response.Response
+        :rtype: str | None
+
+        :param context: The current context
+        :return: the entity_id of the idp or None
         """
 
-        target_entity_id = context.get_decoration(Context.KEY_TARGET_ENTITYID)
-        if target_entity_id:
-            entity_id = target_entity_id
-            return self.authn_request(context, entity_id)
+        # XXX TODO should not look into sp_config
+        # XXX TODO make sense of the config options
 
         # if there is only one IdP in the metadata, bypass the discovery service
         idps = self.sp.metadata.identity_providers()
         if len(idps) == 1 and "mdq" not in self.config["sp_config"]["metadata"]:
             entity_id = idps[0]
-            return self.authn_request(context, entity_id)
+        # if the user has selected an IdP and it is available in the context.state,
+        # then set entity_id to that unless ForceAuthn is set to true and
+        # use_disco_when_forcauthn is false
+        elif (
+            self.config["sp_config"].get(self.KEY_REMEMBER_SELECTED_IDP_FROM_DISCO)
+            and self.KEY_SELECTED_IDP_FROM_DISCO in context.state
+
+            and not context.get_decoration(Context.KEY_FORCE_AUTHN)
+        ):
+            satosa_logging(
+                logger, logging.INFO,
+                "Bypassing discovery service. Using IdP %s" %
+                context.state[self.KEY_SELECTED_IDP_FROM_DISCO],
+                context.state,
+            )
+            entity_id = context.state[self.KEY_SELECTED_IDP_FROM_DISCO]
+        elif (
+            self.config["sp_config"].get(self.KEY_REMEMBER_SELECTED_IDP_FROM_DISCO)
+            and self.KEY_SELECTED_IDP_FROM_DISCO in context.state
+
+            and context.get_decoration(Context.KEY_FORCE_AUTHN)
+            and not self.config["sp_config"][self.KEY_USE_DISCO_WHEN_FORCEAUTHN]
+        ):
+            satosa_logging(
+                logger, logging.INFO,
+                "Bypassing discovery service. Using IdP %s" %
+                context.state[self.KEY_SELECTED_IDP_FROM_DISCO],
+                context.state,
+            )
+            entity_id = context.state[self.KEY_SELECTED_IDP_FROM_DISCO]
+        else:
+            entity_id = context.get_decoration(Context.KEY_TARGET_ENTITYID)
+
+        return entity_id
 
-        return self.disco_query(context)
+    def start_auth(self, context, internal_req):
+        """
+        See super class method satosa.backends.base.BackendModule#start_auth
+
+        :type context: satosa.context.Context
+        :type internal_req: satosa.internal.InternalData
+        :rtype: satosa.response.Response
+        """
+
+        entity_id = self.get_idp_entity_id(context)
+        if entity_id is None:
+            # since context is not passed to disco_query
+            # keep the information in the state cookie
+            context.state[Context.KEY_FORCE_AUTHN] = context.get_decoration(
+                Context.KEY_FORCE_AUTHN
+            )
+            return self.disco_query(context)
+
+        return self.authn_request(context, entity_id)
 
     def disco_query(self, context):
         """
@@ -155,6 +214,17 @@ def construct_requested_authn_context(self, entity_id):
 
         return authn_context
 
+    def mirror_saml_forceauthn(self, context, kwargs):
+        if (self.KEY_MIRROR_SAML_FORCEAUTHN in self.config['sp_config']
+                and self.config['sp_config'][self.KEY_MIRROR_SAML_FORCEAUTHN]):
+            # If ForceAuthn is found in the state cookie, use that
+            if (Context.KEY_FORCE_AUTHN in context.state
+                    and context.state[Context.KEY_FORCE_AUTHN] == 'true'):
+                kwargs['force_authn'] = context.state[Context.KEY_FORCE_AUTHN]
+            elif context.get_decoration(Context.KEY_FORCE_AUTHN) == 'true':
+                kwargs['force_authn'] = context.get_decoration(Context.KEY_FORCE_AUTHN)
+        return kwargs
+
     def authn_request(self, context, entity_id):
         """
         Do an authorization request on idp with given entity id.
@@ -183,6 +253,8 @@ def authn_request(self, context, entity_id):
         if authn_context:
             kwargs['requested_authn_context'] = authn_context
 
+        kwargs = self.mirror_saml_forceauthn(context, kwargs)
+
         try:
             binding, destination = self.sp.pick_binding(
                 "single_sign_on_service", None, "idpsso", entity_id=entity_id)
@@ -250,6 +322,8 @@ def authn_response(self, context, binding):
         context.decorate(Context.KEY_BACKEND_METADATA_STORE, self.sp.metadata)
 
         del context.state[self.name]
+        # we should not remember ForceAuthn any longer
+        context.state[Context.KEY_FORCE_AUTHN] = None
         return self.auth_callback_func(context, self._translate_response(authn_response, context.state))
 
     def disco_response(self, context):
@@ -271,6 +345,10 @@ def disco_response(self, context):
             satosa_logging(logger, logging.DEBUG, "No IDP chosen for state", state, exc_info=True)
             raise SATOSAAuthenticationError(state, "No IDP chosen") from err
 
+        if (self.KEY_REMEMBER_SELECTED_IDP_FROM_DISCO in self.config['sp_config']
+                and self.config['sp_config'][self.KEY_REMEMBER_SELECTED_IDP_FROM_DISCO]):
+            context.state[self.KEY_SELECTED_IDP_FROM_DISCO] = entity_id
+
         return self.authn_request(context, entity_id)
 
     def _translate_response(self, response, state):

src/satosa/base.py

@@ -161,9 +161,13 @@ def _auth_resp_finish(self, context, internal_response):
             self.config.get("USER_ID_HASH_SALT", ""),
         )
 
-        # remove all session state
+        # remove all session state unless CONTEXT_STATE_DELETE is false
         context.request = None
-        context.state.delete = True
+        if "CONTEXT_STATE_DELETE" in self.config:
+            context.state.delete = self.config["CONTEXT_STATE_DELETE"]
+        else:
+            context.state.delete = True
+
         frontend = self.module_router.frontend_routing(context)
         return frontend.handle_authn_response(context, internal_response)
 

src/satosa/context.py

@@ -17,6 +17,7 @@ class Context(object):
     """
     KEY_BACKEND_METADATA_STORE = 'metadata_store'
     KEY_TARGET_ENTITYID = 'target_entity_id'
+    KEY_FORCE_AUTHN = 'force_authn'
 
     def __init__(self):
         self._path = None

src/satosa/frontends/saml2.py

@@ -192,6 +192,8 @@ def _handle_authn_request(self, context, binding_in, idp):
         authn_req = req_info.message
         satosa_logging(logger, logging.DEBUG, "%s" % authn_req, context.state)
 
+        context.decorate(Context.KEY_FORCE_AUTHN, authn_req.force_authn)
+
         try:
             resp_args = idp.response_args(authn_req)
         except SAMLError as e:

tests/satosa/backends/test_saml2.py

@@ -169,7 +169,7 @@ def test_redirect_to_idp_if_only_one_idp_in_metadata(self, context, sp_conf, idp
         resp = samlbackend.start_auth(context, InternalData())
         self.assert_redirect_to_idp(resp, idp_conf)
 
-    def test_always_redirect_to_discovery_service_if_using_mdq(self, context, sp_conf, idp_conf):
+    def test_default_redirect_to_discovery_service_if_using_mdq(self, context, sp_conf, idp_conf):
         # one IdP in the metadata, but MDQ also configured so should always redirect to the discovery service
         sp_conf["metadata"]["inline"] = [create_metadata_from_config_dict(idp_conf)]
         sp_conf["metadata"]["mdq"] = ["https://mdq.example.com"]
@@ -178,12 +178,80 @@ def test_always_redirect_to_discovery_service_if_using_mdq(self, context, sp_con
         resp = samlbackend.start_auth(context, InternalData())
         self.assert_redirect_to_discovery_server(resp, sp_conf, DISCOSRV_URL)
 
+    def test_use_of_disco_or_redirect_to_idp_when_using_mdq_and_forceauthn_is_not_set(self, context, sp_conf, idp_conf):
+        sp_conf["metadata"]["inline"] = [create_metadata_from_config_dict(idp_conf)]
+        sp_conf["metadata"]["mdq"] = ["https://mdq.example.com"]
+
+        sp_conf["remember_selected_idp_from_disco"] = True
+        samlbackend = SAMLBackend(None, INTERNAL_ATTRIBUTES, {"sp_config": sp_conf, "disco_srv": DISCOSRV_URL,},
+                                  "base_url", "saml_backend")
+        resp = samlbackend.start_auth(context, InternalRequest(None, None))
+        self.assert_redirect_to_discovery_server(resp, sp_conf)
+
+        context.state["selected_idp_from_disco"] = idp_conf['entityid']
+        samlbackend = SAMLBackend(None, INTERNAL_ATTRIBUTES, {"sp_config": sp_conf, "disco_srv": DISCOSRV_URL,},
+                                  "base_url", "saml_backend")
+        resp = samlbackend.start_auth(context, InternalRequest(None, None))
+        self.assert_redirect_to_idp(resp, idp_conf)
+
+        sp_conf["remember_selected_idp_from_disco"] = False
+        samlbackend = SAMLBackend(None, INTERNAL_ATTRIBUTES, {"sp_config": sp_conf, "disco_srv": DISCOSRV_URL,},
+                                  "base_url", "saml_backend")
+        resp = samlbackend.start_auth(context, InternalRequest(None, None))
+        self.assert_redirect_to_discovery_server(resp, sp_conf)
+
+    def test_use_of_disco_or_redirect_to_idp_when_using_mdq_and_forceauthn_is_set(self, context, sp_conf, idp_conf):
+        context.decorate(Context.KEY_FORCE_AUTHN, 'true')
+        sp_conf["metadata"]["inline"] = [create_metadata_from_config_dict(idp_conf)]
+        sp_conf["metadata"]["mdq"] = ["https://mdq.example.com"]
+
+        sp_conf["remember_selected_idp_from_disco"] = True
+        context.state["selected_idp_from_disco"] = idp_conf['entityid']
+
+        sp_conf["use_disco_when_forceauthn"] = True
+        samlbackend = SAMLBackend(None, INTERNAL_ATTRIBUTES, {"sp_config": sp_conf, "disco_srv": DISCOSRV_URL,},
+                                  "base_url", "saml_backend")
+        resp = samlbackend.start_auth(context, InternalRequest(None, None))
+        self.assert_redirect_to_discovery_server(resp, sp_conf)
+
+        sp_conf["use_disco_when_forceauthn"] = False
+        samlbackend = SAMLBackend(None, INTERNAL_ATTRIBUTES, {"sp_config": sp_conf, "disco_srv": DISCOSRV_URL,},
+                                  "base_url", "saml_backend")
+        resp = samlbackend.start_auth(context, InternalRequest(None, None))
+        self.assert_redirect_to_idp(resp, idp_conf)
+
     def test_authn_request(self, context, idp_conf):
         resp = self.samlbackend.authn_request(context, idp_conf["entityid"])
         self.assert_redirect_to_idp(resp, idp_conf)
         req_params = dict(parse_qsl(urlparse(resp.message).query))
         assert context.state[self.samlbackend.name]["relay_state"] == req_params["RelayState"]
 
+    def test_mirror_saml_forceauthn(self, context, sp_conf):
+        sp_conf["metadata"]["mdq"] = ["https://mdq.example.com"]
+        samlbackend = SAMLBackend(None, INTERNAL_ATTRIBUTES, {"sp_config": sp_conf, "disco_srv": DISCOSRV_URL,},
+                                  "base_url", "saml_backend")
+
+        context.state[Context.KEY_FORCE_AUTHN] = 'true'
+
+        kwargs = {}
+        kwargs = samlbackend.mirror_saml_forceauthn(context, kwargs)
+        assert kwargs == {}
+
+        sp_conf[samlbackend.KEY_MIRROR_SAML_FORCEAUTHN] = True
+
+        kwargs = samlbackend.mirror_saml_forceauthn(context, kwargs)
+        assert kwargs == {'force_authn': 'true'}
+
+        kwargs = {}
+        del context.state[Context.KEY_FORCE_AUTHN]
+        kwargs = samlbackend.mirror_saml_forceauthn(context, kwargs)
+        assert kwargs == {}
+
+        kwargs = {}
+        context.decorate(Context.KEY_FORCE_AUTHN, 'true')
+        kwargs = samlbackend.mirror_saml_forceauthn(context, kwargs)
+        assert kwargs == {'force_authn': 'true'}
+
     def test_authn_response(self, context, idp_conf, sp_conf):
         response_binding = BINDING_HTTP_REDIRECT
         fakesp = FakeSP(SPConfig().load(sp_conf, metadata_construction=False))