Setting Up OSM Security

4 Setting Up OSM Security

This chapter describes how to set up security on your Oracle Communications Order and Service Management (OSM) system.

About OSM Security

You use the Oracle WebLogic Server Administration Console to manage OSM security.

When you manage OSM security, you can perform the following tasks:

Add users to groups. See "Adding Users to OSM."
Set up Secure Sockets Layer (SSL). See "Using Secure Sockets Layer"
Use WebLogic Server's LDAP or another authenticator that is integrated with WebLogic Server. See "Using WebLogic Server Authenticators with OSM."

Note:

If you use an external security implementation such as LDAP, you should also use a caching realm to improve performance. See "Setting Up a Caching Realm" for more information.
Manage credentials securely using the EncryptPasswords utility or the Oracle Fusion Middleware Credential Store Framework (CSF). See "Secure Credential Management."
Administer users and workgroups Using XML documents. See "Using the XML Import/Export Application to Administer Users and Workgroups."
Manage workgroups. See OSM Order Management Web Client User's Guide for more information.

For more information about WebLogic Server security realms, refer to the WebLogic Server Console documentation.

Note:

OSM supports LDAP Version 2.

Secure Solution Data Storage

As a fulfillment system, OSM does not need a fixed data model, and so is not required or typically used to store sensitive data other than that used for OSM user authentication.

You can secure OSM user credentials as described in this chapter, but if your implementation requires OSM to store or log other sensitive data that appears on orders, Oracle recommends that you encrypt the data outside of OSM. Because the encryption happens outside of OSM, you are responsible for developing and maintaining the encryption method.

Adding Users to OSM

In WebLogic Server, a security realm consists of a set of configured security providers, users, groups, security roles, and security policies that protect WebLogic resources. To access WebLogic resources that belong a security realm, a user must be defined in that realm.

To add a user to OSM:

Add users to groups in the WebLogic Server Administration Console.
Create workgroups as roles in Oracle Communications Design Studio.
Assign users to workgroups in the OSM Administrator.

For information about the users and groups created by the OSM installer, see "Users and Groups."

Adding Users to Groups in the WebLogic Server Administration Console

All security for OSM users and groups is managed through the WebLogic Server Administration Console. See the WebLogic Server documentation for more information about creating and deleting users and groups.

To add users to groups:

Log in to the WebLogic Server Administration Console.

You must be a WebLogic administrator.
In the Domain Structure tree, click Security Realms.

The Summary of Security Realms page is displayed.
Click the name of your security realm. The default name is myrealm.

The settings for the security realm are displayed.
Click the Users and Groups tab.

A list of users that have been configured is displayed.
Click on a user.

The user's description, password, and group membership is displayed. Users are assigned to one or more parent groups that have different levels of access to WebLogic Server resources, depending on their roles and the tasks they can perform. Groups in the WebLogic Server security realm represent the roles.
On the page that displays the settings for the selected user, click the Groups tab.
Select a group or groups from the Available list, click the right arrow to move the selected group to the Chosen list. See "Users and Groups" for more information about the groups.
Click Save.

Creating Workgroups as Roles in Design Studio

In Design Studio, you create roles and assign permissions to give users in that role access to related functions in the Task and Order Management web clients and the OSM Web Service and XML APIs.

Note:

You assign individual users to roles using the Administration area of the Order Management web client. See OSM Order Management Web Client User's Guide for more information.

Table 4-1 describes the client functions to which you provide access.

Table 4-1 Client Permissions

Function	Description	Applies To
Create Versioned Orders	Enables users to create orders for different versions of cartridges. If not granted this permission, users can only create orders for the default version of the cartridge. This permission relates to: In the Task web client: creating a new order In the Web Service API: using the CreateOrderBySpecification calls In the XML API: using the CreateOrder XML API call	Task web client Web Service API XML API
Exception Processing	Enables users to alter the flow of a process by applying exception statuses at any time throughout the process. This permission relates to: In the Task web client: raising exceptions on a task In the XML API: using the SetException call	Task web client XML API
Online Reports	Enables users to view summarized reports on all orders and tasks on the system. This permission relates to: In the Task web client: using the reporting feature	Task web client
Order Priority Modification	Enables users to modify the priority of an order or of a task in an order. This permission relates to: In the Order Management web client: setting the order priority In the Task web client: setting the task priority In the Web Service API: changing the order priority using the UpdateOrder call In the XML API: changing the order or task priority using the UpdateOrder call	Order Management web client Task web client Web Service API XML API
Reference Number Modification	Enables users to modify the reference number of an order. This permission relates to: In the Order Management web client and Task web client: Modifying the reference number of an order In the Web Service API and XML API: changing the reference number using the UpdateOrder call	Order Management web client Task web client Web Service API XML API
Search View	Enables users to access the order Query function. This permission relates to: In the Order Management web client: using the main search screen for the client In the Task web client: using the Search functionality (for example, clicking the Query button from the Worklist) In the Web Service API: using the FindOrder call In the XML API: using the Query call	Order Management web client Task web client Web Service API XML API
Task Assignment	Enables users to assign tasks to others. This permission relates to: In the Task web client: assigning a task to another user In the XML API: using the AssignOrder calls	Task web client XML API
Worklist Viewer	Enables users to access the Worklist function. This permission relates to: In the Task web client: accessing the worklist In the XML API: using the Worklist call	Task web client XML API

