Redo the configurable memoization capability

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

- CONTEXT_STATE_DELETE
- memorize_disco_idp
- use_memorized_disco_idp_when_force_authn
- mirror_saml_force_authn

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 keep state across different authentication flows,
while the user uses the same browser.

The second configuration option, memorize_disco_idp, controls whether
SATOSA will remember and reuse the IdP that is selected from a discovery
service. If ForceAuthn is set in the authentication request, then the
user 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_memorized_disco_idp_when_force_authn, controls whether SATOSA will
skip the discovery service, even when memorize_disco_idp is set, for the
current session there is an entity id of an IdP stored in the cookie
state, and ForceAuthn is requested.

SPs that need to force a new IdP selection (e.g. for account linking
purposes) should set this option to False, in order to be able to use
ForceAuthn to redirect the user to the discovery service.

The fourth configuration option, mirror_saml_force_authn, 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_force_authn` 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: c00kiemon5ter

doc/README.md

@@ -37,7 +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|
+| `CONTEXT_STATE_DELETE` | bool | `True` | controls whether SATOSA will delete the state cookie 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 |
@@ -233,7 +233,7 @@ in its UI. The following flow diagram shows the communcation:
    `SP -> optional discovery service -> selected proxy SAML entity -> target IdP`
 
 3. The **SAMLVirtualCoFrontend** module enables multiple IdP frontends, each with its own distinct
-entityID and SSO endpoints, and each representing a distinct collaborative organization or CO. 
+entityID and SSO endpoints, and each representing a distinct collaborative organization or CO.
 An example configuration can be found [here](../example/plugins/frontends/saml2_virtualcofrontend.yaml.example).
 
    The following flow diagram shows the communication:
@@ -323,43 +323,57 @@ config:
     disco_srv: http://disco.example.com
 ```
 
-##### Remember the IdP provided in the discovery service
+##### Mirror the SAML ForceAuthn option
+
+By default when the 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 SAML backend towards the
+upstream identity provider. If the configuration option
+`mirror_saml_force_authn` is set to `True`, then the default behaviour changes
+and the SAML backend will set `ForceAuthn` to true when it proxies a SAML
+authentication request with `ForceAuthn` set to `True`.
 
-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
+  mirror_saml_force_authn: True
+  [...]
 ```
 
-##### Use the configured discovery service if ForceAuthn is set to true
+##### Memorize the IdP selected through the discovery service
+
+In the classic flow, the user is asked to select their home organization to
+authenticate to. The `memorize_disco_idp` configuration option 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 `ForceAuthn` is not set),
+the proxy will remember and reuse the selected target provider for the duration
+that the state cookie is valid. If `ForceAuthn` is set, then the
+`use_memorized_disco_idp_when_force_authn` configuration option can overide
+this property and still reuse the selected target provider.
 
-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`.
+The default behaviour is `False`.
 
 ```yaml
 config:
-  sp_config: [...]
-    use_disco_when_forceauthn: True
+  memorize_disco_idp: True
+  [...]
 ```
 
-##### Mirror the SAML ForceAuthn option
+##### Use the configured discovery service if ForceAuthn is set to true
 
-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`.
+The `use_memorized_disco_idp_when_force_authn` configuration option controls
+whether the user will skip the configured discovery service when the SP sends a
+SAML authentication request with `ForceAuthn` set to `True` but the proxy has
+memorized the user's previous selection.
+
+The default behaviour is `False`.
 
 ```yaml
 config:
