3 Setting Up OSM Security

This chapter describes how to set up security on your Oracle Communications Order and Service Management (OSM) system.

About OSM Security

When you manage OSM security, you can perform the following tasks:

For more information about WebLogic Server security realms, refer to the WebLogic Server Console documentation.

Note:

OSM supports LDAP Version 2.

Secure Solution Data Storage

As a fulfillment system, OSM does not need a fixed data model, and so is not required or typically used to store sensitive data other than that used for OSM user authentication.

You can secure OSM user credentials as described in this chapter, but if your implementation requires OSM to store or log other sensitive data that appears on orders, Oracle recommends that you encrypt the data outside of OSM. Because the encryption happens outside of OSM, you are responsible for developing and maintaining the encryption method.

Adding Users to OSM

To add a user to OSM:

  • Create workgroups as roles in Oracle Communications Design Studio.

  • Assign users to workgroups in the OSM Administrator.

For information about the users and groups created for OSM, see "Users and Groups".

Creating Workgroups as Roles in Design Studio

In Design Studio, you create roles and assign permissions to give users in that role access to related functions in the Task and Order Management web clients and the OSM Web Service and XML APIs.

Note:

You assign individual users to roles using the Administration area of the Order Management web client. See OSM Order Management Web Client User's Guide for more information.

Table 3-1 describes the client functions to which you provide access.

Table 3-1 Client Permissions

Function Description Applies To

Create Versioned Orders

Enables users to create orders for different versions of cartridges. If not granted this permission, users can only create orders for the default version of the cartridge.

This permission relates to:

  • In the Task web client: creating a new order

  • In the Web Service API: using the CreateOrderBySpecification calls

  • In the XML API: using the CreateOrder XML API call

Task web client

Web Service API

XML API

Exception Processing

Enables users to alter the flow of a process by applying exception statuses at any time throughout the process.

This permission relates to:

  • In the Task web client: raising exceptions on a task

  • In the XML API: using the SetException call

Task web client

XML API

Online Reports

Enables users to view summarized reports on all orders and tasks on the system.

This permission relates to:

  • In the Task web client: using the reporting feature

Task web client

Order Priority Modification

Enables users to modify the priority of an order or of a task in an order.

This permission relates to:

  • In the Order Management web client: setting the order priority

  • In the Task web client: setting the task priority

  • In the Web Service API: changing the order priority using the UpdateOrder call

  • In the XML API: changing the order or task priority using the UpdateOrder call

Order Management web client

Task web client

Web Service API

XML API

Reference Number Modification

Enables users to modify the reference number of an order.

This permission relates to:

  • In the Order Management web client and Task web client: Modifying the reference number of an order

  • In the Web Service API and XML API: changing the reference number using the UpdateOrder call

Order Management web client

Task web client

Web Service API

XML API

Search View

Enables users to access the order Query function.

This permission relates to:

  • In the Order Management web client: using the main search screen for the client

  • In the Task web client: using the Search functionality (for example, clicking the Query button from the Worklist)

  • In the Web Service API: using the FindOrder call

  • In the XML API: using the Query call

Order Management web client

Task web client

Web Service API

XML API

Task Assignment

Enables users to assign tasks to others.

This permission relates to:

  • In the Task web client: assigning a task to another user

  • In the XML API: using the AssignOrder calls

Task web client

XML API

Worklist Viewer

Enables users to access the Worklist function.

This permission relates to:

  • In the Task web client: accessing the worklist

  • In the XML API: using the Worklist call

Task web client

XML API

In addition to granting web client permissions, you can also grant permissions at the order level (by associating a role to an order type) and the task level.

See the discussion about creating new roles in Design Studio Modeling OSM Processes for more information. After you create a role, you must assign permissions to the role entities. See "Role Editor Role Tab" in Design Studio Modeling OSM Processes for more information about permissions for role entities.

Assigning Users to Workgroups

See the discussion about assigning users to a workgroup in OSM Order Management Web Client User's Guide for more information.

Using WebLogic Server Authenticators with OSM

