Working with Web Service Authentication (WWSA)

Web service authentication allows you to define a valid web service authentication user for each web service used by Order Management System.

Which web services are eligible? You can define web service authentication for:

• Web services used to process inbound messages to Order Management System Cloud Service. In this situation, the external system sending a message to Order Management System Cloud Service must send authentication information in the HTTP header of the message. See Web Service Authentication Process for Order Management System.

• Web services used to process inbound messages to Order Broker. In this situation, when Order Management System Cloud Service generates a message to send to Order Broker it includes the web service authentication user and password in the HTTP header of the message. Web service authentication is available starting in version 15.0 of Order Broker. See Web Service Authentication Process for Order Broker.

• Web services used to process inbound messages to Oracle Retail Customer Engagement. In this situation, when Order Management System Cloud Service generates a message to send to Oracle Retail Customer Engagement it includes the web service authentication user and password in the HTTP header of the message. Web service authentication is available starting in version 11.4 of Oracle Retail Customer Engagement. See Web Service Authentication Process for Oracle Retail Customer Engagement.

• A web service to send a job notification to an external system. See Using the Job Notification Outbound REST Message for more information.

In this chapter:

• Web Service Authentication Process for Order Management System

- Order Management System Web Services Eligible for Authentication

• Web Service Authentication Process for Order Broker

- Order Broker Web Services Eligible for Authentication

• Web Service Authentication Process for Oracle Retail Customer Engagement

- Oracle Retail Customer Engagement Web Services Eligible for Authentication

• Work with Inbound Web Service Authentication Screen

• Work with Inbound Web Service Authentication Users Screen

• Add User Window

• Work with Outbound Web Service Authentication Screen

• Change Outbound Web Service Authentication Screen

Web Service Authentication Process for Order Management System

When an external system calls an Order Management System Cloud Service web service, the system requires you to pass valid web service authentication.

Oracle Identity Cloud Service: When you use Oracle Identity Cloud Service (IDCS) for password authentication, you do not define passwords in Work with Web Service Authentication (WWSA) for inbound web services; instead:

• Basic HTTPS:

- Create a user profile in IDCS for inbound web service authentication and assign the password in IDCS. You can create a single user, or a separate user for different inbound messages.

- Create the web service authentication user, using the User Name defined in IDCS, in Work with Web Service Authentication (WWSA) for the inbound web service message. No password entry is required or supported, because the authentication takes place through IDCS.

This is currently the required configuration for integration with Customer Engagement and Order Broker.

• OAuth: Uses the IDCS Client ID of the client that generates the OAuth token as the user ID in Web Service Authentication (WWSA). You use the Manage External Application Access page in Modern View to create web service authentication records for applications created in IDCS that use OAuth authentication.

About OAuth: OAuth is a standard for web service authentication through the use of access tokens rather than passwords. When OAuth is used, the inbound web service request specifies a client ID and a temporary token for authentication, rather than a user ID and a password.

When OAuth not used: OAuth is not currently supported for:

- Web service requests from Order Management System to Order Broker.

- Web service requests from Order Broker to Order Management System.

- Web service requests from Order Management System to Customer Engagement.

For these integrations, you should use the Work with Inbound Web Service Authentication screen (WWSA) rather than the Manage External Application Access page in Modern View.

For more information: See Oracle Identity Cloud Service (IDCS) Authentication in the Administration Guide.

When Order Management System receives an inbound web service request:

• If the web service passes authentication, the web service continues with regular processing.

• If the web service fails basic authentication, the web service returns an error. If Oracle Identity Cloud Service (IDCS) is enabled, a 401 error is returned; otherwise,

- For SOAP-based web service types, if IDCS is not enabled, the web service returns a general exception error:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soapenv:Body>

<soapenv:Fault>

<faultcode>soapenv:Server.generalException</faultcode>

<faultstring>Invalid access</faultstring>

<detail>

<ns1:hostname xmlns:ns1="http://xml.apache.org/axis/">OMS-qa2</ns1:hostname>

</detail>

</soapenv:Fault>

</soapenv:Body>

</soapenv:Envelope>

- For RESTful web service types, if IDCS is not enabled, the web service returns an access not allowed error: Access not allowed.

If the password is invalid or expired: If IDCS is not enabled and the password used for web service authentication is invalid or expired, the system writes an error message to the CWDirect log.

