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 |
---|---|
This is the credential store object, which is the domain credential store class and contains a single instance of the CredentialStore object. |
|
This is the password credential store object. |
|
This is the credential store exception object. |
|
The attributes in this class provide the attributes for the credential store when you define SOAP data provider instances in your cartridges. |
|
The attributes in this class provide the attributes for the credential store when you define Objectel HTTP data provider instances in your cartridges. |
|
This interface object provides operations for the credential store. |
|
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
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>username</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()