Merge pull request #234 from c00kiemon5ter/feature-memorize-idp

Add configuration options to memorize a user-selected IdP

Author: c00kiemon5ter

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 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 |
@@ -232,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:
@@ -322,6 +323,59 @@ config:
     disco_srv: http://disco.example.com
 ```
 
+##### 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_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 default behaviour is `False`.
+
+```yaml
+config:
+  mirror_force_authn: 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_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_idp_when_force_authn` configuration option can overide
+this property and still reuse the selected target provider.
+
+The default behaviour is `False`.
+
+```yaml
+config:
+  memorize_idp: True
+  [...]
+```
+
+##### Use the configured discovery service if ForceAuthn is set to true
+
+The `use_memorized_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:
+  memorize_idp: True
+  use_memorized_idp_when_force_authn: True
+  [...]
+```
+
 ### <a name="openid_plugin" style="color:#000000">OpenID Connect plugins</a>
 
 #### Backend

example/plugins/backends/saml2_backend.yaml.example

@@ -2,6 +2,11 @@ module: satosa.backends.saml2.SAMLBackend
 name: Saml2
 config:
   idp_blacklist_file: /path/to/blacklist.json
+
+  mirror_force_authn: no
+  memorize_idp: no
+  use_memorized_idp_when_force_authn: no
+
   sp_config:
     key_file: backend.key
     cert_file: backend.crt

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: yes
 STATE_ENCRYPTION_KEY: "asdASD123"
 CUSTOM_PLUGIN_MODULE_PATHS:
   - "plugins/backends"

src/satosa/backends/saml2.py

@@ -35,6 +35,40 @@
 logger = logging.getLogger(__name__)
 
 
+def get_memorized_idp(context, config, force_authn):
+    memorized_idp = (
+        config.get(SAMLBackend.KEY_MEMORIZE_IDP)
+        and context.state.get(Context.KEY_MEMORIZED_IDP)
+    )
+    use_when_force_authn = config.get(
+        SAMLBackend.KEY_USE_MEMORIZED_IDP_WHEN_FORCE_AUTHN
+    )
+    value = (not force_authn or use_when_force_authn) and memorized_idp
+    return value
+
+
+def get_force_authn(context, config, sp_config):
+    """
+    Return the force_authn value.
+
+    The value comes from one of three place:
+    - the configuration of the backend
+    - the context, as it came through in the AuthnRequest handled by the frontend.
+      note: the frontend should have been set to mirror the force_authn value.
+    - the cookie, as it has been stored by the proxy on a redirect to the DS
+      note: the frontend should have been set to mirror the force_authn value.
+
+    The value is either "true" or False
+    """
+    mirror = config.get(SAMLBackend.KEY_MIRROR_FORCE_AUTHN)
+    from_state = mirror and context.state.get(Context.KEY_FORCE_AUTHN)
+    from_context = mirror and context.get_decoration(Context.KEY_FORCE_AUTHN)
+    from_config = sp_config.getattr("force_authn", "sp")
+    is_set = str(from_state or from_context or from_config).lower() == "true"
+    value = is_set and "true"
+    return value
+
+
 class SAMLBackend(BackendModule, SAMLBaseModule):
     """
     A saml2 backend module (acting as a SP).
@@ -43,6 +77,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_MIRROR_FORCE_AUTHN = 'mirror_force_authn'
+    KEY_MEMORIZE_IDP = 'memorize_idp'
+    KEY_USE_MEMORIZED_IDP_WHEN_FORCE_AUTHN = 'use_memorized_idp_when_force_authn'
+
     VALUE_ACR_COMPARISON_DEFAULT = 'exact'
 
     def __init__(self, outgoing, internal_attributes, config, base_url, name):
@@ -64,10 +102,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)
 
-        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)
@@ -85,26 +125,60 @@ def __init__(self, outgoing, internal_attributes, config, base_url, name):
             with open(p) as key_file:
                 self.encryption_keys.append(key_file.read())
 
+    def get_idp_entity_id(self, context):
+        """
+        :type context: satosa.context.Context
+        :rtype: str | None
+
+        :param context: The current context
+        :return: the entity_id of the idp or None
+        """
+
+        idps = self.sp.metadata.identity_providers()
+        only_one_idp_in_metadata = (
+            "mdq" not in self.config["sp_config"]["metadata"]
+            and len(idps) == 1
+        )
+
+        only_idp = only_one_idp_in_metadata and idps[0]
+        target_entity_id = context.get_decoration(Context.KEY_TARGET_ENTITYID)
+        force_authn = get_force_authn(context, self.config, self.sp.config)
+        memorized_idp = get_memorized_idp(context, self.config, force_authn)
+        entity_id = only_idp or target_entity_id or memorized_idp or None
+
+        satosa_logging(
+            logger, logging.INFO,
+            {
+                "message": "Selected IdP",
+                "only_one": only_idp,
+                "target_entity_id": target_entity_id,
+                "force_authn": force_authn,
+                "memorized_idp": memorized_idp,
+                "entity_id": entity_id,
+            },
+            context.state,
+        )
+        return entity_id
+
     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
         """
 
-        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)
-
-        # 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)
+        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] = get_force_authn(
+                context, self.config, self.sp.config
+            )
+            return self.disco_query(context)
 
-        return self.disco_query(context)
+        return self.authn_request(context, entity_id)
 
     def disco_query(self, context):
         """
@@ -122,9 +196,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:
@@ -181,7 +258,11 @@ 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["requested_authn_context"] = authn_context
+        if self.config.get(SAMLBackend.KEY_MIRROR_FORCE_AUTHN):
+            kwargs["force_authn"] = get_force_authn(
+                context, self.config, self.sp.config
+            )
 
         try:
             binding, destination = self.sp.pick_binding(
@@ -248,8 +329,11 @@ def authn_response(self, context, binding):
             raise SATOSAAuthenticationError(context.state, "State did not match relay state")
 
         context.decorate(Context.KEY_BACKEND_METADATA_STORE, self.sp.metadata)
-
-        del context.state[self.name]
+        if self.config.get(SAMLBackend.KEY_MEMORIZE_IDP):
+            issuer = authn_response.response.issuer.text.strip()
+            context.state[Context.KEY_MEMORIZED_IDP] = issuer
+        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):

src/satosa/base.py

@@ -161,9 +161,10 @@ 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.state.delete = self.config.get("CONTEXT_STATE_DELETE", True)
         context.request = None
-        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,8 @@ class Context(object):
     """
     KEY_BACKEND_METADATA_STORE = 'metadata_store'
     KEY_TARGET_ENTITYID = 'target_entity_id'
+    KEY_FORCE_AUTHN = 'force_authn'
+    KEY_MEMORIZED_IDP = 'memorized_idp'
 
     def __init__(self):
         self._path = None

src/satosa/frontends/saml2.py

@@ -192,6 +192,9 @@ 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:
             resp_args = idp.response_args(authn_req)
         except SAMLError as e: