2 Managing Security

This section contains the following topics:

• "Security Model Overview"

• "Definition and Definition Management Security"

• "System Level Security"

2.1 Security Model Overview

Access to Oracle I/PM is granted through the configured credential store managed within the Oracle WebLogic Server domain using the available Oracle WebLogic Server providers. Once access to I/PM is granted, specific features within Oracle I/PM require security rights assigned by an Oracle I/PM administrator or user designated to grant rights to a specific feature.

The first person to log in to Oracle I/PM after initial installation is granted full rights to all features, in order to properly set up an Oracle I/PM solution to meet company needs. After the system is properly set up, security rights can be changed or revoked if necessary. Additionally, initial security rights can be reset if the credential store has been changed during set up. See "Installation Security Initialization" for more information.

Note:

When Oracle I/PM is first deployed, the role of IPMSYS_ADMIN is created within Oracle Content Server. This role provides specialized security rights necessary for Oracle I/PM and Oracle Content Server to operate together. The IPMSYS_ADMIN role is not intended for public use. This role is created and managed programmatically by the Oracle I/PM system.

Changes to the security rights assigned to the role or adding or removing users associated with that role will have a negative impact on the operation of both Oracle I/PM and Oracle Content Server. One such negative impact is that any users added to this role will be deleted from the Oracle Content Server system.

2.1.1 System Access

As managed servers running within an Oracle WebLogic Server domain, user and group access to Oracle I/PM and its repository is controlled by Oracle WebLogic Server. As such, system security configuration, as well as SSL configuration if desired, is handled through the Oracle WebLogic Server console. If additional services are required, such as Oracle Internet Directory or single sign on using Oracle Access Manager, these can be linked to the WLS domain managing I/PM using Oracle WebLogic Server controls.

Access to Oracle I/PM through web services is controlled by Oracle Web Services Manager (OWSM) policies. Policies are configured through the Oracle WebLogic Server console. Some policies require a keystore be defined. For example, Oracle I/PM must use access credentials stored in Credential Store Framework (CSF) to communicate with a workflow server or to use SSL. Keystores can be defined using Keytool from the Java Development Kit. Credentials can be added to defined keystores using WebLogic Scripting Tool (WLST).

Note:

Oracle Content Server account and collaboration security can be enabled on a content server repository being used by Oracle I/PM, however Oracle I/PM does not support their use on Oracle I/PM documents.

Figure 2-1 Oracle I/PM Security Overview

For additional information, see the following documentation:

Table 2-1 Additional System Security Documentation

Task	Where to Go For More Information
Administering Oracle WebLogic Server	Oracle Application Server Administrator's Guide
Using WebLogic Scripting Tool	Oracle Fusion Middleware WebLogic Scripting Tool Command Reference
Administering Universal Content Management	Oracle Fusion Middleware System Administrator's Guide for Content Server

2.1.2 Installation Security Initialization

The first person to log in to Oracle I/PM after initial installation is granted full rights to all features, in order to properly set up an Oracle I/PM solution to meet company needs.

During Oracle WebLogic Server installation, a credential store is defined as the default. Oracle I/PM uses this default credential store for its security. If the credential store changes after the first Oracle I/PM user logs in, system security must be reset. For example, if the security configuration is changed to point to an Oracle Internet Directory (OID) provider or a Microsoft Active Directory provider, you must reset I/PM system security.

To reset system security, do the following:

1. Create or migrate users and groups to the new policy store using the management tools associated with the policy store.

2. Open WebLogic Scripting Tool (WLST) and run refreshIPMSecurity() MBean command. The system security is reset. For information on using WLST to run MBean commands, see "Using WLST to Change MBeans" or Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

Note:

During the refresh, users or groups for whom matching identifying information is not found are ignored. As security changes are made, invalid users or groups are removed from the I/PM database.

For information on configuring Oracle WebLogic Server security providers, such as Oracle Internet Directory (OID) or Microsoft Active Directory, see Oracle Fusion Middleware Installation Guide for Oracle Enterprise Content Management Suite.

2.1.2.1 Migrating User Store from LDAP Server to Oracle Internet Directory

For information on migrating an existing LDAP Server credential store to Oracle Internet Directory, see “Reassociating the Identity Store with an External LDAP Authentication Provider” in Oracle Fusion Middleware Installation Guide for Oracle Enterprise Content Management Suite.

2.1.3 Integration with Single Sign-On

Oracle Access Manager (OAM), part of Oracle's enterprise class suite of products for identity management and security, provides a wide range of identity administration and security functions, including several single sign-on options for Fusion Middleware and custom Fusions Middleware applications. OAM is the recommended single sign-on solution for Oracle Fusion Middleware 11g installations.

For smaller scale Oracle Fusion Middleware 11g installations, where you do not have an enterprise-class single sign-on infrastructure like Oracle Access Manager, you only need to provide a single sign-on capability within your specific Fusion Middleware application, you can configure a SAML-based SSO solution. If you need to provide single sign-on with other enterprise applications, this solution is not recommended.

If your enterprise uses Microsoft desktop logins that authenticate with a Microsoft domain controller with user accounts in Active Directory, then configuring SSO with Microsoft Clients may also be an option to consider.

The setup required for each of these SSO solutions is described in the following documents/sections:

Table 2-2 Single Sign-on Documentation

For Information On...	See The Following Guide...
Configuring OAM and OSSO	Oracle Fusion Middleware Security Guide: Configuring Single-Sign On in Oracle Fusion Middleware
Using Windows Native Authentication for Single Sign-on	Oracle Fusion Middleware Securing Oracle WebLogic Server: Configuring Authentication Providers
Using WebLogic SAML for Single Sign-on	Oracle Fusion Middleware Securing Oracle WebLogic Server, Section 5.7: Configuring the SAML Authentication Provider

