Skip Headers
Oracle® Communications Order and Service Management System Administrator's Guide
Release 7.2.2

E35414-02
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

4 Securing Credentials Required to Access External Systems

Oracle Communications Order and Service Management (OSM) applications, such as OSM Web clients and OSM cartridge applications, often are required to provide credential information to gain access and log in to external systems. The credential information must be secure and cannot be hard coded in OSM code. This chapter describes how to secure credentials for accessing external systems by using a credential store, through the Fusion Middleware Credential Store Framework (CSF).

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 (PSS) 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 Command and API Reference Material" 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.

See the Oracle Fusion Middleware Application Security Guide at:

http://download.oracle.com/docs/cd/E12839_01/core.1111/e10043.pdf

for information on PSS and managing credentials in the credential store.

How OSM Retrieves Credentials from the Credential Store

The credential store in the WebLogic 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 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 (an XML Import/Export application 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:

  1. The automation plug-in script uses the getCredential or getOsmCredentialPassword method of the AutomationContext API.

  2. WebLogic Server checks the JPS (Java Platform Security) policy and confirms the automation plug-in has access permissions from the OSM domain to the credential store.

  3. 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.

  4. 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.

  5. The message is sent to the external system with the credential information.

  6. The automation task completes.

Using the Credential Store in OSM

OSM uses the credential store offered through CSF (see "About the Credential Store"). You can use the credential store to store the user name and password information that OSM and its applications require to log in to and send a request to external systems.

See "About the Credential Store" for a description of the credential store OSM uses by default.

See "How OSM Retrieves Credentials from the Credential Store" for information on how OSM retrieves the credentials from the credential store.

See "Managing Credentials in the Credential Store" for information on adding credentials to the credential store and managing credentials.

See "Developing Cartridges to Use the Credential Store" for information on developing OSM cartridges to use the credential store.

See "Upgrading Existing Cartridge Code to Use the Credential Store" to update your existing cartridge code to use the credential store.

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 PSS, credential store access permission is configured through the JPS policy. The default JPS policy instance is in the system-jazn-data.xml file in ${domain.home}/config/fmwconfig.

When you configure the JPS 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 JPS 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 JPS policy using your own map name.

In a clustered environment, use the administration server URL and not the managed server when you configure the credential store and the JPS policy.

To configure the JPS policy, you can use either of the following methods:

Verifying the Java Security Policy Configuration

To verify the JPS policy is configured for your credential store:

Open the ${domain.home}/config/fmwconfig/system-jazn-data.xml file and verify that it contains the following lines in bold text:

Note:

This JPS policy entry shows credential store access from the OSM application (oms) to the default OSM credential store map osm in the credential store.
<grant>
    <grantee>
        <codesource>
            <url>file:${domain.home}/servers/${weblogic.Name}/-</url>
        </codesource>
    </grantee>
    <permissions>
        <permission>             <class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>            <name>context=SYSTEM,mapName=osm,keyName=*</name>            <actions>read</actions>
        </permission>
    </permissions>
</grant>

Do not update the JPS policy configuration manually by editing system-jazn-data.xml directly. Use the methods described in "Configuring the Java Security Policy for the OSM Credential Store" to configure the JPS policy.

Configuring the Java Security Policy Using credStoreAdmin Command

To configure the JPS policy for the OSM credential store map using the credStoreAdmin command batch script (recommended method):

Note:

This procedure assumes you have:
  • Installed OSM.

  • Installed OSM SDK.

  1. Create and edit the configuration file for credStoreAdmin command (config.xml). See "Creating the Configuration File for the credStoreAdmin Command".

  2. Create and edit the XML data file for credStoreAdmin command (credential.xml). See "Creating the XML Data File for the credStoreAdmin Command". The JPS policy and credentials are configured based on the data in the credential.xml file.

  3. From the XML Import/Export application directory (OSM_home/SDK/XMLImportExport), 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.

  4. Set the required properties in the build.properties file. See "Setting Build Properties for Credential Store Commands".

  5. Run the credStoreAdmin batch script as follows:

    credStoreAdmin credential.xml config/config.xml
    
  6. When prompted, enter the password for WebLogic user.

  7. Verify the JPS policy is configured for your credential store as described in "Verifying the Java Security Policy Configuration".

  8. Restart WebLogic Server.

You can also configure the JPS policy for the OSM credential store map using the credStoreAdmin command Ant script.

To configure the JPS policy for the OSM credential store map using the credStoreAdmin command Ant script:

Note:

This procedure assumes you have:
  • Installed OSM.

  • Installed OSM SDK.

  1. Create and edit the configuration file for the credStoreAdmin command (config.xml). See "Creating the Configuration File for the credStoreAdmin Command".

  2. Create and edit the XML data file for the credStoreAdmin command (credential.xml). See "Creating the XML Data File for the credStoreAdmin Command".

  3. From the XML Import/Export application directory (OSM_home/SDK/XMLImportExport), set required properties in the build.properties file as described in "Setting Build Properties for Credential Store Commands".

  4. Run the credStoreAdmin Ant script and provide the WebLogic administrator user password in the command line as follows:

    >ant –Dwls_admin_password=password credStoreAdmin
    
  5. Verify the JPS policy is configured for your credential store as described in "Verifying the Java Security Policy Configuration".

  6. 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 credStoreAdmin Target in Another Ant Script".

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 console.

Store all OSM users in the default OSM map, osm, 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:

To manage credentials in the credential store using the userAdmin command:

  1. From the XML Import/Export application directory (OSM_home/SDK/XMLImportExport), set required properties in the build.properties file as described in "Setting Build Properties for Credential Store Commands".

  2. Create and edit the configuration file for the userAdmin command (config.xml). See "Creating the Configuration File for the userAdmin Command".

  3. Create and edit the XML data file for the userAdmin command (user.xml). See "Creating the XML Data File for the userAdmin Command".

    It is recommended that you do not enter password values in user.xml. By leaving password values empty, you can enter passwords interactively at run time.

  4. From the XML Import/Export application directory (OSM_home/SDK/XMLImportExport), do either of the following:

    • (Recommended method) Run the batch 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 Oracle Communications 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 UserAdmin Target in Another Ant Script".

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:

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

See "About 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 of 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

A data provider class in your cartridge where credential information is required by an external system must be set up to read the required credentials from the credential store. For information on setting up your data provider classes to be able to read from the credential store, see the following:

Using the Credential Store with Custom Data Providers

When you add a data provider class in your cartridge where credential information is required by 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 method retrieveInstance() of interface ExternalInstanceAdapter.

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 "ObjectelHPPTAdapter" 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.

If you use the SoapAdapter, add the input parameters:

  • Name of parameter "oms:credentials.mapname", contentType is "XPATH", default value is "myMap" (this example uses a custom map)

  • Name of parameter "oms:credentials.keyname", contentType is "XPATH", default value is "myUser"

If you use the ObjectHTTPAdapter, add the input parameters:

  • Name of parameter "obj:mapname", contentType is "XPATH", default value is "osm" (this example uses the default map)

  • Name of parameter "obj:keyname", contentType is "XPATH", default value is "osmUser_osm" (this example uses user "osm" stored in default map)

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 on developing cartridges to use the credential store.

In addition to upgrading your cartridge code, provision the credential store for the WebLogic domain for OSM applications with required credentials (see "Managing Credentials in the Credential Store") and configure the JPS policy for the WebLogic domain to allow OSM access to the credential store (see "Configuring the Java Security Policy for the OSM 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 built-in SOAPAdapter 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 the user name only in the parameter. When you use your custom credential store map, automation plug-in users 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:

  1. Remove hard coded passwords from the existing "oms:credentials:password" input parameter.

  2. Ensure that credentials exist in the credential store under map="osm" key="osmUser_"+<SoapRequest_username>.

  3. Test that the SOAP adapter works correctly after the update.

OSM Credential Store Commands

OSM offers two credential store commands available in the XML Import/Export application which can be used for OSM credential store setup or management:

See "Using the XML Import/Export Application" for information on using the XML Import/Export application.

Setting Build Properties for Credential Store Commands

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) in 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.


OSM Credential Store Command and API Reference Material

To develop OSM cartridges to use the credential store offered through CSF (see "About the Credential Store"), use the OSM credential store APIs. OSM credential store APIs are wrapper APIs to the CSF APIs. Use the OSM credential store APIs in your OSM-related code that requires credential retrieval, such as in data providers and automation plug-ins.

The OSM credential store APIs and credential store-related classes are:


userAdmin Command

The userAdmin command is part of the XML Import/Export application and is used to administer OSM users and workgroups. The userAdmin command also supports credential store management.

Use the userAdmin command to create an OSM user and also add the user in the credential store.

For credential-store related interface and object details, see "J2ee Manager/WLUserManager" and "UserAdminOperation".

Use the userAdmin command to add OSM users to the default OSM credential store (to the default map with default key values).

Syntax

Batch script:

userAdmin user.xml config/config.xml

Ant script:

ant userAdmin

Creating the XML Data File for the userAdmin Command

To create the XML data file for the userAdmin command (user.xml):

Important:

Remove the file when the operation is complete because it contains unencrypted passwords.

Example input data file (user.xml):

<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>mypassword1</password >
   </user>
   <user name="testOsmUser2">
         <description>OSM test user 2</description >
         <password>mypassword2</password >
   </user>
   <clientGroup>
         <user>testOsmUser1</user>
         <user>testOsmUser2</user>
   </clientGroup>
   <automationGroup>
         <user>testOsmUser1</user>
         <user>testOsmUser2</user>
   </automationGroup>
   <wsAPIGroup>
         <user>testOsmUser1</user>
         <user>testOsmUser2</user>
   </wsAPIGroup>
   <xmlAPIGroup>
         <user>testOsmUser1</user>
         <user>testOsmUser2</user>
   </xmlAPIGroup>
   <workgroup name="testRole1">
         <user>testOsmUser1</user>
   </workgroup>
   <workgroup name="testRole2">
         <user>testOsmUser2</user>
   </workgroup>
</userConfig>

Creating the Configuration File for the userAdmin Command

To create the configuration file for the userAdmin command (config.xml):

  1. Copy the sample XML Import/Export application configuration file config/config_sample.xml and rename it to config/config.xml.

  2. Edit the "j2eeAdminConnection" and "log" sections of the file with your installation information.

    The following is an example "j2eeAdminConnection" section which contains the data for WebLogic Server:

    <j2eeAdminConnection>
        <user>weblogic</user>
        <password/>
        <hostname>localhost</hostname>
        <port>7001</port>
    </j2eeAdminConnection>
    

    When the password value is empty in the configuration file, which is the recommended approach for security purposes, you must):

    • Input the password at run time when prompted if running the batch script or Ant task.

  3. Edit the "credentialStore" section to define the credentialStore element as true:

    <credentialStore addUser="true"/>
    

    This enables the userAdmin command to perform credential store updates.

  4. (Optional) Edit the "databaseConnection" section.

    If you configure workgroups using the userAdmin command and the XML data file contains "workgroup" sections, you are required to edit this section. However, it is better to avoid configuring workgroups using the userAdmin command because it requires setting up database connection parameters in the configuration file which is not a secure approach. Instead, it is recommended that you configure workgroups after OSM user is created using OSM Administrator or during cartridge deployment.

