{"type":"doc","content":[{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"This material is specific to V4 (and to some extent V3) of the IdP and is not yet geared/optimized for V5+.","type":"text"}]}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"2"}},"macroMetadata":{"macroId":{"value":"eae1095b4f85692eba226f1c29bdf4ba"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"3872d717-81bc-4982-8505-3e4ad57d0e90"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Background","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"REFEDS MFA Profile","type":"text","marks":[{"type":"link","attrs":{"href":"https://refeds.org/profile/mfa"}}]},{"text":" is a convention for defining basic criteria needed to plausibly claim that one has applied multi-factor authentication to a subject and a standard SAML AuthnContext class reference value for communicating that between IdPs and SPs so that it's possible to leverage MFA on a wider scale than simple internally to an IdP organization.","type":"text"}]},{"type":"paragraph","content":[{"text":"Typically, MFA is something people apply today based on IdP-centric policy rules, whereas in the original SAML standard it was imagined that SPs would not have to rely on an IdP rule but simply ask for MFA when they needed it at runtime. This became a problem not only because of lack of software support outside of Shibboleth but also because there were no sensible values to use to communicate this. REFEDS as a community can't fix the former, but sought to address the latter by defining a value to use with a reasonably but not overly onerous bar for IdPs to meet in satisfying it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Please note that this is ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" the same as, or related really at all to, the REFEDS Assurance Profile. Identity Assurance is distinct from, and expressed differently, than authentication quality.","type":"text"}]},{"type":"paragraph","content":[{"text":"It is difficult to document exactly how to \"support\" this because it is dependent on how one operates their IdP and what mechanisms are used for authentication but as a basic guide, this recipe assumes a very vanilla configuration and uses ","type":"text"},{"text":"Password","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631611"}}]},{"text":" and ","type":"text"},{"text":"Duo","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631604"}}]},{"text":" authentication as the two factors involved. The examples should be readily generalizeable to other methods because the IdP treats all login methods more or less abstractly and with the same machinery.","type":"text"}]},{"type":"paragraph","content":[{"text":"There are separate examples for V3.3 - V4.0, and for V4.1 and above, because of changes made in V4.1 to simplify some of the configuration that is directly applicable.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Do NOT attempt to just cut and paste these examples; in most cases they will NOT work as is because they're excerpts of files and even beans that will contain other settings. They simply demonstrate the specific settings involved in this use case.","type":"text"}]},{"type":"paragraph","content":[{"text":"Also, this example is NOT suitable for use by anyone using third-party SAML IdP products to actually handle user authentication. That's a much different, and much more complex, problem that involves fairly advanced usage of the ","type":"text"},{"text":"SAML proxying","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1282539600"}}]},{"text":" support in the IdP. That would require very faithful support of the SAML standard that is unlikely to be found in the commercial IdP space. In particularly, the IdP product would have to support requesting and signaling MFA via the SAML ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" mechanism, or it may be impossible (or at least much more difficult) to pull off what this example is demonstrating for a Shibboleth-only deployment.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Assumptions","type":"text"}]},{"type":"paragraph","content":[{"text":"The example assumes that the IdP is using the ","type":"text"},{"text":"Password","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631611"}}]},{"text":" and ","type":"text"},{"text":"Duo","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631604"}}]},{"text":" flows together in a simple/standard way by means of the ","type":"text"},{"text":"MFA","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631610"}}]},{"text":" flow that ties them together. The approach shown is usable to support both IdP-based and SP-based rules for applying the second (Duo) factor to a request.","type":"text"}]},{"type":"paragraph","content":[{"text":"The example further assumes that you want to define both an internal means of identifying and communicating MFA but also support the REFEDS signal value of \"","type":"text"},{"text":"https://refeds.org/profile/mfa","type":"text","marks":[{"type":"link","attrs":{"href":"https://refeds.org/profile/mfa"}}]},{"text":"\". The benefit of this approach is that it isolates internal use and separates the behavior of a REFEDS Profile deployment from any local policies or exceptions needed because of internal business decisions. For example, locally a decision to exempt certain users from a requirement to perform MFA through some kind of bypass mechanism would violate the REFEDS Profile requirements, so using a different string internally allows for that flexibility.","type":"text"}]},{"type":"paragraph","content":[{"text":"The example uses a made-up internal value which should be adjusted into a locally-defined/owned URI. The REFEDS value is of course the actual value needed.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Initial Setup","type":"text"}]},{"type":"paragraph","content":[{"text":"The example proceeds by establishing the configuration to support the internal value, which for example purposes is just \"http://example.org/ac/classes/mfa\". The REFEDS support will be added later below. For completeness, the example also includes support for expressing MFA as a SAML 1.1 ","type":"text"},{"text":"AuthenticationMethod","type":"text","marks":[{"type":"code"}]},{"text":" but this is unlikely to matter much at this point.","type":"text"}]},{"type":"paragraph","content":[{"text":"To begin with, the ","type":"text"},{"text":"Password","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631611"}}]},{"text":" and ","type":"text"},{"text":"Duo","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631604"}}]},{"text":" configurations must be established, and this is largely outside the scope of this example. Having done so, the ","type":"text"},{"text":"MFA","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631610"}}]},{"text":" flow is then configured to tie the two factors together in a simple way that is designed to always apply the password factor and conditionally apply the Duo factor when and if it is necessary to do so. (For V4.1+, the MFA \"module\" has to be enabled first, which is noted in the documentation, so we assume this is already done.)","type":"text"}]},{"type":"paragraph","content":[{"text":"This is virtually verbatim done via the distributed example that is installed with the software, but is repeated here for context:","type":"text"}]},{"type":"expand","attrs":{"title":"conf/authn/mfa-authn-config.xml"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":" \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n ","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The additional setup will vary by version and is the process by which you associate the \"internal\" SAML AuthnContext class reference value with your second-factor method (Duo in this case) so that it can act as a signal.","type":"text"}]},{"type":"expand","attrs":{"title":"V4.1+"},"content":[{"type":"paragraph","content":[{"text":"New (or modernized) installs of V4.1+ can be taught what context classes to associate with login flows using ","type":"text"},{"text":"conf/authn/authn.properties","type":"text","marks":[{"type":"em"}]},{"text":":","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"conf/authn/authn.properties","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"plaintext"},"content":[{"text":"...\n\nidp.authn.Duo.supportedPrincipals = \\\n saml2/http://example.org/ac/classes/mfa, \\\n saml1/http://example.org/ac/classes/mfa\n\n...\n\nidp.authn.MFA.supportedPrincipals = \\\n saml2/http://example.org/ac/classes/mfa, \\\n saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport, \\\n saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:Password, \\\n saml1/http://example.org/ac/classes/mfa, \\\n saml1/urn:oasis:names:tc:SAML:1.0:am:password","type":"text"}]}]},{"type":"expand","attrs":{"title":"Older Versions"},"content":[{"type":"paragraph","content":[{"text":"Earlier versions rely on the ","type":"text"},{"text":"conf/authn/general-authn.xml","type":"text","marks":[{"type":"em"}]},{"text":" file to associate the class reference, using the ","type":"text"},{"text":"supportedPrincipals","type":"text","marks":[{"type":"code"}]},{"text":" property on the login flows. The class reference object must be connected to ","type":"text"},{"text":"both","type":"text","marks":[{"type":"strong"}]},{"text":" the Duo and MFA flows because the latter is a superset of the former. The IdP is being told that these flows \"support\" this context class so it's necessary that both flows are told to do so. This is an excerpt (note the \"...\"'s) of the complete file and just the relevant aspects are shown; other settings will vary by local need.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"conf/authn/general-authn.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n...\n\t\n \n \n \n \n \n \n\n...\n\n\t\n \n \n \n \n \n \n \n \n \n\n...\n","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Testing","type":"text"}]},{"type":"paragraph","content":[{"text":"Once this is in place, you can test the behavior (e.g., in development) by temporarily adjusting the default behavior of the IdP to require MFA for all requests by attaching the same local value to the DefaultRelyingParty configuration of the SAML 2.0 SSO profile:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"conf/relying-party.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":" \n \n \n...\n \n\t\t\t \n \t\t\t\n\t\t\t \n\t\t\t\t\n...\n \n \n ","type":"text"}]},{"type":"paragraph","content":[{"text":"Aside from seeing MFA applied, you should also find that the resulting assertions carry an ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element matching the expected value.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Adding REFEDS","type":"text"}]},{"type":"paragraph","content":[{"text":"The final step is to extend what's already been done to include the REFEDS context class so that SPs that need it can request it. This is a straight addition to the principal sets in the earlier examples, and the original values are included for completeness. You could also add the value as a SAML 1.1 option in an obvious way but that isn't likely to matter or come into play given that SAML 1.1 SPs, if they exist, can't actually request anything.","type":"text"}]},{"type":"expand","attrs":{"title":"V4.1+"},"content":[{"type":"heading","attrs":{"level":5},"content":[{"text":"conf/authn/authn.properties","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"plaintext"},"content":[{"text":"...\n\nidp.authn.Duo.supportedPrincipals = \\\n\tsaml2/https://refeds.org/profile/mfa, \\\n saml2/http://example.org/ac/classes/mfa, \\\n saml1/http://example.org/ac/classes/mfa\n\n...\n\nidp.authn.MFA.supportedPrincipals = \\\n\tsaml2/https://refeds.org/profile/mfa, \\\n saml2/http://example.org/ac/classes/mfa, \\\n saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport, \\\n saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:Password, \\\n saml1/http://example.org/ac/classes/mfa, \\\n saml1/urn:oasis:names:tc:SAML:1.0:am:password","type":"text"}]}]},{"type":"expand","attrs":{"title":"Older Versions"},"content":[{"type":"heading","attrs":{"level":5},"content":[{"text":"conf/authn/general-authn.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n...\n\t\n \n \n \t\t\t\n \n \n \n \n\n...\n\n\t\n \n \n \t\t\t\n \n \n \n \n \n \n \n\n...\n","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Testing","type":"text"}]},{"type":"paragraph","content":[{"text":"Once the REFEDS value is in place, you can test that in the same way as earlier, just changing the trigger value:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"conf/relying-party.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":" \n \n \n...\n \n\t\t\t \n \t\t\t\n\t\t\t \n\t\t\t\t\n...\n \n \n ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Supporting Multiple Duo Policies","type":"text"}]},{"type":"paragraph","content":[{"text":"As a final extention of this example, suppose that, having deployed separate context class values for REFEDS and local use, a decision is made to implement a Duo policy of some kind that would violate the REFEDS Profile. The only way to prevent that change from contaminating requests for the REFEDS Profile is to establish a second Duo integration for local use where that policy change is implemented. The original integration would be left alone.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Duo flow documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631604"}}]},{"text":" describes in general how to support multiple integrations. The same general approach applies to the ","type":"text"},{"text":"DuoOIDC","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.atlassian.net/wiki/spaces/IDPPLUGINS/pages/1374027959"}}]},{"text":" plugin (with one exception, noted at the end), so this example can be adapted to that version as well, but for simplicity, the example will use the original one. The point of this example is to demonstrate concretely how to use ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" values in the form of custom Principals to make the determination as to which integration to use at runtime.","type":"text"}]},{"type":"paragraph","content":[{"text":"The core of this approach is that you want the Duo and MFA flows to support both the local and REFEDS context class values, which was done earlier, but you then need to further subdivide things by explicitly associating each Duo integration object with the specific context class Principals supported by that integration. In other words, the Duo flow as a whole supports both, but the actual integrations don’t. Then you need a scripted function that will properly select among the two based on whether they support the current request or not. This approach actually generalizes to more than just 2 possible context class values, so multiple local values could also be defined to represent different policies, but the example will stick to just two.","type":"text"}]},{"type":"paragraph","content":[{"text":"The example also makes use of additional custom properties to allow storage of the various keys outside the XML.","type":"text"}]},{"type":"paragraph","content":[{"text":"A key assumption of this example is that the “local” integration as ","type":"text"},{"text":"less","type":"text","marks":[{"type":"em"}]},{"text":" strict in some sense than the REFEDS integration. That is, it assumes that a request for local MFA would be satisfied if the user had already performed REFEDS MFA. Because of that assumption, the appropriate configuration is for the “local” integration to support only the local Principal values, but the REFEDS integration to support both local and REFEDS Principal vales. If the local integration were actually more strict, such that a request for REFEDS MFA is satsified by local MFA but ","type":"text"},{"text":"not","type":"text","marks":[{"type":"em"}]},{"text":" the converse, then this would be reversed.","type":"text"}]},{"type":"expand","attrs":{"title":"Multiple Integrations via conf/authn/duo-authn-config.xml"},"content":[{"type":"codeBlock","content":[{"text":" \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n \n \n \n \n \n","type":"text"}]}]},{"type":"paragraph","content":[{"text":"For this to work properly with the MFA flow, you need to perform an additional step, and attach a “reuseCondition” to the Duo flow that determines whether or not the Duo result can actually be reused if it exists, because not every result will satisfy a particular request. This requires a bit of scripting like so, which you can place in ","type":"text"},{"text":"global.xml","type":"text","marks":[{"type":"em"}]},{"text":":","type":"text"}]},{"type":"expand","attrs":{"title":"global.xml"},"content":[{"type":"codeBlock","content":[{"text":" \n \n \n \n \n \n \n","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Finally, to make this all work, you need to prevent the Duo flow from automatically attaching all of the Principals the flow supports to the resulting Subject. This allows only the Principals supported by the integration that was actually used to be included, preventing an earlier local MFA result from being reused for REFEDS requests.","type":"text"}]},{"type":"paragraph","content":[{"text":"In V4.1+, to attach the condition above, and turn off the auto-attach behavior, you modify ","type":"text"},{"text":"conf/authn/authn.properties","type":"text","marks":[{"type":"em"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":"...\nidp.authn.Duo.addDefaultPrincipals = false\nidp.authn.Duo.reuseCondition = my.DuoReuseCondition\n...","type":"text"}]},{"type":"paragraph","content":[{"text":"In earlier versions, you would need to edit the Duo flow descriptor bean and set these in ","type":"text"},{"text":"conf/authn/general-authn.xml","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"DuoOIDC Use","type":"text"}]},{"type":"paragraph","content":[{"text":"The example works essentially the same for the Universal Prompt plugin, but due to a bug, the plugin doesn’t actually support a property for turning off the ","type":"text"},{"text":"addDefaultPrincipals","type":"text","marks":[{"type":"code"}]},{"text":" property yet (a bug has been filed and will be fixed in a subsequent patch). There is a bit of a complex rule used by the plugin now to decide how to set that property and a workaround for now (that avoids the need to declare the whole flow descriptor somewhere) is to add this additional function to ","type":"text"},{"text":"conf/authn/duo-oidc-authn-config.xml","type":"text","marks":[{"type":"em"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":" \n \n \n \n \n ","type":"text"}]},{"type":"paragraph","content":[{"text":"That function hook provides a more advanced way to derive the right set of Principals to attach at runtime, but using a null function tricks the plugin into not automatically adding any, allowing the per-integration Principals to be added instead. Even after the bug is fixed, that won’t break.","type":"text"}]}],"version":1}