Exploring OpssADFDemoApp in JDeveloper

<Do not delete this text because it is a placeholder for the generated list of "main" topics when run in a browser>

Purpose

This tutorial walks you through a pre-existing ADF application that uses OPSS security. By understanding the OPSS security artifacts found on the development side of an application, you will more easily understand how these artifacts are migrated when this type of an application is deployed to WebLogic Server, which is covered in the Deploying an OPSS Application OBE, which has you deploy this same application.

After completing this exercise, you should be able to:

Time to Complete

Approximately 1 hour or less

Overview

OPSS is Oracle's security framework for developing and managing security services in Java SE and EE environments. This tutorial is Exploring the OpssADFDemoApp in JDeveloper.

OBE Environment Architecture

This is the high-level architecture of the environment used for the OPSS hands-on OBE tutorials. The environment consists of the following:

Exploring the OpssADFDemoApp in JDeveloper

This OBE walks through the OPSS security settings and configuration contained within an ADF application developed using JDeveloper. The environment consists of the following:

Software and Hardware Requirements

The following is a list of requirements:

Prerequisites

Before starting this tutorial, complete the following prerequisites:

.

This OBE requires that you have completed the OPSS Set Up OBE.

.

This OBE requires that you have completed the Configuring an OID Authentication Provider in WebLogic OBE.

Open JDeveloper and OpssADFDemoApp Application

Follow the steps below to expore an OPSS-enabled application using JDeveloper:

.

Open the JDeveloper IDE using the icon on the launch panel.

The JDeveloper splash screen appears while JDeveloper is starting. NOTE: It doesn't matter if your version of JDeveloper is slightly different. The version of JDeveloper found on the virtual image is 11.1.1.2.

 

.

If the Select Role window appears, leave it selected as Default Role. and click OK. This enables all JDeveloper technologies.

 

.

If the Tip of the Day window appears, close it. Optionally, you can uncheck the Show tips at startup checkbox to avoid this message again.

 

.

If the Application Navigator shows the New Application... and Open Application... options, then select Open Application...

Browse to the /home/oracle/labs/apps/OpssADFDemoApp folder, select the OpssADFDemoApp.jws project file, and click Open.

 

.

Expand all of the tree nodes in the Projects view so that you can see all of the files in the project.

 

.

Expand all of the tree nodes in the Application Resources view so that you can see all of the deployment descriptor files in the project.

Now that the OpssADFDemoApp application is open and visible in the JDeveloper IDE, we can explore how this application works with OPSS.

 

Explore OPSS Artifacts in the OpssADFDemoApp Application

This section guides you through the aspects of the OpssADFDemoApp application that relate to OPSS. Keep in mind that this is not a developer course, so we are not covering how to create security policies. This course is focused on configuration and administrative tasks. This is also not a course on ADF applications in general so we are not testing the application to see how it works. Feel free to run and test the application if you like.

Follow the instructions below to learn how ADF applications configure and use OPSS.

Explore the jps-config.xml File


.

Double-click the jps-config.xml file in the Application Resources view to open the file in the editor.

Note: Because the jps-config.xml file is packaged within the OpssADFDemoApp's META-INF folder that all OPSS configuration for this application during development within the IDE is based on Java SE. When the application is deployed to an OPSS-enabled server, the OPSS configuration applied will be the WebLogic domain's jps-config.xml file.

Click the Overview tab to show the graphical representation of the file if it isn't selected already. We will be using this view of the file for the duration of this tutorial. If you like, you can also explore the file using the Source tab, which provides the entire XML source of the file.

You should see a screen similar to the following:

This screen shows the configuration settings of the jps-config.xml file. This includes: Security Contexts, Identity Store, Credential Store, Login Modules, and Key Store services. The default page has Security Contexts selected and displayed as shown here. There are two contexts, OpssADFDemoApp and anonymous. The default context is OpssADFDemoApp, and the anonymous context is configured to represent a login for users that have not authenticated with the system yet.

NOTE: The anonymous provider is going away and you should ignore it in the UI. It's capabilities have been implemented elsewhere within the OPSS framework.

First, we will examine the Security Contexts section.

 

.

Security Contexts Configuration

The Security Contexts tab displays the JPS contexts configured for the environment. We are going to focus on the OpssADFDemoApp context. Click the plus symbol next to the OpssADFDemoApp context to expand the view and see its configuration.