Usage Notes

The userAdmin command can create a new WebLogic user and add the user to the OSM default credential store map at the same time.

Calling UserAdmin Target in Another Ant Script

The following is an example on how to invoke the userAdmin Ant script in your own Ant script:

<target description="Configure OSM user" name="setupUsers" depends="wls_password">
      <echo message="Create users in WebLogic and Credential Store"/>
          <ant inheritRefs="true" antfile="${xmlieRoot}/build.xml" dir="${xmlieRoot}" target="userAdmin">
                   <property name="wls_admin_user" value="weblogic"/>
                   <property name="wls_admin_password" value="${wls.password}"/>
                   <property name="wls_host" value="localhost"/>
                   <property name="wls_port" value="7001"/>
                   <property name="middlewareHome" value="${middleware.home}"/>
                   <property name="xmlie.root.modelDocument" value="user.xml"/>
                   <property name="xmlie.root.configDocument" value="config.xml"/>
          </ant>
  </target>
  <target name="wls_password">
      <input message=" Enter WebLogic Admin User Password:  " addproperty="wls.password">
          <handler classname="org.apache.tools.ant.input.SecureInputHandler"/>
      </input>
  </target>    
</input>  
</target>

J2ee Manager/WLUserManager

Business Object Name: J2eeManager/WLUserManager

