This chapter describes how to set up security on your Oracle Communications Order and Service Management (OSM) system.
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.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.
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."
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.
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.
| 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:
|
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:
|
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:
|
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:
|
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:
|
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:
|
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:
|
Task web client XML API |
|
Worklist Viewer |
Enables users to access the Worklist function. This permission relates to:
|
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 the Design Studio Modeling OSM Processes Help for more information. After you create a role, you must assign permissions to the role entities. See the description of the Role Editor Role tab in the Design Studio Modeling OSM Processes Help for more information about permissions for role entities.
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.
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.
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.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.
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.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.
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 Fusion Middleware Securing Oracle WebLogic Server.
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."
You use the EncryptPasswords utility to encrypt the user name and password credentials of XML Import/Export application users.
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 on running the utility.
The EncryptPasswords utility (located in the OSM_home/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, OSM_home/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:
OSM_home/SDK/CartridgeManagementTool/production
OSM_home/SDK/CartridgeManagementTool/development
The Ant build files have targets corresponding to each of the batch files in the OSM_home/SDK/XMLImportExport directory that include the EncryptPasswords functionality.
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, do one of the following:
UNIX and Linux:
Source the following command:
. EncryptPasswords.sh XMLConfig [-dbUser] [-xmlapiUser] [-wlsUser] MW_home
for example:
. EncryptPasswords.sh config/config.xml -dbUser /u01/admin/Oracle/Middleware
Windows:
Run the following command:
EncryptPasswords XMLConfig [-dbUser] [-xmlapiUser] [-wlsUser]
for example:
EncryptPasswords config\config.xml -dbUser -xmlapiUser
where XMLConfig indicates the XML Import/Export application configuration XML file you are using (for example, config.xml) and the following optional parameters indicate which passwords should be encrypted:
-dbUser: the OSM database
-xmlapiUser: the XML API interface
-wlsUser: the WebLogic domain administration server
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.
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.
You use the credential store to store credentials that OSM uses to interact with external systems.
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 on 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 on security options and recommendations.
For information on Platform Security Services and managing credentials in the credential store, see Oracle Fusion Middleware Application Security Guide.
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 on 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.
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 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 the Oracle Fusion Middleware Security Guide for information on 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 the Oracle Fusion Middleware Application Security Guide for more information. You can also verify the Java security policy configuration from this GUI.
There are two methods for configuring the Java security policy. Both methods require that 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 batch script (recommended method):
Create and edit the configuration file for credStoreAdmin command (config.xml). See "Creating the Configuration File for the credStoreAdmin Command."
Create and edit the XML data file for credStoreAdmin command (credential.xml). See "Creating the XML Data File for the credStoreAdmin Command." The Java Platform Security policy and credentials are configured based on the data in the credential.xml file.
From the OSM_home/SDK/XMLImportExport directory, set the following required environment variables for the credStoreAdmin command in config.bat (Windows) or config.sh (Unix):
JAVA_HOME
APP_ROOT: Point to the XMLImportExport directory in the OSM SDK installation.
MIDDLEWARE_HOME: Point to the Fusion Middleware installation directory.
Set the required properties in the build.properties file. See "Setting Build Properties for Credential Store Commands."
Run the credStoreAdmin batch script as follows:
credStoreAdmin credential.xml config/config.xml
When prompted, enter the password for WebLogic Server user.
Restart WebLogic Server.
You can also configure the Java Platform Security policy for the OSM credential store map using the credStoreAdmin command Ant script.
To configure the Java Platform Security policy for the OSM credential store map using the credStoreAdmin command Ant script:
Create and edit the configuration file for the credStoreAdmin command (config.xml). See "Creating the Configuration File for the credStoreAdmin Command."
Create and edit the XML data file for the credStoreAdmin command (credential.xml). See "Creating the XML Data File for the credStoreAdmin Command."
From the OSM_home/SDK/XMLImportExport directory, set required properties in the build.properties file as described in "Setting Build Properties for Credential Store Commands."
Run the credStoreAdmin Ant script and provide the WebLogic Server administrator user password in the command line as follows:
>ant –Dwls_admin_password=password credStoreAdmin
Restart WebLogic Server.
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."
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 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).
Use the credStoreAdmin command, and the following XML sample snippet, to store the password.
<?xml version="1.0" encoding="UTF-8"?>
<user:CredentialConfig
xmlns:oms=" http://www.metasolv.com/OMS/OrderModel/2015/06/25"
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 snippet file after you are done using it.
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 an example of the contents of a properties file containing three encrypted passwords, the first of which was created by the sample CreateEncryptPasswords command above:
#Wed Apr 29 10:13:24 EDT 2015 pw3=1eb8b2255bdb49f732db0fad8e639aa0 pw2=1e3898e12403a6a98b17522efa971d5c pw=40ee2b3264e26e78c0cf2246cbb12299
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.
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 Security Guide for information on 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 on this command.
To manage credentials in the credential store using credStoreAdmin command:
From the OSM_home/SDK/XMLImportExport directory, set required properties in the build.properties file as described in "Setting Build Properties for Credential Store Commands."
From the OSM_home/SDK/XMLImportExport directory, run the script credStoreAdmin:
>credStoreAdmin credential.xml config/config.xml
where credential.xml is the XML data file that includes the map, key, user name, and password values. See "Creating the XML Data File for the credStoreAdmin Command."
The following is an example of the XML data file:
Note:
If you are using a custom map name, replace the map name in the example (osm) with your map name.
<?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_osm</ns2:keyname>
<ns2:user>osm</ns2:user>
<ns2:password>f490722e13cf88fd8a8c0160a34729f72</ns2:password>
<ns2:saltstore>C:/security/osm/salt.store</ns2:saltstore>
</ns2:credential>
<ns2:credential operation="create" overwrite="true">
<ns2:mapname>osmlf</ns2:mapname>
<ns2:keyname>osmUser_osmlf</ns2:keyname>
<ns2:user>osmlf</ns2:user>
<ns2:password>f940016e13cf29fd8a8c7220a34756f72</ns2:password>
<ns2:saltstore>C:/security/osmlf/salt.store</ns2:saltstore>
</ns2:credential>
</ns2:CredentialConfig>
where config.xml is the configuration file that contains the data for WebLogic Server. See "Creating the Configuration File for the credStoreAdmin Command."
The following is an example of the config.xml file:
<j2eeAdminConnection> <user>weblogic</user> <password/> <hostname>localhost</hostname> <port>7001</port> </j2eeAdminConnection>
To manage credentials in the credential store using the userAdmin command:
From the OSM_home/SDK/XMLImportExport directory, set required properties in the build.properties file as described in "Setting Build Properties for Credential Store Commands."
Create and edit the configuration file for the userAdmin command (config.xml). See "Creating the Configuration File for the userAdmin Command."
Create and edit the XML data file for the userAdmin command (user.xml). See "Creating the XML Data File for the userAdmin Command."
Oracle recommends that you do not enter password values in user.xml. By leaving password values empty, you can enter passwords interactively at run time.
From the OSM_home/SDK/XMLImportExport directory, do either of the following:
(Recommended method) Run the shell script userAdmin and input password information when prompted:
>userAdmin user.xml config/config.xml
Run the Ant script userAdmin and provide password information in the command line:
>ant –Dwls.admin.password=password -Dxmlie.root.dbPassword=password userAdmin
If the Ant target userAdmin is called by an Ant script that is running in your Design Studio workspace, interactive mode is not supported and passwords must be entered in the XML data file. In this case, delete the XML data file immediately after use. For an example of how to call the userAdmin command Ant script in another Ant script, see "Calling the UserAdmin Target in Another Ant Script."
To use the credential store commands credStoreAdmin and userAdmin, you must set the following properties in OSM_home/SDK/XMLImportExport/build.properties:
xmlie.root.dir: The XML Import/Export application directory (/XMLImportExport) relative to the OSM SDK installation.
middlewareHome: The Fusion Middleware installation directory.
xmlie.root.modelDocument: The XML data file that contains the credential information (credential.xml).
xmlie.root.configDocument: The configuration file for the credStoreAdmin command (config/config.xml).
Note that the credStoreAdmin command does not use the other properties in the build.properties file.
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.
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.
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.
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
}
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.
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 on 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 (see "Configuring the Java Security Policy for the OSM Credential Store").
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.
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.
You must encrypt the passwords in the source XML document prior to running the userAdmin command. Otherwise, when you run userAdmin, you will trigger an error indicating that the EncryptPassword utility should be run. See "Using the EncryptPasswords Utility" for more information.
To run the userAdmin command, you should first modify the class path. If you are using the command-line script, modify the config.bat file (Windows) or the config.sh file (Unix). If you are using Ant, modify the xml.project.class.path in the build.xml file. Modify the appropriate file to ensure the following:
The file contains only one reference to the weblogic.jar file associated with the WebLogic Server installation to which the command is connecting. If there is no such reference, add it. If there is any reference pointing to the one under XMLImportExport/lib, change it.
The file contains only one reference to an ojdbcnn.jar file (where nn is a number) associated with the WebLogic Server instance to which the command is connecting. If there is a reference pointing to the file under XMLImportExport/lib, change it.
The file contains a reference to XMLImportExport/classes/schemaTypes.jar. If there is no such reference, add it.
The file does not contain any references to XMLImportExport/lib/nls_charset12.jar and XMLImportExport/lib/classes12.zip. If there are references to these files, remove them.
To set up your environment and run the command:
Define an XML file with the user information to add, similar to the sample shown below, and save this file in the XMLImportExport directory. See the OSM_home/SDK/XMLImportExport/models/UserAdmin.xsd file for more details on the XML schema.
<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>
Encrypt the passwords in your source XML file. See "Using the EncryptPasswords Utility."
If required, edit the config.xml file to modify your connection information to WebLogic Server. You must have the authority to administer users in WebLogic Server.
<j2eeAdminConnection> <user>weblogic</user> <password>password</password> <hostname>localhost</hostname> <port>7001</port> </j2eeAdminConnection>
Note:
The <password> element in the config.xml file is optional. If you opt not to specify the password in the <password> element, you will be prompted to supply it when you run the script.In the config.xml file, edit the credentialStore section to define the CredentialStore element as true:
<credentialStore addUser="true"/>
This enables the userAdmin command to perform credential store updates.
Run one of the following commands:
UNIX and Linux:
ant userAdmin
Windows:
userAdmin XMLModel XMLConfig
where:
XMLModel is the name of the XML model document containing the user information, and
XMLConfig is the name of the configuration file.
for example:
userAdmin data\users.xml config\config.xml
In the OSM Administrator, use the refresh buttons to refresh the Users and Workgroups lists, or use another method of refreshing the OSM metadata. For more information about refreshing OSM metadata, see "Refreshing OSM Metadata."
After the users have been created and assigned to workgroups/roles, you can assign functions and tasks to the roles using Design Studio.