OSM supports using either the WebLogic Server's embedded LDAP directory or another authenticator that is external to, and integrated with, WebLogic Server. The latter is referred to in this section as an external authenticator. This section provides information about how these directories work with OSM.

Note:

If multiple authentication providers are configured in WebLogic Server, all the authentication providers (even if they are configured as optional in WebLogic Server) should be active. If any of the authentication providers is not active, an exception will be raised and the users will not be able to log in to OSM.

User-Level Authenticator Support

OSM fully supports external authenticators and embedded LDAP directories at the user level. A user that exists in either the WebLogic server's embedded LDAP directory or in an external authenticator receives the privileges of any group to which it is assigned in WebLogic Server. Also, users can be assigned to workgroups in the Administration area of the OSM Order Management web client and will receive the appropriate permissions for the workgroup.

Group-Level Authenticator Support

OSM also supports external authenticators and embedded LDAP directories at the group level. A group that exists in either the WebLogic server's embedded LDAP directory or in an external authenticator receives the privileges of any OSM group to which it is assigned in WebLogic Server. Also, groups can be assigned to workgroups in the Administration area of the OSM Order Management web client and will receive the appropriate permissions for the workgroup.

A child LDAP group will inherit the following from its parent LDAP group:

  • Permissions from OSM roles in Design Studio

  • Permissions from groups assigned in the WebLogic Administration Console

  • Tasks

  • Filters

  • Flexible headers

It is not possible to restrict a child group from inheriting from the parent group.

Note:

If a user is assigned (directly or indirectly) to multiple groups which have different query tasks for the same order, it is not predictable which query task view the user will see when querying the order.

Authenticator User and Group Assignment Considerations

There are some considerations and best practices to take into account when assigning users and groups to OSM workgroups/roles.

  • The first step in assigning permissions for external authenticator and embedded LDAP users and groups is to assign them to either the OMS_client or OSM_automation groups in WebLogic Server.

  • Only users and groups which have been assigned directly to the OMS_client or OSM_automation groups in WebLogic Server will be available to assign to workgroups in the Administration area of the OSM Order Management web client. For example, if UserA1 is a member of GroupA, and GroupA has been assigned to the OMS_client group in WebLogic Server, only GroupA will be displayed in the OSM Order Management web client. However, when GroupA is assigned to a workgroup, UserA1 (and all of the users in GroupA) will inherit the permissions of the workgroup.

    Both users and groups will be displayed the same in the OSM Order Management web client. There is no indication which elements are users and which are groups.

  • If new users are added to the authenticator, they will not be able to access OSM functionality until the OSM Metadata is refreshed. For information about refreshing OSM metadata, see "Refreshing OSM Metadata".

  • Oracle recommends that you assign automation users to the OSM_automation WebLogic Server group directly, rather than as members of a group. If you decide to assign automation users using a group instead of individually, you must ensure that you do not remove from the WebLogic Server group any users that are specified in the "Run As" property of an automation plug-in.

Setting Up a Caching Realm

If you use an external security implementation such as LDAP, you should also use a caching realm to improve performance. A caching realm holds the results of security checks in memory so that subsequent checks are not required to communicate directly with an external security server. The default settings for caching realms are appropriate for small numbers of users in the external realm; however, they do not help if your external security implementation has large numbers of users.

To set up a caching realm:

  1. Log in to the WebLogic Administration Console.

  2. In the Domain Structure tree, select Security Realms.

    The Summary of Security Realms page is displayed.

  3. Click the name of your security realm. The default name is myrealm.

    The settings for the security realm are displayed.

    From this window, you can change the settings for your realm.

For more information about setting up security in WebLogic Server, see Oracle Fusion Middleware Administering Security for Oracle WebLogic Server.

Secure Credential Management