Business Object Component Name: Package name: com.mslv.oms.j2ee.useradmin

Description: This class is used to create J2EE user in WebLogic and add the user to appropriate J2EE groups. It can also add the user in the WebLogic CSF credential store.

Attributes

credStoreName

Type: ObjectName

Description: MBean object for credential store: JpsJmxConstants.MBEAN_JPS_CREDENTIAL_STORE

Business Object Operations

Operation Name: createUserInCredentialStore

Description: Method which adds the user in credential store.

If the map/key pair exists in the credential store already, it will be overwritten with new values.

UserAdminOperation

Business Object Name: UserAdminOperation

Business Object Component Name: Package name com.mslv.oms.metadatahandler.operation

Description: This class is used to create J2EE user in WebLogic, and add the user to appropriate J2EE groups. It also can add the user in the credential store.

Attributes

Business Object Operations

Operation Name: configureJ2eeUsers

Description: This method can add users to the credential store.

After a user is created in the J2EE server, a check is made if configuration is defined to add the user in the credential store. The following line is the example configuration (the default value of this configuration is set to "false"):

<credentialStore addUser="true"/>

The user is added to the credential store using the default map name OSM_CREDENTIAL_MAPNAME and default key name OSM_CREDENTIAL_KEYNAME_PREFIX+OSM_username. For example, if OSM user name is "osmlf", then the map and key values used for it will be map="osm" and key="osmUser_osmlf".