Order Management System Web Services Eligible for Authentication

You must define web service authentication, either through this menu option or through the Manage External Application Access page in Modern View, for the following Order Management System Cloud Service web services.

• CWCustomer, both SOAP-based and RESTful web service types. This web service is used to process an Inbound Customer Message (CWCustomerIn) received from an external system. See Generic Customer API for more information.

• CWEmailRequest; this web service is available as a SOAP-based web service type only. It is used to process an Email Request Message (CWEmailRequest) received from an external system. See Store Pickup Confirmation Email Program (L48) for more information.

• CWManifest; this web service is available as a SOAP-based web service type only. It is used to process a Manifest Pick Request Message (CWManifestPickRequest) and Manifest Ship Request Message (CWManifestShipRequest) received from an the external system. See PC Manifesting Interface for more information.

• CWMessageIn, both SOAP-based and RESTful web service types. This web service works with any of the integration layer processes set up through Working with Integration Layer Processes (IJCT). See XML Messages Processed By the CWMessageIn Web Service for a list of the messages processed by the CWMessageIn web service and see CWMessageIn Web Service for an overview.

• CWOrderIn, both SOAP-based and RESTful web service types. This web service is used to process an Inbound Order XML Message (CWORDERIN) from an external system. See Generic Order Interface (Order API) for more information.

• CWPickIn, both SOAP-based and RESTful web service types. This web service is used to process a CWPickIn XML Message from an external system. See Generic Pick In API (Shipments, Voids, and Backorders) for more information.

• CWReceiptIn, both SOAP-based and RESTful web service types. This web service is used to process a PO Receipt In XML Message (CWReceiptIn) from an external system. See Purchase Order Receipt In API for more information.

• CWServiceIn, both SOAP-based and RESTful web service types. This web service is used to process the following messages received from an external system:

- Order Transaction History Message (CWOrderTransactionHistory) if its type attribute is CWOrderTransactionHistory. See Generic Order Transaction History API for more information.

- Order Line History In Message (CWOrdLnHstIn) if its type attribute is CWOrdLnHstIn. See Order Line History In API for more information.

- Item Availability Request XML Message (CWItemAvailabilityWeb) if its type attribute is CWItemAvailabilityWeb. See Item Availability API for more information.

- E-Commerce Cancel Request Message (CWCancel) if its type attribute is CWCancel. See E-Commerce Cancel Process for more information.

- E-Commerce Catalog Request Message (CWCatRequest) if its type is CWCatRequest. See E-Commerce Catalog Requests for more information.

- CWProcessIn Message if its type attribute is CWProcessIn. See Using the CWProcessIn Message to Start a Periodic Process for more information.

• JMSQueue. This web service is used during Advanced Queuing to read from a queue in the queuing database.

• PrivateDataRequest RESTful web service. This web service is used to process a Get Personal Data Request and Forget Personal Data Request from an external system. See the Personal Data API in the Data Security and Encryption guide for more information.

• ProcessIn. This RESTful web service is used to start a periodic process. See Using the ProcessIn REST Message to Start a Periodic Process for more information.

• Storage. This RESTful web service is used to upload, download, delete, or inquire on files imported or exported through the File Storage API.

Job Notification Outbound Message. This web service is used to notify an external system of a periodic process or job completion. See Using the Job Notification Outbound REST Message for more information.

Web Service Authentication Process for Order Broker

When Order Management System Cloud Service calls an Order Broker web service, the web service looks at the authentication settings defined at the Web Service Authorization screen in Order Broker to determine whether authentication is required.

• Order Broker requires you to pass a valid web service authentication user ID and password, as defined on the Web Service User screen, using Basic Authentication.

- If the web service passes basic authentication, the web service continues with regular processing.

- If the web service fails basic authentication, the web service refuses the request with an error: Inbound Message failed validation.

• If the Auth Required field for the web service is disabled, the web service does not require authentication. This option is available only for releases of Order Broker earlier than 16.0.

If the password is invalid or expired: If the password used for web service authentication is invalid or expired, the system writes an error message to the CWDirect log.

Order Broker Web Services Eligible for Authentication

You can define web service authentication for the following Order Broker web services:

• OROB Discovery. Requests include Location discovery and System discovery. See Importing Store Cross Reference Locations through Order Broker’s Discovery Web Service for more information.

