Securing a Web Application on Oracle Java Cloud Service - SaaS Extension

Overview

Purpose

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

Time to Complete

Approximately 45 minutes

Introduction

Web applications deployed to Oracle Java Cloud Service - SaaS Extension can be available to anyone or can be restricted to users who log in. A web application's deployment descriptors determine how it behaves. This tutorial shows you how to set up the deployment descriptors both ways.

If you want to restrict access to users who log in, you must create user accounts. This tutorial covers creating one user account at a time on the Security tab in the My Services Administration portal.

If a web application uses role-based security to further protect some of its resources, you must also create a role within My Services. This tutorial shows you how to do that, too, as well as assign certain 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.

Scenario

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

Prerequisites

Before starting this tutorial, you should:

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

    Note for Internet Explorer Users: Internet Explorer may download timeoff.war as timeoff.zip. It is the same file. Just rename it timeoff.war.

Creating Users and Roles

In this section, you create users and roles in the My Services Administration portal.

  1. In a web browser, enter the My Services Administration URL.

    The link to this URL is in the welcome email that you received when you signed up for the trial Oracle Java Cloud Service - SaaS Extension. Look for the My Services URL in the My Services Administration Details section.

  2. Sign in with the identity domain administrator credentials.

    1. Enter the username in the User Name field. In this tutorial, it is edgar.******@******.com.
    2. Enter the password in the Password field.
    3. Enter the name in the Identity Domain field. You can find the identity domain name in the welcome email. In this tutorial, it is usoracletrial04861. (Your identity domain name will be different.)
    4. Click Sign In.
    Sign in to Oracle Cloud
  3. At the top of the screen, click the Users tab.

    Security tab
  4. On the Users tab, click Add.

    Create User
  5. Fill in the user information and click Add. You do not have to assign a role now.

    Add User button

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

  6. Repeat steps 4 and 5 to add user Jim Ignatowski.

    Add button

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

  7. In the Security section, click the Custom Roles tab.

    Custom Roles
  8. On the Custom Roles screen, click Add.

    Add custom role button
  9. In the Add Custom Role window, perform the following steps:

    1. Enter boss for the role name and display name.
    2. Enter Big Boss for the description.
    3. Click Add.
    Create Role window

    If you do not enter a display name, the system uses the same value that you specified for the role name

  10. Click the Users tab.

    Users tab
  11. Click the Menu button next to the Louie De Palma account and select Manage Roles.

    Manage Roles
  12. Select the boss role from the Available Roles column, click the right arrow to move the role to the Assigned Roles column, and then click Save.

    Assign role
  13. On the Users screen, position the cursor over the Louie De Palma user to view the boss role that was assigned to him.

    Louie De Palma
  14. Click Sign Out to exit My Services.

    Sign Out

Modifying the Web Application

In this section, you learn 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. You also learn how to modify these deployment descriptors.

Deployment Descriptors Overview

The standard web application deployment descriptor is web.xml:

  • The <login-config> tag 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), create an empty <login-config> tag, like this:

    <login-config />                

    To restrict the web application to logged-in users, the <login-config> tag and its subtags 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 uses the Oracle Java Cloud Service - SaaS Extension single sign-on, and Oracle Java Cloud Service - SaaS Extension passes a certificate to the web application containing information about the logged-in user. You must define users to Oracle Java Cloud Service - SaaS Extension, as you did in the previous section of this tutorial.

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

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

The deployment descriptor for Oracle WebLogic Server is weblogic.xml.

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

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

Editing Deployment Descriptors