credStoreAdmin Command

Use the credStoreAdmin command to configure the JPS policy for the credential store and to manage credentials in the credential store.

Cartridges can use the credStoreAdmin command to create and configure credential stores during setup.

The credStoreAdmin command is available as an Ant script and as a batch script in the XML Import/Export application (which is included in the OSM SDK package). The batch script supports interactive mode which allows users to input passwords at run time; this is the recommended method of using the credStoreAdmin command because entering the password at run time is a more secure approach.

See "Configuring the Java Security Policy for the OSM Credential Store" for instructions on configuring the JPS policy for the OSM credential store map using the credStoreAdmin command.

See "Managing Credentials in the Credential Store" for information on using the credStoreAdmin command to manage credentials in the credential store.

ANT Task Name

credStoreAdmin

Batch Script Name

credStoreAdmin.bat (Windows)

Schema File

The schema file for the credStoreAdmin command is OSM_home/SDK/XMLImportExport/models/CredStoreAdmin.xsd

Task Arguments

XML data file that contains credential information: credentials.xml (see "Creating the XML Data File for the credStoreAdmin Command" for information on creating this file).

XMILE configuration file: config.xml

WLS administrator password (if not provided in config.xml)

If the WLS administrator password is provided in the command line, the following values can be passed in also:

Note:

This mode is used when a cartridge uses this command to create and configure credential stores during setup.

Schema File Input Data Format

The following is the schema for the XML Import/Export application configuration file (config.xsd):

<xs:element name="configuration">
   <xs:complexType>
         <xs:sequence>
            ……
               <xs:element name="credentialStore" type="oms:credentialStoreType" minOccurs="0">
                  <xs:annotation>
<xs:documentation>It determines if user should be added in OSM credential store for new OSM user. The default would be no if node not exist.</xs:documentation>
                  </xs:annotation>
               </xs:element>
         </xs:sequence>
   </xs:complexType>
</xs:element>
……
<xs:complexType name="credentialStoreType">
      <xs:annotation>
            <xs:documentation>It determines if user should be added in OSM credential store for new OSM user. The default would be no if node not exist.</xs:documentation>
      </xs:annotation>
      <xs:attribute name="addUser" type="xs:boolean" default="false"/>
</xs:complexType>

Creating the XML Data File for the credStoreAdmin Command