Here you see the different contexts that are configured for the environment. This includes the following:

  • Identity Store
  • Credential Store
  • Key Store
  • Login Modules

The identity store for this environment is referenced by the name, idstore.xml. The name can really be anything, but in this case it is following a typical naming convention that indicates the identity store is contained within a file-based XML store.

The credential store is referenced by the name, credstore. The name doesn't indicate what type of store is in use, but because this is an ADF development environment, you can assume it is also file-based, and the configuration will reference a cwallet.sso file. We'll see when we take a closer look at that configuration in a few minutes.

There is no key store configured for this environment so this parameter says <no selection>.

The check box in the Login Modules section indicates that the login module selected for this JPS context is idstore.loginmodule.

Let's take a closer look at the identity store configuration.

 

.

Identity Store Configuration

Click the Identity Store tab to display the configuration for the idstore.xml service instance.

In this case, the graphical display doesn't show the full configuration of the identity store. It tells us that the security realm for this environment is called jazn.com. To see the full configuration, click the Source tab, and find the serviceInstance in the file that looks like the following code snippet.

Hint: You can use the Structure view to easily find elements in the file. Expand the jpsConfig and serviceInstances nodes, and select the next to last serviceInstance which should be the correct element for the idstore.xml instance.

<serviceInstance provider="idstore.xml.provider" name="idstore.xml">
  <property value="./jazn-data.xml" name="location"/>
  <property value="OBFUSCATE" name="jps.xml.idstore.pwd.encoding"/>
  <property value="jazn.com" name="subscriber.name"/>
</serviceInstance>

This shows some more detail regarding the identity store configuration:

Parameter Description
name: The name of this service instance, as referenced by the JPS context
provider: The name of the serviceProvider element that specifies the class that implements this identity store
location: The location of the file-based identity store. In this case, it is a file in the current folder (same location as the jps-config.xml file) called jazn-data.xml. In this scenario, the jazn-data.xml file serves as the identity store and the policy store. More on this later.
jps.xml.idstore.pwd.encoding: This specifies the type of encoding to use for passwords associated with a user's login. This is so that the passwords stored in the jazn-data.xml file cannot be determined simply by opening and reading the file.
subscriber.name: This indicates that the security realm name for this configuration is jazn.com.

Do not worry about examining the jazn-data.xml file at this point. We will cover that in the next section.

Return to the Overview tab for the next step.

 

.

Credential Store Configuration

Click the Credential Store tab to display the configuration for the credstore service instance.

Currently, there is no credential store configured so there is only a location specified. The application does not have a cwallet.sso file associated or packaged within it so there is no credential store. There is also no need for a bootstrap credential store because the identity and policy stores are file-based XML files.

Now let's look at the configuration for Login Modules.

 

.

Login Modules Configuration

Click the Login Modules tab to display the configuration for login modules. Expand the plus sign next to the idstore.loginmodule entry to display the configuration for the idstore.loginmodule service instance.

The parameters in the screen shot are defined below:

Parameter Description
Class Name: Contains the fully-qualified class name that implements the LoginModule. In this case, it is an Oracle internally-defined LoginModule that works with ADF application development.
Login Control Flag: The control flag that indicates how this authentication provider behaves.
Log Level: A set of logging levels that determine how much logging information to output.
Debug: A boolean setting whether or not to allow debugging of the LoginModule code.
Add All Roles: Tells OPSS to add all roles associated with the user to the Subject.
Other Properties: Allows you to configure other properties to pass to the LoginModule.
remove.anonymous.role A property that is used to tell the LoginModule not to remove the anonymous-role from the user's Subject.

Now let's look at how to configure ADF Security.

 

.

Configuring ADF to use OPSS Security

You can use the JDeveloper IDE to configure the type of security your ADF application uses. Right-click the application in the Application Navigator tab, then select Secure > Configure ADF Security.

NOTE: We are not actually changing the setting here, however we did want to show you how this configuration is done.

The Configure ADF Security wizard is displayed. The first screen alows you to choose the Security Model of the application. There are three choices:

  • ADF Authentication and Authorization
  • ADF Authentication
  • Remove ADF Security Configuration

For detailed explanations of each of these selections, click the ADF authentication and authorization link shown on the first wizard page. This opens up the related JDeveloper inline help system. Click Next when ready.