2.1.4 Definition Management Security Rights and Definition Security Rights

Once a user or group has been authenticated and access to Oracle I/PM has been granted, security rights to Oracle I/PM definitions take over.

Oracle I/PM definitions include the following:

• Applications

• Inputs

• Searches

• Connections

Note:

Document security is defined within an application and includes security rights to annotations associated with a document. See "Working with Document Security" and "Working with Annotation Security".

If a user has been authenticated for access to Oracle I/PM but has not yet been given security rights to any Oracle I/PM definitions or definition management, they are presented with the Home page, but no navigation links are displayed in the Navigator Pane.

To properly administer an I/PM solution, a distinction must be made between definition management rights and definition rights:

• Definition management security rights grant a user the ability to create or administer definitions (applications, inputs, searches, and connections).

• Definition rights grant a user the ability to view, modify, delete, or manage access to specific definitions, such as an application named Invoices_US or search named US Purchase Orders.

Oracle I/PM definition management security rights and definition security rights are managed within the Oracle I/PM user interface.

2.1.4.1 Definition Management Rights

Definition management security is done using the Definition Management Security pages, accessed from the Manage Security panel of the Navigator Pane. Definition management rights have two levels of security:

Security Right	Description
Administrator	Grants users or groups full rights to definition management and includes the ability to assign other users or groups Administrator or Create rights.
Create	Grants the ability to create new definitions. Users who create a definition are automatically assigned all definition rights for that definition by default.

Administrator Rights

Administrator rights are typically given to few people, as they allow full control of definitions across the enterprise with the following exceptions:

• they cannot modify or delete any application definitions that are dependent on connections to which they do not have View security rights

• they cannot modify or delete any search or input definitions that are dependent on applications to which they do not have View security rights

• they cannot modify any document security within an application

These exceptions are designed to prevent people with Administrator rights to definition management from changing definitions in order to gain access to documents that are restricted to them. For this reason, users must be granted access to all of the security layers in order to have access to specific definitions. This approach comes from need to have separation of business units. For example, if you set up a Content Server for a specific business unit in order to limit access to content on the server, you would not want other business units to have rights to put applications in that Content Server, nor to find documents within it.

The same holds true when creating an application. You will only see the connections to which you have been given View access as potential locations for your new application. Similarly you are only able to create workflow integration mappings to workflow servers to which you have been given View access to the corresponding connection definition.

Example

For example, an IT administrator named Sasha at XYZ Company has Administrator rights to application and search definitions. This gives Sasha the ability to grant rights to application and search definitions in other departments. Two new employees have started, one in Accounts Receivable named Theo, and one in HR named Bob.

Theo must be able to create searches and have access to all documents in Accounts Receivable, including orders that have customer credit card information in them. To secure the credit card information, all US orders are uploaded to the Orders_US application and stored in a specific repository connected to Oracle I/PM that Sasha doesn't have access to.

Sasha could add Theo as a user and grant him Create rights to searches using the Definition Management Security page, as well as add him as a user to most of the HR applications and grant him rights to the documents they contain. However, Sasha does not have View rights to the connection defined in the Orders_US application, and so she cannot add him as a user to that application.

Most likely, someone other than Sasha who manages system access but has no specific definition management rights in Oracle I/PM would add Theo to a group that has Create rights to searches and is already defined in the Orders_US application as having access to the documents within that application. By separating access control and limiting access to the connection, Sasha is prevented from modifying the Orders_US application to add herself as a user and therefore gain access to customer credit card data.

Example

Bob must have rights to search all HR documents including private employee information, such as Social Security numbers, salary and health related documents. Such documents are stored in Oracle I/PM using the HR_Confidential application and retrieved using the Private Employee Information search.

Sasha doesn't have View rights to the HR_Confidential application, so she cannot modify the Private Employee Information search to give Bob access. Like Theo, Bob will most likely be added to a group already defined in the necessary search by someone other than Sasha who manages system access but has no specific definition management rights in Oracle I/PM.

Create Rights

Create rights are typically given to business managers throughout the enterprise, as these people know the business processes associated with the documents being uploaded to Oracle I/PM. They allow a manager to create and modify application, search, input, and connection definitions unique to their business needs. And by controlling access to the repository connections used to store documents, different business units can be isolated to help secure documents.

Example

For example, Theo is the new Director of Accounting for the XYZ Company US division. Bob in Human Resources says that the company is implementing a new employee program that allows employees to debit their pay check when ordering company product.

Initially Theo wants to modify the Pending Orders search to not only search the Orders_US application for orders not yet filled, but also the HR_Confidential application. Theo wants to verify that the person placing the order is a current employee by verifying Social Security information from the search results against Social Security information entered on the new order form. However, Theo doesn't have access to the repository connection used to store the documents in the HR_Confidential application.

When Theo contacts Bob to ask for access, Bob explains the legal reasons that Theo cannot capture Social Security information on an order form nor access such information from Human Resources. Instead, Bob suggests Theo use the employee e-mail address as a unique identifier that is available on documents accessible to Theo.

In this example, Theo knew the business need he was implementing, but his knowledge of business practice outside of his area was limited. The security put in place by Oracle I/PM allowed him to meet his business need without compromising privacy.

2.1.4.2 Definition Rights

Definition security is defined on the security train stop when the definition is created and managed using the appropriate panel of the Navigator Pane. For example, security for an application definition is defined on the Application Security Page and security for a search definition is defined on the "Search Security Page". Definition rights have four levels of security:

Security Right	Definition
View	Enabled by default. Grants the user or group the right to view this definition.
Modify	Grants the user or group the right to modify all aspects of this definition except for granting security rights.
Delete	Grants the user or group the right to delete this definition.
Grant Access	Grants a user or group the right to grant security rights to others for this definition. If this is the only security level granted, the user can modify only the security information for this definition.

Definition rights are specific to each definition created. Anyone needing access to a specific definition through other definition types must have at least View rights to it. For example, users in XYZ Company needing to create or modify search definitions against the Invoices_US application need to have at least View rights to that application definition. Theo, as director of the US Accounting department, has View rights to the Invoices_US application and all rights to the All US Invoices search in order to be able to refine or change the search as business needs refine or change. Theo also has Grant Access rights to the search in order to provide View rights to individual contract employees that help during high volume periods.

2.1.5 Users and Groups

Definition management rights and definition rights are defined for either individual users or for user groups managed through separate security providers to Oracle WebLogic Server, such as Oracle Internet Directory (OID) or other. Once authenticated and available to Oracle I/PM, users or groups are granted various levels of access to definitions and definition management using the Oracle I/PM user interface. For example, when an application definition is created, a user or group is granted View rights to the application when they are added using the Application Security Page. Additional rights are then specified as required.

Groups are an efficient way to assign security rights to many individuals in an organization with identical access needs. For example, a Managers group could contain managers across an enterprise who need View rights to documents in the Resumes application. An HR_Managers group can be given Write, Delete, and Grant Access document rights to the same application in order to upload and delete resumes to and from Oracle I/PM, or grant access to the Resumes application and related searches to individual employees who might be asked to help when hiring a new employee.

Note:

Group membership is loaded at the time a user logs in to Oracle I/PM and remains active throughout the session until the user logs out. If a user is removed from a group while the user is logged in, that user retains the full rights of the group until the user logs out or the session is closed. The new user rights will take effect at the next log in.

Note that document security is assigned when an application is defined and only allows security rights to be assigned at the group level.

2.2 Definition and Definition Management Security

Definition and definition management security is managed through the I/PM user interface. This section covers the following topics:

• "Working With Definition Management Security"

• "Working with Definition Security"

• "Working with Document Security"

• "Working with Annotation Security"

• "Security Example"

2.2.1 Working With Definition Management Security

Definition management security is managed using the Definition Management Security pages, accessed from the Manage Security panel of the Navigator Pane. To grant, revoke, or copy users and groups rights to applications, inputs, searches or connections, do the following:

Changing Existing User and Group Rights To Definitions

1. Click Manage Security in the Navigator Pane to expand the pane and expose the definition type you want to manage.

2. Click the definition type you want to manage:

   • Applications

   • Inputs

   • Searches

   • Connections

   The Definition Management Security page for that definition type is displayed.

3. Click Modify. A toolbar is displayed above the listing of security members and the Create and Administrator security rights columns become active.

4. Enable or disable the rights next to the security member being modified and click Submit. The modification toolbar closes and the definition management security has been changed.

Revoking Existing Users and Groups Security Rights to Definitions

1. With the Manage Security page displayed, click Modify.

2. Select the user or group to delete from the Security Member column.

3. Click Remove. The user or group is removed from the list and definition management rights for the definition type are revoked.

Granting Users and Groups Rights to Definitions

1. With the Manage Security page displayed, click Modify.

2. Click Add or select a user or group and click Copy to replicate the security options of the item selected. The Add Security Member Page is displayed.

3. Select Search Groups or Search Users from the choice list and enter the search criteria, then click Search. If no criteria is entered, a listing of all users or groups is returned.

4. Select the user or group to grant rights from the Security Member column. Multiple selections can be made by holding down either the Shift key on your keyboard when clicking to select a range, or the Control key when clicking to select non-sequential members.

5. Click Add. The Add Security Member page closes and the users or groups are listed in the Security Member column of the security page.

6. Enable or disable the rights next to the security member being added and click Submit. The modification toolbar closes and the definition management security has been changed.

2.2.2 Working with Definition Security

Definition security is defined when the definition is created and managed using the appropriate panel of the Navigator Pane. For example, Searches are managed using the Manage Searches panel in the Navigator Pane.

Managing definition security is detailed in the sections of this guide specific to the definition:

• "Managing Applications"

• "Managing Inputs"

• "Managing Searches"

• "Managing Connections"

Note:

Definitions can be accessed and modified by anyone with Administrator security rights to the definition. Definitions cannot be locked while being modified. Consequently, if the same definition is being modified at the same time by different people, only the last changes submitted are saved.

2.2.3 Working with Document Security

While application definition security and document security are different, document security is defined in the application when it is created. Document security rights can only be applied to groups and are specified for each group using the Application Document Security Page when the application is defined. Note that this means if you modify document security rights in an application, all documents currently in that application are affected. The following document rights can be enabled:

Security Right	Definition
View	Grants a user group rights to view documents within a specific application. If a user does not have at least View rights to a document, the document is not listed in a search result when the user executes a search.
Write	Grants a user group rights to upload, update, and copy documents and document metadata within a specific application. Until a user has Write security rights to documents in at least one application, the Upload tool is not visible in the Tools panel of the Navigator Pane.
Delete	Grants a user group rights to delete a specific document from an application. If a user has Delete rights to one application and Write security rights to a second application, then they can move a document from the first to the second application. Note that users with Delete permission are automatically assigned Write permission.
Grant Access	Grants a user group rights to assign document rights to other user groups. Note that users with Grant Access rights are automatically assigned Delete and Write security rights.
Lock Admin	Grants a user group rights to unlock any locked document in the application.

2.2.4 Working with Annotation Security

All users who have the rights to view a document also have the rights to view Standard and Restricted annotations. Annotations are placed on a document by a user with the rights to do so, but when viewed by a user who does not have rights to modify the annotation, a TIFF version of the document is rendered and displayed with the annotation burned in. This helps ensure that any redactions or other necessary annotations keep the document secure. A user must be granted annotation security rights in order to create, modify, or hide annotations.