Function

Description

Applies To

Create Versioned Orders

Enables users to create orders for different versions of cartridges. If not granted this permission, users can only create orders for the default version of the cartridge.

This permission relates to:

In the Task web client: creating a new order
In the Web Service API: using the CreateOrderBySpecification calls
In the XML API: using the CreateOrder XML API call

Task web client

Web Service API

XML API

Exception Processing

Enables users to alter the flow of a process by applying exception statuses at any time throughout the process.

This permission relates to:

In the Task web client: raising exceptions on a task
In the XML API: using the SetException call

Task web client

XML API

Online Reports

Enables users to view summarized reports on all orders and tasks on the system.

This permission relates to:

In the Task web client: using the reporting feature

Task web client

Order Priority Modification

Enables users to modify the priority of an order or of a task in an order.

This permission relates to:

In the Order Management web client: setting the order priority
In the Task web client: setting the task priority
In the Web Service API: changing the order priority using the UpdateOrder call
In the XML API: changing the order or task priority using the UpdateOrder call

Order Management web client

Task web client

Web Service API

XML API

Reference Number Modification

Enables users to modify the reference number of an order.

This permission relates to:

In the Order Management web client and Task web client: Modifying the reference number of an order
In the Web Service API and XML API: changing the reference number using the UpdateOrder call

Order Management web client

Task web client

Web Service API

XML API

Search View

Enables users to access the order Query function.

This permission relates to:

In the Order Management web client: using the main search screen for the client
In the Task web client: using the Search functionality (for example, clicking the Query button from the Worklist)
In the Web Service API: using the FindOrder call
In the XML API: using the Query call

Order Management web client

Task web client

Web Service API

XML API

Task Assignment

Enables users to assign tasks to others.

This permission relates to:

In the Task web client: assigning a task to another user
In the XML API: using the AssignOrder calls

Task web client

XML API

Worklist Viewer

Enables users to access the Worklist function.

This permission relates to:

In the Task web client: accessing the worklist
In the XML API: using the Worklist call

Task web client

XML API

In addition to granting web client permissions, you can also grant permissions at the order level (by associating a role to an order type) and the task level.

See the discussion about creating new roles in Design Studio Modeling OSM Processes for more information. After you create a role, you must assign permissions to the role entities. See "Role Editor Role Tab" in Design Studio Modeling OSM Processes for more information about permissions for role entities.

Assigning Users to Workgroups

See the discussion about assigning users to a workgroup in OSM Order Management Web Client User's Guide for more information.

Adding Users to WebLogic Server Security Realms

You can add users to WebLogic Server security realms using the Administration console or Oracle WebLogic Scripting Tool commands provided by WebLogic Server, or you can use the userAdmin command. You should add users to a security realm after they have been added to the credential store. For more information about adding users to the credential store, see "Managing Credentials in the Credential Store." However, if you do add a user using userAdmin command and the user has not already been added to the credential store, the userAdmin command will also add the user to the credential store in the osm map.

To add users to WebLogic Server security realms using the userAdmin command, see "Using the userAdmin Command." Following is a sample XML data file for adding users:

<userConfig xmlns="http://www.metasolv.com/Provisioning/UserConfig"
 xmlns:oms="http://www.metasolv.com/OMS/OrderModel/2002/06/25"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <user name="testOsmUser1">
      <description>OSM test user 1</description >
      <password>password_from_createEncryptPasswords</password>
      <saltstore>/u01/security/testOsmUser1/salt.store</saltstore>
   </user>
   <user name="testOsmUser2">
      <description>OSM test user 2</description >
      <password>password_from_createEncryptPasswords</password>
      <saltstore>/u01/security/testOsmUser2/salt.store</saltstore>
   </user>
</userConfig>

Using Secure Sockets Layer

OSM supports the following levels of security for interactive users:

No use of SSL. If no SSL support is chosen, the HTTP connection is made on the WebLogic Server non-secure port.
SSL for all communications. Complete SSL support is provided by the WebLogic server. An HTTPS connection is made to the SSL port for that server and all communication takes place using SSL on that port.

Changing Secure Sockets Layer Configuration in OSM