This section describes how to secure credentials for accessing external systems. OSM provides two distinct secure credential management solutions, each appropriate to the type of credential to be secured:

  • EncryptPasswords utility: This utility is used to secure the credentials required to run other OSM utilities that require those credentials, for example the XML Import/Export tool. Oracle recommends that you use this if you are running utilities unattended. If you are running the utilities attended, Oracle recommends that you provide the required credentials interactively as prompted by the utility, rather than using the EncryptPasswords utility. Because the utility is assumed to run unattended, it must be able to decrypt credentials without user intervention. Therefore, the output of the EncryptPasswords utility should be considered obfuscated and not encrypted. Secure the files containing the output with appropriate file-system-level restrictions. For more information, see "Using the EncryptPasswords Utility."

  • Credential Store: This utility is used to secure credentials required to access systems with which your OSM solution interacts. It builds on CSF, adding OSM-specific features. For more information, see "Using the Credential Store."

Using the EncryptPasswords Utility

You use the EncryptPasswords utility to encrypt the user name and password credentials of XML Import/Export application users.

About the EncryptPasswords Utility

When you install the XML Import/Export application, you can optionally provide passwords for the OSM database, the XML API interface, and the WebLogic domain administration server. To set and reset those passwords, you run the EncryptPasswords utility. See "Running the EncryptPasswords Utility" for information about running the utility.

The EncryptPasswords utility (located in the SDK/XMLImportExport directory) is a password management utility that secures the credentials that the XML Import/Export application uses. The EncryptPasswords utility encrypts the credentials, preventing their accidental exposure.

Running the EncryptPasswords utility prompts you to enter the user name and password credentials of each XML Import/Export application user that requires access to the OSM database, the XML API interface, and the WebLogic domain administration server. It then stores the user names and passwords for these users in encrypted format in the configuration file which the XML Import/Export application uses to provide these credentials (for example, SDK/XMLImportExport/config/config.xml). When the XML Import/Export application runs, it decrypts the passwords as part of loading its configuration file.

The EncryptPasswords utility can be run only by a user who has write access to the XML files in which the credentials are stored.

Ant build files for the EncryptPasswords utility are located in the following directories:

  • SDK/CartridgeManagementTool/production

  • SDK/CartridgeManagementTool/development

The Ant build files have targets corresponding to each of the batch files in the SDK/XMLImportExport directory that include the EncryptPasswords functionality.

Running the EncryptPasswords Utility

Run the EncryptPasswords utility script:

  • As part of the initial setup of the XML Import/Export application

  • Each time the user name or password credentials of an XML Import/Export application user changes

Note:

To run the EncryptPasswords utility, you must have write access to the XML files in which the XML Import/Export application user credentials are stored.

To run the EncryptPasswords utility:

  1. Create a config file that complies with the SDK/XMLImportExport/config/config.xsd file.

    The same directory also contains a sample file: config_sample.xml.

    Note:

    The configuration file must contain the <user> and <password> elements, but the values of these elements do not matter because the script will prompt for these values.

  2. Do one of the following:

    • UNIX and Linux:

      Run the following command:

      EncryptPasswords.sh XMLConfig [-dbUser] [-xmlapiUser] [-wlsUser]
      

      for example:

      EncryptPasswords.sh config/config.xml -dbUser
      
    • Windows:

      Run the following command:

      EncryptPasswords XMLConfig [-dbUser] [-xmlapiUser] [-wlsUser]
      

      for example:

      EncryptPasswords config\config.xml -dbUser -xmlapiUser
      

    where XMLConfig indicates the configuration XML file you created in the previous step, and the following optional parameters indicate which passwords should be encrypted:

    • -dbUser: the OSM database password

    • -xmlapiUser: the XML API interface password

    • -wlsUser: the WebLogic domain administration server password

    When you set a user's credentials, you specify only the systems that they use for the XML Import/Export application operations they perform. For example, if the user only imports or exports cartridges, you only need to specify the -dbUser flag.

  3. When prompted by the script, enter the user names and passwords that you selected when running the script.

    When you type in passwords, nothing will be displayed on the screen.

Removing an Encrypted Password

To remove a user name and password for a user that no longer requires credentials, open the XML file where the credentials are stored and remove them manually. If you do not remove them manually, the user name and password combination continues to exist in the XML file.

Using the Credential Store

You use the credential store to store credentials that OSM uses to interact with external systems.

About the Credential Store