All or some annotations can be burned in or hidden based on the security rights granted a group when the application is defined. For example, in the event that a user has Annotate Standard permissions and a document has Standard, Restricted, and Hidden annotations, the user would view a TIFF image of the document with the Restricted annotations burned in, the Standard annotations overlaid on top, and the Hidden annotations not displayed.

Annotations are specific to individual documents, but annotation security rights are defined in an application when specifying document security on the Application Document Security Page. Granted when the application is defined, annotation security rights apply to every document in the application. Changing annotation security rights for a group in an application affects access to all annotations on documents in the application. Note that even though annotations are associated with and specific to each document in a repository, the annotations are stored separately so as to preserve the original document.

Because annotations are laid on top of documents, documents containing text data can sometimes shift underneath annotations. This can be a concern if text or images overlaid with a redaction annotation shift and become exposed. This is not an issue with improper security rights. It can happen when documents are created using fonts not available to the rendering engine when the document was uploaded. The rendering engine will then substitute fonts which may cause text shift and repagination. For information on how to avoid this problem, see "Font Errors".

2.2.4.1 Annotation Permissions

There are three levels of security applicable to a document annotation within a specific application.

Security Right	Definition
Annotate Standard	Grants view, create, modify, and delete security rights to all annotations within the application that are not explicitly specified as Restricted or Hidden.
Annotate Restricted	Grants security rights to mark annotations within an application as Restricted and create, modify, or delete annotations marked as Restricted by others. All users have permission to view restricted annotations but must have Restricted annotation rights to create, modify, or delete them.
Annotate Hidden	Grants security rights to mark annotations within an application as Hidden and create, modify, and delete annotations marked as Hidden by others. You must have Annotate Hidden rights to view Hidden annotations.

2.2.5 Security Example

Maya, Sasha, John, Bob and Louis are employees at XYZ Company. They have the following business roles and are members of the following departments and groups:

Name	Department	Role	Group
Maya	IT	Director of Information Technology at XYZ Company. She was the first to log into Oracle I/PM after installation and set up all definitions, definition security rights, and definition management security rights. She has full administrative access to all of Oracle I/PM across the enterprise, but does not use it on a daily basis.	IT_Director
Sasha	IT	Administrator for Oracle I/PM at XYZ Company. She has full administrative access to all of Oracle I/PM across the enterprise, except confidential employee information isolated on some repository connections to which she does not have access.	IT_Admin
John	HR	The Oracle I/PM administrator for the entire department. Because John is the HR Department administrator, he requires security rights to all Oracle I/PM actions pertinent to HR, but not security rights to anything pertinent to the Accounts Payable department, for example. John is the only individual allowed to create and modify application, search and input and connection definitions for Human Resources.	HR_IT
Bob	HR	Determines salary offerings to potential new employees, making the offer to a potential employee, and receiving the document when it has been accepted. Bob uses references external to the company to determine salary offers but once an offer has been accepted, he uploads the salary acceptance document to the Oracle I/PM system in an application called Offers and annotates it with an Accepted stamp. Once it has been uploaded, stamped, and saved, a workflow process is initiated that creates an HR new employee file that contains the stamped salary acceptance document. So Bob requires security rights to View, Create and Modify Documents called Offers.	HR_Managers
Louis	HR	Administrative assistant. Updates the database of employees' personal information. He does not use the personal salary information in an Offers document for his job, therefore, Louis would not have security rights to access, search, or upload Offers documents in Oracle I/PM	HR_Users

Definition Management Security Rights

Within the HR_Managers and HR_Users group of Oracle I/PM, Bob and Louis do not have any security rights to define definitions. That is because they do not create or manage applications, inputs, searches, and connections. They only use them.

Maya, Sasha and John however are granted the following definition management security rights according to the needs of their specific job responsibilities:

Security Right	Application	Input	Search	Connection
Administrator	Maya, Sasha	Maya, Sasha	Maya, Sasha	Maya, Sasha
Create	John	John	John	John

Definition Security Rights

Four of the five people need some level of security rights to the Offers definitions. John needs to administer them and Maya needs to have the ability to administer them or assign rights to someone else to administer them if John leaves or becomes incapacitated. Bob must have full rights to upload, annotate (to approve and redact salary information), find, view, and initiate the workflow process to create the new employee file. Louis must have rights to search and view documents to update personal information, but not to view redacted salary information. Sasha, however, does not have responsibility for administering confidential information, and so does not have rights to the repository connection where confidential information such as salaries and personal information is stored.

Each are granted the following definition security rights according to the needs of their specific job responsibilities:

Security Right	Offers Application	Offers Input	Offers Search	Workflow Connection
View	Maya, John, Bob, Louis	Maya, Bob	Maya, John, Bob, Louis	Maya, John
Modify	Maya, John	Maya, John	Maya, John	Maya, John
Delete	Maya, John	Maya, John	Maya, John	Maya, John
Grant Access	Maya, John	Maya, John	Maya, John	Maya, John

Document Security Rights

Only Bob and Louis work with the documents stored in the Offers application, so only the HR_Managers and HR_Users groups would be added on the Application Document Security Page when the Offers application was defined. Maya and John would not have access to the documents in the application, even though the application definition security rights grant them access to see and modify the Application definition.

Bob and Louis are granted the following document security rights according to their specific responsibilities:

Security Right	Documents	Group Members
View	HR_Managers, HR_Users	Bob, Louis
Write	HR_Managers	Bob
Delete	HR_Managers	Bob
Lock Admin	HR_Managers	Bob
Grant Access	HR_Managers	Bob
Annotate Standard	HR_Managers, HR_Users	Bob, Louis
Annotate Restricted	HR_Managers	Bob
Annotate Hidden	HR_Managers	Bob

These permissions allow Bob to upload and redact salary information from a document into the Offers application, where Louis can search for and view it to get updated personal information without being able to modify the redactions and see the salary information.