- System discovery: Used to request a listing of all systems.

- Location discovery: Used to request a listing of all locations set up in Order Broker for the specified system.

• OROB Imports. Includes all imports using Order Broker’s Product, Product Location, and Incremental Inventory Import Process when the OROB_IMPORTS_ENABLED setting in Working with Customer Properties (PROP) is set to true.

- Order Broker Product Output File: Used to import product information into Order Broker.

- Order Broker Product Location Output File: Used to import product location, attribute, and availability information into Order Broker.

- Oracle Retail Order Broker Incremental Inventory Output File: Used to import inventory updates into Order Broker.

• OROB Locate. Includes all requests related to the Routing Engine. See Order Broker Integration for more information.

- EchoTest: Used to test the connection to Order Broker.

- Fulfillments: Used to request a list of pickup and shipment orders assigned to the requesting location.

- LocateItems: Used to request pickup or delivery availability information for a product.

- OrderSearch: Used to request a list of orders based on information available about the sold to or ship to customer.

- OrderUpdate: Used to update the Under Review indicator for an order.

- ProductAvailability: Used to request product availability for one or more items based on one or more order types.

- ProductUpdate: Used to create or update a product or product location, or both.

- StatusListRequest: Used to request current order status for a list of orders.

- StatusRequest: Used to request current information on a pickup or shipment order.

- StatusUpdate: Used to request a status update to a pickup or shipment order.

- SubmitOrder: Used to request creation of a pickup order in the requesting location, or request selection of a location for shipment of an order.

• OROB Purchasing. Includes all requests related to the Supplier Direct Fulfillment module. See Interface with Order Broker’s Supplier Direct Fulfillment Module: Overview and Setup for more information.

- CreateDSOrder: Used to create a drop ship purchase order.

- CreateDSVendor: Used to create or update a vendor.

- GetDSChanges: Used to request a listing of changes to all drop ship purchase order lines since the last request for changes was processed.

- GetDSInvoices: Used to request information on invoices submitted by the vendor and approved since the last request for invoices was processed.

- SetDSAddressChange: Used to request a shipping address change for a drop ship purchase order.

- SetDSCancel: Used to request the cancellation of a line on a drop ship purchase order.

- SetDSCostChange: Used to request a change to the retailer or vendor unit price, or both, for a drop ship purchase order line.

Web Service Authentication Process for Oracle Retail Customer Engagement

Releases earlier than 16.0: When Order Management System Cloud Service calls an Oracle Retail Customer Engagement web service earlier than release 16.0, the web service looks at the AUTHENTICATION_SCHEME setting defined in Conflate to determine whether authentication is required. If the AUTHENTICATION_SCHEME is set to Org-User, the web service requires authentication. In this situation, the system requires you to pass a valid user ID and password, as defined in the USR_RELATE_USER table, and to also identify the organization to which the user belongs, based on the relevant element in the URL.

Note: If you integrate with Relate 11.4 or earlier, you must upgrade to at least release 15.0 of Customer Engagement to use web service authentication.

Release 16.0 or later: In release 16.0 of Customer Engagement and later, authentication is required.

• If the web service passes authentication, the web service continues with regular processing.

• If the web service fails authentication, the web service returns a 401 error: unauthorized.

If the password is invalid or expired: If the password used for web service authentication is invalid or expired, the system writes an error message to the CWDirect log.

Note: You should not upgrade to release 18.0 of Customer Engagement you are using release 18.1 or higher of Order Management System Cloud Service.

Oracle Retail Customer Engagement Web Services Eligible for Authentication

You can define web service authentication for the following Oracle Retail Customer Engagement web services:

• ORCE Customer. This web service is used to create and update customer information between Oracle Retail Customer Engagement and Order Management System Cloud Service. See Customer Engagement Customer Integration for more information.

• ORCE Loyalty. This web service is used to assign a loyalty card to a customer and process activity for the loyalty account. See Customer Engagement Loyalty Integration for more information.

• ORCE Purchase History. This web service is used to review a customer’s completed sales and return transactions across multiple channels using the Display Purchase History screen. See Customer Engagement Purchase History Integration for more information.

• ORCE Stored Value Card. This web service is used to generate a new loyalty card and process stored value card transactions between Order Management System Cloud Service and Oracle Retail Customer Engagement. See Customer Engagement Stored Value Card Integration for more information.