A credential store is a central repository you can use to store credentials such as user names and passwords. OSM can use a credential store for the credentials needed to log in to and send requests to external systems (meaning any resources or systems that are out of the scope of your OSM cartridge-owned code and resources). These credentials can be used by OSM and OSM applications.

In OSM cloud native, the type of credential store that OSM uses is offered through the Kubernetes Secret.

Use the OSM credential store APIs when developing your OSM cartridges so your OSM applications can access and read credentials from the credential store in a secure form. For example, use the OSM credential store APIs when you define data provider classes in your cartridges which must access web service and database systems with credentials. See "Developing Cartridges to Use the Credential Store" and "OSM Credential Store API Command Reference" for more information about using the credential store in your cartridge development.

Oracle recommends you to use the credential store as a repository for credentials and use the OSM credential store APIs in OSM-related code to access the repository in a secure form. Oracle strongly recommends you do not hard-code user names and passwords in cartridge code and that you update any current cartridges that have hard-coded credentials to use the OSM credential store APIs. See "Developing Cartridges to Use the Credential Store" for more information about security options and recommendations.

For information about Platform Security Services and managing credentials in the credential store, see Oracle Fusion Middleware Securing Applications with Oracle Platform Security Services.

How OSM Retrieves Credentials from the Credential Store

The credential store for OSM applications contains credentials that are stored using a Kubenetes secret with key names. OSM applications, such as OSM web clients and OSM cartridge applications, retrieve credentials from the Kubernetes secret based on key names. Automation plug-ins are used to call OSM credential store APIs to retrieve the credentials. OSM applications then use the credentials to gain access to external systems.

OSM credential store APIs are used inside automation plug-ins to retrieve credentials and to gain access to external systems. OSM cartridge code can call the credStoreAdmin command to create and configure the required entries, such as map name, user name, and password, for OSM applications in the credential store. For more information, see "Provisioning Cartridge User Accounts" OSM Cloud Native Deployment Guide.

OSM plug-in users in a cartridge application, such as automation plug-ins or external instance adapters access the OSM credential store map and read the credentials.

The following steps summarize how an automation plug-in in OSM cloud native retrieves credentials from the credential store for an automation task that requires the credentials to access an external system:

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

  2. The automation plug-in user accesses the correct Kubernetes secret and reads the credentials required to access the external system.

  3. The automation plug-in user accesses the correct credential store map and reads the credentials required to access the external system.

    If the credentials are not in the store, the API fails with an exception and the automation task fails.

  4. If the credentials are in the store, the user name and password variables in the plug-in script will be set with values retrieved from the credential store.

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

  6. The automation task completes.

Managing Credentials in the Credential Store

To learn how to create credential store secrets and provide the instance configuration so that OSM cloud native can access the credentials, see "Provisioning Cartridge User Accounts" in OSM Cloud Native Deployment Guide.

Developing Cartridges to Use the Credential Store

When your OSM cartridges require data from external systems, trigger actions at external systems, or provide data to external systems, credential information may be required by the external system. The external system can be any resource or system that is out of the scope of your OSM-cartridge-owned codes and resources.

When you develop OSM cartridges, Oracle recommends you use the credential store to allow plug-in code to access credential information in a secured way. You can use the OSM credential store APIs for code that requires credential retrieval.

OSM uses the credential store offered through WebLogic Server; however, you are not required to use this credential store to secure credentials. You can use other methods of securing credentials. Oracle strongly recommends you do not hard-code user credential information in OSM code such as in plug-in script files and cartridge model description files. Passing and storing passwords in plain text poses a security risk. Follow proper security guidelines to develop OSM cartridges to protect data over communication channels. Oracle recommends using SSL communication between OSM and an external system, particularly for web services of external systems.

The following are examples of external systems used in OSM cartridges that may require credential information:

  • OSM Web Service

  • Databases

  • JMS queues and topics (except JMS queues deployed by the cartridge)

  • Web services of any system

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

See "Using the Credential Store" for information about the credential store.

Developing Automation Plug-ins to Use the Credential Store

