# Step 4: Role-Based Security

In this step you will secure you page flow application using role-based security. You will restrict access to the page flow to only those users who have been granted the Investigators role.
Any time you implement a role-based security strategy you must do two things: you must set up (1) an authentication procedure and (2) an authorization procedure.
An authentication procedure verifies that an incoming user is who he says he is. In this case, the authentication procedure will be based on a username/password challenge. A user who wants to access the Investigate page flow will be asked to provide a matching username and password.

An authorization procedure decides whether a given (already authenticated) user has been granted the necessary permissions to access a given resource. In this case, the authorization procedure will be based on role membership. We will modify the Investigate page flow so that only users in the Investigators role can access the page flow.

Note that the authorization procedure assumes that the authentication procedure has already been completed. This is because a user's role membership can be decided only once his identity has been established by the authentication procedure.

The tasks in this step are:

- to set up an authentication procedure
- to set up an authorization procedure
- to add a test user
- to test the Investigate page flow

Set up an Authentication Procedure

In this task you will place a security constraint on the Investigate page flow, a constraint that requires clients to provide a valid username and password before they can access the Investigate page flow. You will use a set of login JSP pages that are already included in the page flow application. The security constraint specifies that users who try to access the Investigate page flow will be redirected to the login pages. If they successfully login in they will be directed back to the page flow.

This sort of authentication procedure is sometimes called "Form-based" security, because of the HTML form submitted from the login JSP pages. (Note that this sort of authentication procedure should not be used to log in users once they have entered the page flow. This is because page flows do not support redirection away from and back to the navigational Action methods within the page flow. But this kind of authentication procedure can be used to login users before they enter the page flow.)

1. On the Application tab, double-click the file PageFlowTutorial/PageFlowTutorialWeb/WEB-INF/web.xml.
2. Add the following <security-constraint>, <login-config> and <security-role> elements to the web.xml file. Add the elements immediately before the closing </web-app> tag. Code to add is shown in red. Do not add code shown in black.

        <taglib>
            <taglib-uri>netui-tags-template.tld</taglib-uri>
            <taglib-location>/WEB-INF/netui-tags-template.tld</taglib-location>
        </taglib>

        <!--
        The following <security-constraint> element specifies which web resource should be protected.
        It also specifies that only users granted the Users role can access the resource.
        Note that this role restriction is "toothless" because any successfully logged in user
        will automatically pass the role restriction (since all logged in users are members of the 'users'
        group, which is mapped to the Users role).
        The purpose of the role restriction is its side effect: it causes WebLogic Server to login candidate users
        to the web resource.
        -->
        <security-constraint>
            <web-resource-collection>
                <web-resource-name>The Investigate Page Flow</web-resource-name>
                <description>
                    Protect the following web resources with a username / password challenge.
                </description>
                <url-pattern>/investigateJPF/investigateJPFController.jpf</url-pattern>
                <http-method>GET</http-method>
                <http-method>POST</http-method>
            </web-resource-collection>
            <auth-constraint>
                <description>
                    These are the roles who have access the web resources above.
                </description>
                <role-name>
                    Users
                </role-name>
            </auth-constraint>
            <user-data-constraint>
                <description>
                    This is how the user data must be transmitted.
                </description>
                <transport-guarantee>NONE</transport-guarantee>
            </user-data-constraint>
        </security-constraint>

        <!--
        Log users in with "Form-based" authentication.
        Use the JPS pages login.jsp and fail_login.jsp
        to login candidate users.
        -->
        <login-config>
            <auth-method>FORM</auth-method>
            <realm-name>default</realm-name>
            <form-login-config>
                <form-login-page>/login_pages/login.jsp</form-login-page>
                <form-error-page>/login_pages/fail_login.jsp</form-error-page>
            </form-login-config>
        </login-config>

        <!--
        The following <security-role> element declares the Users role
        so that it can be mapped to the users principal.  For the mapping
        see weblogic.xml.
        -->
        <security-role>
            <description>
                The Users role is mapped to the users group, a pre-defined principal in WebLogic Server's
                default authentication provider.  For the mapping see weblogic.xml.
            </description>
            <role-name>
                Users
            </role-name>
        </security-role>

    </web-app>