The next step in the wizard allows you to select the authentication type used by the web-based aspect of the application. For detailed explanations of each of these selections, click the authentication type link shown on this wizard page. This opens up the related JDeveloper inline help system on these settings. Click Next when ready.

The next step in the wizard allows you to elect how the application will manage policy grants. For detailed explanations of each of these selections, click the ADF policy grants link shown on this wizard page. This opens up the related JDeveloper inline help system on these settings. Click Next when ready.

The next step in the wizard allows you to select the welcome page for a successfully authenticated user of this application. Leave everything as the default, with nothing configured, and click Next when ready.

The wizard then displays a summary of the configuration selections made up to this point. This screen shows where the ADF, Java EE, WebLogic extensions, and OPSS configuration files are located and where they are packaged within the application. Because ADF security is already configured the way we want it to be, click Cancel to ignore these settings.

You just learned how the jps-config.xml file is configured for an ADF application in JDeveloper. Next, let's look at the OPSS file-based store, jazn-data.xml.

 

Explore the jazn-data.xml File


.

Double-click the jazn-data.xml file in the Application Resources view to open the file in the editor.

Note: Because the jazn-data.xml file is packaged within the OpssADFDemoApp's META-INF folder that the OPSS security store is file-based. As you will see while going through these instructions, this file also serves as the file-based identity store for the application. This makes it easy for ADF developers to quickly create users, groups, and roles to test their applications without the need for running, configuring, or connecting to an LDAP-based identity store. It also serves the same purpose for quickly and easily creating security policies for the application without the need for running, configuring, or connecting to an LDAP or database security store. Everything is self-contained within the application.

When the application is deployed to an OPSS-enabled server, the OPSS security store data will be merged into the OPSS security store configured in the WebLogic domain. Identity store data is not typically merged because user and group data usually changes from environment to environment.

Click the Overview tab to show the graphical representation of the file if it isn't selected already. We will be using this view of the file for the duration of this tutorial. If you like, you can also explore the file using the Source tab, which provides the entire XML source of the file.

You should see a screen similar to the following:

This screen shows the configuration settings of the jazn-data.xml file. This includes: Users, Enterprise Roles (or Groups), Application Roles, Resource Grants, and Entitlement Grants. The default page has Users selected and displayed as shown here. There are two users configured within the file for developing purposes, Jane Doe and John Smith.

First, we will examine the Users tab.

 

.

Users Configuration

The Users tab displays the users configured for the ADF development environment that are defined as part of the jazn.com security realm. This page provides controls to do the following:

  1. Searching for a particular user
  2. Managing users in the identity store
  3. Managing the details of a user in the identity store
  4. Managing the mapping of users to enterprise roles (groups) and application roles

Take a few minutes and explore this page to become familiar with it. Move on to the next step when you are ready.

Now let's look at configuring enterprise roles.

 

.

Enterprise Roles Configuration

Click the Enterprise Roles tab to display the configuration for the enterprise roles configured in the identity store. This page provides controls to do the following:

  1. Searching for a particular enterprise role by name
  2. Managing the enterprise roles in the identity store
  3. Managing the details of enterprise roles in the identity store
  4. Managing the mapping of users to enterprise roles (groups) and application roles

Take a few minutes and explore this page to become familiar with it, and answer the following questions:

  • Which users and groups are mapped to the employees enterprise role?
  • Are there any application roles assigned to the employees enterprise role? If so, what are they?
  • Which users and groups are mapped to the supervisors enterprise role?
  • Are there any application roles assigned to the supervisors enterprise role? If so, what are they?

Now let's look at configuring application roles.

 

.

Application Roles Configuration

Click the Application Roles tab to display the configuration for the application roles configured in the OPSS security store. This page provides controls to do the following:

  1. Searching for a particular application role by name
  2. Managing the application roles in the OPSS security store
  3. Specifying which application configured application roles are scoped to
  4. Managing the details of application roles in the OPSS security store
  5. Managing the mapping of users to application roles, and viewing permission grants assigned to application roles

Note that in the screen shot below the Manager role has already been expanded to show that the Developer role is a child role. This is an example of an application role hierarchy. Policies created for the Manager role automatically apply to the Developer role as well.

