18 Integrating Java EE Application Security with OPSS

This chapter provides the starting material for application developers looking to integrate their Java EE applications with security components in OPSS. It explains the guidelines to follow to integrate required components, and it also outlines those to follow to integrate advanced, optional security features.

This chapter is not a comprehensive guide on identity management technologies but a departing point for developers to get acquainted with security integration tasks.

It contains the following sections:

18.1 Introduction

The goal of this chapter is to get developers and application architects acquainted with the various tasks required to integrate application security with OPSS.

OPSS provides an abstraction layer in the form of standard application programming interfaces (APIs) that insulate developers from security and identity management implementation details. Integrating application security with OPPS provides applications with a uniform way to implement security, identity management, and audit services across an enterprise.

For a complete list and links to all available APIs, see Appendix H, "References."

18.2 Terminology

This section defines most of the acronyms used in this chapter. Some of them have been introduced elsewhere in this guide, but they are included here for the sake of completeness.

Identity and Access Management (IAM)

IAM is a set of tools, processes, and best practices to manage user identities and their access to resources.

Oracle Application Development Framework (ADF)

ADF is a comprehensive Java EE development framework integrated with the Oracle JDeveloper development environment. ADF greatly simplifies Java EE development and minimizes the need to write code by providing application infrastructure as part of the framework.

Being also integrated with Oracle Fusion Middleware Security, ADF allow developers to implement security concepts using a declarative approach.

Oracle Access Manager (OAM)

OAM provides a full range of Web access security management functions including Web single sign-on, user self-service, and self-registration.

Oracle Adaptive Access Manager (OAAM)

OAAM secures access to Web resources through strong multi-factor authentication and real-time fraud prevention.

Oracle Authorization Policy Manager (OAPM)

OAPM is graphical interface tool to provision and administer security application artifacts.

Oracle Enterprise Manager (OID)

OID provides an LDAP-based directory for the storage of identity, policies, and business-related data.

Oracle Enterprise Manager (OEM)

OEM is the central tool to manage Oracle applications.

Oracle Identity Manager (OIM)

OIM is a user provisioning and administration tool that facilitates adding, updating, and deleting user accounts from enterprise applications.

Oracle Security Developer Tools (OSDT)

OSDT provides the cryptographic building blocks necessary to develop secure applications. It includes secure messaging and the implementation of a secured service-oriented architecture.

OPSS Subject

An OPSS subject is a collection of principals and, possibly, user credentials (such as passwords or cryptographic keys). The Oracle WebLogic Server authentication populates the OPSS subject with principals, that is, with users and groups, and application roles.

Oracle Web Services Manager (OWSM)

OWSM is a tool to secure, manage, and deploy SOAP-based applications, that is, built on service-oriented architectures.

Oracle Wallet (OW)

OW stores credentials such as certificates, trusted certificates, certificate requests and private keys.

Web Services Security (WSS)

WSS provides authentication, authorization, confidentiality, privacy, and integrity among SOAP-based applications.

Web Single Sign-On (Web-SSO)

Web-SSO allows users access to multiple Web applications by being authenticated just once.

18.3 Oracle Identity and Access Management Suite

The Oracle IAM suite of products is designed to support heterogeneous, multiple-vendor developments and run-time environments, including operating systems, Web servers, application servers, and database management systems.

The products in the suite and their support of key areas of application security are described in the following sections:

For a detail list of required OPSS security features when integrating security with OPSS, see Required Security Features.

18.3.1 OID for Identity and Policy Stores

Applications use OID to store user identities, identity profiles, roles, policies, and credentials.

18.3.2 OAM and OSSO for User Authentication and Web SSO

It is critical that user identities be established correctly and securely in environments that allow users access to applications. Once a user identity has been established, he must be able to sign on to other enterprise applications without being prompted.

OAM provides user authentication and Web SSO services and hides single sign-on implementation details from applications. Oracle offers two single sing-on solutions: OAM and OSSO.

For details, see Part IV, "Single Sign-On Configuration"

18.3.3 OIM for User and Role Provisioning