The following is an example XML data file for the credStoreAdmin command (credential.xml). This example uses the map name osm, the default map for OSM applications. If you do not use the default map, replace 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:jpsPolicy operation="add">
      <ns2:mapname>osm</ns2:mapname>
    </ns2:jpsPolicy>
 </ns2:CredentialConfig>

Creating the Configuration File for the credStoreAdmin Command

To create the configuration file (config/config.xml):

  1. Copy the sample configuration file config/config_sample.xml and rename it to config/config.xml.

  2. Edit the "j2eeAdminConnection" and "log" section of the file with your installation information.

    Note that other sections of the file are not used in the credStoreAdmin command, but they must exist and can use dummy values.

    The following is an example "j2eeAdminConnection" section which contains the data for WebLogic Server; for example.

    <j2eeAdminConnection>
        <user>weblogic</user>
        <password/>
        <hostname>localhost</hostname>
        <port>7001</port>
    </j2eeAdminConnection>
    

    When the password value is empty in the configuration file (which is the recommended approach for better security):

    • You must input the password at run time when prompted if running the batch script or Ant task.

Calling credStoreAdmin Target in Another Ant Script

The credStoreAdmin target can be called directly in Ant scripts or batch scripts; this capability can be used during an OSM installation with OSM cartridges and custom cartridges.

The following is an example of how to call the credStoreAdmin target in another Ant script:

<target description="Configure JPS Policy" name="setupJPSPolicy" depends="wls_password">
      <echo message="Configure JPS Policy for default credential store in WebLogic"/>
          <ant inheritRefs="true" antfile="${xmlieRoot}/build.xml" dir="${xmlieRoot}" target="credStoreAdmin">
            <property name="wls_admin_user" value="weblogic"/>
            <property name="wls_admin_password" value="${wls.password}"/>
            <property name="wls_host" value="localhost"/>
            <property name="wls_port" value="7001"/>
            <property name="middlewareHome" value="${middleware.home}"/>
            <property name="xmlie.root.modelDocument" value="credential.xml"/>
            <property name="xmlie.root.configDocument" value="config.xml"/>
          </ant>  
</target>
  <target name="wls_password">
      <input message=" Enter WebLogic Admin User Password:  " addproperty="wls.password">
          <handler classname="org.apache.tools.ant.input.SecureInputHandler"/>
      </input>
</target>

If the Ant target "credStoreAdmin" is called by another Ant script, which is running in your Design Studio workspace, interactive mode is not supported. In this case, passwords must be provided in the XML data file.

Note:

It is recommended that you delete this data file immediately after use because it contains unencrypted passwords.

The following is an example of an XML data file that contains the passwords for user osm and osmlf:

<?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">
      <ns2:mapname>osm</ns2:mapname>
      <ns2:keyname>osmUser_osm</ns2:keyname>
      <ns2:user>osm</ns2:user>
      <ns2:password>osmAdmin</ns2:password>
    </ns2:credential>
    <ns2:credential operation="create">
      <ns2:mapname>osmlf</ns2:mapname>
      <ns2:keyname>osmUser_osmlf</ns2:keyname>
      <ns2:user>osmlf</ns2:user>
      <ns2:password>osmlfAdmin</ns2:password>
    </ns2:credential>
 </ns2:CredentialConfig>

Business Object Operations for credStoreAdminOperation

For business operations for credStoreAdminOperation, see "CredStoreAdminOperation".

CredStoreAdminOperation

Business Object Name: CredStoreAdminOperation

Business Object Component Name: Package name: com.mslv.oms.metadatahandler.operation

Description: This new class is used to configure the JPS policy for your custom credential store map and to manage credentials in the credential store.

Attributes

Business Object Operations

configJPSPolicy

This method is used to:

  • Update the JPS policy to use the default credential store map (the default map is not configured during OSM installation).

  • Configure the JPS policy with an entry for your custom credential store map. The supported operations are add and remove.

    Example credential data in XML file with JPS policy information:

    ……
       <jpspolicy operation="add">
          <mapname>osm_systemAmap</mapname>
       </jpspolicy >
      ……
    
configCredentialStore