3. On the Application tab, double-click the WEB-INF/weblogic.xml file.
4. Add the following <security-role-assignment> element to weblogic.xml. Make sure to add the code directly after the opening <weblogic-web-app> tag. Code to add is shown in red. Do not add code shown in black.

       <weblogic-web-app>

           <!--
           Grants the Users role to clients who possess the users principal.

           The users group is a pre-defined pricipal in the WebLogic Server default authentication provider.
           All clients who log in with a valid username/password pair automatically
           possess the users principal.

           Since logged in clients automatically possess the users principal,
           and the <security-role-assignment> below grants the Users role to anyone possessing
           the users principal, anyone who logs in with a valid username/password pair
           is automatically granted the Users role.
           -->
           <security-role-assignment>
               <role-name>Users</role-name>
               <principal-name>users</principal-name>
           </security-role-assignment>

           <jsp-descriptor>
               <!-- Comment the jspServlet param out to go back to weblogic's jspc -->
               <jsp-param>
                   <param-name>jspServlet</param-name>
                   <param-value>weblogic.servlet.WlwJSPServlet</param-value>
               </jsp-param>
               <jsp-param>
                   <param-name>debug</param-name>
                   <param-value>true</param-value>
               </jsp-param>
           </jsp-descriptor>

           <url-match-map>
              weblogic.servlet.utils.SimpleApacheURLMatchMap
           </url-match-map>
       </weblogic-web-app>

   In web.xml, the <auth-constraint> element, standing for authorization constraint, states that clients must be granted the Users role in order to access the Investigate page flow. It may seem strange to set up an authorization procedure at this point. Wasn't the idea to set up an authentication procedure? There is a trick here: the presence of the <auth-constraint> element causes WebLogic Server to both authenticate and authorize the client. WebLogic Server first asks the candidate user for a username/password pair; second WebLogic Server applies the authorization procedure called for by the <auth-constraint>.
   Also note that any client who passes the username/password challenge automatically passes the authorization procedure. This is because any client with a valid username/password pair is automatically granted the users principal by WebLogic Server (users is a pre-configured principal in WebLogic Server) and the users principle is mapped to the Users role in weblogic.xml. So at this point we have set up a authentication procedure that challenges clients for a username and password and a "toothless" authorization procedure that an authenticated client will automatically pass. We will set up the "real" authorization procedure below.
5. Press Ctrl+S to save your work. Press Ctrl+F4 twice to close web.xml and weblogic.xml.

Set up an Authorization Procedure

In this task you will place an authorization constraint on the Investigate page flow, such that only those users who have been granted the role of Investigator will be able to gain access to the Investigate page flow.

1. Confirm that investigateJPFController.jpf is displayed in the main work.
2. Click the Flow View tab, if necessary.
3. In Flow View, click a spot within the white space to confirm that the page flow file as a whole is selected.
4. On the Property Editor tab, in the Roles Allowed property, enter Investigator.
5. Press Enter.
6. Press Ctrl+S to save your work.

Declare the Investigator Security Role, Add a Test User, and Map this User to the Investigator Security Role

In this task you do three things. First, you will declare the security role Investigator. This role is a scoped-role. It is scoped at the application level. Application-scoped roles are declared in the META-INF/application.xml file. (This file does not appear on the Application tab by default, but, if you wish, you can see this file by opening PageFlowTutorial/META-INF/application.xml using your operating system.) Second, you will add a test user with the same name: Investigator. Third you will map this user to the security role. (The mapping is declared in the PageFlowTutorial/META-INF/weblogic-application.xml file)

1. On the Application tab right-click the Security folder and select Create new role.
2. In the New Security Role dialog, in the Name field, enter Investigator. In the section labeled Principal Name, ensure that Use role name is selected.
3. Click Ok.
   The New Security Role dialog has three effects:
   (1) A new (application-scoped) role is added to the application.
   (2) A new user is added to the WebLogic Workshop security framework. When "Use role name" is selected, this user has the same name as the role. By default, the password for this user is password.
   (3) The user is mapped to the role.
   (For more information on creating security users and roles with the New Security Role dialog, see the help topic How Do I: Create An Application-Scoped Security Role?)

Test the Investigate Page Flow

Test for Successful Authentication and Successful Authorization
In this test you will ensure that users who have been granted the role of Investigator can pass both the authentication procedure and authorization procedure.

1. Confirm that investigateJPFController.jpf is displayed in the main work area.
2. Right-click the folder PageFlowTutorialWeb and select Build PageFlowTutorialWeb. (It is a good idea to re-compile your web application project after making changes to the configuration files web.xml and weblogic.xml. This helps ensure that the web application properly deploys to WebLogic Server.)
3. Click the Start button.
   The Investigate page flow builds and the login.jsp page launches.
4. In the login.jsp page, in the Username field, enter Investigator.
   In the Password field, enter password.
   Click Submit.
5. In the Workshop Test Browser, in the TaxID field, enter the 9 digit number 222222222 and click Submit.
   The credit report is retrieved and displayed.
6. Close the Workshop Test Browser.

Test for Successful Authentication but Failed Authorization

In this test you will ensure that users who have not been granted the role of Investigator do not pass the authorization process. You will do this by logging in as the user 'weblogic'. This user will pass the authentication procedure, since it is a user known to the WebLogic Security authentication provider. But 'weblogic' has not been granted the Investigator role, so it will fail the the authorization procedure.

1. Confirm that investigateJPFController.jpf is displayed in the main work area.
2. Click the Start button.
   The Investigate page flow builds and the login.jsp page launches.
3. In the login.jsp page, in the Username field, enter weblogic.
   In the Password field, enter weblogic.
   Click Submit
   The Workshop Test Browser displays the following error.
4. Close the Workshop Test Browser.

Test For Failed Authentication and Failed Authorization

In this test you will ensure that users that are unknown to the WebLogic Server authentication provder cannot successfully login.

1. Confirm that investigateJPFController.jpf is displayed in the main work area.
2. Click the Start button.
   The Investigate page flow builds and the login.jsp page launches.
3. In the login.jsp page, in the Username field, enter wrong_user.
   In the Password field, enter wrong_password.
   Click Submit
   The Workshop Test Browser displays the failed_login.jsp page.

Related Topics

Role-Based Security

Handling Exceptions in Page Flows

Click one of the following arrows to navigate through the tutorial.