You configure SSL for OSM using the XML parameter file web.xml which is stored in the oms.war file inside the oms.ear file. To edit the web.xml file, you must unpack the oms.ear file, edit the web.xml file, and then repack the oms.ear file and re-deploy it to the OSM server. For more information about unpacking and repacking the oms.ear file, see OSM Developer's Guide.

To change SSL configuration on the OSM server:

Locate and extract the web.xml file from the oms.ear/oms.war file.
Add or modify the parameter secure_login in the web.xml file.
Edit the parameter value as follows:
- For no SSL support, enter 0.
- For SSL support, enter 1.
Save the file.

Using WebLogic Server Authenticators with OSM

OSM supports using either the WebLogic Server's embedded LDAP directory or another authenticator that is external to, and integrated with, WebLogic Server. The latter is referred to in this section as an external authenticator. This section provides information about how these directories work with OSM.

Note:

If multiple authentication providers are configured in WebLogic Server, all the authentication providers (even if they are configured as optional in WebLogic Server) should be active. If any of the authentication providers is not active, an exception will be raised and the users will not be able to log in to OSM.

User-Level Authenticator Support

OSM fully supports external authenticators and embedded LDAP directories at the user level. A user that exists in either the WebLogic server's embedded LDAP directory or in an external authenticator receives the privileges of any group to which it is assigned in WebLogic Server. Also, users can be assigned to workgroups in the Administration area of the OSM Order Management web client and will receive the appropriate permissions for the workgroup.

Group-Level Authenticator Support

OSM also supports external authenticators and embedded LDAP directories at the group level. A group that exists in either the WebLogic server's embedded LDAP directory or in an external authenticator receives the privileges of any OSM group to which it is assigned in WebLogic Server. Also, groups can be assigned to workgroups in the Administration area of the OSM Order Management web client and will receive the appropriate permissions for the workgroup.

A child LDAP group will inherit the following from its parent LDAP group:

Permissions from OSM roles in Design Studio
Permissions from groups assigned in the WebLogic Administration Console
Tasks
Filters
Flexible headers

It is not possible to restrict a child group from inheriting from the parent group.

Note:

If a user is assigned (directly or indirectly) to multiple groups which have different query tasks for the same order, it is not predictable which query task view the user will see when querying the order.

Authenticator User and Group Assignment Considerations

There are some considerations and best practices to take into account when assigning users and groups to OSM workgroups/roles.

The first step in assigning permissions for external authenticator and embedded LDAP users and groups is to assign them to either the OMS_client or OSM_automation groups in WebLogic Server.
Only users and groups which have been assigned directly to the OMS_client or OSM_automation groups in WebLogic Server will be available to assign to workgroups in the Administration area of the OSM Order Management web client. For example, if UserA1 is a member of GroupA, and GroupA has been assigned to the OMS_client group in WebLogic Server, only GroupA will be displayed in the OSM Order Management web client. However, when GroupA is assigned to a workgroup, UserA1 (and all of the users in GroupA) will inherit the permissions of the workgroup.

Both users and groups will be displayed the same in the OSM Order Management web client. There is no indication which elements are users and which are groups.
If new users are added to the authenticator, they will not be able to access OSM functionality until the OSM Metadata is refreshed. For information about refreshing OSM metadata, see "Refreshing OSM Metadata".
Oracle recommends that you assign automation users to the OSM_automation WebLogic Server group directly, rather than as members of a group. If you decide to assign automation users using a group instead of individually, you must ensure that you do not remove from the WebLogic Server group any users that are specified in the "Run As" property of an automation plug-in.

Setting Up a Caching Realm

If you use an external security implementation such as LDAP, you should also use a caching realm to improve performance. A caching realm holds the results of security checks in memory so that subsequent checks are not required to communicate directly with an external security server. The default settings for caching realms are appropriate for small numbers of users in the external realm; however, they do not help if your external security implementation has large numbers of users.

To set up a caching realm:

Log in to the WebLogic Administration Console.
In the Domain Structure tree, select Security Realms.

The Summary of Security Realms page is displayed.
Click the name of your security realm. The default name is myrealm.

The settings for the security realm are displayed.

From this window, you can change the settings for your realm.

For more information about setting up security in WebLogic Server, see Oracle Fusion Middleware Administering Security for Oracle WebLogic Server.

Secure Credential Management

This section describes how to secure credentials for accessing external systems. OSM provides two distinct secure credential management solutions, each appropriate to the type of credential to be secured:

