Setting Up Web Service Authentication

Overview: Oracle recommends the use of OAuth rather than basic authentication. With basic authentication, the user password will expire periodically and require a reset. Each of these authentication options is described below.

In this chapter:

• Basic or OAuth Authentication

  • OAuth Support for Omnichannel Products

• Setting Up Inbound Authentication

  • Implementing Basic Authentication with IDCS or OCI IAM

  • Implementing OAuth through the Manage External Application Access page in Modern View

  • Validation of Inbound Requests

  • Order Administration Web Services Eligible for Authentication

• Setting Up Outbound Authentication

  • Basic Authentication

• Web Service Authentication Process for Order Orchestration

  • Order Orchestration Web Services Eligible for Authentication

• Web Service Authentication Process for Customer Engagement

  • Oracle Retail Customer Engagement Web Services Eligible for Authentication

Basic or OAuth Authentication

Basic authentication requires the requesting system to pass a user ID and a password to authenticate a web service request. The destination system validates the user ID and password.

When basic authentication is used, you should use the Working with Web Service Authentication (WWSA) rather than the Manage External Application Access page in Modern View.

OAuth requires the requesting system to provide an access token with the web service request. Oracle Cloud Services use IDCS (Oracle Identity Cloud Service) or OCI IAM (Oracle Cloud Infrastructure Identity and Access Management) as the authenticating service. The requesting system will use its configured client ID and secret to request an OAuth token from IDCS or OCI IAM and then include that token in service requests.

In addition to being more secure, OAuth provides better performance than basic authentication.

With OAuth authentication:

• The requesting system first passes a client ID and a client secret to an authenticating service, such as IDCS or OCI IAM.
• The authenticating service, such as IDCS or OCI IAM, generates a temporary token.
• The requesting system submits the token to the destination system, rather than a password and user ID as with basic authentication.
• The destination system validates the token and client ID with the authenticating service.

Note:

Order Management System and Order Administration, supports OAuth 2.0 for inbound and outbound requests.

OAuth Support for Omnichannel Products

Product	Supports Receiving OAuth	Supports Sending OAuth
Order Broker	19.0 or higher	19.1.1 or higher
Order Broker Cloud Service	18.2 or higher	19.1 or higher
Order Orchestration	23.2.401.0	23.2.401.0
Order Management System	18.3 or higher; 19.0 or higher supports XOffice OnPrem validation of stores with parent ID. 19.0 or higher. See the Manage External Application page in Modern View for background.	19.1 or higher
Order Administration	23.2.401.0	23.2.401.0
Customer Engagement	18.0 or higher; 18.3or higher supports XOffice OnPrem validation of stores with parent ID.	not currently supported

Setting Up Inbound Authentication

Implementing Basic Authentication with IDCS or OCI IAM

When an external system calls an Order Administration web service, the external system sending the message to Order Administration must send authentication information in the HTTP header of the message.

To implement:

• Create a user profile in IDCS or OCI IAM for inbound web service authentication and assign the password in IDCS or OCI IAM. 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 or OCI IAM, 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 or OCI IAM.

Implementing OAuth through the Manage External Application Access page in Modern View

Typically, you would use the Manage External Application Access page in Modern View to:

• Review the clients that have already been created in IDCS or OCI IAM.
• Generate a new client for the XOffice On Premises application and assign web service access.
• Generate a new client for another application and assign inbound web service access.

For more information: See the Oracle Retail Omnichannel Web Service Authentication Configuration Guide on My Oracle Support (2728265.1) for web service authentication configuration instructions.

Validation of Inbound Requests

When Order Administration 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 IDCS or OCI IAM is enabled, a 401 error is returned.

Order Administration Web Services Eligible for Authentication

You must define web service authentication, either through Work with Web Service Authentication (WWSA) or through the Manage External Application Access page in Modern View, for the following Order Administration web services.

• CWCustomer. This web service is used to process an Inbound Customer Message (CWCustomerIn) received from an external system. See the Order Administration Web Services Guide on My Oracle Support (ID 2953017.1) for more information.
• CWMessageIn. This web service works with any of the integration layer processes set up through Work 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 the Order Administration Web Services Guide on My Oracle Support (ID 2953017.1).
• CWOrderIn,. This web service is used to process an Inbound Order XML Message (CWOrderIn) from an external system. See Generic Order Interface (Order API) in the Order Administration Web Services Guide on My Oracle Support (ID 2953017.1) for more information.
• CWPickIn. This web service is used to process a CWPickIn XML Message from an external system. See Generic Pick In API (Shipments, Voids, and Backorders) in the Order Administration Web Services Guide on My Oracle Support (ID 2953017.1) for more information.
• CWReceiptIn. This web service is used to process a PO Receipt In XML Message (CWReceiptIn) from an external system. See Purchase Order Receipt In API in the Order Administration Web Services Guide on My Oracle Support (ID 2953017.1) for more information.