This method is used to manage credentials in the WebLogic Server credential store. Use this command to manage credentials of external systems. Use the "userAdmin Command" to configure the OSM user in the credential store.

Example credential data in the XML file with credential information:

……
   <credential operation="create">
      <mapname>osm_systemAmap</mapname>
      <keyname>user1</keyname>
      <user>mobileUser1</user>
      <password>user1pwd</password>
   </credential>
……

Supported operations are create, update, and delete.

Note: If create fails when specified map/key values already exist in the credential store, set attribute "overwrite" to "false".

Note: Password value can be provided through console input.


CredStore

Credential store object.

The credential store object is the domain credential store class which contains a single instance of the CredentialStore object. The JpsServiceLocator APIs in the Credential Store Framework look up the single instance of the CredentialStore object.

Package name: com.mslv.oms.security.credstore

Package name

com.mslv.oms.security.credstore

Attributes

Name: store

Type: Oracle.security.jps.service.credstore.CredentialStore

Description: A reference object to the JPS credential store object.

Business Object Operations

getInstance

Description: Return an instance of the object. Only a single instance of the class is ever created. If "store" is not initiated, look up the credential store from class "oracle.security.jps.service.credstore.CredentialStore".

Operation Outputs: Output Name: store; Type: CredStore; Description: An instance of the CredentialStore object.

getJPSCredentialStore

Description: Retrieving attribute "store".

Operation Outputs: Output Name: store; Type: oracle.security.jps.service.CredentialStore.

Output of new methods

An instance of the object is returned by getInstance(). At the first time invocation, object will be initiated, and a credential store of class Oracle.security.jps.service.credstore.CredentialStore is resolved through the CSF lookup API.

Error Conditions

Improper JPS configuration can cause credential store lookup to fail.

Usage Notes

This API can be used directly if you have your own implementation JAVA class of "ViewRuleContext" and "AutomationContext".


PasswordCredStore

Password credential store object.

Use com.mslv.oms.security.credstore.PasswordCredStore APIs in your JAVA classes to retrieve user name and password from the credential store.

Package Name

com.mslv.oms.security.credstore

Attributes

Business Object Operations

Operation Name: getPasswordCredential
Description

Return a PasswordCredential object stored with specified map and key names.

Input Parameters
mapName

Type: String

Description: Map name of the stored password credential object

keyName

Type: String

Description: Key name of the stored password credential object

Operation Outputs
passwordCredential

Type: PasswordCredential

Description: An object of Oracle.security.jps.service.credstore.PasswordCredential, which contains credential information stored under map and key name pair.

Operation Name: getCredential
Description

Return a string of user name and password for specified map and key names.

Input Parameters
mapName

Type: String

Description: Map name of the stored password credential object

keyName

Type: String

Description: Key name of the stored password credential object

Operation Outputs

Type: String

Description: A string contains user name and password information stored under map and key name pair. Format is "username/password".

Operation Name: getOsmCredentialPassword
Description

Return password value for specified OSM user. This API is used to access credentials stored in the credential store using the default map and key names that follow OSM naming convention:

  • Map name is osm

  • Key name is osmUser_+username

Input Parameters
username

Type: String

Description: OSM user name.

Operation Outputs

Type: String

Description: A string contains password value for specified OSM user. OSM user name and password values are stored under credential store with map value OSM_CREDENTIAL_MAPNAME, and key value starts with OSM_CREDENTIAL_KEYNAME_PREFIX, following with user name.

Operation Name: getCredentialAsXML
Description

Return user name and password in XML format for specified map and key names.

Input Parameters
mapName

Type: String

Description: Map name of the stored password credential object

keyName

Type: String

Description: Key name of the stored password credential object

Operation Outputs

Type: org.w3c.dom.Element

Description: An element that contains user name and password information stored under map and key name pair.

Output of Methods

These methods will return a PasswordCredential/String/Element object if the credential store contains a credential with specified map name and key name. If a match is not found, null value will be returned.

Error Conditions

Improper JPS configuration can cause "read" operation on the credential store to fail due to "no permission" error. Incorrect map and key names can cause "no credential found" problem.

Usage Notes

This API can be used directly if you have your own implementation JAVA class of "ViewRuleContext" and "AutomationContext".