EncryptPasswords utility: This utility is used to secure the credentials required to run other OSM utilities that require those credentials, for example the XML Import/Export tool. Oracle recommends that you use this if you are running utilities unattended. If you are running the utilities attended, Oracle recommends that you provide the required credentials interactively as prompted by the utility, rather than using the EncryptPasswords utility. Because the utility is assumed to run unattended, it must be able to decrypt credentials without user intervention. Therefore, the output of the EncryptPasswords utility should be considered obfuscated and not encrypted. Secure the files containing the output with appropriate file-system-level restrictions. For more information, see "Using the EncryptPasswords Utility."
Credential Store: This utility is used to secure credentials required to access systems with which your OSM solution interacts. It builds on CSF, adding OSM-specific features. For more information, see "Using the Credential Store."

Using the EncryptPasswords Utility

You use the EncryptPasswords utility to encrypt the user name and password credentials of XML Import/Export application users.

About the EncryptPasswords Utility

When you install the XML Import/Export application, you can optionally provide passwords for the OSM database, the XML API interface, and the WebLogic domain administration server. To set and reset those passwords, you run the EncryptPasswords utility. See "Running the EncryptPasswords Utility" for information about running the utility.

The EncryptPasswords utility (located in the SDK/XMLImportExport directory) is a password management utility that secures the credentials that the XML Import/Export application uses. The EncryptPasswords utility encrypts the credentials, preventing their accidental exposure.

Running the EncryptPasswords utility prompts you to enter the user name and password credentials of each XML Import/Export application user that requires access to the OSM database, the XML API interface, and the WebLogic domain administration server. It then stores the user names and passwords for these users in encrypted format in the configuration file which the XML Import/Export application uses to provide these credentials (for example, SDK/XMLImportExport/config/config.xml). When the XML Import/Export application runs, it decrypts the passwords as part of loading its configuration file.

The EncryptPasswords utility can be run only by a user who has write access to the XML files in which the credentials are stored.

Ant build files for the EncryptPasswords utility are located in the following directories:

SDK/CartridgeManagementTool/production
SDK/CartridgeManagementTool/development

The Ant build files have targets corresponding to each of the batch files in the SDK/XMLImportExport directory that include the EncryptPasswords functionality.

Running the EncryptPasswords Utility

Run the EncryptPasswords utility script:

As part of the initial setup of the XML Import/Export application
Each time the user name or password credentials of an XML Import/Export application user changes

Note:

To run the EncryptPasswords utility, you must have write access to the XML files in which the XML Import/Export application user credentials are stored.

To run the EncryptPasswords utility:

Create a config file that complies with the SDK/XMLImportExport/config/config.xsd file.

The same directory also contains a sample file: config_sample.xml.

Note:

The configuration file must contain the <user> and <password> elements, but the values of these elements do not matter because the script will prompt for these values.
Do one of the following:
- UNIX and Linux:
  
  Run the following command:
```
EncryptPasswords.sh XMLConfig [-dbUser] [-xmlapiUser] [-wlsUser]
```
  for example:
```
EncryptPasswords.sh config/config.xml -dbUser
```
- Windows:
  
  Run the following command:
```
EncryptPasswords XMLConfig [-dbUser] [-xmlapiUser] [-wlsUser]
```
  for example:
```
EncryptPasswords config\config.xml -dbUser -xmlapiUser
```
where XMLConfig indicates the configuration XML file you created in the previous step, and the following optional parameters indicate which passwords should be encrypted:
- -dbUser: the OSM database password
- -xmlapiUser: the XML API interface password
- -wlsUser: the WebLogic domain administration server password
When you set a user's credentials, you specify only the systems that they use for the XML Import/Export application operations they perform. For example, if the user only imports or exports cartridges, you only need to specify the -dbUser flag.
When prompted by the script, enter the user names and passwords that you selected when running the script.

When you type in passwords, nothing will be displayed on the screen.

Removing an Encrypted Password

To remove a user name and password for a user that no longer requires credentials, open the XML file where the credentials are stored and remove them manually. If you do not remove them manually, the user name and password combination continues to exist in the XML file.

Using the CreateEncryptPasswords Utility

You use the CreateEncryptPasswords utility to encrypt the user name and password credentials of users to put in XML configuration files for the userAdmin and credStoreAdmin commands. See "userAdmin Command" and "credStoreAdmin Command" for more information about these commands.

The CreateEncryptPasswords utility (located in the OSM_home/SDK/XMLImportExport directory) is a password management utility that secures the credentials being administered by the userAdmin and credStoreAdmin commands. The CreateEncryptPasswords utility provides an encrypted password and a separate file (a salt file) that are used together to provide password security. You put the encrypted password value and the path and name of the additional file in the XML file you are configuring for the userAdmin or credStoreAdmin command.

Before Running the CreateEncryptPasswords Utility

Before running the CreateEncryptPasswords utility, you must create or have present a file to contain the encrypted password. This file must be located in the same directory in which you are running the utility. It can be empty, and it does not have to have a .properties extension. For example, you can use a file name like password.txt.