Managing users is an on-going activity that requires externalizing some amount of user information typically kept in a central repository. OIM exposes SPML, an interface to provision users and roles, manage user and role profiles, and change user passwords.

Applications are expected to use the SPML interface for all write and update operations on users and roles.

18.3.4 OPSS for User and Role Profiling

OPSS exposes the User and Role API, a standard, privacy-enabled interface to read identity and role data without having to open explicit connections to the underlying data repositories.

For details, see Chapter 25, "Developing with the User and Role API."

18.3.5 OPSS for User Authorization

OPSS provides a scalable, extensible, role-based authorization framework that allows applications to specify and control their security artifacts, including entitlements, roles, and grants. The application defines security policies (stored in the policy store) that are enforced at runtime by the authorization engine.

For details, see Chapter 23, "Authorization for Java SE Applications."

18.3.6 OAPM for Application Policy Management

OAPM is used to manage security artifacts once the application has been deployed. Working with OPSS, OAPM facilitates many administration tasks, such as managing entitlements and roles, and mapping application roles to enterprise groups.

18.3.7 OPSS for Cryptography

OPSS provides other security services, including the Credential Store Framework for storing application credentials, cryptographic toolkits for message confidentiality, a toolkit to manage keys, and the audit framework for security auditing.

For a complete list of developer tool APIs, see Appendix H, "References."

18.4 Security Life Cycle of an Application

This section introduces the phases of the security life cycle of an application. It is assumed that the application uses ADF and that it is developed in the Oracle JDeveloper environment.

The phases of the security life cycle of an application are the development phase, the deployment phase, and the management phase. The participants are the product manager or application architect, application developers, and application security administrators. For a summary of tasks, see Summary of Tasks per Participant per Phase.

18.4.1 Development Phase

In the development phase developers design the application to work with the full range of security options available in Oracle Fusion Middleware. Developers have access to a rich set of security services exposed by Oracle JDeveloper, the built-in ADF framework, and the Oracle WebLogic Server. All these components are based on OPSS, which ensures a consistent approach to security throughout the application's life span.

Typically, a developer uses the ADF Security Wizard, an authorization editor, and an expression language editor, all within Oracle JDeveloper; additionally, he uses OPSS APIs to achieve more complex security tasks. Thus, some parts of the application use declarative security, other use programmatic security, and they both rely on security features available in the development and run-time environment.

Application developers also define policy seed data (application entitlements and roles) according to the application's security requirements, which is kept in a source control system together with application source code.

18.4.2 Deployment Phase

Once completed, an application is typically tested in a staging environment before being deployed to a production environment. In a production environment, both the application and the run-time services are integrated with other security components, such as user directories, single sign-on systems, user provisioning systems, and auditing. The security services usually change with the phase: for example, during development, a developer relies on a file or Oracle Wallet to store user credentials, but, in a production environment, credentials are stored in an LDAP directory.

In the deployment phase, typically, an administrator migrates the policy seed data to the production policy store, and maps application roles to enterprise groups to effect application security policies.

18.4.3 Management Phase

The management phase starts once an application has been deployed to a production environment. In this phase, application administrators or enterprise security administrators manage day-to-day security tasks, such as granting users access to application resources, reviewing audit logs, responding to security incidents, and applying security patches.

18.4.4 Summary of Tasks per Participant per Phase

The following tables summarize the major responsibilities per participant in each of the security life cycle phases.

Table 18-1 Security Tasks for the Application Architect

Phase Task


Defines high-level application roles based on functional security and data security requirements.

Populates the initial file-based application policy store (jazn-data.xml).


Defines real-world customer scenarios to be tested by the QA team.


Understands and identifies the requirements to customize application policies.

Considers defining templates for vertical industries.

Table 18-2 Security Tasks for the Application Developer

Phase Task


Uses tools and processes, specifically Oracle JDeveloper, to build the application and to create security artifacts, such as application roles and permissions.

Uses FND Grants to specify data-level security.

Tests the application using a local policy store with sample users and roles.


Assists the QA team to troubleshoot and resolve runtime issues.

Table 18-3 Security Tasks for the Application Security Administrator

