# Securing Page Flow Applications

The following topic describes

- how to use transport security (SSL and the HTTPS protocol) in Page Flow applications
- how to use logins in Page Flow applications.

## Transport Security

### Securing an Entire Page Flow Application Using HTTPS

The simplest way to use HTTPS in a Page Flow application is to secure the entire session with HTTPS. When a session uses HTTPS, all of the traffic between the client and the server is encrypted, preventing any third parties from intercepting any meaningful data from the session. To specify that a Page Flow application use HTTPS, you place a `<security-constraint>` element within the application's `web.xml` file. The following `<security-constraint>` element, when placed in the application's `web.xml` file, will cause the user session with the Page Flow to be conducted over the HTTPS protocol.

WEB-INF/web.xml

        <security-constraint>
            <web-resource-collection>
                <web-resource-name>My Page Flow</web-resource-name>
                <description>Requires that all traffic with the Page Flow application be conducted over HTTPS</description>
                <!-- URL pattern for the web resource -->
                <url-pattern>/myPageFlowDirectory/*</url-pattern>
                <http-method>GET</http-method>
                <http-method>POST</http-method>
            </web-resource-collection>
            <user-data-constraint>
                <transport-guarantee>CONFIDENTIAL</transport-guarantee>
            </user-data-constraint>
        </security-constraint>

The most important parts of the `<security-constraint>` element above are shown in red. The `<url-pattern>` element points to the entire Page Flow directory, indicating that all communication with the Page Flow application should be protected. The `<transport-guarantee>` element has the value `CONFIDENTIAL`, indicating that the session should be encrypted.

How URL Patterns Work

When a user invokes the action `myForwardAction.do`, say through a `<netui:anchor>` tag or `<netui:form>` tag, the following URL will is formed and requested from the Page Flow Controller.

        http://my.domain.com/MyWebApp/myPageFlowDirectory/myForwardAction.do

The invoking `<netui>` tag will check the requested URL against the web.xml file for protected URL patterns. If the requested URL matches the `<url-pattern>`, the user is asked to proceed with HTTPS encryption. If the user opts to proceed, the rest of the session will be protected by HTTPS encryption. (To switch back to the HTTP protocol, see the section )

For more detailed information about URL patterns and `<security-constraint>` elements, see One-Way SSL.

Page Flow Portlets

The <netui> tag libraries look for the same URL patterns whether your Page Flow is inside or outside of a Portal. So if you have security constraints defined for a Page Flow and then create a portlet out of that Page Flow, there is nothing else you need to do in order to get HTTPS to work with that portlet.

### Securing Parts of a Page Flow Application (Actions and JSP Pages) Using HTTPS

In some cases, you may want the bulk of a user session to be conducted over HTTP, while the traffic associated with specific actions and JSP pages is conducted over HTTPS. For example, you may want to allow a customer to browse the product pages over HTTP, but require that the check-out pages be encrypted using HTTPS.

To protect an individual Action, refer to them in the `<url-pattern>` element using the `.do` syntax to indicate an Action. In the following example, the the Action `myAction` is declared as a protected resource. When the Action is invoked, the rest of the user's communication with the application will be through the HTTPS port.

        <security-constraint>
            <web-resource-collection>
                <web-resource-name>My Page Flow</web-resource-name>
                <description>When the Action myAction is invoked, encrypt the traffic with the Page Flow application.</description>
                <!-- URL pattern for the web resource -->
                <url-pattern>/myPageFlowDirectory/myAction.do</url-pattern>
                <http-method>GET</http-method>
                <http-method>POST</http-method>
            </web-resource-collection>
            <user-data-constraint>
                <transport-guarantee>CONFIDENTIAL</transport-guarantee>
            </user-data-constraint>
        </security-constraint>

To protect an individual JSP page, the `<url-pattern>` element should refer to the action method that forwards users to that JSP page, not to the JSP directly.

In the following example, assume that `myForwardAction` forwards users to the `next.jsp` page.

        /**
         * @jpf:action
         * @jpf:forward name="success" path="next.jsp"
         */
        protected Forward myForwardAction()
        {
            return new Forward("success");
        }

To protect the `next.jsp` page, use an `<url-pattern>` element that references the Action method `myForwardAction`.

        <security-constraint>
            <web-resource-collection>
                <url-pattern>/myPageFlowDirectory/myAction.do</url-pattern>
                <url-pattern>/myPageFlowDirectory/myForwardAction.do</url-pattern>
                <http-method>GET</http-method>
                <http-method>POST</http-method>
            </web-resource-collection>
            <user-data-constraint>
                <transport-guarantee>CONFIDENTIAL</transport-guarantee>
            </user-data-constraint>
        </security-constraint>

Switching Back to the HTTP Protocol

Note that once the HTTPS protocol has been turned on, the rest of the session will be conducted over HTTPS until it is explicitly turned off. To return the session to the HTTP protocol from the HTTPS protocol, the user must invoke another (appropriately constrained) Action. The following example shows how to constrain an Action so that it will revert a session to the HTTP protocol (assuming that the session is already being conducted on the HTTPS protocol).

        <security-constraint>
            <web-resource-collection>
                <url-pattern>/myPageFlowDirectory/revertToHTTP.do</url-pattern>
                <http-method>GET</http-method>
                <http-method>POST</http-method>
            </web-resource-collection>
            <user-data-constraint>
                <transport-guarantee>NONE</transport-guarantee>
            </user-data-constraint>
        </security-constraint>

Because the `<transport-guarantee>` element is set to `NONE`, encrytion will be turned off when a user invokes the `revertToHTTP` Action.

## Authentication and Login

#### Using "Form-based" Authentication in Page Flows

You should not use Form-based authentication to protect individual JSP pages or actions within a Page Flow. This is because Form-based authentication redirects the user back to the Page Flow after authentication. But redirects to a particular JSP page or action in a Page Flow (almost) always fail. This is because the Controller file intercepts any redirects and runs the `begin()` method, instead of the intended method. (An exception to this rule are redirects to the `begin()` method itself. These redirects will succeed, since the `begin()` is always run first when a new session begins.)

The following example shows the wrong way to set up Form-based authentication in a Page Flow application.

        <security-constraint>
            ...
            <url-pattern>/myPageFlowDirectory/myJSP.jsp</url-pattern>   --   WRONG! (In a Page Flow application)
            ...
        </security-constraint>

    	<login-config>
            <auth-method>FORM</auth-method>
            ...
        </login-config>

You may however use form-based security to secure an entire Page Flow directory.

        <security-constraint>
            ...
            <url-pattern>/myPageFlowDirectory</url-pattern>   --   OK
            ...
        </security-constraint>

    	<login-config>
            <auth-method>FORM</auth-method>
            ...
        </login-config>

For detailed information on Form-based security, see Form Authentication.

### Using Annotations to Control Login

Page flows provides class-level and method-level annotations to control the login and authentication of users. See the help topic Page Flow Authentication for detailed information.

## Related Topics

Transport Security

One-Way SSL

Form Authentication

Page Flow Authentication