2.3 System Level Security

Oracle I/PM runs as a managed server within an Oracle WebLogic Server domain. Access to Oracle I/PM and the Oracle Content Server repository is controlled by Oracle WebLogic Server. System security, including SSL configuration, is handled through the Oracle WebLogic Server console. For additional information, see the following:

Task	Where to Go For More Information
Administering Oracle WebLogic Server	Oracle Application Server Administrator's Guide
Administering Universal Content Management	Oracle Fusion Middleware System Administrator's Guide for Content Server

2.3.1 Configuring a Fusion Middleware Application to use SSL

You can configure Oracle Fusion Middleware to secure communications between Oracle Fusion Middleware components using SSL, which is an industry standard for securing communications. Oracle Fusion Middleware supports SSL version 3, as well as TLS version 1:

Table 2-3 SSL Documentation

For Information On...	See The Following Guide...
Configuring SSL with Oracle Fusion Middleware: Web Tier, Middle Tier, and Data Tier	Oracle Fusion Middleware Administration Guide: Chapter 6, SSL Configuration in Oracle Fusion Middleware
Configuring SSL with Oracle WebLogic Server	Oracle Fusion Middleware Securing Oracle WebLogic Server Guide: Chapter 12, Configuring SSL

2.3.1.1 Configuring an SSL Content Server Repository Connection

To connect to a Content Server repository over SSL, the following steps must be taken:

1. Enable SSL on the Content Server Connection Content Server Settings Page

2. Add and configure an SSL incoming socket provider to the Content Server.

2.3.2 Integrating with a Workflow

Workflow integration is detailed in "Understanding Workflow Agents" and "Creating a Workflow Connection".

2.3.2.1 Integration Points

Oracle I/PM connects to a workflow process at the following times, using different mechanisms for each:

• Configuration

• Runtime

Configuration

Oracle I/PM connects to a workflow server when application fields are mapped to workflow payload elements. To connect, the provider, port, and credential information are passed using a BPEL JNDI-based API. Java Naming and Directory Interface (JNDI) and Enterprise JavaBeans use the T3 protocol, which is an Oracle WebLogic Server version of Remote Method Invocation (RMI). This API is used to enumerate the list of available composites, the web services exposed by each composite, and the WSDL URI for each service.

Once a composite and service are selected, the WSDL document is read from the server and parsed to obtain the list of available operations as defined by the service bindings in the WSDL. The protocol for reading the WSDL is HTTP and the address and port used are contained in part of the WSDL URI. Note that the address and port used may be different than the connection hostname and port if the workflow server is configured with an HTTP front end load balancer such as Oracle HTTP Server (OHS).

Once read, the WSDL is used to obtain the schema of the operation payload so that application fields can be mapped to it.

Details of the connection, composite name, service name, operation name, and application field to payload mapping are stored in the Application.BpelConfig section for use at runtime.

Runtime

Runtime communication occurs when Workflow Agent has received a notification that a document has been created in Oracle I/PM and a workflow process instance must be created for the document. For this communication, the connection, composite, and service name stored in BpelConfig is first used through the BPEL JNDI/EJB API to obtain the service WSDL URI.

The WSDL URI is read to obtain the operation payload schema. The payload schema is used to construct the XML for the payload and the application field values are then inserted into the XML as defined by the mapping.

Once the payload is fully defined to include the mapped field values, the payload is submitted to the workflow service operation as a web service call using the address as specified in the WSDL document. The web service call is submitted using the HTTP protocol.

2.3.2.2 Workflow Connection Configuration

The first step in configuring the Oracle I/PM workflow integration is to create a connection definition for the workflow system within Oracle I/PM. The procedure for creating a workflow connection is detailed in "Creating a Workflow Connection".

It is important to understand that the connection is used when connecting through the workflow EJB API, so the information is used to communicate though the T3 protocol and not HTTP.

The parameters required for the configuration are described as follows:

Parameter	Details
Provider	Specifies the hostname or names used for the connection. If the workflow server is a single instance, it is the machine name or IP of the workflow machine. If the workflow server is operating within a cluster, this may be a comma separated list of machine names or IP addresses of servers in the cluster or it may be the cluster name. If multiple machines provided in a comma separated list, they must all be defined to use the same port as supplied by the port parameter. If the workflow server instance in the cluster needs to be defined with different ports, then the cluster name configuration must be used. When the cluster name is used, the cluster name must be defined in domain name server to resolve to the multiple machines within the cluster. Neither Oracle I/PM nor BPEL defines this behavior. Rather, it is defined by the WebLogic support for JNDI in a cluster. For details on clustered JDNI support, see the section “Using WebLogic JNDI in a Clustered Environment” in the Oracle Fusion Middleware Programming JNDI for Oracle WebLogic Server guide.
Port	This specifies the port number used in the connection. For WebLogic, this is the standard listening port for the server. If the SSL option is enabled, then the port provided must be the SSL listening port for the server and T3 communication will use T3S, the SSL version of T3.
SSL	This indicates whether or not the port parameter is the SSL listening port of the workflow server.
Credential Alias	Provides the alias of a user name and password that are stored in the Credential Store Framework (CSF). These credentials are required to make the remote JNDI connection. The parameter is not the actual user name or password, but rather an alias, or key used to look up the user name and password in the CSF, which encrypted them to provide for proper security. The credential must be created in the CSF before the workflow connection configuration can be completed. A credential can be created in the CSF in one of two ways: through Enterprise Manager (EM) or through WebLogic Scripting Tool (WLST).

2.3.2.3 SSL Configuration

The Oracle I/PM integration can be configured to use SSL to secure communications with the workflow server instance. The procedure for enabling and configuring an SSL connection to a workflow server is detailed in "Configuring SSL for the Workflow Server".

