Securing a Web Application on a Java Cloud Service

Overview

    Purpose

    This tutorial covers using role-based security in a web application deployed to a Java Cloud Service.

    Time to Complete

    Approximately 45 minutes.

    Introduction

    This tutorial shows how to use standard role-based security in a Java Enterprise Edition web application that is deployed to a Java Cloud Service.

    Scenario

    This tutorial assumes that you are an Oracle customer. It would also be helpful if you have some Java web application programming experience.

    Once you have completed this tutorial, to better understand users, roles and the Identity Console, it is suggested you try the tutorial titled Managing Users and Roles Using the Identity Console.

    Prerequisites

    Before starting this tutorial, you should have:

    • An Oracle.com account
    • Already completed the Oracle by Example tutorials titled:
      • Signing Up for a Java Cloud Service
      • Deploying an Application to a Java Cloud Service
    • Downloaded the sample Java web application archive file timeoff.war. Download the file here: timeoff.war.

      Note for Internet Explorer Users: IE may download timeoff.war as timeoff.zip. It is really the same file. To get the WAR file back, just rename it to timeoff.war.

Creating Users and Roles

    Web applications deployed to a Java Cloud Service can be available to anyone, or restricted to users that log in. A web application's deployment descriptors determine which way it behaves. This tutorial will show you how to set up the deployment descriptors both ways.

    If you want to restrict access to your web application to users that log in, you must create user accounts. This tutorial will cover creating one user account at a time by using the Identity Console.

    In the case of a web application that uses role-based security to further protect some of its resources, you must also create a role within the Identity Console. This tutorial will show you how to do that, too, as well as assign certain of the defined users to that role. Of course, you can have more than one collection of protected resources within the same web application, which would mean creating a role for each collection.

    To create users and roles by using the Identity Console, perform the following steps:

    Access the Identity Console by entering its URL in a web browser. You were given its URL in the welcome email sent to you after you signed up for a Java Cloud Service. Look in the section titled Identity Domain Details and click the link for the Identity Management Console.

    Sign in to the Identity Console with the Identity Domain Administrator credentials. In this tutorial the Username is bill.bell@oracle.com and the Identity Domain is trialaaop (yours will be different). Click the Sign In button.

    Once signed in, on the left of the screen, click the Manage Users link.

    Then click the Create button.

    Fill in the user information. When finished, click the Create button.

    Click OK in the confirmation window.

    In this tutorial, this first user created, Louie De Palma, will be set up so he can access the web application resources that are for managers only.

    Back on the users screen, click the Create button again. Once again, fill in the user information and click the Create button.

    Click OK in the confirmation window.

    In this tutorial, this second user created, Jim Ignatowski, will be set up so he CANNOT access the web application resources that are for managers only.

    Back on the Identity Console, on the left of the screen, click the Manage Roles link.

    On the roles screen, click the Create button.

    In the Create Role window, enter a role Name and Description. Click the Create button.

    In this tutorial, the Name entered is boss and the Description entered is Big Boss.

    Click OK in the confirmation window.

    Back on the roles screen, enter an * in the field and click the Search button.

    Then select the row that has the new role, boss.

    Now that the boss row has been selected, click the Assign button.

    In the Grant Role window, enter an * in the search field and click the Search button.

    Then select the row that has the user you wish to assign to the role of boss. In this tutorial the user selected is Louie De Palma.

    Click the Assign button.

    Click OK in the confirmation window.

    Sign out of the Identity Console.