Example: Retrieve Password from OSM Default Map Given User Name

        PasswordCredStore pwdCredStore;
        try {
             pwdCredStore = new PasswordCredStore();
          return pwdCredStore.getOsmCredentialPassword(username);
       } catch (final Exception e) {
           throw new AutomationException("Fail to find password credential with specified map and key name.", e);
  }

Example: Retrieve Password from Custom Map Given Map and Key Names Used to Store the Credentials

PasswordCredStore pwdCredStore;
 try {
           pwdCredStore = new PasswordCredStore();
return pwdCredStore.getCredentialAsXML(map, key);
     } catch (final Exception e) {
 throw new AutomationException("Fail to find password credential with specified map and key name.", e);
}

CredStoreException

Credential store exception object.

Package Name

com.mslv.oms.security.credstore

Attributes

Name: target

Type: Exception

Description: Target exception is the original exception caught in the three OSM credential store classes: CredStore, PasswordCredStore, JPSPasswordCredential.

Business Object Operations

Operation Name: getTargetException
Description

Get attribute "target".

Operation Outputs
exception

Type: Exception

Usage Notes

This API can be used directly if you have your own implementation JAVA class of "ViewRuleContext" and "AutomationContext".


SoapAdapter

Use the attributes for the credential store when you define data provider instances in your cartridges.

For detailed information on data provider adapters, see the discussion on behaviors in OSM Developer's Guide.

Description

Built-in adapter.

Attributes

Business Object Operations

Operation Name: retrieveInstance
Description

This method includes support to retrieve credential information from the credential store, from map and key name parameters if provided.

Business Logic

The business logic for retrieveInstance is as follows:

  • If "oms:credentials.username" is provided in parameters:

    If "oms:credentials.password" is also provided in parameter, then input values are used directly.

    If "oms:credentials.password" is not provided in the parameter, call context API "getOsmCredentialPassword(username)" to retrieve the password value from the credential store and use it in the SOAP request.

  • Otherwise, if "oms:credentials.mapname" and "oms:credentials.keyname" are provided in the parameters, call context API "getCredential(mapname, keyname)" to retrieve user name and password, and use them in the SOAP request.

Error Conditions

Invalid map and key names can cause credential lookup to return a "null" object.

Message text is "Password credential with map name %s and key name %s does not exist in the credential store."

Usage Notes

Do not use operation APIs directly in this object.


ObjectelHPPTAdapter

Use the attributes for the credential store when you define data provider instances in your cartridges.

For detailed information on data provider adapters, see the discussion on behaviors in OSM Developer's Guide.

Description

Built-in adapter. Objectel HTTP adapter.

Attributes

Business Object Operations

Operation Name: parseParameters
Description

This method includes support to parse parameters for credential store map and key names. Add context to input parameter. Same method in the super class will be changed as well.

Input Parameters

Context

Type: ViewRuleContext

Operation Name: sendCommand
Description

This method includes support to retrieve credential information from the credential store, from map and key name parameters if provided.

Business Logic

The business logic for sendCommand is as follows:

  • If "obj.user_name" is provided in the parameters:

    If "obj:password" is also provided in the parameter, then input values are used directly.

    If "obj:password" is not provided in the parameter, call context API "getOsmCredentialPassword(username)" to retrieve password value from the credential store and use it in the SOAP request.

  • Otherwise, if "obj:mapname" and "obj:keyname:" are provided in parameters, call context API "getCredential(mapname, keyname)" to retrieve user name and password and use them in the SOAP request (after the command, the code will send a SOAP message via HTTP to the specified URL).

Usage Notes

Do not use operation APIs directly in this object.

Error Conditions

Invalid map and key names can cause credential lookup to return a "null" object.

Message name: ViewRuleFailedException

Message text: "Password credential with map name %s and key name %s does not exist in the credential store."


ViewRuleContext

Use operation APIs defined in this interface object for the credential store.

Description

Interface object.

Business Object Operations

Operation Name: getCredential
Description

Return a string of user name and password for specified map and key names.

Input Parameters
map

Type: String

Description: Map name

key

Type: String

Description: Key name

Operation Outputs

