Working with Web Service Authentication (WWSA)

Web service authentication allows you to define which web services require authentication and the valid web service authentication users for each web service.

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

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

• web services used to process inbound messages to Oracle Retail Order Broker. In this situation, when Oracle Retail Order Management System generates a message to send to Oracle Retail 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 Oracle Retail Order Broker. See Web Service Authentication Process for Oracle Retail Order Broker.

• web services used to process inbound messages to Oracle Retail Customer Engagement. In this situation, when Oracle Retail Order Management System 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.

In this chapter:

• Web Service Authentication Process for Oracle Retail Order Management System

- Oracle Retail Order Management System Web Services Eligible for Authentication

• Web Service Authentication Process for Oracle Retail Order Broker

- Oracle Retail 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 Oracle Retail Order Management System

When an external system calls an Oracle Retail Order Management System web service, the web service looks at the require_auth field in the Webservice table to determine whether authentication is required.

By default, the require_auth field in the Webservice table for each web service is set to Y, indicating the web service requires authentication. In this situation, the system requires you to pass a valid web service authentication user ID and password, as defined in the Webservice Users table, 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 returns an error.

* For SOAP-based web service types, 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, the web service returns an access not allowed error:

Access not allowed

Oracle Retail Order Management System Web Services Eligible for Authentication

You can define web service authentication for the following Oracle Retail Order Management System 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.

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

Web Service Authentication Process for Oracle Retail Order Broker

When Oracle Retail Order Management System calls an Oracle Retail 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.

• If the Auth Required field for the web service is enabled, the web service requires authentication. In this situation, Oracle Retail 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.

Oracle Retail Order Broker Web Services Eligible for Authentication

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

• OROB Discovery. Requests include Location discovery and System discovery. See Importing Store Cross Reference Locations through Oracle Retail 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 Oracle Retail Order Broker for the specified system.

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

- EchoTest: Used to test the connection to Oracle Retail 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 Oracle Retail 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

When Oracle Retail Order Management System calls an Oracle Retail Customer Engagement web service, 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.

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

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 Oracle Retail Order Management System. 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 Oracle Retail Order Management System 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 which Oracle Retail Order Management System web services require authentication and the valid users and passwords for the web service. You must define web service authentication for each of your Oracle Retail Order Management System companies.

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 Oracle Retail Order Management System web service for which you can require web service authentication. Valid web services are: • CWCustomer • CWEmailRequest • CWManifest • CWMessageIn • CWOrderIn • CWPickIn • CWReceiptIn • CWServiceIn Enter a full or partial web service name to display web services that contain your entry. See Oracle Retail 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 Oracle Retail Order Management System 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 for which you wish to define authentication. Alphanumeric, 50 positions; display-only.
Required	Indicates whether the web service requires authentication. • Selected = The web service requires basic web service authentication. See Web Service Authentication Process for Oracle Retail Order Management System for an overview. • Unselected = The web service does not require basic web service authentication. Note: Regardless if you unselect this field, the system requires basic web service authentication.
User	A valid web service authentication user that can authenticate the web service using Basic Authentication. Enter a full or partial user ID to display users that contain your entry. Alphanumeric, 50 positions; optional.

Screen Option	Procedure
Create a web service authentication user	Select Create to advance to the Add User Window.
Change a web service authentication user	Select Change for a user to advance to the Change User window. You can change only the password. See Add User Window for field descriptions.
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.

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. The case you define for the user ID is not used; for example, user ID TBROWN and tbrown are considered the same user ID. Alphanumeric, 50 positions. Add window: required. Change window: display-only.
Password	The password assigned to the web service authentication user. The password you assign to the user must adhere to the following rules: • The password must be greater than 6 positions, • cannot match the user ID, • must contain at least one letter, • must contain at least one number, and • must contain at least one special character. In addition, 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 Webservice Users table. Alphanumeric, 50 positions; 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 Oracle Retail Order Management System companies that communicates with the external system.

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. Enter a full or partial web service name to display web services that contain your entry. 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. Web services listed for Oracle Retail Order Broker are: • OROB Discovery • OROB Locate • OROB Purchasing See Oracle Retail Order Broker Web Services Eligible for Authentication for a summary of each web service. 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, 50 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 Oracle Retail Order Management System 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 Oracle Retail 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, 50 positions; required.
Password	The password assigned to the web service authentication user. The password you assign to the user must adhere to the following rules: • The password must be greater than 6 positions, • cannot match the user ID, • must contain at least one letter, • must contain at least one number, and • must contain at least one special character. In addition, 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.