If you run the utility multiple times, you can store all of the passwords in the same properties file.

Running the CreateEncryptPasswords Utility

Run the CreateEncryptPasswords utility script:

for each user element in the userConfig element in the XML file for the userAdmin command. See "Creating the XML Data File for the userAdmin Command" for more information about this file.
for each credential element in the CredentialConfig element in the XML file for the userAdmin command. See "Creating the XML Data File for the credStoreAdmin Command" for more information about this file.

To run the CreateEncryptPasswords utility:

Do one of the following:
- UNIX and Linux:
  
  Run the following command:
```
CreateEncryptPasswords.sh username password filename label
```
  for example:
```
CreateEncryptPasswords.sh user1 password1 pass.properties pw
```
- Windows:
  
  Run the following command:
```
CreateEncryptPasswords username password filename label
```
  for example:
```
CreateEncryptPasswords user1 password1 pass.properties pw
```
where:
- username: is the name of the user to be encrypted
- password: is the plain-text password of the user
- filename: is the name of the properties file in which to store the password
- label: is the label to put on the password in the properties file. The label in the file is to differentiate between different passwords. If you reuse an existing label, the password in the file will be overwritten. If you use a new label, the new encrypted password will be added to the beginning of the file. Following is the format of a properties file containing three encrypted passwords created by the CreateEncryptPasswords command:
```
#Wed Apr 29 10:13:24 EDT 2015
pw3=encrypted_password_3
pw2=encrypted_password_2
pw=encrypted_password_1
```
After running the command, rename the file that was generated by the script. When the script is run, it creates the auxiliary file as salt.store in the directory from which you ran the script. Since it creates a file with the same name each time, you should rename it to keep it from being overwritten, and also so you know which user it is for. For example, you could rename it user1_salt.store.

Using the Credential Store

You use the credential store to store credentials that OSM uses to interact with external systems.

About the Credential Store

A credential store is a central repository you can use to store credentials such as user names and passwords. OSM can use a credential store for the credentials needed to log in to and send requests to external systems (meaning any resources or systems that are out of the scope of your OSM cartridge-owned code and resources). These credentials can be used by OSM and OSM applications.

The type of credential store that OSM uses is offered through the Oracle Platform Security Services and is part of the CSF security service available to WebLogic Server. CSF offers both file-based and LDAP-based credential stores. OSM uses the file-based credential store by default. Oracle recommends using LDAP-based stores in a production environment.

The CSF is a set of APIs that applications can use to create, read, update, and manage credentials securely. OSM includes wrapper APIs to the CSF APIs. Use the OSM credential store APIs when developing your OSM cartridges so your OSM applications can access and read credentials from the credential store in a secure form. For example, use the OSM credential store APIs when you define data provider classes in your cartridges which must access web service and database systems with credentials. See "Developing Cartridges to Use the Credential Store" and "OSM Credential Store API Command Reference" for more information about using the credential store in your cartridge development.

Oracle recommends you to use the credential store as a repository for credentials and use the OSM credential store APIs in OSM-related code to access the repository in a secure form. Oracle strongly recommends you do not hard-code user names and passwords in cartridge code and that you update any current cartridges that have hard-coded credentials to use the OSM credential store APIs. See "Developing Cartridges to Use the Credential Store" for more information about security options and recommendations.

For information about Platform Security Services and managing credentials in the credential store, see Oracle Fusion Middleware Securing Applications with Oracle Platform Security Services.

How OSM Retrieves Credentials from the Credential Store

The credential store in the WebLogic Server domain for OSM applications contains credentials which are stored using a credential store map and key names. OSM applications, such as OSM web clients and OSM cartridge applications, retrieve credentials from the credential store based on the credential store map and key names. Automation plug-ins are used to call OSM credential store APIs to retrieve the credentials. OSM applications then use the credentials to gain access to external systems.

OSM credential store APIs are used inside automation plug-ins to retrieve credentials and to gain access to external systems. OSM cartridge code can call the credStoreAdmin command to create and configure the required entries, such as map name, user name, and password, for OSM applications in the credential store. See "credStoreAdmin Command" for information about this utility.

OSM plug-in users in a cartridge application, such as automation plug-ins or external instance adapters access the OSM credential store map and read the credentials.

The following steps summarize how an OSM automation plug-in retrieves credentials from the credential store for an automation task that requires the credentials to access an external system:

The automation plug-in script uses the getCredential or getOsmCredentialPassword method of the AutomationContext API.
WebLogic Server checks the Java Platform Security policy and confirms the automation plug-in has access permissions from the OSM domain to the credential store.
The automation plug-in user accesses the correct credential store map and reads the credentials required to access the external system.