Modifying the Web Application

    The sample web application, in the timeoff.war archive file, protects some of its resources by using the two deployment descriptors: web.xml and weblogic.xml. Before deploying the web application, you need to edit weblogic.xml to ensure that it will function properly with the work just completed in the Identity Console. You will also view web.xml to see how it is configured.

    Before performing these tasks, let's talk about the deployment descriptors and the three security scenarios for a deployed web application: open to the public, restricted to logged-in users, or restricted to logged-in users with some web application resources further protected.

    The standard web application deployment descriptor is web.xml:

    • The tag <login-config> defines how users are authenticated.

      To let everyone access the web application without logging in, in other words, make the web application open to the public, have an empty <login-config> tag, like this:
      <login-config />

      To restrict the web application to logged-in users, the <login-config> tag and its sub-tags should look like this:
      <login-config>
        <auth-method>CLIENT-CERT</auth-method>
        <realm-name>default</realm-name>
      </login-config>

      This means that the web application will use the Java Cloud Service single sign-on, and the Java Cloud Service will pass a certificate to the web application containing information about the logged-in user. This also means that you must define users to the Java Cloud Service, as you did in the previous section of this tutorial.

    • The <security-role> tag and its sub-tag define a user role (type of user). Web application roles are needed if you want to not only restrict the web application to logged-in users, but also further protect certain parts of the web application. Protected web application resources can only be accessed by logged-in users that have the proper role. Using role-based security means you must define roles here in the deployment descriptor. You must also define roles in the Java Cloud Service, as you did in the previous section of this tutorial..

    • The <security-constraint> tag and its sub-tags are used to specify the web resources that are protected, as well as declare which roles are allowed to access them. This tag is not needed if your web application is open to the public. It is also not needed if all logged-in users will have access to all the parts of the web application.

    The WebLogic-specific deployment descriptor is weblogic.xml.

    • If you are using role-based security you need the <security-role-assignment> tag and its sub-tags to map web application roles to principals. Principals are usually users or groups defined within your authentication provider. With applications deployed to a Java Cloud Service, a principal is a Java Cloud Service role.

    • Another tag is <session-descriptor> with the sub-tag <cookie-path>. If your application is participating in the Java Cloud Service single sign-on, it must have a unique value specified for cookie-path.


    To view and edit the web application's deployment descriptors, perform the following steps:

    Make a copy of the timeoff.war file and rename it timeoff.zip. Unzip the timeoff.zip file into a directory called timeoff.

    In the new timeoff directory, expand WEB-INF, and you will see the two deployment descriptors.

    Open web.xml in a text editor.

    Scroll down until you will see the <login-config> tag. Here you can see that it is set up as we discussed earlier: users must log in via the Java Cloud Service single sign-on, and the web application will be passed a certificate by the Java Cloud Service. By the way, the <realm-name> specifies the WebLogic Server security realm name and its value should be default.

    Just below <login-config> you can see the <security-role> tag. Its sub-tag <role-name> defines a web application role called manager.

    Now scroll back up and find both <security-constraint> tags. Look at the second one, called Constraint-2, first. Notice within it the subtag <web-resource-collection> with its subtags <url-pattern>. Those URL patterns (like /managers/*) define protected resources in this web resource collection.

    Notice below the </web-resource-collection> tag the <auth-constraint> tag with its subtag <role-name>manager</role-name>. This means a user assigned to the web application role of manager will be allowed access to the protected resources in this collection. Other users will receive an error when trying to access these resources.

    Now look at the first <security-constraint> tag, the constraint called Constraint-1. Its <web-resource-collection> has only one <url-pattern>. That pattern is the first page of this web application, welcome.html.

    Also notice that within this <security-constraint> tag there is no <auth-constraint> sub-tag. Without the <auth-constraint> tag, all logged-in users have access to this web resource collection.

    What this does is force all users to log in when they first access the web application. And, without the <auth-constraint>, all defined users have access. We need to do this because, with role-based security in a web application deployed to a Java Cloud Service, users are required to be logged in BEFORE trying to access role-secured resources.

    Exit the text editor. Do NOT make any changes to web.xml.

    Now open weblogic.xml in a text editor. Within the <security-role-assignment> tag you find two subtags: <role-name> and <principal-name>. The role name is the web application role (called manager) defined in web.xml. The principal name needs to be the name of the Identity Domain, followed by a ".", and then the role defined in the Identity Console.

    Replace the generic value <IDENTITY_DOMAIN_NAME>.<IDM_ROLE_NAME> with the values of your Identity Domain and the role you created in the Identity Console. In this tutorial the generic value is replaced with:
    trialaaop.boss

    Before the change:

    After the change:

    Notice two more things in weblogic.xml:

    • The <session-descriptor> tag with its subtag <cookie-path>. All applications participating in the Java Cloud Service single sign-on must have a unique value specified for cookie-path.
    • The <context-root> tag, which specifies the URL pattern used to call this web application. In this case, the web application is called with /timeoff.

    Save weblogic.xml and exit the text editor.

    Zip the contents of the timeoff directory into a new timeoff.zip file. Include all subdirectories, but not their full path. Also, do NOT include the timeoff directory itself.

    If you are zipping from the command line, first cd into the timeoff directory. Then zip with the options -r -p (for recursion but not full path). Include all the files by using *.*. The command is:

    wzzip -r -p timeoff.zip *.*

    Note: You may need to add the WinZip folder to the PATH to use the command-line version of WinZip:
    set PATH="C:\Program Files\WinZip";%PATH%

    After the new zip file has been created, rename it timeoff.war. This is the web application archive file that you will deploy.

    IMPORTANT NOTE FOR MAC USERS: If you are using a Mac, you cannot use the default Finder utility for zipping up the new archive file. You must instead download and use WinZip Mac Edition. If you use the default Mac utility, it places extra files in the archive which will cause a 403 error when you try to access the application after it is deployed.

Deploying the Application to the Java Cloud Service

    To deploy the application to the Java Cloud Service, perform the following steps:

    Go to the welcome email and click the link for the Java Service Console.

    Sign in using the Service Administrator's credentials, which in this tutorial is the same as the Identity Domain Administrator's credentials.

    In this tutorial, the Username is bill.bell@oracle.com.
    The Identity Domain is trialaaop. (Yours will be something else.)

    After signing in, you should see the Java Cloud Services Control console for your Java Cloud Service. To deploy an application, below the Applications heading, click the Deploy New button.

    On the Deploy Application screen, enter timeoff in the Application Name field, and click the Choose File button to browse the file system for the application archive file.

    Browse to the location of the new timeoff.war file that you just created. This is the one that has the updated deployment descriptor. Select this file and click Open.

    Back on the Deploy Application screen, click the Deploy button.

    You are returned to the Java Cloud Service screen for this Java Cloud Service. Notice the message that the application is uploaded and will be deployed.

    After a while, refresh the page. You can refresh the page by clicking the curved arrow at the top-right of the screen next to the date and time. You will eventually see an entry for the timeoff application in the Applications table. You can tell that the deployment was successful by the green arrow in the Status column and the indication of "Active" in the State column.

    Note: The applications listed, besides timeoff, may be different than those shown here.

    To find the URL of the deployed application, in the Applications table, in the timeoff row, click the icon under "Test Application."

    In the Application URLs pop-up window, right-click the URL for the application and select Copy link address (or your browser's equivalent). You will paste this address into another web browser momentarily.

    Click OK to close the Application URLs pop-up window.

    Close the browser window. You do not want to access the application as the already logged-in Service Administrator. You want to log in as one of the users you created.

Testing the Application

    To test the security of the deployed application, perform the following steps:

    Open a new browser window and paste in the copied application URL. You should be asked to log in. Log in as the user without access to the resources for managers only. In this tutorial, that is the user Jim Ignatowski, with the userid jim.

    Note: If you are not asked to log in, then you may have other browser windows open and they are holding on to the session ID. Close all browser windows and try again.

    If this is the first time this user has logged in, the Password Management screen displays so that the user can enter a password to replace the one assigned by the Identity Domain Administrator. Enter the old password in the Old Password field, and a new one in the New Password and Re-Type New Password fields. Pay attention to the password policies when choosing a new password.

    The new user must also select challenge questions and provide their answers.

    Then click the Submit button.

    When the password changing process is complete, you will be taken to the application.

    If this is NOT the first time this user has logged in, you will be taken to the application.

    When the application appears, if you wish, try the Request Time Off link. Jim should be able to do that, because that part of the web application is not protected.

    After clicking the link, fill out the form and click the Submit Report button.

    On the next screen, click the Back To Home Page link.

    Next, as Jim, try the Close an Office link. This link requests a protected resource (it matches a protected URL pattern) and only users with the manager role are allowed to access it. Jim was not given the boss role, which is tied to the web application's manager role, so this link should fail.

    Sure enough, Jim gets a 403--Forbidden error.

    Close the browser window.

    Open a new browser window and once again paste in the copied application URL. Log in as the user that has access to the resources for managers only. In this tutorial, that is the user Louie De Palma, with the userid louie.

    As before, if this is the first time this user has logged in, the Password Management screen displays so that the user can enter a password to replace the one assigned by the Identity Domain Administrator. If this happens, give this user a new password as well as challenge questions and answers.

    When the password changing process is complete, you will be taken to the application.

    If this is NOT the first time this user has logged in, you will be taken to the application.

    When the application appears, as Louie, try the Close an Office link. Louie was given the boss role, which is tied to the web application's manager role, so this link should work for him.

    This time, the link works. Louie can access this protected part of the web application and close the office.

    Fill out the form and click the Submit Form button.

    On the next screen, click the Back To Home Page link.

    Close the browser window.

Summary

    In this tutorial, you have learned how to:

    • Create users and roles for use by the Java Cloud Service by using the Identity Console
    • Modify the weblogic.xml deployment descriptor of a sample application so a web application role is mapped to an Identity Domain role
    • Deploy an application to a Java Cloud Service by using the Java Cloud Services Control console

    Resources

    Credits

    • Lead Curriculum Developer: Bill Bell
    • Other Contributors: Reza Shafii, Anand Kothari

To help navigate this Oracle by Example, note the following:

Hiding Header Buttons:
Click the Title to hide the buttons in the header. To show the buttons again, simply click the Title again.
Topic List Button:
A list of all the topics. Click one of the topics to navigate to that section.
Expand/Collapse All Topics:
To show/hide all the detail for all the sections. By default, all topics are collapsed
Show/Hide All Images:
To show/hide all the screenshots. By default, all images are displayed.
Print:
To print the content. The content currently displayed or hidden will be printed.

To navigate to a particular section in this tutorial, select the topic from the list.