Working with the Default Demo Credential Store Framework and Credential Certificates

Once SSL is enabled on the workflow server instance, T3 communication to the server will work properly for testing if both workflow and Oracle I/PM servers are configured to use the default DemoTrust certificates, because WebLogic configures a specific self-signed demo certificate and trust configuration when it is installed. These files are located in $WL_HOME/server/lib and are named DemoIdentity.jks and DemoTrust.jks. By default, WebLogic is configured to use these files.

Note:

These files should be used for test and demonstration purposes only. In a production environment, you should obtain proper and valid certificates and follow appropriate procedures for importing and configuring those certificates to establish identity and trust. When properly signed certificates are used and configured properly, SSL will work properly without special configuration.

You can use the demo certificate to test and confirm a workflow SSL connection. The SSL configuration allows Oracle I/PM to enumerate the composites and services, but when Oracle I/PM goes to read the WSDL, it will fail. This is because two SSL stacks are being used within the server:

• The WLS SSL stack, which is integrated with the demo identity and trust configuration, is used for T3 communication.

• The native Java SSL stack, which is not integrated with the WebLogic demo identity and trust configuration, is used by the WSDL reader, which uses a native Java API.

To make the WSDL reader work, the Java SSL stack on the Oracle I/PM server instance must be told to trust the self-signed certificate on the workflow server.

To do this, the javax.net.ssl.trustStore system property must be set on the Oracle I/PM managed server JVM to point to the SSL trust store. To configure this to point to the DemoTrust.jks, add the following to the JAVA_OPTIONS in the setDomainEnv script:

-Djavax.net.ssl.trustStore=$WL_HOME/server/lib/DemoTrust.jks.

After pointing to the DemoTrust.jks, restart the managed I/PM server.

This works because all Oracle WebLogic Server shares use the same DemoTrust.jks file.

At runtime, there is still a potential that when WebLogic is installed and automatically generates an identity keystore (DemoIdentity.jks), the identity is keyed to the machine name. In some cases, the identity may only be hostname with no domain (so, sta00319, not sta00319.us.oracle.com). When Oracle I/PM goes to send the workflow process message, WebLogic performs hostname verification as part of its SSL handshake that attempts to validate that the hostname in the HTTPS request matches the identity to the server. However, the URL that the workflow system is giving is full DNS name, not just the hostname. So the handshake fails verification and the communication fails.

The simplest solution for demo purposes is to disable host name verification on the Oracle I/PM system. This is probably the easiest solution, but not a real world production solution. The procedure for this is documented here:

Configuring New CSF Credentials

You can also create self-signed CSF credentials instead of using the default demo credentials. For information on configuring a CSF credential for a workflow connection, see "Configuring a Workflow Connection CSF Credential".

2.3.3 Configuring a Fusion Middleware Application to Use Web Services

WebLogic Web Services are implemented according to the Web Services for Java EE 1.2 specification, which defines the standard Java EE runtime architecture for implementing Web Services in Java. The specification also describes a standard Java EE Web Service packaging format, deployment model, and runtime services, all of which are implemented by WebLogic Web Services.

Table 2-4 Web Services Documentation

For Information On...	See The Following Guide...
Web Services consumed by JAX-WS clients	Oracle Fusion Middleware Getting Started with JAX-WS Web Services for Oracle WebLogic Server
Apply OWSM security to Web Services	Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server: Appendix A: Using Oracle Web Service Security Policies
Use MTOM with Web Services	Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server: Section 2.2: Example of Adding Security to MTOM Web Service
Invoke secured Web Service from BPEL	Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite: Chapter 7, Invoking a Synchronous Web Service from a BPEL Process Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite: Chapter 8, Invoking a Asynchronous Web Service from a BPEL Process
Invoke Web Service using Oracle Server Bus	Oracle® Fusion Middleware Developer's Guide for Oracle Service Bus: 32 WS Transport
Invoke Web Service using Oracle Enterprise Server Bus	Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite: Chapter 19 Creating Mediator Routing Rules

2.3.4 Web Services Security Configuration for I/PM

Access to Oracle I/PM through web services is controlled by Oracle Web Services Manager (OWSM) policies. Policies are configured through the WebLogic Server console. Some policies require a keystore be defined. For example, Oracle I/PM must use access credentials stored in Credential Store Framework (CSF) to communicate with a workflow server or to use SSL. Keystores can be defined using Keytool from the Java Development Kit. Credentials can be added to defined keystores using WebLogic Scripting Tool (WLST).

Oracle Web Services Manager is designed to be flexible by allowing the end user to define the security policy that will be used rather than to have them predefined.

2.3.4.1 Working with Oracle Web Services Manager

When no policy is applied, the services default to using Http Basic Authorization or WS-Security UsernameToken based authorization. Http Basic Authorization passes user credentials in the HTTP header in the Authorization field. The value of this field contains a base64 encode of the username and password. The BasicUserToken client class is intended to use this form of authentication.

WS-Security UsernameToken profile passes both username and password but in a SOAP header structure. Refer to documentation on WS-Security UsernameToken Profile 1.0 for details. Note that the UsernameToken policies can also be enforced using an OWSM policy, in which case the OWSM policy implementation supersedes the default implementation. This option applies only when OWSM policies are not in use.

Because the password is transmitted unencrypted when using basic authentication and UsernameToken security, Oracle I/PM includes a configuration MBean called RequireBasicAuthSSL, allowing the service to require that SSL be used with this form of authentication.

For more robust security, OWSM polices can be applied to the services provided the OWSM Policy Manager is installed to the domain. OWSM policies can enforce various ws-security token usage, including message level encryption, transport level encryption, or supplying credentials in the SOAP header rather than HTTP header. Because SSL can be specified as part of the applied policies, the RequireBasicAuthSSL MBean setting does not apply when security policies are in use.