If the credentials are not in the store, the API fails with an exception and the automation task fails.
If the credentials are in the store, the user name and password variables in the plug-in script will be set with values retrieved from the credential store.
The message is sent to the external system with the credential information.
The automation task completes.

Configuring the Java Security Policy for the OSM Credential Store

For OSM and its plug-in applications to read data from the credential store, the WebLogic server must be configured to grant them Java permissions to access the credential store map. In Platform Security Services, credential store access permission is configured through the Java Platform Security policy.

When you configure the Java Platform Security policy, you specify the code source directory of the OSM application (oms); this grants credential store access permission to all JAR files in the code source directory.

The default credential store map name for OSM applications is osm. For OSM plug-in users to access the default map, configure the Java Platform Security policy using map name osm. You can create your own credential store map in the credential store. For OSM plug-in users in cartridge applications to access your credential store map and read the credentials, configure the Java Platform Security policy using your own map name.

In a clustered environment, use the administration server URL rather than the managed server when you configure the credential store and the Java Platform Security policy.

To configure the Java Platform Security policy, you can use any of the following methods:

The credStoreAdmin command. See "Configuring the Java Security Policy Using the credStoreAdmin Command" to configure the Java Platform Security policy for the OSM credential store map using this command. See "credStoreAdmin Command" for a description of this command.
The Fusion Middleware WebLogic Scripting Tool grantPermission command. See Oracle Fusion Middleware Securing Applications with Oracle Platform Security Services for information about managing policies with the WebLogic Scripting Tool commands.
The Fusion Middleware Control GUI. Credential store and Java Platform Security policy MBeans can be configured from this GUI. See Oracle Fusion Middleware Administering Security for Oracle WebLogic Server for more information. You can also verify the Java security policy configuration from this GUI.

Configuring the Java Security Policy Using the credStoreAdmin Command

You can configure the Java Security Policy if you have already installed both OSM and the OSM SDK.

To configure the Java Platform Security policy for the OSM credential store map using the credStoreAdmin command, see "Using the credStoreAdmin Command." Following is a sample XML data file for configuring the security policy:

<?xml version="1.0" encoding="UTF-8"?>
<CredentialConfig
 xmlns="http://www.metasolv.com/Provisioning/CredentialConfig"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="…/XMLImportExport/models/CredStoreAdmin.xsd">
   <jpsPolicy operation="add">
      <mapname>osm</mapname>
   </jpsPolicy>
</CredentialConfig>

You can call the credStoreAdmin target in another Ant script. For an example of calling the credStoreAdmin Ant script in your own Ant script, see "Calling the credStoreAdmin Target in Another Ant Script."

Setting Up Email Notifications Using the credStoreAdmin Command

You can set up OSM to send users notifications by email. When a notification occurs, the system sends a notification ID number. For information about managing notifications, see OSM Order Management Web Client User's Guide.

To set up email notifications for a user using the credStoreAdmin command:

Add the oms-automation user to the workgroup that contains the user who will receive email notifications.

The oms-automation user is the internal automation user account for the processing of OSM automation and email notifications.
Make sure that email_server_ssl and email_server_authentication parameters in the oms-config.xml file are set to true.

If the user's email server requires server authentication, you must store the password for the administrator's email user in OSM credential store. The administrator's email address is specified by the admin_email_address parameter (located in the oms-config.xml file).

Run the credStoreAdmin command using the instructions in "Using the credStoreAdmin Command." Following is a sample XML data file for configuring email notifications.

<?xml version="1.0" encoding="UTF-8"?>
<user:CredentialConfig
xmlns:user=" http://www.metasolv.com/Provisioning/CredentialConfig"
xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=" http://www.metasolv.com/Provisioning/CredentialConfig
../models/CredStoreAdmin.xsd ">
   <user:jpsPolicy operation="add">
     <user:mapname>osm</user:mapname>
   </user:jpsPolicy>
   <user:credential operation="create" overwrite="true">
     <user:mapname>osm</user:mapname>
     <user:keyname>osmUser_{OSM_ADMIN_EMAIL_ADDRESS}</user:keyname>
     <user:user>OSM_admin_email_address</user:user>
     <user:password>OSM_admin_email_password</user:password>
   </user:credential>
 </user:CredentialConfig>

Delete the XML data file after you are done using it, since it contains a password.

Managing Credentials in the Credential Store

You must provision the credential store with credentials before OSM applications can use them. Provision the credential store by adding the user names and passwords required for OSM and external systems. You must also update passwords in the credential store every time you change user passwords through the WebLogic Server Administration Console.

Store all OSM users in the default OSM map (osm) or in a custom map that you have configured into the Java security policy, and use a default value in key name osmUser_username.

To manage credentials, such as adding, updating, or deleting credentials for OSM and external systems in the credential store, do either of the following:

