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 creates an OSM user and also adds the user in the credential store.

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 Credential Store Command and 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.

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

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

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):

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>f940016e13cf29fd8a8c7220a34756f72</password>
      <saltstore>C:/security/testOsmUser1/salt.store</saltstore>
   </user>
   <user name="testOsmUser2">
      <description>OSM test user 2</description >
      <password>fd8a8c7220a34756f72f940016e13cf29</password>
      <saltstore>C:/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>

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

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

  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 Server user and add the user to the OSM default credential store map at the same time.

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

  • map="osm"

  • key="osmUser_osmlf"

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.

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.

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 about creating this file.

XMILE configuration file: config.xml

WebLogic Server administrator password (if not provided in config.xml)

If the WebLogic Server 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.

  • WebLogic Server administrator user name

  • WebLogic server host

  • WebLogic server port

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"?>
<CredentialConfig
 xmlns="http://www.metasolv.com/Provisioning/CredentialConfig"
 xmlns:ns1="http://www.metasolv.com/OMS.OrderModel/2002/06/25"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="…/XMLImportExport/models/CredStoreAdmin.xsd">
   <jpsPolicy operation="add">
      <ns2:mapname>osm</ns2:mapname>
   <jpsPolicy>
   <credential operation="create" overwrite="true">
      <mapname>osm</mapname>
      <keyname>osm</keyname>
      <user>user1</user>
      <password>40ee2b3264e26e78c0cf2246cbb12299</password>
      <saltstore>C:/security/testOsmUser1/salt.store</saltstore>
   </credential>
<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 security purposes, you must input the password at run time when prompted if running the batch script or Ant task.

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

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>

If the Ant target "credStoreAdmin" is called by another Ant script, which is running in your Oracle Communications 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>

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.

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 >
……
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. (See "userAdmin 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>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 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 in OSM Developer's 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 the discussion on behaviors in OSM Developer's 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()