Phase Task


Uses deployment services to migrate security seed data in jazn-data.xml to the production policy store.

Maps application roles to enterprise groups so that security policies can be enforced.


Applies patches and upgrades software, as necessary.

Manages users and roles, as enterprise users and the application role hierarchy changes overtime.

Manages policies packed with the application and creates new ones.

Integrates with and manages the IAM infrastructure.

18.5 Getting Started with Application Security Integration

Application security defines and enforces users' access to application resources. Access to resources vary depending on the level of risk associated with those resources. Thus, developers must secure application resources against unauthorized use by designing and implementing a robust security and identity model.

Oracle Fusion Middleware prescribes a number of tools and procedures for defining and implementing such a model. The security low-level details are hidden from application developers because they use pre-integrated frameworks that enable both declarative and programmatic approaches.

18.5.1 Oracle Platform Security Services

OPSS provides an abstraction layer in the form of standard application programming APIs that insulate developers from security implementation details. For example, when using OPSS, developers need not be concerned with low-level details of cryptographic key management, or interfacing with user repositories and identity management infrastructures.

Application developers use ADF declarative security in Oracle JDeveloper to integrate with OPSS, so that, in the development phase, OPSS services can be invoked directly from Oracle JDeveloper through wizards, and later on, in the deployment phase, systems and security administrators can configure OPSS services using OEM or command-line tools.

OPSS also includes OSDT, a set of Java-based cryptographic libraries supporting XML signature, XML encryption, XML Key Management Specification (XKMS), SAML, WS-Security, and other non-XML standards such as Secure/Multipurpose Internet Mail Extensions (S/MIME) and Online Certificate Status Protocol (OCSP).

18.5.2 Use Case 1 - Java EE Application

The ezshare application, an example of Java EE application whose security has been integrated with OPSS and that uses permission-based grants, is available by clicking Sample Application in the Resources area of the following page: http://www.oracle.com/technology/products/id_mgmt/opss/index.html.

18.6 Required Security Features

This section describes the features that an application integrating with OPSS must implement. These features are:

18.6.1 Credentials

If the application uses an external system as the credential store, then the passwords stored in such external system must be secured using the Credential Store Framework (CSF). Otherwise, the application must use an LDAP-based OID store as the credential store and CSF to access and manage data in that store.

In any case, the application must use the CSF to access and manage credentials. For details, see Integrating the Credential Store.

For further information about CSF, see Section 24.2, "Overview of Application Development with CSF."

18.6.2 Authentication

An application integrating authentication with OPSS must use one of the following models:

  • Secure a servlet using container authentication (web.xml).

  • Secure an EJB using container authentication (ejb-jar.xml).

  • Use programmatic authentication.

A combination of the above models should be considered when the same code or authentication configuration is shared by both Java SE and Java EE components.

Regardless of the model, the component (servlet, EJB, Web) must use an OID identity store. For details about integration, see Integrating Authentication.

For further information about authentication, see also Chapter 22, "Authentication for Java SE Applicaitons."

18.6.3 Authorization

An application integrating authorization with OPSS must use one of the following models:

  • Policy-based authorization against an OID LDAP-based policy store.

  • Container-based authorization to secure servlets, EJBs, and Web components.

For details about integration, see Integrating Authorization.

For further information about programmatic authorization, see also Chapter 22, "Authentication for Java SE Applicaitons."

18.6.4 User and Role Management

An application integrating with OPSS must use the User and Role API to manage users and external roles programmatically. This API facilitates the use of identity services without the developer having to know low-level details such as the location of a user account or the particular physical implementation of roles.

The User and Role API supports the following operations:

  • Create, update, delete, modify, get attributes, and change password on a user profile.

  • Create, update, delete, modify, and get attributes on a role.

For details about the User and Role API, see Chapter 25, "Developing with the User and Role API."

18.7 Integrating Authentication

This section explains the most important points of the following topics:

18.7.1 Container-Based Authentication

To enable user authentication during the development phase, developers run the ADF security wizard that generates the necessary OPSS configuration and specify authentication methods in the application deployment descriptor web.xml.

