{"type":"doc","content":[{"type":"paragraph","content":[{"text":"The authentication \"engine\" includes support for a range of use cases from the very simple to the very complex, along with a lot of extension points for handling even more complex cases that it doesn't support out of the box. The core of this engine is a set of steps that evaluate a request for authentication and local policy to winnow a set of possible login flows down to a smaller set that it determines are suitable. This process might be extremely simple or extremely not-simple, depending on configuration and on the number of login methods in use.","type":"text"}]},{"type":"paragraph","content":[{"text":"In the vast majority of cases, only a single \"top level\" method may be enabled (often the ","type":"text"},{"text":"MFA","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP4/pages/1265631610"}}]},{"text":" method), but for those with very complex requirements to support widely varied mechanisms at the same time, the process is described below, along with the options available to influence the process without writing code. Of course, understanding the process is important for those writing code as well.","type":"text"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"061f6e59-e26f-4644-82c1-390a3e225c2d"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"4038e40d-0df9-4ca3-9a75-e83daa21d3a5"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Inputs","type":"text"}]},{"type":"paragraph","content":[{"text":"At a very high level, the following runtime information is captured as input to the process:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"any active session for the client along with any still-valid previous ","type":"text"},{"text":"AuthenticationResult","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.authn.AuthenticationResult"}}]},{"text":" objects that may be possible to reuse","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"the","type":"text"},{"text":" AuthenticationFlowDescriptor","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.authn.AuthenticationFlowDescriptor"}}]},{"text":" objects for any login flows enabled for use via the ","type":"text"},{"text":"idp.authn.flows","type":"text","marks":[{"type":"strong"}]},{"text":" property and the ","type":"text"},{"text":"authenticationFlows","type":"text","marks":[{"type":"code"}]},{"text":" property attached to the ","type":"text"},{"text":"profile configuration","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP4/pages/1265631678"}}]},{"text":" in effect; any flows not included in both sets are considered unavailable","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"the request to the IdP (the specifics of which depend on the protocol in use)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"the ","type":"text"},{"text":"defaultAuthenticationMethods","type":"text","marks":[{"type":"code"}]},{"text":" property attached to the ","type":"text"},{"text":"profile configuration","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP4/pages/1265631678"}}]},{"text":" in effect","type":"text"}]}]}]},{"type":"expand","attrs":{"title":"V4.0"},"content":[{"type":"paragraph","content":[{"text":"Internally, the ","type":"text"},{"text":"AuthenticationFlowDescriptor","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/pages/resumedraft.action?draftId=1265631603"}}]},{"text":" objects are maintained in the order they're declared in the list of beans in ","type":"text"},{"text":"authn/general-authn.xml","type":"text","marks":[{"type":"em"}]},{"text":". This means that absent other influences, the general order flows will be tried can be controlled with that list.","type":"text"}]}]},{"type":"expand","attrs":{"title":"V4.1+"},"content":[{"type":"paragraph","content":[{"text":"Internally, the ","type":"text"},{"text":"AuthenticationFlowDescriptor","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/pages/resumedraft.action?draftId=1265631603"}}]},{"text":" objects are maintained in an order driven by the ","type":"text"},{"text":"idp.authn..order","type":"text","marks":[{"type":"strong"}]},{"text":" properties in ","type":"text"},{"text":"authn/authn.properties","type":"text","marks":[{"type":"em"}]},{"text":". Lower-numbered flows are sorted ahead of higher.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"With respect to the request, the chief piece of information extracted is anything the request specifies to limit or control the login method used. Out of the box, this is only supported for SAML 2.0 requests (the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element), but the information is extracted in a portable form ahead of this step, so any protocol with this feature can be supported equally and uniformly. For example, the ","type":"text"},{"text":"OIDC OP","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDPPLUGINS/pages/1376878976"}}]},{"text":" extension supports a similar ","type":"text"},{"text":"feature","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDPPLUGINS/pages/1376879155"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"In the event that nothing is specified in the request, the ","type":"text"},{"text":"defaultAuthenticationMethods","type":"text","marks":[{"type":"code"}]},{"text":" property is essentially a pseudo-requirement that will be imposed automatically, as if the request specified that an exact match to one of the specified custom Principals is required. In SAML terms, a profile configuration such as this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n\t\n\t\t\n\t\t\t\n\t\t\n\t\n","type":"text"}]},{"type":"paragraph","content":[{"text":"is equivalent to an SP for which the configuration applies requesting this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n\turn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken\n","type":"text"}]},{"type":"paragraph","content":[{"text":"Thus, the property is proscriptive, not advisory.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Flow Filtering","type":"text"}]},{"type":"paragraph","content":[{"text":"The simplest steps performed during this pipeline are a straightforward filtering of the possible login flows based on high-level requirements. This fiiltering includes:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"eliminating flows that don't support \"passive\" use if the request requires this (corresponding to the IsPassive flag in SAML 2)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"eliminating flows that don't support \"forced authentication\" if the request requires this (corresponding to the ForceAuthn flag in SAML 2)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"eliminating flows that require a browser client if the request is from a non-browser client (e.g., the ECP profile in SAML 2)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Flow Selection","type":"text"}]},{"type":"paragraph","content":[{"text":"The heart of the process is a step that picks either a pre-existing ","type":"text"},{"text":"AuthenticationResult","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.authn.AuthenticationResult"}}]},{"text":" to reuse (SSO), or a login flow to attempt to fulfull the request. This is where a lot of complex logic is embedded.","type":"text"}]},{"type":"paragraph","content":[{"text":"One of the things this step does is prevent the same methods from being attempted multiple times in a loop by tracking the ones that have been tried already. This can be cirumvented in exceptional cases, but when it's allowed to just \"do its thing\", the selection process will eventually try each flow in arbitrary order until one succeeds or all have failed.","type":"text"}]},{"type":"paragraph","content":[{"text":"Apart from that, one of three cases applies:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"the request contained no requirements as to which login flow to use","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"the request contained specific requirements as to which login flow to use","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"a login flow explicitly asked that another login flow be tried (inter-flow signaling, mentioned under ","type":"text"},{"text":"AuthenticationConfiguration","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP4/pages/1265631601"}}]},{"text":", Advanced Features)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The first two general cases are described below.","type":"text"}]},{"type":"paragraph","content":[{"text":"In the last case, a specific flow is being selected, so in essence it just \"promotes\" a flow into first position for the other two cases to handle. In other words, if the request doesn't dictate any constraints, the signaled flow is attempted, whereas if the request does contain constraints, those constraints have to be met by the signaled flow or it won't be tried and the explicit attempt to run it will fail.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Handling Requests With No Requirements","type":"text"}]},{"type":"paragraph","content":[{"text":"When the request to the IdP doesn't explicitly have method requirements, the selection process proceeds as follows:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If the request doesn't call for forced authentication, then one of the active ","type":"text"},{"text":"AuthenticationResult","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.authn.AuthenticationResult"}}]},{"text":"s from a session will be reused if the login flow that produced it is enabled for the request (SSO).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Otherwise, one of the enabled and unattempted login flows is chosen and attempted, based on the order of priority as discussed earlier.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If no unattempted flows remain, authentication fails.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"This is the basic/simple case and requires no special attention.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Handling Requests With Requirements","type":"text"}]},{"type":"paragraph","content":[{"text":"When the request to the IdP does have explicit method requirements, or a ","type":"text"},{"text":"defaultAuthenticationMethods","type":"text","marks":[{"type":"code"}]},{"text":" property is set on the applicable ","type":"text"},{"text":"profile configuration","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP4/pages/1265631678"}}]},{"text":", then the selection process is as follows:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If the request calls for forced authentication, or if there are no active ","type":"text"},{"text":"AuthenticationResult","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.authn.AuthenticationResult"}}]},{"text":"s from a session, go to step 3.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If the ","type":"text"},{"text":"idp.authn.favorSSO","type":"text","marks":[{"type":"strong"}]},{"text":" property is true, then the collection of active ","type":"text"},{"text":"AuthenticationResult","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.authn.AuthenticationResult"}}]},{"text":"s is searched for a result that matches the request's requirements (SSO).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The request's requirements are examined in order so that its precedence rules are applied, and the collection of enabled and unattempted flows is searched (in the order of priority) for a match to the requirement being examined. Assuming a match is found, one of the following applies:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The collection of active ","type":"text"},{"text":"AuthenticationResult","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.authn.AuthenticationResult"}}]},{"text":"s from a session is searched for a result from that flow, and the result is further checked to determine if it matches the request requirement. If so, it is reused (SSO).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The matching flow is chosen.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If no unattempted flows that match any of the requirements remain, authentication fails.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"A subtle point: login flows may claim to support a variety of requirements but an ","type":"text"},{"text":"AuthenticationResult","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.authn.AuthenticationResult"}}]},{"text":" is only reused if that result itself supports a particular requirement. As a concrete example, a single flow might handle both password and multi-factor authentication but generate results specific to one type or the other. Alternatively, separate flows might be used for the two. The selection process handles either case.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Comparison Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"authn/authn-comparison.xml","type":"text","marks":[{"type":"em"}]},{"text":" file is an advanced configuration file used to support the matching process described above.","type":"text"}]},{"type":"paragraph","content":[{"text":"Some protocols, and the IdP's ","type":"text"},{"text":"defaultAuthenticationMethods","type":"text","marks":[{"type":"code"}]},{"text":" property, rely on \"exact\" matching of a request's requirements. This is a straightforward \"string-matching\" process that is built-in by default and doesn't require additional setup.","type":"text"}]},{"type":"paragraph","content":[{"text":"SAML 2.0, and thus the IdP, also supports \"inexact\" matching. This is a very advanced feature that has never seen significant use because of the difficulty in making it work. This file defines the relationships between authentication types in order to support this inexact matching. The support for this is not limited to SAML in the design, but since SAML is the only implemented case, there are classes and beans defined to manage the relationships and support the operators specific to that case.","type":"text"}]},{"type":"paragraph","content":[{"text":"As noted, exact matching is automatic; this applies when a SAML 2.0 request specifies \"exact\" matching in an ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element, or if nothing is requested but the ","type":"text"},{"text":"profile configuration","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP4/pages/1265631678"}}]},{"text":" includes the ","type":"text"},{"text":"defaultAuthenticationMethod","type":"text","marks":[{"type":"code"}]},{"text":" property.","type":"text"}]},{"type":"paragraph","content":[{"text":"To make inexact matching work, you have to define the matching rules. These rules apply only to SAML 2.0 requests at the moment. While you can define matching rules for AuthnContextDeclRef constants, these are rarely used in practice, and you will generally only need to define rules for AuthnContextClassRef constants (if anything at all).","type":"text"}]},{"type":"paragraph","content":[{"text":"There are beans predefined and registered for each of the inexact matching types possible to support the basic mechanics of the \"better\", \"minimum\", and \"maximum\" operators. The latter two cases are defaulted internally to allow degenerate support by treating the request as equivalent to \"exact\" (because they're inclusive of the value supplied in the request), but \"better\" matching won't succeed without explicit comparison rules added since it's non-inclusive.","type":"text"}]},{"type":"expand","attrs":{"title":"V4.0"},"content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"authn/authn-comparison.xml","type":"text","marks":[{"type":"em"}]},{"text":" file includes an example of how to define such rules. Each bean contains a property to set with a map of values that might be requested and a corresponding list of values that should satisfy the request.","type":"text"}]}]},{"type":"expand","attrs":{"title":"V4.1+"},"content":[{"type":"paragraph","content":[{"text":"The latest shipped version of the ","type":"text"},{"text":"authn/authn-comparison.xml","type":"text","marks":[{"type":"em"}]},{"text":" file has been simplified and no longer contains a lot of extraneous content to support this edge case. The commented map bean named ","type":"text"},{"text":"shibboleth.AuthnComparisonRules","type":"text","marks":[{"type":"strong"}]},{"text":" must be uncommented and an overridden matching rule added to the map to supply behavior for one of the operators to change its behavior.","type":"text"}]},{"type":"paragraph","content":[{"text":"The map entry key determines which type of object and which matching operator to configure behavior for. The map entry value is a bean that inherits from ","type":"text"},{"text":"shibboleth.InexactMatchFactory","type":"text","marks":[{"type":"strong"}]},{"text":" that provides the ruleset.","type":"text"}]},{"type":"paragraph","content":[{"text":"The latter bean in turn contains a ","type":"text"},{"text":"matchingRules","type":"text","marks":[{"type":"code"}]},{"text":" property that is itself a map. The keys of this map are the values that might be requested, while the values of the map entries are the values that should satisfy the request.","type":"text"}]},{"type":"paragraph","content":[{"text":"As an example, say you wanted to support an SP that's insisting on requesting the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" value of ","type":"text"},{"text":"urn:oasis:names:tc:SAML:2.0:ac:classes:Password","type":"text","marks":[{"type":"code"}]},{"text":" and an operator of \"minimum\", and you have a couple of supported values that you want to teach the IdP are \"as good as\" this value. This is what that looks like:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"authn/authn-comparison.xml","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n\t\n\t\t\n\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\turn:oasis:names:tc:SAML:2.0:ac:classes:Password\n\t\t\t\t\t\t\turn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport\n\t\t\t\t\t\t\turn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken\n\t\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n\n","type":"text"}]},{"type":"paragraph","content":[{"text":"Other cases are similar. The beans ","type":"text"},{"text":"shibboleth.SAMLACClassRefMinimum, shibboleth.SAMLACClassRefMaximum,","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"shibboleth.SAMLACClassRefBetter","type":"text","marks":[{"type":"strong"}]},{"text":" are predefined as keys you can use for the three operators, and the example above illustrates the sort of bean you'd define as a map value for the rules.","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Ignoring Requested Values","type":"text"}]},{"type":"paragraph","content":[{"text":"Lastly, note that a bean named ","type":"text"},{"text":"shibboleth.IgnoredContexts","type":"text","marks":[{"type":"strong"}]},{"text":" can be defined to identify specific AuthnContextClassRef or AuthnContextDeclRef values to ignore if found in a SAML 2.0 ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" element. By default this consists of a single value, ","type":"text"},{"text":"urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified","type":"text","marks":[{"type":"code"}]},{"text":", which has been ignored since V2 out of simple common sense.","type":"text"}]}],"version":1}