The sample web application, which is 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 the weblogic.xml file to ensure that it will function properly with the work just completed in the My Services Administration portal. You also view web.xml to see how it is configured.

  1. Perform the following steps to view the two deployment descriptors:

    1. Make a copy of the timeoff.war file and rename it timeoff.zip.
    2. Create a directory named timeoff.
    3. Unzip the timeoff.zip file into the timeoff.war directory.
    4. Expand WEB-INF.
    timeoff.war
  2. Open web.xml in a text editor and scroll down to the <login-config> tag.

    Here you can see its setup: Users must log in through the Oracle Java Cloud Service - SaaS Extension single sign-on, and the web application will be passed a certificate by Oracle Java Cloud Service - SaaS Extension. Notice that the <realm-name> tag specifies the security realm name for WebLogic Server, and its value should be default.

    login-config tag
  3. Scroll down to the <security-role> tag, whose <role-name> subtag defines a web application role named manager.

    security-role tag
  4. Scroll up to the <security-constraint> tags and look at the Constraint-2 tag.

    Notice the <web-resource-collection> subtag with its <url-pattern> subtags. Those URL patterns (like /managers/*) define protected resources in this web resource collection.

    Notice the <auth-constraint> subtag with its <role-name>manager</role-name> subtag. A user assigned to the manager web application role is allowed access to the protected resources in this collection. Other users receive an error when they try to access these resources.

    security-constraint tag
  5. Look at the first <security-constraint> tag, the constraint named Constraint-1.

    Its <web-resource-collection> subtag has only one <url-pattern> subtag. That pattern is the first page of this web application, welcome.html.

    Notice that this <security-constraint> tag has no <auth-constraint> subtag. Because of that, all logged-in users have access to this web resource collection. All users are forced to log in when they first access the web application. And, without the <auth-constraint> subtag, all defined users have access. You must do this because, with role-based security in a web application deployed to Oracle Java Cloud Service - SaaS Extension, users are required to be logged in before they try to access role-secured resources.

    security-constraint tag
  6. Close web.xml without changing it.

  7. Open weblogic.xml in the text editor and notice that the <security-role-assignment> tag contains two subtags: <role-name> and <principal-name>.

    • The role name is the web application role (called manager) that is defined in web.xml.
    • The principal name needs to be the name of the identity domain, followed by a period, and then followed by the role that you defined in the My Services Administration portal.
  8. In the <principal-name> subtag, replace the generic value, <IDENTITY_DOMAIN_NAME>.<IDM_ROLE_NAME>, with boss, which is the value of the role that you created in the My Services Administration portal.

    Before the change:

    security-role-assignment tag

    After the change:

    security-role-assignment tag
  9. Look at two other tags in weblogic.xml:

    • The <session-descriptor> tag with its <cookie-path> subtag. All applications participating in the Oracle Java Cloud Service - SaaS Extension single sign-on must specify a unique value 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.
    session-descriptor tag
  10. Save weblogic.xml and exit the text editor.

  11. Perform one of the following steps to create a new timeoff.zip file:

    • WinZip: Zip the contents of the timeoff directory into a new timeoff.zip file. Include all subdirectories, but not their full path, and do not include the timeoff directory itself.
    • Command-Line Version of WinZip: Add the WinZip folder to the path (set PATH="C:\Program Files\WinZip";%PATH%). Change to the timeoff directory, and then enter the following command to zip all files for recursion but not full path (-r -p), and include all files (*.*): wzzip -r -p timeoff.zip *.*
      security-role-assignment tag
    • Mac Users: Download the WinZip Mac Edition, and then follow the steps for WinZip. Do not use the default Finder utility to zip the new archive file. If you do, extra files are placed in the archive, and they cause a 403 error when you try to access the application after it is deployed.
  12. Rename the new zip file timeoff.war.

You will deploy this web application archive file next.

Deploying the Application to Oracle Java Cloud Service - SaaS Extension

In this section, you deploy the application to Oracle Java Cloud Service - SaaS Extension.

  1. In your welcome email, click the Java Service Console link.

  2. Sign in with the service administrator's credentials. In this tutorial, the credentials are the same as the identity domain administrator's credentials.

    In this tutorial, the username is edgar.******@******.com.
    The identity domain name is usoracletrial04861. (Your identity domain name will be different.)

    Sign in to Oracle Cloud

    The Oracle Java Cloud Service - SaaS Extension Control for your Oracle Java Cloud Service - SaaS Extension instance appears.

  3. In the Applications section, click Deploy New.

    Java Cloud Services Control console
  4. On the Deploy Application screen, enter timeoff in the Name field, and click Browse to search for the application archive file.

    Deploy Application screen
  5. Browse to the location of the timeoff.war file with the updated deployment descriptor, select the file, and click Open.

    Open timeoff.war
  6. On the Deploy Application screen, click Deploy.

    Deploy application

    After the file is uploaded, you are returned to the Oracle Java Cloud Service - SaaS Extension Control home page for this Oracle Java Cloud Service - SaaS Extension instance. The Information message indicates that the application was uploaded and will be deployed.

    Java Cloud Service screen
  7. Click Reload to refresh the page.

    The timeoff application is eventually displayed in the Applications table. The green arrow in the Status column and the Active notation in the State column indicate that the deployment was successful.

    timeoff application

    Note: Other than timeoff, the listed applications may be different than those shown here.

  8. In the Test Application column for timeoff, click the icon to find the URL of the deployed application.

    Applications table
  9. In the Application URLs pop-up window, perform the following steps:

    1. Right-click the URL for the application and select Copy Link Location (or your browser's equivalent). In the next section, you will paste this URL into another web browser.
    2. Click OK to close the Application URLs pop-up window.
    3. 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 that you created.
    4. Application URLs

Testing the Application

In this section, you test the security of the deployed application.

  1. Open a new browser window and paste in the application URL that you copied. The Sign In to Oracle Cloud screen appears.

    Note: If the Sign In to Oracle Cloud screen is not displayed, other browser windows may be open, and they are holding on to the session ID. Close all browser windows and try again.

  2. Log in as the user without access to the resources for managers only. In this tutorial, that user is Jim Ignatowski and his username is jim.

    Sign in to Oracle Cloud

    If this is the first time this user has logged in, the Password Management screen appears. There, the user can enter a password to replace the one that the identity domain administrator assigned.

    If this is not the first time this user has logged in, the application appears.

  3. Perform the following steps:

    1. 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.
    2. Select challenge questions and provide the answers.
    3. Click Submit.

    When the password changing process is completed, the application appears.

    Password Management
  4. Perform the following steps:

    1. Click the Request Time Off link. Jim should be able to click the link, because that part of the web application is not protected.
    2. Dizzyworld Time Off web page
    3. Fill out the form and click Submit Report.
    4. On the next screen, click the Back To Home Page link.
  5. Click 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.

    Close an Office link

    Sure enough, a 403--Forbidden error appears.

    Forbidden Error
  6. Close the browser window.

  7. Open a new browser window, paste in the application URL that you copied, and log in as the user who has access to the resources for managers only. In this tutorial, that user is Louie De Palma and his username is louie.

    Sign in to Oracle Cloud

    If this is the first time this user has logged in, the Password Management screen appears. There, the user can enter a password to replace the one that the identity domain administrator assigned.

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

  8. Give this user a new password, challenge questions, and challenge answers.

  9. As Louie, click 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.

    Click Close an Office link

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

  10. Fill out the form and click Submit Form.

    Submit Form button
  11. On the next screen, click the Back To Home Page link.

    Back to Home Page link
  12. Close the browser window.

Summary

In this tutorial, you learned to:

  • Use the My Services Administration portal to create users and roles for use by Oracle Java Cloud Service - SaaS Extension
  • Modify the weblogic.xml deployment descriptor of a sample application so that a web application role is mapped to an identity domain role
  • Deploy an application to Oracle Java Cloud Service - SaaS Extension by using the Oracle Java Cloud Service - SaaS Extension Control

Resources

Credits

  • Lead Curriculum Developer: Edgar Martinez
  • Curriculum Developer: Bill Bell
  • Editorial: Susan Moxley
  • Other Contributors: Reza Shafii

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

Topic List:
Click a topic to navigate to that section.
Expand All Topics:
Click the button to show or hide the details for the sections. By default, all topics are collapsed.
Hide All Images:
Click the button to show or hide the screenshots. By default, all images are displayed.
Print:
Click the button to print the content. The content that is currently displayed or hidden is printed.

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