At run time, the container authenticates the end user of an application in one of the following ways: basic, form, or client cert. In most situations, form-based authentication is the appropriate choice.The container obtains the authentication data (such as user name and password) from the user, which is processed by the Oracle WebLogic Server to establish a user session. OPSS then queries Oracle WebLogic Server for the authenticated subject when a protected resource is to be accessed.

18.7.2 Oracle WebLogic Server Authentication Providers

OPSS uses authentication providers available in Oracle WebLogic Server. These providers validate user credentials or system processes based on a user name-password combination or a digital certificate. They also make user identity information available (through subjects) to other components in a domain when needed.

Available authentication providers include the Default Authenticator and the external LDAP stores. For details, see section Authentication Providers in Oracle Fusion Middleware Developing Security Providers for Oracle WebLogic Server.

18.7.3 Programmatic Authentication

In addition to container-managed authentication, OPSS allows programmatic authentication through the LoginService, an API that enable applications authenticating user credentials and establishing a principal. Once the principal has been established, the LoginService API creates a subject with principals corresponding to the authenticated user, the authenticated role, and the application roles of which the user is a member. This subject is then used to perform privileged actions. Additionally, OPSS also provides an API for identity and token assertion.

Typically, Java SE applications require programmatic authentication; in contrast, Java EE applications do not have such a requirement.

18.7.4 Single Sign-On through OPSS

To enable applications to participate in an SSO environment, it is necessary to use an Identity Asserter built specifically for the SSO solution. The recommended solution, OAM/OSSO, provides a dedicated Identity Asserter designed to work with the Oracle WebLogic Server.

For details about configuring and managing SSO using the OAM/OSSO solution, see Part IV, "Single Sign-On Configuration"

18.8 Integrating Authorization

Authorization protects access to application resources by enforcing policies, which determine what types of actions, tasks, or services a user can access.

OPSS provides functional security for Java EE and ADF applications in the following authorization models:

Both of these models provide fine-grained authorization capabilities to control access to application artifacts, such as the individual tasks one can perform in an application or the method one can invoke in a Java EE bean, according to the role(s) of which the user is a member.

18.8.1 Functional Security

Defining functional security starts at the early stages of the development phase. A product manager authors security functional data that is kept in a source code repository and that includes the definitions of application privileges, roles, the role hierarchy, and role categories.

When using functional security, developers need not be concerned with users and roles; instead, they focus on wiring the application permissions (usually defined by their respective product managers) to application artifacts developed by them.

Functional security supports the externalizing of users and enterprise roles, and enterprise administrators can use OIM to manage them. The Functional Security Model

The functional security model is based on grants that use the resource catalog whose entities are described in Table 18-4.

Table 18-4 Resource Catalog Entities

Entity Description Comments and Examples

Resource Type

A type defined by a Java permission class which includes the set of actions allowed on an instance of the type.

Examples: WebService, ADF TaskFlow, and Scheduled Jobs (ESS)


A instance of a resource type and a subset of the actions allowed by the resource type.