2.3.4.2 Setting Policies on Services

During domain creation, the Oracle I/PM application is supplied with a default deployment plan defined in the applications directory, although this plan is not yet assigned to the deployment. The default plan uses the wss_username_token_service_policy which enforces simple username and password in the ws-security soap header and requires no encryption. This default plan assigns the wss_username_token_service_policy to all Oracle I/PM services.

To assign the default plan, do the following:

1. Login to the WebLogic Server Console.

2. Click Deployments, enable imaging in the Deployments table, then click Update. The Update Application Assistant is displayed.

3. Click Change Path next to Deployment plan path. Changing the source path does not redeploy with a new plan.

4. Using the links in the Current Location field, browse to $MW_HOME/user_projects/applications/<domain_name>/server/ipm and enable the Plan.xml file.

5. Continue through the wizard to complete the deployment.

Once this process is complete, services all have the wss_username_token_service_policy applied.

If you want to change the policies at runtime, do the following:

1. Login to WebLogic Server console

2. Click Deployments and then expand imaging in the Deployments table. A list of Oracle I/PM web services is displayed. You may need to scroll to see them.

3. Click the service name for each service you want to configure and do the following:

   Note:

   No policy should ever be applied to the DocumentContentService service.

   1. Select the Configuration tab

   2. Select the Ws-Policy tab. The currently applied policy is displayed.

   3. Click the service end point. For example, the ApplicationServicePort. A listing of Available Message Policies and Chosen Message Policies is displayed.

   4. Select the currently applied policy from the Chosen Message Policies list on the right and click the arrow to move it to remove it from the Chosen Message Policy list.

   5. Select the preferred policy from the Available Message Policies list on the left and click the arrow to move it to the Chosen Message Polices list on the right.

   Note:

   You need to apply the same policy to all Oracle I/PM services with the exception of DocumentContentService. No policy should be applied to the DocumentContentService service.

4. When changes are made to all services, update the deployment with the newly edited plan.

   1. Enable imaging in the Deployments table on the main deployments page, then click Update. The Update Application Assistant is displayed.

   2. Check the top option to update only the deployment plan.

   3. Click Finish.

To facilitate deployment, alternative deployment plan descriptors have been created. The are located in $MW_HOME/user_projects/applications/<domain_name>/server/ipm/plan/imaging-ws.war/WEB-INF directory. You can copy any one of the policy-<X> files on to weblogic-webservices-policy.xml in that same directory, and then update the deployment with the plan. Note that for the default plan, weblogic-webservices-policy.xml = policy-username_token.xml.

2.3.4.3 API Usage

It is important that all services be assigned the same policies. In the client API the ServicesFactory is coded to obtain the appropriate client policy from the provided UserToken, along with the required configuration parameters for the policy, and use that client policy configuration on all service interfaces. In order to work, client code must know what service policy is in effect. The following are examples of how to code the client for each of the predefined policy types within the UserToken class.

The UserToken class exposes a number of new properties to facilitate configuring client side policies. The set of parameters exposed is a subset of the full set of possible Oracle Web Service Manager parameters, but is commonly used. Note that the properties are wrappers around a name/value pair map which is directly exposed using the securityParameters property. All properties in this map get passed along to the web service request context and therefore any OWSM policy is usable.

2.3.4.4 Examples

The following examples are detailed here:

• "No Policy: Http Basic Auth"

• "Policy: wss_username_token_client_policy"

• "Policy: wss11_username_token_with_message_protection_client_policy"

• "Policy: wss10_saml_token_client_policy"

• "Policy: wss11_saml_token_with_message_protection_client_policy"

Example 2-1 No Policy: Http Basic Auth

The simplest and the default. Because this is the default the BasicUserToken provides the client implementation.

UserToken userToken = new BasicUserToken("weblogic", "weblogic");
ServicesFactory.login(userToken,  wsurl);

BasicUserToken is functionally equivalent to the following.

UserToken userToken = new UserToken();
userToken.setUserName("weblogic");
userToken.setPassword("weblogic");

When OWSM policies are applied to the services, the WsmUserToken is used to provide the client side policy configurations. This is done as follows for various policies.

Example 2-2 Policy: wss_username_token_client_policy

This is the simplest policy.

WsmUserToken userToken = new WsmUserToken ("weblogic", "weblogic");
userToken.setClientPolicy(WsmUserToken.USERNAME_TOKEN_POLICY);
ServicesFactory.login(userToken,  wsurl);

Example 2-3 Policy: wss11_username_token_with_message_protection_client_policy

Message_protection policies provide message level encryption. However to make them work, client and server keystores need to be configured. See the section "Working With Keystores" for how to create and configure the key stores. When a keystore is used client side by a JSE client, the client code needs to configure the location, type, and password for the keystore. The client side keystore must contain a RecipientAlias which is the key used to encrypt the message sent to the server. This same key must exist server side to decrypt and encrypt the responses.

WsmUserToken userToken = new WsmUserToken ("weblogic", "weblogic");              
userToken.setClientPolicy(WsmUserToken.USERNAME_TOKEN_MP_POLICY);
userToken.setKeystore(".\\config\\default-keystore.jks", "JKS", "welcome");
userToken.setRecipientAlias("orakey");

If this policy were being used server side, for example, from a web app or servlet, the key store would be configured underneath JPS security and therefore the client would not need to specify the keystore configuration parameters. This behavior can be replicated in JSE as well by setting the oracle.security.jps.config environment property to point to a jps-config file.

System.setProperty("oracle.security.jps.config", ".\\config\\jps-config.xml");
WsmUserToken userToken = new new WsmUserToken ("weblogic", "weblogic");               
userToken.setClientPolicy(WsmUserToken.USERNAME_TOKEN_MP_POLICY);