• ORCE Wish List. This web service is used to review and modify a customer’s wish list from Oracle Retail Customer Engagement. See Customer Engagement Customer Wish List Integration for more information.

Work with Inbound Web Service Authentication Screen

Purpose: Use this screen to define valid web service authentication users for the Order Management System Cloud Service web services.

Oracle Identify Cloud Service: When you use Oracle Identity Cloud Service (IDCS) for password authentication, you do not define passwords in Work with Web Service Authentication (WWSA) for inbound web services; instead:

• Basic HTTPS:

- Create a user profile in IDCS for inbound web service authentication and assign the password in IDCS. You can create a single user, or a separate user for different inbound messages.

- Create the web service authentication user, using the User Name defined in IDCS, in Work with Web Service Authentication (WWSA) for the inbound web service message. No password entry is required or supported, because the authentication takes place through IDCS.

• OAuth: Use the IDCS Client ID of the client that generates the token as the user ID in Web Service Authentication (WWSA).

About OAuth: OAuth is a standard for web service authentication through the use of access tokens rather than passwords. When OAuth is used, the inbound web service request specifies a client ID and a temporary token for authentication, rather than a user ID and a password.

You can use the Manage External Application Access page in Modern View to create web service authentication records for applications created in IDCS.

When OAuth not used: OAuth is not currently supported for:

• Web service requests from Order Management System to Order Broker.

• Web service requests from Order Broker to Order Management System.

• Web service requests from Order Management System to Customer Engagement.

For these integrations, you should use the Work with Inbound Web Service Authentication screen (WWSA) rather than the Manage External Application Access page in Modern View.

For more information: See Oracle Identity Cloud Service (IDCS) Authentication in the Administration Guide.

How to display this screen: Enter WWSA in the Fast path field at the top of any menu or select Work with Web Service Authentication from a menu.

Field

Description

Web Service

An Order Management System Cloud Service web service that requires web service authentication. Valid web services are: • CWCustomer • CWEmailRequest • CWManifest • CWMessageIn • CWOrderIn • CWPickIn • CWReceiptIn • CWServiceIn • JMSQueue • PrivateDataRequest • ProcessIn • Storage Enter a full or partial web service name to display web services that contain your entry. See Order Management System Web Services Eligible for Authentication for a summary of each web service. Alphanumeric, 50 positions; optional.

Screen Option	Procedure
Configure web service authentication for an Order Management System Cloud Service web service	Select Authentication for a web service to advance to the Work with Inbound Web Service Authentication Users Screen.
Configure web service authentication for an external web service	Select Outbound Svcs to advance to the Work with Outbound Web Service Authentication Screen.

Work with Inbound Web Service Authentication Users Screen

Purpose: Use this screen to configure web service authentication for a web service.

How to display this screen: Select Authentication for a web service on the Work with Inbound Web Service Authentication Screen.

Field	Description
Web Service	The web service requiring authentication. Alphanumeric, 50 positions; display-only.
User	A valid web service authentication user that can authenticate the web service through one of the following methods: • OAuth authentication: When you use OAuth authentication, this is the IDCS Client ID of the client that requests the OAuth token. • IDCS authentication: When you use Oracle Identity Cloud Service (IDCS) for password authentication, this is the user ID defined in IDCS. About OAuth: OAuth is a standard for web service authentication through the use of access tokens rather than passwords. When OAuth is used, the inbound web service request specifies a client ID and a temporary token for authentication, rather than a user ID and a password. You can use the Manage External Application Access page in Modern View to create web service authentication records for applications created in IDCS that use OAuth authentication. When OAuth not used: OAuth is not currently supported for: • Web service requests from Order Management System to Order Broker. • Web service requests from Order Broker to Order Management System. • Web service requests from Order Management System to Customer Engagement. For these integrations, you should use the Work with Inbound Web Service Authentication screen (WWSA) rather than the Manage External Application Access page in Modern View. Enter a full or partial user ID to display users that contain your entry. Alphanumeric, 100 positions; optional.

