{"type":"doc","content":[{"type":"paragraph","content":[{"text":"A profile action is a discrete piece of code, packaged into a Java bean, that peforms a specific function, such as building a SAML assertion, signing a message, encrypting an attribute, validating a password, or displaying a message to a user. Just as the functionality in the IdP is made up of \"profiles\", a profile is implemented by connecting together a series of profile action beans into a sequence of steps. The steps can be sequential or include conditional branches based on data or user input.","type":"text"}]},{"type":"paragraph","content":[{"text":"Spring Web Flow is the mechanism used to orchestrate the sequence of actions that implement a complete profile. Authentication is also implemented using a reusable set of web flows that support the login mechanisms a deployer wants to enable, and new mechanisms can be added by implementing small amounts of code and configuring new flows.","type":"text"}]},{"type":"paragraph","content":[{"text":"The interface used by Spring to invoke an action bean is ","type":"text"},{"text":"org.springframework.webflow.execution.Action","type":"text","marks":[{"type":"strong"}]},{"text":" and a single method is used:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"SWF Action interface","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"text":"package org.springframework.webflow.execution;\n\npublic interface Action {\n public Event execute(RequestContext context) throws Exception;\n} ","type":"text"}]},{"type":"paragraph","content":[{"text":"All action beans ultimately support this interface. However, the vast majority of beans in the IdP will implement an OpenSAML interface, ","type":"text"},{"text":"ProfileAction","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org/opensaml/profile/action/ProfileAction"}}]},{"text":", which is a Spring-independent interface with a similarly simple signature:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"OpenSAML ProfileAction interface","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"text":"package org.opensaml.profile.action;\n\npublic interface ProfileAction extends InitializableComponent {\n\n\tpublic void execute(@Nonnull final ProfileRequestContext profileRequestContext)\n throws ProfileException;\n} ","type":"text"}]},{"type":"paragraph","content":[{"text":"There is intentional symmetry between these interfaces. The purpose of the OpenSAML interface is to support independence from Spring when possible, and make a larger amount of functional SAML processing code available within OpenSAML for those that are implementing their own applications.","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that some profile action beans may require other IdP services and components, and so may not be independent of the IdP. They often, though, will still be mostly independent of Spring.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Spring-Independent Actions","type":"text"}]},{"type":"paragraph","content":[{"text":"More often than not, a profile action bean will not need access to the Spring Web Flow context or the Spring container, in which case it will not need to implement the Web Flow interface itself, just the OpenSAML interface. Usually this is done by deriving a bean from the ","type":"text"},{"text":"AbstractProfileAction","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org/opensaml/profile/action/AbstractProfileAction"}}]},{"text":" base class and overriding this method:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Implementing an OpenSAML ProfileAction","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"text":"protected void doExecute(@Nonnull ProfileRequestContext profileRequestContext)\n\tthrows ProfileException;","type":"text"}]},{"type":"paragraph","content":[{"text":"The action bean interacts with the current request using the ","type":"text"},{"text":"ProfileRequestContext","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org/opensaml/profile/context/ProfileRequestContext"}}]},{"text":", which is the root of an extensible tree of context objects representing the state of a profile execution, the inputs to the action, and the outputs of the action when it completes. If executing in a servlet container, the action can access the servlet objects by requiring their injection as properties on the action bean.","type":"text"}]},{"type":"paragraph","content":[{"text":"When an action completes, it signals a transition by attaching an ","type":"text"},{"text":"EventContext","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org/opensaml/profile/context/EventContext"}}]},{"text":" object to the context tree. The \"proceed\" Event ID is generally used to signal a standard successful transition. Helper methods for attaching events are provided in the ","type":"text"},{"text":"ActionSupport","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-opensaml.cgi/org/opensaml/profile/action/ActionSupport"}}]},{"text":" helper class. In most cases, actions do nothing on success, but call a helper method to signal a non-proceed event. Exceptions may be, but generally should not be, thrown. Using events provides the best model for control and customization.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Spring-Based Actions","type":"text"}]},{"type":"paragraph","content":[{"text":"If an action bean requires access to the Spring Web Flow context object or Spring container, it has a couple of options that are functionally equivalent. Both start by deriving from the ","type":"text"},{"text":"AbstractProfileAction","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net/shibboleth/idp/profile/AbstractProfileAction"}}]},{"text":" base class. It can choose to directly implement the Spring Web Flow ","type":"text"},{"text":"Action","type":"text","marks":[{"type":"strong"}]},{"text":" interface by overriding this method:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Implementing a Spring Web Flow Action","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"text":"protected Event doExecute(@Nonnull final RequestContext springRequestContext,\n\t@Nonnull final ProfileRequestContext profileRequestContext)\n\t\tthrows ProfileException;","type":"text"}]},{"type":"paragraph","content":[{"text":"An alternative approach that is more consistent with the rest of the action beans that don't involve Spring is to override the ProfileAction method shown in the Spring-Independent example above. As in that case, results are signaled by adding an ","type":"text"},{"text":"EventContext","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.net/cgi-bin/java-opensaml.cgi/org.opensaml.profile.context.EventContext"}}]},{"text":" to the context tree. Access to Spring is via a ","type":"text"},{"text":"SpringRequestContext","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net/shibboleth/idp/profile/context/SpringRequestContext"}}]},{"text":" object available as a child of the context tree.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Web Flow and Bean Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"This is not an exhaustive discussion as to how web flows can or will be configured, but to illustrate the two cases discussed, here is an example of how a couple of action beans are declared so that they can be referenced by a web flow:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Spring Web Flow Bean Example","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"html/xml"},"content":[{"text":"\n\n\n \n \n \n \n\n \n \n\n \n \n \n ","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"ProfileActionBeanPostProcessor","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.profile.impl.ProfileActionBeanPostProcessor"}}]},{"text":" bean is a Spring post-processor that detects any OpenSAML ProfileAction beans that do not implement the Spring Action interface, and wraps them in a ","type":"text"},{"text":"WebFlowProfileActionAdaptor","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net/shibboleth/idp/profile/impl/WebFlowProfileActionAdaptor"}}]},{"text":". This is a simple bean that turns any implementation of the OpenSAML ProfileAction interface into a Spring Web Flow action.","type":"text"}]},{"type":"paragraph","content":[{"text":"The \"SpringIndependentBean\" bean is an example of such a bean. It will automatically be wrapped. The \"SpringAware\" bean uses Spring internally and implements the Action interface, so will not be wrapped. Either of the techniques described earlier to implement a bean can be used. Because of the post-processor, declaration of the two types of actions is the same.","type":"text"}]},{"type":"paragraph","content":[{"text":"The examples shown use the \"prototype\" scope to allow the beans to be stateful, such that each invocation of the action will involve a unique bean instance. This is the norm. The default scope can be used for stateless action beans, but declaring it as a prototype means it can eventually acquire state without having to worry about how it's been declared. Using non-prototype beans is a source of potentially serious concurrency bugs so it is strongly discouraged and we may implement bean processors to enforce this at some point.","type":"text"}]}],"version":1}