Take a few minutes and explore this page to become familiar with it, and answer the following questions:

  • Are there any users or roles mapped to the anonymous-role? Why or why not?
  • Are there any users or roles mapped to the authenticated-role? Why or why not?
  • What permission is granted to the authenticated-role?
  • Are there any users or roles mapped to the Manager application role? If so, what are they?
  • Are there any users or roles mapped to the Developer application role? If so, what are they?
  • Do the Manager or Developer roles have any permissions granted to them?

Answers:

  • There are no users or  roles mapped to the anonymous-role. This role is not assigned to users manually. Instead, it is added to the user's Subject when they are accessing aspects of the application that do not require a login, and they have not logged in yet.
  • There are no users or roles mapped to the authenticated-role. This role is not assigned to users manually. Instead, it is added to the user's Subject after successfully logging into the system.
  • Yes, the authenticated-role is granted view privileges for the ADF Task Flow called taskFlowCall1. This is seen by clicking the authenticated-role entry, and clicking the Grants tab on the right-hand side of the page.
  • Yes, the supervisors enterprise role is mapped to the Manager application role. Also, the employees enterprise role is mapped to the Manager application role because the employees enterprise role is mapped to the supervisors enterprise role. This cannot be seen directly in this tab, but if you refer back to the supervisors enterprise role in the Enterprise Roles tab, you can see that employees is mapped to the supervisors enterprise role.
  • Yes, the employees enterprise role is mapped to the Developer application role.
  • This is a trick question. The answer is yes and no. No, neither role has a permission grant directly configured for it. However, if a user is in either the Manager or Developer role, then they must have successfully logged into the system. This means that users that are members of both application roles would implicitly be granted view privileges to taskFlowCall1 because they would also be in the authenticated-role application role. The permisson granted to the authenticated-role would apply to these users.

Now let's look at configuring resource grants.

 

.

Resource Grants Configuration

Click the Resource Grants tab to display the configuration for the policies configured in the OPSS security store that grant access to application resources. This page provides controls to do the following:

  1. Specifying which application configured resource grants are scoped to
  2. Linking to the JDeveloper help system for Security Best Practices to consider when using this page
  3. Specifying the Resource Type and Source Project the grant applies to
  4. Specifying whether only task flows with test-all grants or task flows from imported ADF libraries should be displayed
  5. Searching for a particular resource by name
  6. Managing the resources in the OPSS security store
  7. Managing the grantees of the resource grant, such as application roles, users, enterprise roles, or code sources
  8. Managing the actions (or privileges) that will be granted as part of this policy

This is where the policy for granting view privileges to the taskFlowCall1 task flow for all users in the authenticated-role is defined. If the policy, or resource grant, is not visible, click the icon to show all the resources that have grants configured.

Take a few minutes and explore this page to become familiar with it, then continue with this step.

JDeveloper is aware that this is an ADF application, and the graphical view of the jazn-data.xml file has an ADF focus. The resource types available out-of-the-box are Task Flow and Web Page. When one of these resource types is selected, the view shows the available ADF application resources of that resource type so that you can configure security policies for them. Just as you are able to see the resource grant for the taskFlowCall1 resource, you can change the resource type to Web Page, which causes the web pages of the ADF application to be displayed, as shown in the screen shot below. What can also be seen is that none of the web pages in this application have any policies defined for them.

Select Web Page as the Resource Type and select each of the web page resources listed to see that there are no policy authorization grants.

The source project for this screen is currently set to ViewController. You could click the search icon next to Source Project to add the Model source project to the filter to cause all of its resources to display in the list. However, there is no source of any kind in the Model project so this would be a waste of time at the moment.

You can also create a resource type of your own by clicking the icon next to the Resource Type drop down list box. However, any resource instances created and derived using this new resource type will have to include an API call within the code to enforce any policies granted to the custom resource because they are unknown to ADF.