• CWServiceIn. 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 see the Order Administration Web Services Guide on My Oracle Support (ID 2953017.1).

  • Item Availability Web 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 the Order Administration Web Services Guide on My Oracle Support (ID 2953017.1) and see E-Commerce Cancel Process for more information.
  • E-Commerce Catalog Request Message (CWCatRequest) if its type is CWCatRequest. See the Order Administration Web Services Guide on My Oracle Support (ID 2953017.1) for more information.
  • CWProcessIn Message if its type attribute is CWProcessIn. See Using the CWProcessIn Message to Start a Periodic Process for more information.

  See the Order Administration Web Services Guide on My Oracle Support (ID 2953017.1).

• 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 guide on My Oracle Support (ID 2953017.1) 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.

Setting Up Outbound Authentication

Required administrative properties: You need to set up the following properties through Work with Admin Properties (CPRP) for communication with IDCS or OCI IAM:

• IDCS_ACCESS_CLIENT_ID: The client ID that identifies Order Administration to IDCS or OCI IAM when using OAuth.
• IDCS_ACCESS_CLIENT_SECRET: The client secret to authenticate Order Administration to IDCS or OCI IAM using OAuth.
• IDCS_SERVICE_ENDPOINT_URL: The URL to use for communicating with IDCS or OCI IAM.

Order Administration also uses the IDCS_ACCESS_CLIENT_ID and the IDCS_ACCESS_CLIENT_SECRET for authentication of web service messages to Order Orchestration or Customer Engagement flagged for OAuth authentication if the Client ID and Client Secret are not defined in Work with Web Service Authentication (WWSA).

Basic Authentication

Which outbound services require basic authentication? OAuth is not supported for the following:

Narvar Service: Used for authentication of RESTful web service requests to generate shipment notification emails through the Narvar Integration.

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 Active PO/Pre-Order Processing).

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.

For more information: See the Work with Outbound Web Service Authentication Screen.

Web Service Authentication Process for Order Orchestration

You can configure Order Administration to use either basic authentication or OAuth authentication for an Order Orchestration web service. When Order Administration generates a message to send to Order Orchestration, it includes the web service authentication user and password in the HTTP header of the message.

The type of authentication you select must be supported by Order Orchestration. Web service authentication is available starting in version 15.0 of Order Broker, or Order Orchestration, and OAuth authentication for outbound requests to Order Orchestration is available in 18.2 or higher of Order Broker, or Order Orchestration.

• Order Orchestration requires you to pass a valid web service authentication based on the settings defined at the Web Service User screen, using either basic authentication or OAuth.

  • If the web service passes 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 message fails web service authentication: If the password used for web service authentication is invalid or expired, or the request for an OAuth token fails, the system writes an error message to the CWDirect log.

Order Orchestration Web Services Eligible for Authentication

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

• OOCS Discovery. The Location discovery request is used to request a listing of all locations set up in Order Orchestration for the specified system. See Importing Store Cross Reference Locations through Order Orchestration’s Discovery Web Service for more information.

• OOCS Imports. Includes all imports using Order Orchestration’s Product, Product Location, and Incremental Inventory Import Process.

  • Order Orchestration Product Output File: Used to import product information into Order Orchestration.
  • Order Orchestration Product Location Output File: Used to import product location, attribute, and availability information into Order Orchestration.
  • Oracle Retail Order Orchestration Incremental Inventory Output File: Used to import inventory updates into Order Orchestration.

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

  • EchoTest: Used to test the connection to Order Orchestration.
  • Fulfillments: Used to request a list of pickup and shipment orders assigned to the requesting location.
  • Inventory Availability: Used to request current availability of active PO items as part of the ACTPO periodic function. See the ACTPO Periodic Function for Order Broker 20.2 or Higher, or Order Orchestration for more information.
  • LocateItems: Used to request locations available for store pickup orders.
  • 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.
  • StatusRequest and StatusListRequest: Used to request current order status for a list of orders.
  • 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.

• OOCS Purchasing. Includes all requests related to the Supplier Direct Fulfillment module. See Interface with Order Orchestration’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 Customer Engagement

Releases earlier than 16.0: When Order Administration calls a 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.

Inbound OAuth authentication is supported in release 18.0 or higher of Customer Engagement. When using OAuth, the Client ID for Order Administration must be assigned an application role of API access in IDCS or OCI IAM.

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

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 Administration. See Customer Engagement Loyalty Integration for more information.

• ORCE File Service. This web service is used to transfer customer, sales, and item information XML files to Oracle Retail Customer Engagement 20.0+. See Customer Engagement File Transfer Service (FTS) for more information.

  Note:

  OAuth authentication is required for ORCE File Service. Also, the client ID specified must be assigned the FileReview role in Customer Engagement.
• 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 process stored value card transactions between Order Administration and Oracle Retail Customer Engagement. See Customer Engagement Stored Value Card Integration for more information.
• ORCE Registry. This web service is used to review or place orders for the customer’s registries through Oracle Retail Customer Engagement. See Customer Engagement Customer Gift Registry and Wish List Integration for more information.