1. System Administrator's Guide
  2. OSM Credential Store API Command Reference

A OSM Credential Store API Command Reference

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 Oracle Fusion Middleware Credential Store Framework (CSF).

The OSM credential store APIs and credential store-related classes are listed in Table A-1:

Table A-1 Credential Store API Commands and Classes

Command or Class Description

userAdmin Command

This command adds an OSM user to a WebLogic Server security realm. If the user does not already exist in the credential store, this script will add it with default values.

credStoreAdmin Command

This command to configures the Java Platform Security policy for the credential store and manages credentials in the credential store.

CredStore

This is the credential store object, which is the domain credential store class and contains a single instance of the CredentialStore object.

PasswordCredStore

This is the password credential store object.

CredStoreException

This is the credential store exception object.

SoapAdapter

The attributes in this class provide the attributes for the credential store when you define SOAP data provider instances in your cartridges.

ObjectelHTTPAdapter

The attributes in this class provide the attributes for the credential store when you define Objectel HTTP data provider instances in your cartridges.

ViewRuleContext

This interface object provides operations for the credential store.

AutomationContext

This interface object provides operations for retrieving information from the credential store in automations.

OSM User Security and Credential Store Commands

To develop OSM cartridges to use the credential store offered through CSF (see "Using 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.

userAdmin Command

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

You can do the following with the userAdmin command:

  • add users to WebLogic Server security realms

  • add users to WebLogic Server groups

  • add users to OSM workgroups (roles)

You should add users to a security realm after they have been added to the credential store. For more information about adding users to the credential store, see "Managing Credentials in the Credential Store." However, if you do add a user using userAdmin command and the user has not already been added to the credential store, you can configure the userAdmin command also to add the user to the credential store with the keyname in the format osmUser_username in the osm map. For more information, see "Creating the Configuration XML File for the userAdmin Command."

For detailed instructions on using the userAdmin command, see "Using the userAdmin Command."

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

Schema File

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

Creating the XML Data File for the userAdmin Command

The following is an example XML data file for the userAdmin command (for example, 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>password_from_createEncryptPasswords</password>
      <saltstore>/u01/security/testOsmUser1/salt.store</saltstore>
   </user>
   <user name="testOsmUser2">
      <description>OSM test user 2</description >
      <password>password_from_createEncryptPasswords</password>
      <saltstore>/u01/security/testOsmUser2/salt.store</saltstore>
   </user>
   <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>

Following are descriptions of some of the elements in the XML data file:

  • userConfig/user: The name of the user to add to the security realm. Use the name attribute to contain the name of the user. If this user does not exist in the credential store, the user will also be added to the credential store with the map name osm and the key name osmUser_username.

  • password: Enter the password that was output from the createEncryptPassword command. For more information, see "Using the CreateEncryptPasswords Utility."

  • saltstore: Enter the current name and location of the salt.store file that was created when you ran the createEncryptPassword command. For more information, see "Using the CreateEncryptPasswords Utility."

  • clientGroup: The name of the workgroup (role in Oracle Communications Design Studio) to which the contained users should be added.

  • clientGroup/user: The name of a user to add to the workgroup/role.

Creating the Configuration XML File for the userAdmin Command

You should create a configuration file that contains information about your environment.

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

  1. Copy the sample XML Import/Export application configuration file OSM_home/SDK/XMLImportExport/config/config_sample.xml and rename it (for example, to config.xml).

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

    Following is the format of the j2eeAdminConnection section: 

    <j2eeAdminConnection>
   <user>admin_user</user>
   <password>password</password>
   <protocol>t3</protocol>
   <hostname>host_name</hostname>
   <port>port</port>
</j2eeAdminConnection>

    where admin_user is an administrative WebLogic Server user, host_name is the name of the server that WebLogic Server is running on, and port is the listen port for WebLogic Server. The value of the password element does not matter. Do not include your real plain-text password here.

    If you want to connect to the WebLogic server using SSL, see "Using SSL Connections."

  3. Edit the log tag of the file so that the logFileUrl attribute points to a valid location on your system.

  4. If you want the userAdmin command to add users to the credential store if not already present, edit the credentialStore tag to define the addUser attribute as true: 

    <credentialStore addUser="true"/>

    This enables the userAdmin command to perform credential store updates.

  5. If you configure workgroups using the userAdmin command (the XML data file contains workgroup sections), edit the databaseConnection section.

    Following is the format of the databaseConnection section:

    <databaseConnection>
   <user>db_user_name</user>
   <password>password</password>
   <dataSource>jdbc:oracle:thin:@hostname:port:SID</dataSource>
</databaseConnection>

    where db_user_user is the OSM database user, hostname is the name of the server that the database is running on, port is the listener port for the database, and SID is the identifier for your database. The value of the password element does not matter. Do not include your real plain-text password here.

  6. Use the EncryptPasswords utility to insert the encrypted passwords in the file. See "Using the EncryptPasswords Utility" for instructions on using this utility.

Editing the Configuration Script for the userAdmin Command

You should edit the configuration script with the appropriate values for your environment.

To edit the configuration script for UNIX or Linux:

  1. If the following are all true, you do not need to perform this step:

    • In the terminal where you are going to run userAdmin, you have the JAVA_HOME and MIDDLEWARE_HOME environment variables set to the correct values.

    • You are running the userAdmin.sh command from the OSM_home/SDK/XMLImportExport directory.

  2. If the conditions in step 1 are not all true, edit the OSM_home/SDK/XMLImportExport/config.sh file, and make the following changes:

    • If the JAVA_HOME environment variable is not set, at the very beginning of the "user configuration below here" section, add the following line:

      export JAVA_HOME="path"

      where path is the path to the appropriate version of Java.

    • If the MIDDLEWARE_HOME variable is not set, uncomment and update the following line so that it points to the location where Oracle Fusion Middleware is installed:

      #export MIDDLEWARE_HOME=/Oracle/middleware

    • If you are not running the userAdmin script from the OSM_home/SDK/XMLImportExport directory, update the following line so that it points to the OSM_home/SDK/XMLImportExport directory: 

      export APP_ROOT="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

      For example:

      export APP_ROOT="/u01/osmdir/SDK/XMLImportExport"

  3. If you are not running the userAdmin script from the OSM_home/SDK/XMLImportExport directory, move the config.sh file to the directory from which you are running the userAdmin.sh script.

To edit the configuration script for Windows:

  1. If the following are all true, you do not need to perform this step:

    • You have the JAVA_HOME and MIDDLEWARE_HOME environment variables set to the correct values.

    • You are running the userAdmin.bat command from the OSM_home/SDK/XMLImportExport directory.

  2. If the conditions in step 1 are not all true, edit the OSM_home/SDK/XMLImportExport/config.bat file, and make the following changes:

    • If the JAVA_HOME environment variable is not set, edit the following line to point to the location of the appropriate version of Java:

      set JAVA_HOME=%JAVA_HOME%

      For example:

      set JAVA_HOME=%"C:\Program Files\Java\Java8"%

    • If the MIDDLEWARE_HOME variable is not set, uncomment and update the following line so that it points to the location where Oracle Fusion Middleware is installed:

      @rem set MIDDLEWARE_HOME=%MIDDLEWARE_HOME%

    • If you are not running the userAdmin script from the OSM_home/SDK/XMLImportExport directory, update the following line so that it points to the OSM_home/SDK/XMLImportExport directory: 

      set APP_ROOT=%~sdp0

      For example:

      set APP_ROOT="C:\Oracle\OSM\SDK\XMLImportExport"

  3. If you are not running the userAdmin script from the OSM_home/SDK/XMLImportExport directory, move the config.bat file to the directory from which you are running the userAdmin.bat script.

Using the userAdmin Command

You can do the following with the userAdmin command:

  • add users to WebLogic Server security realms

  • add users to WebLogic Server groups

  • add users to OSM workgroups (roles)

You should add users to a security realm after they have been added to the credential store. For more information about adding users to the credential store, see "Managing Credentials in the Credential Store." However, if you do add a user using userAdmin command and the user has not already been added to the credential store, the userAdmin command will also add the user to the credential store in the osm map.

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 EncryptPasswords utility should be run. See "Using the EncryptPasswords Utility" for more information.

The userAdmin command can be used in two ways. You can run a script on either UNIX/Linux or Windows, or you can run the command as an Ant target. The instructions for both methods are below.

To run the userAdmin command as a script:

  1. Encrypt the user passwords for use in the XML data file. See "Using the CreateEncryptPasswords Utility" for more information.

  2. Create an XML data file for the userAdmin command. See "Creating the XML Data File for the userAdmin Command."

  3. Create a configuration file for the userAdmin command. See "Creating the Configuration XML File for the userAdmin Command."

  4. Edit the configuration script with information about your environment. See "Editing the Configuration Script for the userAdmin Command."

  5. Run the following command:

    UNIX or Linux:

    userAdmin.sh data_file config_file

    Windows:

    userAdmin.bat data_file config_file

    where data_file is the XML data file that you created in step 2 and config_file is the configuration file you created in step 3. This script is ordinarily located in the OSM_home/SDK/XMLImportExport directory, but it is possible to run it from somewhere else. For information about running the script from another location, see "Editing the Configuration Script for the userAdmin Command."

To run userAdmin as an Ant target:

  1. Create an XML data file for the userAdmin command. See "Creating the XML Data File for the userAdmin Command."

  2. Create a configuration file for the userAdmin command. See "Creating the Configuration XML File for the userAdmin Command."

  3. From the OSM_home/SDK/XMLImportExport directory, set the following properties in the build.properties file:

    • xmlie.root.dir: The XML Import/Export application directory relative to the OSM SDK installation (for example, /XMLImportExport).

    • middlewareHome: The Fusion Middleware installation directory.

    • xmlie.root.modelDocument: The XML data file that you created in step 1.

    • xmlie.root.configDocument: The configuration file that you created in step 2.

    The other properties in the build.properties file are not used by the userAdmin target.

  4. Run the following command:

    ant userAdmin

Calling the 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>

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 Server and add the user to appropriate J2EE groups. It can also add the user in the WebLogic Server 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 Server, and add the user to appropriate J2EE groups. It also can add the user in the credential store.

Attributes

  • OSM_CREDENTIAL_MAPNAME

    Type: String (static final)

    Sensitive: Value is "osm"

    Description: Pre-defined map name for OSM application in credential store.

  • OSM_CREDENTIAL_KEYNAME_PREFIX

    Type: String (static final)

    Sensitive: Value is "osmUser_"

    Description: Prefix of key names used for OSM users in credential store.

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 "osm2", then the map and key values used for it will be:

  • map="osm"

  • key="osmUser_osm2"

credStoreAdmin Command

Use the credStoreAdmin command to configure the Java Platform Security 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.

For detailed instructions on using the credStoreAdmin command, see "Using the credStoreAdmin Command."

See "Configuring the Java Security Policy for the OSM Credential Store" for instructions on configuring the Java Platform Security 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.

You must create encrypted passwords to use in this script before running it. See "Using the CreateEncryptPasswords Utility" for more information.

Schema File

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

Creating the XML Data File for the credStoreAdmin Command

The following is an example XML data file for the credStoreAdmin command (for example, credential.xml). This example uses the map name osm. It is a good idea to create this map, since some operations use that as the default value for the map name. 

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

Following are descriptions of some of the elements in the XML data file:

  • jpsPolicy: This element contains the name of a map to add or remove. Use the operation attribute to determine the action to perform on the map. Available values for the operation attribute are:

    • add: Add a new credential store map. It is a good idea to use osm as the name of the primary (or only) map.

    • remove: Remove an existing credential store map.

  • credential: This element contains information about a user to be added, modified, or removed from the credential store. Use the operation attribute to determine the action to perform on the user. Available values for the operation attribute are:

    • create: Add a new user.

    • modify: Change the password for an existing user.

    • delete: Delete an existing user from the credential store.

    Set the overwrite attribute to true.

  • mapname: The name of the credential store to which the user should be added.

  • keyname: The key value for the user in the credential store. Oracle recommends using osmUser_username as the key value, where username is the name of the OSM user.

  • user: The name of the user to add to the credential store.

  • password: Enter the password that was output from the createEncryptPasswords command. For more information, see "Using the CreateEncryptPasswords Utility."

  • saltstore: Enter the current name and location of the salt.store file that was created when you ran the createEncryptPasswords command. For more information, see "Using the CreateEncryptPasswords Utility."

Creating the Configuration File for the credStoreAdmin Command

You should create a configuration file that contains information about your environment.

To create the configuration file (for example, config.xml):

  1. Copy the sample XML Import/Export application configuration file OSM_home/SDK/XMLImportExport/config/config_sample.xml and rename it (for example, to config.xml).

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

    Following is the format of the j2eeAdminConnection section: 

    <j2eeAdminConnection>
   <user>admin_user</user>
   <password>password</password>
   <protocol>t3</protocol>
   <hostname>host_name</hostname>
   <port>port</port>
</j2eeAdminConnection>

    where admin_user is an administrative WebLogic Server user, host_name is the name of the server that WebLogic Server is running on, and port is the listen port for WebLogic Server. The value of the password element does not matter. Do not include your real plain-text password here.

    If you want to connect to the WebLogic server using SSL, see "Using SSL Connections."

  3. Edit the log tag of the file so that the logFileUrl attribute points to a valid location on your system.

  4. Use the EncryptPasswords utility to insert the encrypted passwords in the file. See "Using the EncryptPasswords Utility" for instructions on using this utility.

Editing the credStoreAdmin Script

You should edit the credStoreAdmin script with the appropriate values for your environment.

To edit the script for UNIX or Linux:

  1. Edit the OSM_home/SDK/XMLImportExport/credStoreAdmin.sh file, and make the following changes:

    • If the JAVA_HOME environment variable is not set, modify the following line to contain the path to the appropriate version of Java:

      export JAVA_HOME=$JAVA_HOME

    • Modify the following line so that it points to the OSM_home/SDK/XMLImportExport directory: 

      export APP_ROOT=$APP_ROOT

      For example:

      export APP_ROOT="/u01/osmdir/SDK/XMLImportExport"

    • If the MIDDLEWARE_HOME variable is not set, modify the following line so that it points to the location where Oracle Fusion Middleware is installed:

      export MIDDLEWARE_HOME=$MIDDLEWARE_HOME

To edit the script for Windows:

  1. If the following are all true, you do not need to perform this step:

    • You have the JAVA_HOME and MIDDLEWARE_HOME environment variables set to the correct values.

    • You are running the credStoreAdmin.bat command from the OSM_home/SDK/XMLImportExport directory.

  2. If the conditions in step 1 are not all true, edit the OSM_home/SDK/XMLImportExport/credStoreAdmin.bat file, and make the following changes:

    • If the JAVA_HOME environment variable is not set, edit the following line to point to the location of the appropriate version of Java:

      set JAVA_HOME=%JAVA_HOME%

      For example:

      set JAVA_HOME=%"C:\Program Files\Java\Java8"%

    • If you are not running the credStoreAdmin.bat script from the OSM_home/SDK/XMLImportExport directory, update the following line so that it points to the OSM_home/SDK/XMLImportExport directory: 

      set APP_ROOT=%~sdp0

      For example:

      set APP_ROOT="C:\Oracle\OSM\SDK\XMLImportExport"

    • If the MIDDLEWARE_HOME variable is not set, uncomment and update the following line so that it points to the location where Oracle Fusion Middleware is installed:

      @rem set MIDDLEWARE_HOME=%MIDDLEWARE_HOME%

Using the credStoreAdmin Command

You can do the following with the credStoreAdmin command:

  • add credential maps

  • add users to the credential store

  • change the password for users in the credential store

  • remove users from the credential store

For more information about adding users to the credential store, see "Managing Credentials in the Credential Store."

The credStoreAdmin command can be used in two ways. You can run a script on either UNIX/Linux or Windows, or you can run the command as an Ant target. The instructions for both methods are below.

To run the credStoreAdmin command as a script:

  1. Encrypt the user passwords for use in the XML data file. See "Using the CreateEncryptPasswords Utility" for more information.

  2. Create an XML data file for the credStoreAdmin command. See "Creating the XML Data File for the credStoreAdmin Command."

  3. Create a configuration file for the credStoreAdmin command. See "Creating the Configuration File for the credStoreAdmin Command."

  4. Edit the configuration script with information about your environment. See "Editing the credStoreAdmin Script."

  5. Run the following command:

    UNIX or Linux:

    credStoreAdmin.sh data_file config_file

    Windows:

    credStoreAdmin.bat data_file config_file

    where data_file is the XML data file that you created in step 2 and config_file is the configuration file you created in step 3. This script is ordinarily located in the OSM_home/SDK/XMLImportExport directory, but it is possible to run it from somewhere else. For information about running the script from another location, see "Editing the credStoreAdmin Script."

To run credStoreAdmin as an Ant target:

  1. Create an XML data file for the credStoreAdmin command. See "Creating the XML Data File for the credStoreAdmin Command."

  2. Create a configuration file for the credStoreAdmin command. See "Creating the Configuration File for the credStoreAdmin Command."

  3. From the OSM_home/SDK/XMLImportExport directory, set the following properties in the build.properties file:

    • xmlie.root.dir: The XML Import/Export application directory relative to the OSM SDK installation (for example, /XMLImportExport).

    • middlewareHome: The Fusion Middleware installation directory.

    • xmlie.root.modelDocument: The XML data file that you created in step 1.

    • xmlie.root.configDocument: The configuration file that you created in step 2.

    The other properties in the build.properties file are not used by the credStoreAdmin target.

  4. Run the following command:

    ant credStoreAdmin

Calling the 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>

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 Java Platform Security policy for your custom credential store map and to manage credentials in the credential store.

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 credStoreAdmin command to configure the OSM user in the credential store. (See "credStoreAdmin Command" for more information.

Example credential data in the XML file with credential information:

……
   <credential operation="create">
      <mapname>osm_systemAmap</mapname>
      <keyname>user1</keyname>
      <user>mobileUser1</user>
      <password>password_from_createEncryptPasswords</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.

Attributes

  • credStoreName

    Type: ObjectName

    Description: Mbean object for credential store: JpsJmxConstants.MBEAN_JPS_CREDENTIAL_STORE

  • globalPolicyName

    Type: ObjectName

    Description: Mbean object for global policy: JpsJmxConstants.MBEAN_JPS_ADMIN_POLICY_STORE

Business Object Operations

configJPSPolicy

This method is used to:

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

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

    Example credential data in XML file with Java Platform Security policy information:

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

OSM User Security and Credential Store API Reference Material

To develop OSM cartridges to use the credential store offered through CSF (see "Using 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.

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 CSF 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 Java Platform Security 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 Java Platform Security 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

  • credstore

    Type: CredStore

    Description: A reference object to OSM credential store object.

  • OSM_CREDENTIAL_MAPNAME

    Type: String (static final)

    Sensitive: Value is "osm"

    Description: Pre-defined map name for OSM application in credential store.

  • OSM_CREDENTIAL_KEYNAME_PREFIX

    Type: String (static final)

    Sensitive: Value is "osmUser_"

    Description: Prefix of key names used for OSM users in credential store.

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 "user name/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 Java Platform Security 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 "Modeling Behaviors" in OSM Modeling Guide.

Description

Built-in adapter.

Attributes

  • CREDENTIAL_MAPNAME_PARAM

    Type: String

    Description: Defines the parameter name to be specified in data provider for SOAP. A constant with value "oms:credentials.mapname".

  • CREDENTIAL_KEYNAME_PARAM

    Type: String

    Description: Defines the parameter name to be specified in data provider for SOAP. A constant with value "oms:credentials.keyname".

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.

ObjectelHTTPAdapter

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

For detailed information on data provider adapters, see "Modeling Behaviors" in OSM Modeling Guide.

Description

Built-in adapter. Objectel HTTP adapter.

Attributes

  • CREDENTIAL_MAPNAME_PARAM

    Type: String

    Description: Defines the parameter name to be specified in data provider for Objectel HTTP type. A constant with value "obj:mapname".

  • CREDENTIAL_KEYNAME_PARAM

    Type: String

    Description: Defines the parameter name to be specified in data provider for Objectel HTTP type. A constant with value "obj:keyname".

  • mapname

    Type: String

    Description: Value specified for map name parameter.

  • keyname

    Type: String

    Description: Value specified for key name parameter.

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 "user name/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 Java Platform Security 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 Credentials."

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 Java Platform Security 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()