Type: String

Description: A string contains user name and password information stored under map and key name pair. Format is "username/password".

Details on operation getCredential():

/**
     * Get user name and password values in string format from credential store, given map and key values. 
     * 
     * @param map
     *            Map name of the credential stored in domain credential store.
     * @param key
     *            Key name of the credential stored in domain credential store.
     * @return A String that contains user name and password values, separated by "/"
     * @throws CredStoreException
     *             If the application cannot access credential store, or if there is no permission to read the credential store with given
     *             map and key values, or if the credential is expired.
     */
    String getCredential(final String map, final String key) throws TransformerException;
Operation Name: getOsmCredentialPassword
Description

Return password value for specified OSM user. This API is used to access credentials stored in the credential store using the default map and key names that follow OSM naming convention:

  • Map name is osm

  • Key name is osmUser_+username

Input Parameters
username

Type: String

Description: OSM user name.

Operation Outputs

Type: String

Description: Return password value for specified OSM user. OSM user name and password values are stored under credential store with map value OSM_CREDENTIAL_MAPNAME, and key value starts with OSM_CREDENTIAL_KEYNAME_PREFIX, following with user name.

Error Conditions

Improper JPS configuration can cause creation of PasswordCredStore to fail.

Message Name: ViewRuleFailedException

Message Text: "Fail to create PasswordCredStore."

Usage Notes

This API is often used in XQuery scripts.


AutomationContext

Use operation APIs from AutomationContext interface to retrieve credentials in XQuery code for automation tasks.

See "Example: Retrieve Password from OSM Default Map Given User Name".

See "Example: Retrieve Password from Custom Map Given Map and Key Names Used to Store the Credential".

Description

Interface object.

Business Object Operations

Operation Name: getCredentialAsXML
Description

Get user name and password values in XML format given map and key values of the credential.

Input Parameters
map

Type: String

Description: Map name

key

Type: String

Description: Key name

Operation Outputs

Type: org.w3c.dom.Element

Description: An element that contains user name and password information stored under map and key name pair.

Details on operation getCredentialAsXML():

/**
     * Get user name and password values in XML format given map and key values of the credential. 
     * 
     * @param map
     *            Map name of the credential stored in domain credential store.
     * @param key
     *            Key name of the credential stored in domain credential store.
     * 
     * @return User name and password for the user in this XML format:
     *     <Credential xmlns=\"urn:com:metasolv:oms:xmlapi:1\">
     *         <Username>NAME</Username>
     *         <Password>PASSWORD</Password>
     *     </Credential>
     * @throws CredStoreException
     *             If the application cannot access credential store, or if there is no permission to read the credential store with given
     *             map and key values, or if the credential is expired.
     */
    Document getCredentialAsXML(final String map, final String key) throws AutomationException, RemoteException;
Operation Name: getOsmCredentialPassword
Description

Return password value for specified OSM user. This API is used to access credentials stored in the credential store using the default map and key names that follow OSM naming convention:

  • Map name is osm

  • Key name is osmUser_+username

Input Parameters
username

Type: String

Description: OSM user name.

Operation Outputs

Type: String

Description: Password value for specified OSM user. OSM user name and password values are stored under credential store with map value OSM_CREDENTIAL_MAPNAME, and key value starts with OSM_CREDENTIAL_KEYNAME_PREFIX, following with user name.

Error Conditions

Fail to read credential store due to improper JPS configuration or invalid map and key names.

Message Name: AutomationException

Message Text: "Fail to create PasswordCredStore. Password credential with map name %s and key name %s does not exist in the credential store."

Example: Retrieve Password from OSM Default Map Given User Name

declare variable $context external;
let $osmPwd := context:getOsmCredentialPassword($context, $username)

Example: Retrieve Password from Custom Map Given Map and Key Names Used to Store the Credential

Note:

This example assumes your map name is (osmTest).
declare namespace oms="urn:com:metasolv:oms:xmlapi:1";
declare variable $context external;
let $customCred := context:getCredentialAsXML($context, "osmTest", $username)/oms:Credential
let $customerName := $customCred/oms:Username/text()
let $customPwd := $customCred/oms:Password/text()