by Ganesh Kamble
Downloads:
Overview
The idea for this article came to me because Oracle's next-generation banking product—Oracle Banking Platform (OBP) (version 2.2)—uses the Oracle Internet Directory (OID) as the centralized location for storing all the access policies and identities. I worked on integrating the OBP and externalizing the security by the means of Oracle Entitlements Server (OES), which used OID as both policy store and identity store.
This article discusses how you can use OES to secure the resources of Oracle Application Development Framework (ADF) applications. OES can use OID, Oracle Unified Directory (OUD), Oracle Database or Apache Derby Database as the policy store. Here we will use OID to store all the policies that we are going to create for securing an ADF application.
Oracle Entitlements Server (OES)
OES provides a comprehensive and centralized solution for managing access policies. It is an externalized, fine-grained authorization service granting or denying access to a resource based on the authorization request context. Protected resources can be deployed on-premise or in the cloud. It enforces controls on all types of resources: software components (URLs, servlets, Java Server Pages (JSPs), Enterprise JavaBeans (EJBs), business objects (e.g., patient records in a health care application), or anything used to define a business relationship. It is used with more than 50 different Oracle Fusion Middleware and Applications components and services.
OES supports the management of authorization policies and role mapping policies:
- Authorization Policy: Defines access to a protected resource or business object. It is formed by a combination of a resource (which is to be protected), subject (an entity to which access is granted or denied), operation (which can be done on the resource), access effect (grant or deny) and, optionally, condition (under what criteria the access is to be granted or denied).
- Role Mapping Policy: Defines the mapping between application roles in the policy store and enterprise roles (also called groups) in the identity store. It can also map users to roles.
OES supports the extensible Access Control Markup Language (XACML) request/response protocol for attribute-based authorization operations. Here are the various phases involved in the management of authorization policies:
- Policy Administration Point (PAP): Used to create and manage authorization policies. OES provides an administration console based on rich web-based UI for access policy management. Access to PAP can also be achieved by authorization management application programming interfaces (API) and the WebLogic Scripting Tool (WLST).
- Policy Decision Point (PDP): At runtime, PDP receives a request for authorization and evaluates it based on application policies that are created at PAP.
- Policy Enforcement Point (PEP): Once the PDP evaluates the result based on the configured authorization policies, PEP enforces the grant or deny decision. It also makes the call to PDP to send the authorization requests.
- Policy Information Point (PIP): The data repository in which all the access policies are maintained, it provides the information that is used when evaluating policies for authorization decision.
Oracle Internet Directory (OID)
OID is a Lightweight Directory Access Protocol (LDAP) version 3 general purpose directory service that provides fast retrieval and centralized management of information about users and resources. It runs as an application on an Oracle Database and provides such features as high performance, scalability, robustness, security and availability. It is predominantly used to support Oracle enterprise applications.
One of the key features of OID is the providsion of seamless integration with other Oracle products. WebLogic Server (WLS) uses embedded LDAP to manage users and groups using Oracle Platform Security Services (OPSS). Using the OID authenticator, the identity store data can be used for authentication. By default, WebLogic stores policy data and credentials in file-based stores.
Oracle Application Development Framework (ADF)
ADF is a mature Java Enterprise Edition (EE) development framework built on top of a Model View Controller (MVC)-based Java Server Faces (JSF) framework. It provides unified access to back-end technologies such as databases, web services, XML, Comma Separated Value (CSV), Business Process Execution Language (BPEL), etc. It is suitable for enterprise developers who want to create applications that perform operations with data using web, mobile and desktop interfaces. ADF Model, Faces and Controller form the Model (M), View (V) and Controller (C) parts of the MVC architecture, respectively.
ADF Security
The ADF Security framework uses and extends the OPSS framework to simplify the securing of ADF applications, and enables fine-grained access control to protect ADF resources (e.g., jsff pages, taskflows, etc.).
Case
OPSS, which comes as an independent portable set of libraries with Oracle WLS, provides a platform for managing the security of an ADF application. It has a mechanism to apply security on ADF pages and taskflows without adding any custom logic. You can control which actions are allowed on a particular resource (e.g., on a page or a taskflow, we can configure actions such view, update, delete, etc.).
File-Based Policy and Identity Store
The default configurations of policies and identities in an ADF application are stored in a file-based policy and identity store as a system-jazn-data.xml file. Typically, this file can be found at <JDEV_SYSTEM_FOLDER>/DefaultDomain/config/fmwconfig. Figure 1, below, shows the file in JDeveloper. It allows you to configure Users, Enterprise Roles, Application Roles, Resource Grants and Entitlements Grants.
Figure 1
When an application with the file-based policy and identity store is deployed on WLS, the OPSS framework evaluates the access to a particular resource based on this file. The identity data from this file is published in the embedded LDAP of the WLS, which is again a file-based identity store.
LDAP-Based Policy and Identity Store
In this article, I am going to show you how you can use the OID-based policy store, which will be managed by the OES. We will not store any policies or roles or users in the system-jazn-data.xml file. We will be using a simple ADF application with the name “MyBank”; four of its five pages can be accessed from the main page. The policies governing this access will be managed in OID using OES.
Figure 2, below, shows the basic architecture of what we are going to develop in the following sections. The WLS of the MyBank application and the OES are associated with the OID server. The ADF application makes use of the OID identity store and policy store to decide which users can access it. The access policies needed for the decision are managed by the OES. The users for authentication are retrieved from the identity store, whereas the authorization engine calls the policy store at runtime to decide what the authenticated user can access.
The most important aspect of this solution is that the security of your application is completely externalized—you need not make any changes to your application or deploy it again when you wish to modify the existing security policy. Simply change some policies in the OES and the application will respond to the changes immediately, or after a certain time if you have configured a caching mechanism.
Figure 2
Setting Up the Environment
To manage and access the resources effectively to and from the OID, we need to integrate all three environments, as shown in Figure 2. This involves integrating the WLS of the OES and of the ADF application with the OID identity and policy store.
Identity Store Configuration
OID Authenticator is used to access the user and group information stored in the OID. This authenticator can be configured in the WLS administration console. We will configure it on the OES server as well as the server on which the ADF application is deployed. Follow these steps for the configuration:
- Log in to the WLS administration console.
- Select Security Realm in the Domain Structure in the left pane > myrealm.
- Select the Providers tab and click on New to add a new authentication provider.
- Enter a suitable Name for the provider and select the Type as OracleInternetDirectoryAuthenticator. Click OK.
Figure 3
- Select the authentication provider that you created in the previous step. Change the control flag to SUFFICIENT. Click on the Provider Specific tab. Provide the details of the OID server (e.g., Host, Port, Bind credentials, User and Group base DN, etc.).
- Change the control flag of DefaultAuthenticator to OPTIONAL.
- Save the changes and restart both the servers.
Policy Store Configuration
To migrate the policy store from file-based to LDAP-based, we must reassociate the WLS with the LDAP; this means you can create/join a node in the LDAP server that serves as the policy store for your server. This step ensures that both the WLS (OES and the MyBank application) are referring to the same policy store in the OID. This operation basically sets the domain to use the OID policy store instead of the file-based policy store, and the domain must be configured as appropriate to use the OID policy store. The reassociation can be achieved in two ways:
-
Using Enterprise Manager Fusion Middleware Control: Enterprise Manager Fusion Middleware Control provides a user-friendly way of reassociation. Select the Security Provider Configuration as shown in Figure 4, below.
Figure 4
Click on the Change Store Type button under Policy and Credential Store Providers. Select the Oracle Internet Directory as the Store Type. Enter all the mandatory OID details and Click OK.
-
Using the reassociateSecurityStore WLST command: The WLST command reassociateSecurityStore can be used to perform the task of reassociating the WLS with the OID. It needs to be run from <MW_HOME>/oracle_common/common/bin/wlst.sh or <MW_HOME>/oracle_common/common/bin/wlst.bat.
The syntax of the command is:
reassociateSecurityStore(domain="myDomain", admin="cn=adminName", password="myPass", ldapurl="ldap://myhost.example.com:3060", servertype="OID", jpsroot="cn=jpsroot")
If you want another domain to share the policy store in myDomain, you will need to use join=true in the command, as shown below:
reassociateSecurityStore(domain="myDomain", admin="cn=adminName", password="myPass", ldapurl="ldap://myhost.example.com:3060", servertype="OID", jpsroot="cn=jpsroot", join=”true”)
If you are reassociating the first WLS and you do not want to share the policy store, you must run the command without join=true. However, during the reassociation of the second WLS, you must include join=true in the command.
To verify if the WLS domain is configured properly, you can check the jps-config.xml file, which is present at <MW_HOME>/user_projects/domains/bpp_domain/config/fmwconfig/jps-config.xml. In the default jpsContext node, you can find the following entries:
<jpsContext name="default">
<serviceInstanceRef ref="credstore.ldap"/>
<serviceInstanceRef ref="keystore.ldap"/>
<serviceInstanceRef ref="policystore.ldap"/>
<serviceInstanceRef ref="audit.ldap"/>
<serviceInstanceRef ref="trust"/>
<serviceInstanceRef ref="pdp.service"/>
<serviceInstanceRef ref="attribute"/>
<serviceInstanceRef ref="idstore.ldap"/>
</jpsContext>
Notice the .ldap extension. This indicates that the instances will refer to the LDAP. In a non-reassociated WLS jps-config.xml file, you will find .xml extensions.
Use ODSM to View Changes in OID
Use the ODSM interface to manage the entries in OID, Oracle Virtual Directory (OVD) and OUD; it lets you add, delete, update, configure users and groups and other entries in the directory. Once the WLS is reassociated, you can view the changes in OID using an LDAP browser (such as JXplorer) or ODSM. In Figure 5, below, you can see that the bpp_domain is created in OID under cn=JPSContext,cn=jpsroot. Your structure might be somewhat different, based on the applications you have deployed on the servers.
Figure 5
Identify Resources in MyBank ADF Application
We need to identify all the resources that are to be secured, but we need not write any custom logic to apply security on ADF pages and taskflows. The rendering of ADF pages and taskflows in an ADF application is based on the pageDef of the jsff or jspx page, and the taskflow id of the taskflow, respectively. Let's say that, in our application, we have five different pages to protect, as follows:
com.inventec.oes.view.mainPageDefcom.inventec.oes.view.accountsPageDefcom.inventec.oes.view.creditcardsPageDefcom.inventec.oes.view.dashboardPageDefcom.inventec.oes.view.preferencesPageDef
MyBank Application Creation in OES
OES provides a rich web UI framework in the form of the administration console – the Authorization Policy Manager (APM) – to manage the application policies. APM is a browser-based, graphical interface for managing policies and related security objects. It supports the creation and management of authorization policies and role mapping policies. (An authorization policy defines the rules for accessing a software component or business object, and a role mapping policy defines which users are assigned which roles, and may be referenced by an authorization policy.)
You can log in to the application by clicking <IP>:<PORT>/apm in the URL. Create a new application with a suitable name, the same name you will use across your ADF application.
Figure 6
Figure 6 shows that the MyBank application is created in the OES and, since this server is reassociated with the OID, an application with the same name gets created in the OID under the reassociated domain node as shown in Figure 7, below. It will have several nodes in the hierarchical structure, including Resources, Resource Types, Roles, Policies, etc.
Figure 7
ResourceType and Resource Creation
To create the resources in the OES, we first need to create ResourceType, which is used to identify the different types of resources such as Page, TaskFlow or any other custom type. In the MyBank application, we have identified five pages. Let's say we will use Page as the ResourceType for them. The allowed action for Page is View.
Note the Evaluation Logic and Permission Class in Figure 8, below. ADF checks the permissions of pageDefs by using the class oracle.adf.share.security.authorization.RegionPermission. If we want to protect the TaskFlows, we will need to use oracle.adf.controller.security.TaskFlowPermission during the ResourceType creation.
Figure 8
Now let's create the resources that we identified in the previous section. Figure 9, below, shows that the five resources are created with Page as the ResourceType. Note: the name of the resource must be the same as the name of the pageDefs in MyBank application.
Figure 9
Users and Groups
For simplicity and better understanding, we will limit the number of groups and application roles to four. OPSS provides many-to-many mapping and evaluates logically the best possible result. Users are mapped to enterprise roles with many-to-many mappings, whereas enterprise roles and application roles have one-to-one mapping.
Figure 10
Application Role Creation
Each of the four MyBank application roles—CreditCardsAppRole, DashboardAppRole, AccountsAppRole, PreferencesAppRole—protects its own module pages plus the main page.
For example, CreditCardsAppRole will have permission to view the Main Page and Credit Cards Page; DashboardAppRole will have permission to view the Main Page and Dashboard Page, and so on.
Figure 11
Enterprise Role and User Creation
Oracle DSM can be used to create enterprise roles in OID. You can also create an LDIF file containing the details of the enterprise roles and users and run it using ldapadd. Figure 12, below, shows that AccountsEntRole is mapped to the users (Members) accountsuser and weblogic.
Figure 12
Role Mapping
The Role Catalog in OES lets you map enterprise roles to application roles. Here, we will map CreditCardsAppRole, DashboardAppRole, AccountsAppRole and PreferencesAppRole to CreditCardsEntRole, DashboardEntRole, AccountsEntRole and PreferencesEntRole, respectively, which will effectively achieve the configuration of Figure 10, above. Figure 13, below, shows that AccountsAppRole is mapped to AccountsEntRole.
Figure 13
Authorization Policy Creation
Figure 14, below, shows how to configure the authorization policy in OES. Principals include the application roles, enterprise roles and the users to whom you want to grant the resource. Target is the name of the resource with the allowed action. Because we are creating a Grant policy, the Effect is Permit. Basically, this policy says that users belonging to CreditCardsEntRole, which is mapped to CreditCardsAppRole, are allowed to view the CreditCardsPage. You can create similar policies for other pages and application roles.
Figure 14
MyBank has the policies shown in Figure 15, below. Main Policy contains multiple Principals because it can be accessed by the users of all roles.
Figure 15
You can also use ODSM to view the changes reflected in the OID policy store:
Figure 16
At this point, we have the access control framework in place. We have configured the ResourceTypes, Resources, Application Roles, Enterprise Roles and Policies. Now we need to configure the MyBank application to point to this policy store in OID. We have already reassociated WLS to use OID as the policy store.
MyBank Application Changes
The ADF application needs to be configured to use OPSS. Click on Configure ADF Security as shown in Figure 17, below, to generate all the descriptors required for Java Authentication and Authorization Service(JAAS).
Figure 17
Once the basic ADF security structure is configured, we can proceed with making changes to the application files:
- web.xml
The application name (application.name) is mentioned in JpsFilter in web.xml as follows:
<filter>
\<filter-name>JpsFilter\</filter-name>
\<filter-class>oracle.security.jps.ee.http.JpsFilter\</filter-class>
\<init-param>
\<param-name>application.name\</param-name>
\<param-value>MyBank\</param-value>
\</init-param>
\<init-param>
\<param-name>enable.anonymous\</param-name>
\<param-value>true\</param-value>
\</init-param>
\<init-param>
\<param-name>remove.anonymous.role\</param-name>
\<param-value>false\</param-value>
\</init-param>
</filter>
The url-pattern to be protected is to be added in security-constraint:
<security-constraint>
\<web-resource-collection>
\<web-resource-name>adfAuthentication\</web-resource-name>
\<url-pattern>/adfAuthentication\</url-pattern>
\<url-pattern>/faces/\*\</url-pattern>
\</web-resource-collection>
\<auth-constraint>
\<role-name>valid-users\</role-name>
\</auth-constraint>
</security-constraint>
- weblogic-application.xml
The migration of application policies at deployment is controlled by the parameters in META-INF/weblogic-application.xml. We will set the parameters jps.policystore.removal and jps.policystore.migration to “false” because we neither intend to delete the policy store from OID nor migrate the policies from the file-based store (system-jazn-data.xml) to OID during the deployment process. The parameter jps.policystore.applicationid holds the name of the application.
<application-param>
<param-name>jps.policystore.removal</param-name>
\<param-value>OFF\</param-value>
</application-param>
<application-param>
\<param-name>jps.policystore.migration\</param-name>
\<param-value>OFF\</param-value>
</application-param>
<application-param>
\<param-name>jps.policystore.applicationid\</param-name>
\<param-value>MyBank\</param-value>
</application-param>
- adf-config.xml
The hooks to enable authentication and authorization are maintained in the adf-config.xml file and are identified by the authenticationRequire and authorizationEnforce flags, respectively. You can turn off the security of your application with the help of these two flags.
<adf-security-child xmlns="http://xmlns.oracle.com/adf/security/config"> <JaasSecurityContext initialContextFactoryClass="oracle.adf.share.security.JAASInitial ContextFactory" jaasProviderClass="oracle.adf.share.security.providers.jps.JpsSecurityContext" authorizationEnforce="true" authenticationRequire="true"/> </adf-security-child>
Deployment
Once these changes are made, you can deploy the application. JpsFilter intercepts the requests coming from the browser and checks whether they need authentication and authorization. For the first login, the login page would be displayed. Once the user is authenticated, user Subject is formed based on the users and groups obtained from the authentication provider that we configured in the identity store configuration step. OPSS uses this subject and makes calls to the OID policy store to determine the access on the page which is to be rendered in the browser. If the appropriate policy is present in the policy store protecting the requested resource against the roles present in the Subject, ADF will render the page in the browser.
As per the access policy configurations that we have made in OES, users belonging to CreditCardsEntRole, DashboardEntRole, AccountsEntRole and PreferencesEntRole can access com.inventec.oes.view.creditcardsPageDef, com.inventec.oes.view.dashboardPageDef, com.inventec.oes.view.accountsPageDef, and com.inventec.oes.view.preferencesPageDef pages, respectively. All these users will have access to com.inventec.oes.view.mainPageDef.
Diagnostics
If there is no policy on the requested page or taskflow and you try to access it in a browser, you will get Error 403—Forbidden. You can find out if there are any errors in the server log files, such as diagnostic logs, which are typically found at: <MW_HOME>/user_projects/domains/app_domain/servers/AdminServer/logs.
By default, the logging of access checks is not enabled. To enable it, we need to set the JAVA_OPTIONS in setDomainEnv.sh (Unix) or setDomainEnv.bat (Windows).
-Djava.security.debug=access,failure -Dweblogic.Stderr=/scratch/mydomain/logs/stderr.log
It will log all the access checks that are made by your application and might significantly impact performance. In production mode, you should never have this logging enabled.
Summary
Externalizing authentication and authorization means that security can be managed by administrators and not developers. When security rules change, no modifications are required to the application, but only to the security rules attached to the application. OES can be used to manage the access policies governing the security of an application's resources. OID provides a highly scalable and secure identity and policy store that can be easily integrated with several Oracle products. With the help of OPSS, ADF applications can make use of JAAS in externalizing and enforcing security with reliable WebLogic framework.
Resources:
About the Author
Ganesh Kamble is an expert in Java and Oracle Fusion Middleware, including SOA, BPM, and ADF. He specializes in Oracle Identity and Access Management High Availability Implementation, including Oracle Access Manager, Oracle Identity Manager, Oracle Internet Directory, Oracle Unified Directory, Oracle Identity Federation.
NOTE: This article has been reviewed by the relevant Oracle product team and found to be in compliance with standards and practices for the use of Oracle products.