Screen Option	Procedure
Create a web service authentication user	Select Create to advance to the Add User Window. Typically, you use the Manage External Application Access page in Modern View to create web service authentication records for applications created in IDCS and using OAuth authentication. You should not delete these records.
Delete a web service authentication user	Select Delete for a user. At the Are you sure you want to delete the web service user? window, select Yes to delete the user; otherwise, select No to cancel. You should use the Manage External Application Access page in Modern View to delete web service authentication records for applications created in IDCS, if necessary, You should not delete these users through the WWSA menu option.

Add User Window

Purpose: Use this window to create a web service authentication user.

How to display this screen: Select Create on the Work with Inbound Web Service Authentication Users Screen.

Field

Description

User

The web service authentication user ID. When you use Oracle Identity Cloud Service (IDCS) for password authentication, this is the user ID defined in IDCS. About OAuth: OAuth is a standard for web service authentication through the use of access tokens rather than passwords. When OAuth is used, the inbound web service request specifies a client ID and a temporary token for authentication, rather than a user ID and a password. Use the Manage External Application Access page in Modern View to create web service authentication records for applications created in IDCS that use OAuth, such as XOffice on premises. When OAuth not used: OAuth is not currently supported for: • Web service requests from Order Management System to Order Broker. • Web service requests from Order Broker to Order Management System. • Web service requests from Order Management System to Customer Engagement. For these integrations, you should use the Work with Inbound Web Service Authentication screen (WWSA) rather than the Manage External Application Access page in Modern View. Alphanumeric, 100 positions. Add window: required.

Work with Outbound Web Service Authentication Screen

Purpose: Use this screen to define a valid web service authentication user and password for an external web service that requires web service authentication.

You must define web service authentication for each of your Order Management System Cloud Service companies that communicates with the external system. Unlike inbound web service authentication, outbound web service authentication is defined at the company level.

Web service authentication for inbound messages to Order Broker or Customer Engagement occurs when the message is received in that application. The web service user for web service authentication on inbound messages to Order Broker or Customer Engagement must be defined in that application.

How to display this screen: Select Outbound Svcs at the Work with Inbound Web Service Authentication Screen.

Field	Description
Web Service	An external web service for which you can define a valid web service authentication user and password. The Job Notification web service is used to notify an external system about the completion of a periodic process or a job. See Using the Job Notification Outbound REST Message for more information. OCDS Service: Used for authentication for RESTful web service requests sent to the Omnichannel Cloud Data Service. See Importing Enterprise Foundation Data through Omnichannel Cloud Data Service (OCDS) for background. Customer Engagement: Web services listed for Oracle Retail Customer Engagement are: • ORCE Customer • ORCE Loyalty • ORCE Purchase History • ORCE Stored Value Card • ORCE Wish List See Oracle Retail Customer Engagement Web Services Eligible for Authentication for a summary of each web service. Order Broker: Web services listed for Order Broker are: • OROB Discovery • OROB Locate • OROB Purchasing See Order Broker Web Services Eligible for Authentication for a summary of each web service. RICS Service: Used for authentication for the pre-order (backorder quantity update) notification message that is part of the Enterprise Order Integration (Future Receipts and Pre-Order Processing). Alphanumeric, 50 positions; optional.
User	The web service authentication user defined for the web service. Enter a full or partial user name to display web service users that contain your entry. Alphanumeric, 100 positions; optional.

Screen Option	Procedure
Define a valid web service authentication user and password	Select Change for a web service to advance to the Change Outbound Web Service Authentication Screen.
Configure web service authentication for an Order Management System Cloud Service web service	Select Inbound Svcs to advance to the Work with Inbound Web Service Authentication Screen.

Change Outbound Web Service Authentication Screen

Purpose: Use this screen to define a valid web service authentication user and password.

How to display this screen: Select Change for a web service on the Work with Outbound Web Service Authentication Screen.

Field	Description
Web Service	The web service for which you wish to define a valid web service authentication user and password. Alphanumeric, 50 positions; display-only.
User	A valid web service authentication user that can authenticate the web service using Basic Authentication. You must enter the user ID in the correct case. This user must be defined in the external system. • You can define a web service authentication user in Order Broker on the Web Service Authorization screen. • You can define a web service authentication user in Oracle Retail Customer Engagement in the USR_RELATE_USER table. Alphanumeric, 10 positions; required.
Password	The password assigned to the web service authentication user. You can define both upper and lower case letters for the password. For security reasons, the system masks the password on the screen and encrypts the password in the database. Alphanumeric, 50 positions; required.