Once JPS is configured for the client, you can also leverage the Credential Store Framework (CSF) to define the username and password credentials. See the section "Working with the CSF through WLST". To use, create the credentials on the server and copy them to your client. You can use any alias in the credential store, but the standard default is the alias basic-credentials.

System.setProperty("oracle.security.jps.config", ".\\config\\jps-config.xml");
WsmUserToken userToken = new WsmUserToken ();
userToken.setClientPolicy(WsmUserToken.USERNAME_TOKEN_MP_POLICY);
userToken.setCsfKey("basic.credentials");

Example 2-4 Policy: wss10_saml_token_client_policy

This policy is similar to username token but only the passes the username in the saml token header. Also, its not encrypted and therefore not secure.

WsmUserToken userToken = new WsmUserToken ("weblogic");
userToken.setClientPolicy(WsmUserToken.SAML_TOKEN_POLICY);

Example 2-5 Policy: wss11_saml_token_with_message_protection_client_policy

This option encrypts and signs the message using keys and certificates from the keystore. This is the most secure of all the options and requires the most configuration. Typically, service-side code has the user identity in the form of a java.security.Principal object. So server-side code might look as simple as the following.

WssUserToken userToken = new WssUserToken (principal.getUserName();
userToken.setClientPolicy(WsmUserToken.SAML_TOKEN_MP_POLICY);
ServicesFactory.login(userToken,  wsurl);

For JSE, the jps configuration trick works here as well.

System.setProperty("oracle.security.jps.config", ".config\\jps-config.xml");
WssUserToken userToken = new WssUserToken ("weblogic");
userToken.setClientPolicy(WsmUserToken.SAML_TOKEN_MP_POLICY);

Without JPS configuration, the client can provide the full set of keys. Since this seems like an extreme use case, the UserToken does not provide full access to all of the key properties required by the policy. This demonstrates how any policy parameters can be supplied through the securityParameters property.

WssUserToken userToken = new WssUserToken ();
userToken.setUserName("weblogic");
userToken.setClientPolicy(WsmUserToken.SAML_TOKEN_MP_POLICY);
userToken.setKeystore(".\\config\\default-keystore.jks", "JKS", "welcome");
userToken.getSecurityParameters().put(SecurityConstants.ClientConstants.WSS_ENC_KEY_ALIAS, "orakey");
userToken.getSecurityParameters().put(SecurityConstants.ClientConstants.WSS_ENC_KEY_PASSWORD, "welcome");
userToken.getSecurityParameters().put(SecurityConstants.ClientConstants.WSS_SIG_KEY_ALIAS, "orakey");
userToken.getSecurityParameters().put(SecurityConstants.ClientConstants.WSS_SIG_KEY_PASSWORD, "welcome");

In these configuration examples, the same key is used in all cases. In a production environment, the keystore should contain client and service-side certificates or signing and encrypting respectively.

2.3.4.5 Working With Keystores

For any of the message_protection policies, client and server keystores need to be configured. In a production environment, you should obtain proper and valid certificates and follow appropriate procedures for importing and configuring those certificates to establish identity and trust. This example is meant to provide a workable solution for development and testing. You can create a keystore using a build in JDK tool called KeyTool. You use the following command to generate a keystore.

>keytool -genkey -alias orakey -keyalg RSA -keystore default-keystore.jks
Enter keystore password:   ß welcome
Re-enter new password:    ß welcome
What is your first and last name?
  [Unknown]:  Joe Smith
What is the name of your organizational unit?
  [Unknown]:  Human Resources
What is the name of your organization?
  [Unknown]:  Our Company
What is the name of your City or Locality?
  [Unknown]:
What is the name of your State or Province?
  [Unknown]:
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=Joe Smith, OU=Human Resources, O=Our Company, L=Unknown, ST=Unknown, C=US correct?
  [no]:  yes
 
Enter key password for <orakey>
        (RETURN if same as keystore password):   ß RETURN...so welcome
>

You can list keys in a keystore with

>  keytool -list -keystore default-keystore.jks

The above example creates the single common key used in all of the examples above. The same default-keystore.jks was used on both the server and the client.

2.3.4.6 Working with the CSF through WLST

The following command can be used from WLST to add credentials into the keys store. However, to use these commands, you have to run WLST from the $ORACLE_HOME/common/bin directory rather than from the WLS home common/bin. In JDeveloper, this is located in Oracle/Middleware/jdeveloper/common/bin and not Oracle/Middleware/wlserver_10.3/common/bin. From the $ORACLE_HOME/common/bin, run wlst.sh (Linux) or wlst.cmd (Windows) and the run connect().

The full set credential store commands are documented in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference, but the main two used in these examples are:

createCred(map="oracle.wsm.security", alias="<alias>", user="<user>", password="<pwd>")

and

listCred(map="<map>", key="<key>)

The credential store can store any userid and password pair accessed by an alias. For WSM policies, the acsf aliases are used to obtain keystore aliases and passwords. These CSF aliases are configured in the jps-config.xml file in the following element.

  <!-- KeyStore Service Instance -->
  <serviceInstance name="keystore" provider="keystore.provider" location="./default-keystore.jks">
      <description>Default JPS Keystore Service</description>
      <property name="keystore.type" value="JKS"/>
      <property name="keystore.csf.map" value="oracle.wsm.security"/>
      <property name="keystore.pass.csf.key" value="keystore-csf-key"/>
      <property name="keystore.sig.csf.key" value="enc-csf-key"/>
      <property name="keystore.enc.csf.key" value="enc-csf-key"/>  
  </serviceInstance>

The keystore needs one alias named keystore-csf-key that includes the password for the key store. In this example, it is the first password entered in the keytool, above. The username here is ignored. Then the keystore needs a second alias named enc-csf-key. The username is a keystore alias and the password is the private password for that keystore alias, which is the second password in the keytool, above.