Example: a Purchase Order TaskFlow with updating privileges. (Purchase Order TaskFlow is a resource instance of the ADF TaskFlowresource type.

Entitlement (or permission set)

A set of resources and actions allowed on them.


Functional policies can be managed with Oracle Entitlements Server; for details, see Oracle Fusion Middleware Administrator's Guide for Oracle Entitlements Server. Checking Permissions with CheckPermission

In some cases, developers may need to check permissions programmatically. This check is carried out by calling the method checkPermission. For details on checking policies using checkPermision and other methods, see Section, "Using the Method checkPermission."

18.8.2 Functional Security with ADF

Typically, developers implement application functional security with the declarative security model provided by ADF in Oracle JDeveloper; this model greatly simplifies security integration by hiding and separating most security details from the application-specific logic.

In ADF, a functional security policy assigns permissions to secured artifacts, such as ADF task flows, pages, and regions; ADF facilitates this task by providing a user interface that lists the available permissions.

To add a functional security grant to an applications using ADF, proceed as follows:

  1. Check out jazn-data.xml, adf-config.xml, weblogic.xml, jps-config.xml, cwallet.sso, and web.xml; all these files must be writable.

  2. Execute the ADF security wizard.

  3. Enable anonymous access to all regions and task flows.

    This task creates the special role TEST-ALL with the anonymous user as a member. Permissions to all regions and task flows are then granted to the TEST-ALL role; this ensures that a non-authenticated user has access to all ADF artifacts in the application and that the application continues to work before security is defined for task flows and regions.

  4. Grant permissions to privilege roles.

    Once the ADF security wizard has been run, the files listed in step 1 are created or updated. Then, a developer uses the authorization policy editor to grant privilege roles permission to task flows and regions.

    If a needed role is not available at that time, the developer must request that the product manager create the privilege role in the file jazn-data.xml. Then, the developer must be check out that file again to have the new role available.


Developers should never change the security data kept in the source control. This recommendation includes not changing entitlements, application roles, the application role hierarchy, test enterprise roles, and test users.

For complete details about developing security in an ADF application, see chapter 29 in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

18.9 Integrating the Credential Store

Developers frequently are concerned with sensitive data necessary to operate the application or to access external services from it. The credential store, part of OPSS, is the repository of such data, and the CSF API allows an application accessing and operating on this data.

Developers should not include clear text user names or passwords in applications; instead, this data should be stored in the credential store, and, when necessary, the application should access credentials programmatically using the CSF API.

Administrators manage credentials using either the Fusion Middleware Control or OPSS scripts. Credentials are protected by code source permissions.

Logically, credentials are grouped in maps or containers for a collection of credentials. Within a map, a credential is uniquely identified by its key. Thus, a credential is uniquely determined by a pair of map and key. It is recommended that the map name be the same as the application name to prevent name collision if multiple applications are deployed to the same domain and, therefore, use the same credential store.

CSF is available for Java EE, Java SE, and C applications.

For details about the credential store, see Chapter 24, "Developing with the Credential Store Framework."

18.9.1 Guidelines for Using CSF

When working with CSF, a developer should follow the following guidelines:

  • Understand the CSF API.

    CSF is implemented by identifying the appropriate map and key names to use. This is particularly important in environments where multiple applications share the credential store. For details, see Section 24.6, "Steps for Using the API."

  • Provision policies that allow access to credentials. These policies are kept in the policy store, which can be file-based (system-jazn-data.xml) or LDAP-based.

    Note the following important guidelines:

    • Application code that requires access to a credential must be packaged into the smallest possible jar.

    • That jar needs to be granted the CredentialAccessPermission on the specific map and key name with a specific set of action(s). For details, see Section 24.3, "Setting the Java Security Policy Permissions."

    • The grant must be specified in the application jazn-data.xml file, which is packaged with the application and migrated to the policy store when the application is deployed.

  • In a clustered environment, use the Credential Store Mbean API over the Credential Store Framework API to create, retrieve, update, and delete application credentials. If, however, you are simply reading credentials either use either API. For details about MBeans, see Section E.2, "Configuring OPSS Services with MBeans."

18.9.2 Cryptography

Oracle Security Developer Tools provide cryptographic building blocks necessary to develop basic tasks, such as secure messaging, and more complex ones, such as implementing a secure service-oriented architecture. These tools build upon the core foundations of cryptography, public key infrastructure, Web services security, and federated identity management, to provide:

  • Authentication, which assures the receiver that the information is coming from a trusted source. Authentication is typically achieved by using a Message Authentication Code (MAC), a digital signature, or a digital certificate.

  • Confidentiality, which ensures that only the intended recipient of the message can read it. Confidentiality is typically achieved through encryption.

  • Integrity, which ensures that the received message has not been tampered. Integrity is typically achieved by using a cryptographic hash function.

  • Non-repudiation, which proves that a given sender actually sent a particular message. Non-repudiation is typically achieved by using digital signatures.

For details about the Oracle Security Developer Tools, see Section H.1, "OPSS API References," and Section 19.5, "Using the Oracle Security Developer Tools."