A OSM Credential Store API Command Reference

This appendix describes how to secure credentials for accessing external systems by using a credential store, through the Oracle Fusion Middleware Credential Store Framework (CSF). 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.

The following table lists the OSM credential store APIs and credential store-related classes:

Table A-1 Credential Store API Commands and Classes

Command or Class	Description
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.

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