Some OSM credential store APIs can be used in custom automation plug-in Java classes. Use these APIs when you define custom automation plug-in classes to access an external system with credentials. You can also call OSM credential store APIs from your automation context classes. The XQuery plug-in code for an automation or activation task can use credential store APIs to retrieve credentials from the credential store. See "AutomationContext" for example code for developing automation plug-ins in OSM cartridges to retrieve credentials from the credential store.

External instance adapters and automation plug-in classes (XQuerySender and XSLTSender) provided by Oracle to send messages and requests to external systems support the OSM credential store APIs.

Defining Data Providers in OSM Cartridges to Use the Credential Store

You must set up a data provider class in your cartridge if it requires credential information for an external system so it can read the required credentials from the credential store.

Using the Credential Store with Custom Data Providers

When you add a data provider class in a cartridge that requires credential information for an external system, the data provider class can call OSM credential store APIs to read the required credentials from the credential store. Your data provider class must implement the retrieveInstance() method of the ExternalInstanceAdapter interface.

To read the required credential from the credential store when you define your own data provider class (provider type is "Custom"), use the following APIs in the retrieveInstance() method in your Java class:

Note:

This example assumes you are using your own map. If you use the default map (osm) and key names for the OSM application, you can use simpler code:

String password = context.getOsmCredentialPassword(username)
public Element retrieveInstance(final ViewRuleContext context, final Map<String, Object> parameters) throws Exception {
    // DoCustomLogic
      
    String mapname = getStringParam(parameters, "para.mapname", null);
    String keyname = getStringParam(parameters, "para.keyname", null);
    String username = "";
    String password = "";
    
    if (mapname != null && keyname != null) {
      try {
        String credential = context.getCredential(mapname, keyname);
        int index = credential.indexOf("/");
        username = credential.substring(0, index-1);
        password = credential.substring(index);
       } catch (Exception e) {
      // DoCredStoreExceptionHandling
      }
    }
    // DoAuthenticationWithUsernamePassword
    // DoCustomerRequest
    // DoResponseHandling
  }
Using the Credential Store with Built-In Data Providers

Oracle provides pre-defined or built-in data provider classes "SoapAdapter" and "ObjectelHTTPAdapter" which contain the code required for using the credential store. To use the credential store when you use these built-in adapters, add the input parameters required for the credential store in your data provider.

Table 3-2 shows the parameters that are required for each adapter type.

Table 3-2 Parameters for SoapAdapter and ObjectelHTTPAdapter

Adapter Parameter Name contextType Default Value

SoapAdapter

oms:credentials.mapname

XPATH

myMap

SoapAdapter

oms:credentials.keyname

XPATH

myUser

ObjectelHTTPAdapter

obj:mapname

XPATH

osm

ObjectelHTTPAdapter

obj:keyname

XPATH

osm

Upgrading Existing Cartridge Code to Use the Credential Store

Upgrade your existing OSM cartridge code to use the credential store by using the OSM credential store APIs. Upgrade your custom data provider classes and XQuery plug-in code to use the OSM credential store APIs for retrieval of credentials. See "Developing Cartridges to Use the Credential Store" for information about developing cartridges to use the credential store.

In addition to upgrading your cartridge code, provision the credential store for the WebLogic Server domain for OSM applications with required credentials (see "Managing Credentials in the Credential Store") and configure the Java Platform Security policy for the WebLogic Server domain to allow OSM access to the credential store.

Using Built-in SOAP Adapter as a Data Provider Class

Credential information is required to send a SOAP request. If your existing automation plug-in code that is used to test the SOAP adapter has hard-coded passwords, you can use the built-in SOAPAdapter class as a data provider class in your cartridges to remove the need for the hard-coded passwords.

When you use the default map for OSM applications, automation plug-in users pass in only the user name in the parameter. When you use your custom credential store map, automation plug-in users also pass in the credential map name and key name for credentials in the parameter.

To update existing automation plug-in code that tests SOAPAdapter to remove hard-coded passwords:

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

  2. Ensure that credentials exist in the credential store under map="osm" key=osmUser_SoapRequest_username.

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

Administering Users and Workgroups

You can add users to WebLogic Server groups by following the procedure in "Provisioning Cartridge User Accounts" in OSM Cloud Native Deployment Guide.