Use Oracle WebLogic Scripting Tool commands provided by WebLogic Server. See Oracle Fusion Middleware Securing Applications with Oracle Platform Security Services for information about managing credentials in the credential store by using WebLogic Scripting Tool commands.
Use the credStoreAdmin command in the XML Import/Export application. See "credStoreAdmin Command" for information about this command.

To manage credentials in the credential store using the credStoreAdmin command, see "Using the credStoreAdmin Command." Following is a sample XML data file for managing credentials:

<?xml version="1.0" encoding="UTF-8"?>
<ns2:CredentialConfig
 xmlns:ns2="http://www.metasolv.com/Provisioning/CredentialConfig"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="…/XMLImportExport/models/CredStoreAdmin.xsd">
   <ns2:credential operation="create" overwrite="true">
      <ns2:mapname>osm</ns2:mapname>
      <ns2:keyname>osmUser_osm1</ns2:keyname>
      <ns2:user>osm1</ns2:user>
      <ns2:password>password_from_createEncryptPasswords</ns2:password>
      <ns2:saltstore>/u01/security/osm1/salt.store</ns2:saltstore>
   </ns2:credential>
   <ns2:credential operation="create" overwrite="true">
      <ns2:mapname>osm</ns2:mapname>
      <ns2:keyname>osmUser_osm2</ns2:keyname>
      <ns2:user>osm2</ns2:user>
      <ns2:password>password_from_createEncryptPasswords</ns2:password>
      <ns2:saltstore>/u01/security/osm2/salt.store</ns2:saltstore>
   </ns2:credential>
</ns2:CredentialConfig>
   <ns2:credential operation="delete">
      <ns2:mapname>osm</ns2:mapname>
      <ns2:keyname>osmUser_osm3</ns2:keyname>
   </ns2:credential>

Developing Cartridges to Use the Credential Store

When your OSM cartridges require data from external systems, trigger actions at external systems, or provide data to external systems, credential information may be required by the external system. The external system can be any resource or system that is out of the scope of your OSM-cartridge-owned codes and resources.

When you develop OSM cartridges, Oracle recommends you use the credential store to allow plug-in code to access credential information in a secured way. You can use the OSM credential store APIs for code that requires credential retrieval.

OSM uses the credential store offered through WebLogic Server; however, you are not required to use this credential store to secure credentials. You can use other methods of securing credentials. Oracle strongly recommends you do not hard-code user credential information in OSM code such as in plug-in script files and cartridge model description files. Passing and storing passwords in plain text poses a security risk. Follow proper security guidelines to develop OSM cartridges to protect data over communication channels. Oracle recommends using SSL communication between OSM and an external system, particularly for web services of external systems.

The following are examples of external systems used in OSM cartridges that may require credential information:

OSM Web Service
Databases
JMS queues and topics (except JMS queues deployed by the cartridge)
Web services of any system

To develop your OSM cartridges to use the credential store, see the following:

Use "AutomationContext" in your automation plug-in code to retrieve credentials from the credential store. See "Developing Automation Plug-ins to Use the Credential Store" for more information.
Use the operation APIs in "ViewRuleContext" in XQuery scripts to access credentials stored in the credential store.
Use "PasswordCredStore" in your JAVA classes to retrieve user names and passwords from the credential store.
Use the attributes for credential store in "SoapAdapter" to retrieve credentials from the credential store when sending a SOAP request using HTTP/HTTPS.
Use the attributes for credential store in "ObjectelHTTPAdapter" to retrieve credentials from the credential store when sending a request to Objectel. See "Defining Data Providers in OSM Cartridges to Use the Credential Store" for more information.
See "OSM Credential Store API Command Reference" for a description of the OSM credential store APIs.

See "Using the Credential Store" for information about the credential store.

Developing Automation Plug-ins to Use the Credential Store

Some OSM credential store APIs can be used in custom automation plug-in Java classes. Use these APIs when you define custom automation plug-in classes to access an external system with credentials. You can also call OSM credential store APIs from your automation context classes. The XQuery plug-in code for an automation or activation task can use credential store APIs to retrieve credentials from the credential store. See "AutomationContext" for example code for developing automation plug-ins in OSM cartridges to retrieve credentials from the credential store.

External instance adapters and automation plug-in classes (XQuerySender and XSLTSender) provided by Oracle to send messages and requests to external systems support the OSM credential store APIs.

Defining Data Providers in OSM Cartridges to Use the Credential Store

You must set up a data provider class in your cartridge if it requires credential information for an external system so it can read the required credentials from the credential store.

Using the Credential Store with Custom Data Providers

When you add a data provider class in a cartridge that requires credential information for an external system, the data provider class can call OSM credential store APIs to read the required credentials from the credential store. Your data provider class must implement the retrieveInstance() method of the ExternalInstanceAdapter interface.

To read the required credential from the credential store when you define your own data provider class (provider type is "Custom"), use the following APIs in the retrieveInstance() method in your Java class:

Note:

This example assumes you are using your own map. If you use the default map (osm) and key names for the OSM application, you can use simpler code:

String password = context.getOsmCredentialPassword(username)

public Element retrieveInstance(final ViewRuleContext context, final Map<String, Object> parameters) throws Exception {
    // DoCustomLogic
      
    String mapname = getStringParam(parameters, "para.mapname", null);
    String keyname = getStringParam(parameters, "para.keyname", null);
    String username = "";
    String password = "";
    
    if (mapname != null && keyname != null) {
      try {
        String credential = context.getCredential(mapname, keyname);
        int index = credential.indexOf("/");
        username = credential.substring(0, index-1);
        password = credential.substring(index);
       } catch (Exception e) {
      // DoCredStoreExceptionHandling
      }
    }
    // DoAuthenticationWithUsernamePassword
    // DoCustomerRequest
    // DoResponseHandling
  }

Using the Credential Store with Built-In Data Providers

Oracle provides pre-defined or built-in data provider classes "SoapAdapter" and "ObjectelHTTPAdapter" which contain the code required for using the credential store. To use the credential store when you use these built-in adapters, add the input parameters required for the credential store in your data provider.

Table 4-2 shows the parameters that are required for each adapter type.

Table 4-2 Parameters for SoapAdapter and ObjectelHTTPAdapter

Adapter	Parameter Name	contextType	Default Value
SoapAdapter	oms:credentials.mapname	XPATH	myMap
SoapAdapter	oms:credentials.keyname	XPATH	myUser
ObjectelHTTPAdapter	obj:mapname	XPATH	osm
ObjectelHTTPAdapter	obj:keyname	XPATH	osm

Upgrading Existing Cartridge Code to Use the Credential Store

Upgrade your existing OSM cartridge code to use the credential store by using the OSM credential store APIs. Upgrade your custom data provider classes and XQuery plug-in code to use the OSM credential store APIs for retrieval of credentials. See "Developing Cartridges to Use the Credential Store" for information about developing cartridges to use the credential store.

In addition to upgrading your cartridge code, provision the credential store for the WebLogic Server domain for OSM applications with required credentials (see "Managing Credentials in the Credential Store") and configure the Java Platform Security policy for the WebLogic Server domain to allow OSM access to the credential store.

Using Built-in SOAP Adapter as a Data Provider Class

Credential information is required to send a SOAP request. If your existing automation plug-in code that is used to test the SOAP adapter has hard-coded passwords, you can use the built-in SOAPAdapter class as a data provider class in your cartridges to remove the need for the hard-coded passwords.

When you use the default map for OSM applications, automation plug-in users pass in only the user name in the parameter. When you use your custom credential store map, automation plug-in users also pass in the credential map name and key name for credentials in the parameter.

To update existing automation plug-in code that tests SOAPAdapter to remove hard-coded passwords:

Remove hard-coded passwords from the existing "oms:credentials:password" input parameter.
Ensure that credentials exist in the credential store under map="osm" key=osmUser_SoapRequest_username.
Test that the SOAP adapter works correctly after the update.

Using the XML Import/Export Application to Administer Users and Workgroups

The userAdmin command, which is part of the XML Import/Export application, lets you add users to WebLogic Server groups and OSM workgroups using an XML document. The XML document contains the user information you want to add or configure based on the OSM_home/SDK/XMLImportExport/models/UserAdmin.xsd schema.

Administering users in this way allows you to manage users in volume instead of assigning them individually, and it permits the integration of OSM users into a larger, enterprise system administration application.

To add users to WebLogic Server security realms using the userAdmin command, see "Using the userAdmin Command." Following is a sample XML data file for adding users:

<userConfig xmlns="http://www.metasolv.com/Provisioning/UserConfig"
 xmlns:oms="http://www.metasolv.com/OMS/OrderModel/2002/06/25"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.metasolv.com/Provisioning/UserConfig
/u01/app/OSM/SDK/XMLImportExport/models/UserAdmin.xsd">
   <user name="demo">
      <description>A test user</description>
   </user>
   <clientGroup>
      <user>demo</user>
   </clientGroup>
   <logManagerGroup>
      <user>demo</user>
   </logManagerGroup>
   <userAssignerGroup>
      <user>demo</user>
   </userAssignerGroup>
   <workgroupManagerGroup>
      <user>demo</user>
   </workgroupManagerGroup>
   <workgroup name="demo">
      <user>demo</user>
   </workgroup>
   <workgroup name="everyone">
      <user>demo</user>
   </workgroup>
</userConfig>