Although you will not use it for anything, let's create a new resource type:

  • Click the add icon next to the Resource Type drop down list box.
  • The Create Resource Type window appears.
  • Enter MyResourceType as the name.
  • Leave the Display Name blank.
  • Leave the Matcher Class as the default, which is oracle.security.jps.ResourcePermission.
  • Leave the Description blank.
  • Using the add button in the Actions pane, add a couple of actions called view, update, and delete.
  • Click OK to finish creating the resource type.
  • Verify resource type created. You should now see that there is a new resource type choice in the drop down list box that has the same name as your new resource type.
  • Note that resource types are not actual resources that can be protected by OPSS, but are more like a template from which a resource instance is derived. The resource instance is what can be protected by OPSS. You may also notice that no matter what settings you use in the Resource Grants page, no resources that match your resource type are displayed. This is because your resource type is not a recognized ADF resource type. This is made apparent by seeing that the Source Project filter now displays <Not Applicable>. This means that for this resource type, you need to create your own resources, and to enforce authorization for these resources you must use OPSS APIs in your application code. This is the same way non-ADF OPSS-enabled Java EE applications would work.

    Now, let's create a new resource instance:

  • Click the add icon in the Resources pane.
  • The Create Resource window appears.
  • Enter MyResourceInstance as the name.
  • Leave the Display Name blank.
  • Leave the Description blank.
  • Click OK to finish creating the resource instance.
  • Verify resource instance created. You should now see that there is a new resource displayed in the Resources pane.
  • So now you have created a resource instance. Next, you need to create a resource grant to allow certain users to perform certain privileges on the resource.

    Now, let's create a new resource grant:

  • Click the add icon in the Granted To pane, and select Add Application Role .
  • The Create Application Roles window appears.
  • Select Developer as the role.
  • Click OK to finish selecting roles for this grant.
  • Verify that the grant is created. You should now see that the Developer role is the grantee for this resource displayed in the Granted To pane. You should also see that the Actions pane is now populated with the actions you created for this resource type. Now you need to select which action, or actions, you want to grant to the Developer role.
  • Select all three actions to grant the Developer role access to all privileges for your new resource.
  • Now that you have created a new resource type, created a resource instance based on that type, and created a resource grant that allows the Developer role access to view, update, and delete privileges on this resource; you can view the source of the jazn-data.xml file to see what this configuration looks like.
  • Click the Source tab to view the XML source for the file.
  • Locate the XML elements: <resource-type>, <resource>, and the <grant> stanza within <jazn-policy> that contains the resource grant you just created. Your XML should look similar to the following:
  • <resource-types>
     <resource-type>
      <name>MyResourceType</name>
      <matcher-class>oracle.security.jps.ResourcePermission</matcher-class>
      <actions-delimiter>,</actions-delimiter>
      <actions>view,update,delete</actions>
     </resource-type>
    </resource-types>
    <resources>
     <resource>
      <name>MyResourceInstance</name>
      <type-name-ref>MyResourceType</type-name-ref>
     </resource>
    </resources>
    <jazn-policy>
     ...
     <grant>
      <grantee>
       <principals>
        <principal>
         <name>Developer</name>
         <class>oracle.security.jps.service.policystore.ApplicationRole</class>
        </principal>
       </principals>
      </grantee>
      <permissions>
       <permission>
        <class>oracle.security.jps.ResourcePermission</class>
        <name>resourceType=MyResourceType,resourceName=MyResourceInstance</name>
        <actions>delete,update,view</actions>
       </permission>
      </permissions>
     </grant>
    </jazn-policy>

  • Because this is not a developer course you do not have to retain this configuration. This was just shown to provide an example of how to configure resource types, resource instances, their associated actions, and configure authorization policy grants using these artifacts. You can delete this configuration from the file prior to moving on to the next step.

Now let's look at configuring entitlement grants.

 

.

Entitlement Grants Configuration

Click the Entitlement Grants tab to display the configuration for the policies configured in the OPSS security store that grant access to application resources. This page provides controls to do the following:

  1. Specifying which application configured entitlement grants are scoped to
  2. Linking to the JDeveloper help system for Security Best Practices to consider when using this page
  3. Specifying the entitlements that are configured within the policy store
  4. Display information for a selected enititlement
  5. Tabs for switching between the resources and grants included in this entitlement
  6. Managing the resources included in the entitlement. If the Grants tab was selected, then this would allow for managing the grantees of the entitlement grant, such as application roles, users, enterprise roles, or code sources
  7. Managing the actions (or privileges) that will be granted as part of this policy

This application currently does not use any entitlements. This page is here just to show you where to find the entitlements configuration tool. If desired, you can click the plus icon in the Entitlements section to try to create an entitlement of your own.

 

Summary

You have now completed Exploring the OpssADFDemoApp in JDeveloper OBE.

In this tutorial, you have learned how to:

Resources

Credits

Hardware and Software Engineered to Work Together Copyright © 2012, Oracle and/or its affiliates. All rights reserved