{"type":"doc","content":[{"type":"paragraph","content":[{"text":"SAML includes an optional feature during login requests called ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" that acts as a signal to the Identity Provider to require a particular kind of authentication be used, instead of the default of leaving the decision up to the IdP. This feature is generic, but the most common use case for this feature tends to be requiring the use of some form of MFA.","type":"text"}]},{"type":"paragraph","content":[{"text":"Between the time that the feature was designed in 2004 and real-world use of the feature started to appear, it became clear that it was a bad idea to try to codify specific technical approaches directly into the values being requested, because this isn't future-proofed. Generally it's more common to use community-defined values that represent general approaches to the problem (e.g., the ","type":"text"},{"text":"REFEDS MFA Profile","type":"text","marks":[{"type":"link","attrs":{"href":"https://refeds.org/profile/mfa"}}]},{"text":"). In the future it may be even more common to align the values used to some kind of scale of authentication \"quality\" that's even more generic.","type":"text"}]},{"type":"paragraph","content":[{"text":"The actual value used doesn't really matter mechnically, so this example applies regardless of the actual value used. The REFEDS value is used in the example that follows.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Usage","type":"text"}]},{"type":"paragraph","content":[{"text":"There are two parts to integrating specific authentication requirements into the SP: enforcement and issuing requests. Both halves are needed, but enforcement is the more crucial of the two because achieving stronger security depends on it.","type":"text"}]},{"type":"paragraph","content":[{"text":"While it may be tempting to skip this step, simply requesting the right form of authentication is not sufficient. The SAML protocol includes capabilities that easily allow a smart attacker to circumvent your request process and the enforcement step is essential if you actually want to require the use of any particular authentication method.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Enforcing Use","type":"text"}]},{"type":"paragraph","content":[{"text":"Enforcement is an authorization function, much like requiring a user to posess a particular attribute value. In this case, the requirement is for the SAML assertion to include an appropriate ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" value.","type":"text"}]},{"type":"paragraph","content":[{"text":"In the Shibboleth SP, the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" value received is exposed in the usual way, in a server variable or header, named ","type":"text"},{"text":"\"Shib-AuthnContext-Class\"","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/SP3/pages/2065335257#AttributeAccess-AttributeAccess-CustomSPVariables"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"If the requirement can be expressed statically (that is, based on the properties of the request such that all matching requests must carry the context), then you can apply static access control rules to check for the proper value and block access otherwise.","type":"text"}]},{"type":"paragraph","content":[{"text":"This can be done using the Apache ","type":"text"},{"text":"configuration","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/SP3/pages/2065335056"}}]},{"text":" with:","type":"text"}]},{"type":"codeBlock","content":[{"text":"require authnContextClassRef https://refeds.org/profile/mfa","type":"text"}]},{"type":"paragraph","content":[{"text":"(Note that if you have other require rules, you will need to take care to wrap them in a ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" block because Apache applies OR logic by default.)","type":"text"}]},{"type":"paragraph","content":[{"text":"For IIS and other servers, the SP software includes a portable feature for applying access control rules in the SP configuration; the ","type":"text"},{"text":"documentation","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/SP3/pages/2065334887"}}]},{"text":" includes examples.","type":"text"}]},{"type":"paragraph","content":[{"text":"Before proceeding further, you should apply the appropriate rules in a development environment to ensure that existing access to your system is blocked by an appropriate rule when plain authentication is done. Having done so, you can proceed with the second half of the process.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Example Apache2 configuration:","type":"text"}]},{"type":"codeBlock","content":[{"text":"RedirectMatch ^/$ /secure\n\n\n Authtype shibboleth\n ShibRequestSetting requireSession On\n \n require authnContextClassRef https://refeds.org/profile/mfa\n require valid-user\n \n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Requiring Use","type":"text"}]},{"type":"paragraph","content":[{"text":"Obviously the goal is not to simply block access, but to actually make sure users that access your system normally will automatically be prompted to use a second factor at the appropriate times. This is possible in SAML by including information in the request message that tells the IdP to do this for you. Specifically, you must include a ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element containing the desired ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" value to use.","type":"text"}]},{"type":"paragraph","content":[{"text":"In the case of Shibboleth, there are a few methods for decorating requests, depending on how the application is integrated with the SP. In the common case of an \"active\" protection strategy that automatically redirects to the IdP based on URL pattern, you can add a setting to Apache:","type":"text"}]},{"type":"codeBlock","content":[{"text":"ShibRequestSetting authnContextClassRef https://refeds.org/profile/mfa","type":"text"}]},{"type":"paragraph","content":[{"text":"You can also, or on IIS must, use the SP's ","type":"text"},{"text":"RequestMap","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/SP3/pages/2065334391"}}]},{"text":" feature, applying an XML attribute, ","type":"text"},{"text":"authnContextClassRef=\"https://refeds.org/profile/mfa\"","type":"text","marks":[{"type":"code"}]},{"text":", to a particular mapped location.","type":"text"}]},{"type":"paragraph","content":[{"text":"If a \"passive/lazy\" protection strategy is used, then your application is in control of the process of requesting a session. In this case, the application's redirect to the SP's session initiation endpoint must include an additional encoded query string parameter (","type":"text"},{"text":"authnContextClassRef=https%3a%2f%2frefeds.org%2fprofile%2fmfa","type":"text","marks":[{"type":"code"}]},{"text":").","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that when this strategy is involved, applications have the opportunity for flexible \"step-up\" models in which users may be forced to elevate their authentication strength based on the actions they perform. While that is also possible with URL-based schemes, that can be difficult with many application frameworks because of the way URLs may be overloaded by them for different functions.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Example Apache2 Configuration","type":"text"}]},{"type":"codeBlock","content":[{"text":"RedirectMatch ^/$ /secure\n\n\n Authtype shibboleth\n ShibRequestSetting requireSession On\n \n ShibRequestSetting authnContextClassRef https://refeds.org/profile/mfa\n require authnContextClassRef https://refeds.org/profile/mfa\n require valid-user\n \n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Error Handling","type":"text"}]},{"type":"paragraph","content":[{"text":"The other requirement to make use of this feature is error handling. A properly configured IdP that does NOT support a value requested by the SP is obligated to return an error to the SP. Handling that case is the SP's responsibility. Generally a static error response is not going to be suitable for most applications because it's not simple to distinguish this particular error in a generic error template. The SP has a ","type":"text"},{"text":"feature","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/SP3/pages/2065334361"}}]},{"text":" to redirect to an application script to handle errors with the script able to switch off of some of the query string parameters to detect the particular SAML status involved.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example","type":"text"}]},{"type":"paragraph","content":[{"text":"Assume the SP is configured with the following ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"shibboleth2.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"...\n \n...","type":"text"}]},{"type":"paragraph","content":[{"text":"Upon an authentication context-based error, the user's browser would be redirected to the following URL. (Note that line breaks have been added and parameters decoded for readability.) The second status code will depend on ","type":"text"},{"text":"why","type":"text","marks":[{"type":"em"}]},{"text":" things failed so may vary.","type":"text"}]},{"type":"codeBlock","content":[{"text":"http://sp.example.org/error?\n &requestURL=https://sp.example.org/Shibboleth.sso/SAML2/POST\n &errorType=opensaml::FatalProfileException\n &errorText=SAML response contained an error.\n &RelayState=https://example.org/secure/getattrs\n &entityID=https://idp.example.org/idp/shibboleth\n &statusCode=urn:oasis:names:tc:SAML:2.0:status:Responder\n &statusCode2=urn:oasis:names:tc:SAML:2.0:status:AuthnFailed","type":"text"}]},{"type":"paragraph"}],"version":1}