-  sp_config: [...]
-    mirror_saml_forceauthn: True
+  memorize_disco_idp: True
+  use_memorized_disco_idp_when_force_authn: True
+  [...]
 ```
 
 ### <a name="openid_plugin" style="color:#000000">OpenID Connect plugins</a>

example/plugins/backends/saml2_backend.yaml.example

@@ -2,8 +2,12 @@ module: satosa.backends.saml2.SAMLBackend
 name: Saml2
 config:
   idp_blacklist_file: /path/to/blacklist.json
+
+  mirror_saml_force_authn: no
+  memorize_disco_idp: no
+  use_memorized_disco_idp_when_force_authn: no
+
   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,7 +2,7 @@
 BASE: https://example.com
 INTERNAL_ATTRIBUTES: "internal_attributes.yaml"
 COOKIE_STATE_NAME: "SATOSA_STATE"
-CONTEXT_STATE_DELETE: False
+CONTEXT_STATE_DELETE: yes
 STATE_ENCRYPTION_KEY: "asdASD123"
 CUSTOM_PLUGIN_MODULE_PATHS:
   - "plugins/backends"

src/satosa/backends/saml2.py

@@ -43,10 +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'
+    KEY_MIRROR_SAML_FORCE_AUTHN = 'mirror_saml_force_authn'
+    KEY_MEMORIZE_DISCO_IDP = 'memorize_disco_idp'
+    KEY_USE_MEMORIZED_DISCO_IDP_WHEN_FORCE_AUTHN = 'use_memorized_disco_idp_when_force_authn'
+
     VALUE_ACR_COMPARISON_DEFAULT = 'exact'
 
     def __init__(self, outgoing, internal_attributes, config, base_url, name):
@@ -68,15 +68,12 @@ def __init__(self, outgoing, internal_attributes, config, base_url, name):
         super().__init__(outgoing, internal_attributes, base_url, name)
         self.config = self.init_config(config)
 
-        sp_config = SPConfig().load(copy.deepcopy(config[self.KEY_SP_CONFIG]), False)
+        sp_config = SPConfig().load(copy.deepcopy(
+            config[SAMLBackend.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.discosrv = config.get(SAMLBackend.KEY_DISCO_SRV)
         self.encryption_keys = []
         self.outstanding_queries = {}
         self.idp_blacklist_file = config.get('idp_blacklist_file', None)
@@ -103,46 +100,51 @@ def get_idp_entity_id(self, context):
         :return: the entity_id of the idp or None
         """
 
-        # 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"]:
+        only_one_idp_in_metadata = (
+            len(idps) == 1 and "mdq" not in self.config["sp_config"]["metadata"]
+        )
+
+        target_entity_id = context.get_decoration(Context.KEY_TARGET_ENTITYID)
+
+        force_authn = context.get_decoration(Context.KEY_FORCE_AUTHN)
+        memorized_disco_idp = (
+            self.config.get(SAMLBackend.KEY_MEMORIZE_DISCO_IDP)
+            and context.state.get(Context.KEY_MEMORIZED_DISCO_IDP)
+        )
+        use_memorized_disco_idp_when_force_authn = self.config.get(
+            SAMLBackend.KEY_USE_MEMORIZED_DISCO_IDP_WHEN_FORCE_AUTHN
+        )
+        use_memorized_disco_idp = memorized_disco_idp and (
+            not force_authn or use_memorized_disco_idp_when_force_authn
+        )
+
+        if only_one_idp_in_metadata:
             entity_id = idps[0]
-        # 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]
+        elif use_memorized_disco_idp:
+            entity_id = memorized_disco_idp
+        elif target_entity_id:
+            entity_id = target_entity_id
         else:
-            entity_id = context.get_decoration(Context.KEY_TARGET_ENTITYID)
-
+            entity_id = None
+
+        satosa_logging(
+            logger, logging.INFO,
+            {
+                "message": "Selected IdP entity ID",
+                "idps": idps,
+                "only_one_idp_in_metadata": only_one_idp_in_metadata,
+                "force_authn": force_authn,
+                "memorized_disco_idp": memorized_disco_idp,
+                "use_memorized_disco_idp_when_force_authn": (
+                    use_memorized_disco_idp_when_force_authn
+                ),
+                "use_memorized_disco_idp": use_memorized_disco_idp,
+                "target_entity_id": target_entity_id,
+                "entity_id": entity_id,
+            },
+            context.state,
+        )
         return entity_id
 
     def start_auth(self, context, internal_req):
@@ -181,9 +183,12 @@ def disco_query(self, context):
         return_url = endpoints["discovery_response"][0][0]
 
         disco_url = (
-            context.get_decoration(self.KEY_SAML_DISCOVERY_SERVICE_URL) or self.discosrv
+            context.get_decoration(SAMLBackend.KEY_SAML_DISCOVERY_SERVICE_URL)
+            or self.discosrv
+        )
+        disco_policy = context.get_decoration(
+            SAMLBackend.KEY_SAML_DISCOVERY_SERVICE_POLICY
         )
-        disco_policy = context.get_decoration(self.KEY_SAML_DISCOVERY_SERVICE_POLICY)
 
         args = {"return": return_url}
         if disco_policy:
@@ -214,17 +219,6 @@ 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.
@@ -251,9 +245,12 @@ def authn_request(self, context, entity_id):
         kwargs = {}
         authn_context = self.construct_requested_authn_context(entity_id)
         if authn_context:
-            kwargs['requested_authn_context'] = authn_context
-
-        kwargs = self.mirror_saml_forceauthn(context, kwargs)
+            kwargs["requested_authn_context"] = authn_context
+        if self.config.get(SAMLBackend.KEY_MIRROR_SAML_FORCE_AUTHN):
+            kwargs["force_authn"] = (
+                context.state.get(Context.KEY_FORCE_AUTHN)
+                or context.get_decoration(Context.KEY_FORCE_AUTHN)
+            )
 
         try:
             binding, destination = self.sp.pick_binding(
@@ -321,9 +318,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
+        context.state.pop(self.name, None)
+        context.state.pop(Context.KEY_FORCE_AUTHN, None)
         return self.auth_callback_func(context, self._translate_response(authn_response, context.state))
 
     def disco_response(self, context):
@@ -345,9 +341,8 @@ 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
+        if self.config.get(SAMLBackend.KEY_MEMORIZE_DISCO_IDP):
+            context.state[Context.KEY_MEMORIZED_DISCO_IDP] = entity_id
 
         return self.authn_request(context, entity_id)
 

src/satosa/base.py

@@ -161,12 +161,9 @@ def _auth_resp_finish(self, context, internal_response):
             self.config.get("USER_ID_HASH_SALT", ""),
         )
 
-        # remove all session state unless CONTEXT_STATE_DELETE is false
+        # remove all session state unless CONTEXT_STATE_DELETE is False
+        context.state.delete = self.config.get("CONTEXT_STATE_DELETE", True)
         context.request = None
-        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

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

src/satosa/frontends/saml2.py

@@ -192,6 +192,7 @@ def _handle_authn_request(self, context, binding_in, idp):
         authn_req = req_info.message
         satosa_logging(logger, logging.DEBUG, "%s" % authn_req, context.state)
 
+        # keep the ForceAuthn value to be used by plugins
         context.decorate(Context.KEY_FORCE_AUTHN, authn_req.force_authn)
 
         try: