Manage External Application Access

Purpose: Use the Manage External Application Access screen to create, review, and work with external applications that integrate with Order Broker using OAuth, and define the web services that use OAuth authentication for inbound web service requests to Order Broker.

About OAuth: 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.

How requests are validated with OAuth: 

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

The following is required in order to support OAuth between Order Broker and other Omnichannel products, including Order Management System and Xstore Cloud Services or Xstore Office (On Premises), as well as an external system such as an ecommerce system:

•         The IDCS or OCI IAM client ID and client secret for the integrating system must be created through an Omnichannel cloud service, if it does not already exist.

•         The system receiving the web service request needs to have a record of the client ID with assigned access for the web service API.

•         A system sending the web service request needs to be able to request the token from IDCS or OCI IAM.

•         The system sending the web service request needs to include the token so the system receiving the web service request can validate the request.

For example, if your ecommerce system will communicate with Order Broker using OAuth, you can use this page to:

•         Create a client ID and secret, which you can then provide to the ecommerce system.

•         Create the associated web service authentication records for the ecommerce system.

Related Tenant-Admin settings: The Identity Cloud Service Settings at the Tenant-Admin screen are required for communication with IDCS or OCI IAM:

•         Use IDCS: This flag must be selected for new installations or upgrades to Order Broker Cloud Service 18.0 or higher.

•         Client ID: The Name identifying Order Broker as an application in IDCS or OCI IAM. Typically formatted as RGBU_OBCS_ENV_APPID, where OBCS identifies Order Broker and ENV identifies the environment, such as production.

•         Endpoint URL: The URL to use when requesting information from IDCS or OCI IAM through the Manage External Application Access screen.

•         Client Secret: The client secret for Order Broker to use when requesting a token for outbound OAuth authentication.

About store locations and XOffice On Prem: The XOffice On Prem application differs from other applications in that it serves as the parent for any related store locations. Any store locations that are assigned a parent ID are not displayed at this page; instead, you configure external access for XOffice On Prem, and this “parent” handles authentication for all related store locations.

When authentication is required for a request originating from any location associated with the XOffice On Prem parent ID, the parent ID’s authentication credentials are used.

Example:                    XOffice On Prem is the parent for location A, so the XOffice On Prem authentication credentials are used.

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

OAuth summary by product:

Product

Inbound Support

Outbound Support

Order Broker

18.2 or higher

19.1 or higher

Order Management System

18.3 or higher; 19.0 or higher supports XOffice On Prem validation of stores with parent ID. 19.0 or higher

19.1 or higher

Customer Engagement

18.0 or higher; 18.3 or higher supports XOffice On Prem validation of stores with parent ID.

not currently supported

Note:             Oracle Retail Integration Cloud Service (RICS) and Omnichannel Cloud Data Service (OCDS) do not currently support using OAuth for authentication of inbound messages. The Authentication Type at the RICS Integration tab and the OCDS Integration tab of the System screen should be set to Basic.

Troubleshooting: Options at this page that require communication with IDCS or OCI IAM, including generating a new client, regenerating the secret for a client, and refreshing the displayed applications, will fail if the administrative properties listed above are not set correctly. See the Identity Cloud Service Settings at the Tenant-Admin screen for more information on setting up these properties, or contact your Oracle representative for more help.

Outbound web services using OAuth authentication: The following outbound services support OAuth authentication:

•         OMS Service: Used for authentication for the inventory request message to be sent to Order Management System. Use the Inventory tab tab of the System screen to define the OAuth Authentication Type, Client ID, and Client Secret for Order Management System. If you are using Basic authentication, it is recommended to move to OAuth.

•         Job Notification Service: Used for authentication for the job notification message to be sent to an external application. Use the Event Logging screen, and select OAuth as the Authentication Type. If you are using Basic authentication, it is recommended to move to OAuth.

•         RICS: Used for authentication for the pre-order (backorder quantity update) notification message that is part of Order Fulfillment through RICS Integration. Configure on the RICS Integration tab of the System screen.

•         OCDS: Used for authentication for RESTful web service requests sent to the Omnichannel Cloud Data Service. Configure on the OCDS Integration tab of the System screen.

Outbound web services using basic authentication: OAuth is not supported for the SIM integration to request inventory updates through Importing Data from Merchandising Cloud Services (RMFCS) through the Omnichannel Cloud Data Service (OCDS) or Merchandising Omni Services. Configure on the Inventory tab of the System screen.

Note:             If any other existing Oracle Cloud Services are configured for basic authentication and support OAuth, you should migrate these services to OAuth.

For more information: See the Oracle Retail Omnichannel Web Service Authentication Configuration Guide, on My Oracle Support at https://support.oracle.com/epmos/faces/DocumentDisplay?id=2728265.1, for information on configuring the Omnichannel products for OAuth.

In this topic:

•         Options at this screen

•         Fields at this screen

How to display this screen: Select Manage External Application Access from the Systems Menu.

Note:             Only users with Manage External Application Access authority can display this screen. This authority is not delivered automatically, so you must assign it manually. See the Role Wizard for more information.

Before you start: The first time a user advances to this screen, no applications are displayed.

Select Refresh to request existing applications from IDCS or OCI IAM and create records for them in Order Broker, which are then displayed, provided the Identity Cloud Service Settings at the Tenant-Admin screen are populated correctly.

Options at this screen

Option

Procedure

refresh the displayed applications

Click Refresh to update the list of currently existing application clients from IDCS or OCI IAM:

•         If any additional client applications are found in IDCS or OCI IAM that did not previously have records in Order Broker, these client application records are created in the Order Broker database. For example, additional client records might have been included through another product, such as Customer Engagement Cloud Services. These new client records are also displayed at the Web Service User screen.

Example:                    When you click Refresh, the updated list of client applications might include client applications created through another application, such as Customer Engagement.

•         If any client applications that previously existed in Order Broker have been deleted from IDCS or OCI IAM, they are deleted from Order Broker, and the web service authentication user records are also removed from the Web Service User screen.

•         If any client applications that previously existed in Order Broker have been changed in IDCS or OCI IAM, then applications are updated if the changed fields are the Client ID (APPLICATION_ID), Description, and the PARENT_APP_ID (used only when the Application Type identifies an XOffice On Prem store location).

Note:  

•         When additional store locations have been created for XOffice On Prem, using the Refresh option creates the records in the Order Broker database; however, these records are not displayed at the Manage External Application Access page because they are assigned to XOffice client applications as their parent ID. The Manage External Application Access does not display any records whose parent ID is populated.

•         Client application records in IDCS or OCI IAM without client ID’s are not imported.

•         Client application records in IDCS or OCI IAM with duplicate client ID’s are tracked as duplicates in logs.

•         The screen displays an error if it cannot refresh the data, typically if communication with IDCS or OCI IAM fails. See above for details on the settings used for communication with IDCS or OCI IAM.

create a new client application

Select New Client to open the Generate Application Client window.

Note:  Typically, before beginning the generation steps, you would select the Refresh option to confirm that the required client application was not already created.

work with the web services to which the client application has access

Select the edit icon (edit_icon.png) for an application to open the Edit Web Services window, where you can review, select, or unselect the web services that can be authorized through the application.

regenerate the client secret for the application

Select the new secret icon (NewSecretIcon.png) for an application to open the Regenerate Application Client Secret window, where you can generate a new client secret to use when requesting an OAuth token.

Note:  This option is available only for external application clients that were created through Order Broker.

search for a client application

To search based on application description: Enter a full or partial Application Description and click Search to display applications that contain your entry.

Note:             External applications that were generated through Customer Engagement Cloud Services have a blank description.

To search based on web service assignment: Select a Web Service from the dropdown list and click Search to display applications assigned to that web service. For example, select Discovery from the dropdown list and click Search to display applications that are configured to authenticate discovery web service requests.

Optionally, you can search based both on Application Description and Web Service assignment.

This screen displays records only if they are not associated in IDCS or OCI IAM with a parent ID. If you use XOffice On Prem, each store location record in IDCS or OCI IAM is associated with the XOffice On Prem application as its parent ID. Because there can be many store locations associated with the parent application record, this screen displays just the XOffice record rather than the individual store locations.

Fields at this screen

Field

Description

Search Fields

Application Description

The description of the client application created for web service authentication. This is the Description in IDCS or OCI IAM. Alphanumeric, 50 positions.

Note:             External applications that were generated through Customer Engagement Cloud Services have a blank description.

Web Service

The Order Broker inbound web service to which the application has access. Optionally, select one of the following to restrict your search results:

•         Admin: Includes:

•         ProductUpdate

•         LocationUpdate

•         LocationDetail

•         Discovery: Requests include Location discovery and System discovery.

•         Locate: Includes all requests related to the Routing Engine:

•         EchoTest

•         Fulfillments

•         Intransit

•         LocateItems

•         OrderSearch

•         OrderUpdate

•         ProductAvailability

•         StatusListRequest

•         StatusRequest

•         StatusUpdate

•         SubmitOrder

•         Private Data Request: Includes all requests to inquire on or delete private data:

•         GetPrivateData

•         ForgetPrivateData

•         Purchasing: Includes all requests from the retailer to Order Broker related to the Supplier Direct Fulfillment module:

•         CreateDSOrder

•         CreateDSVendor

•         GetDSChanges

•         GetDSInvoices

•         SetDSAddressChange

•         SetDSCancel

•         SetDSCostChange

 

•         Oracle Retail Integration Cloud Service: Includes all requests received from Oracle Retail Integration Cloud Service (RICS). See Order Fulfillment through RICS Integration for background on order-related messages. Not currently implemented.

This authentication is also required to receive individual updates to the available quantities for product locations through the Retail Integration Bus (RIB). See Available-to-Sell Individual Inventory Updates through Oracle Retail Integration Cloud Service (RICS) for a discussion.

•         Storage: Includes all requests from an integrating system to upload, download, inquire on, or delete files through File Storage API for Imports and Exports:

•         putFile

•         getFile

•         getFiles

•         deleteFile

For more information: See the Operations Guide for details on the above messages.

•         Vendor: Includes all requests submitted by an integrated vendor to Order Broker for the Supplier Direct Fulfillment module:

•         setDSAcknowledge

•         getDSOrders

•         setDSShipConfirm

For more information: See the Vendor Integration Guide for details on the above messages.

Search Results

Application Description

The description of the application created for web service authentication. This is the Description in IDCS or OCI IAM. Alphanumeric, 50 positions.

Client ID

The client ID uniquely identifies the client in IDCS or OCI IAM:

•         If the Application Type is XOffice On Prem, the client ID is RGBU_XTROFFOP_ <ENV>_XOFFICE_APPID, where <ENV> is the environment, such as PROD for production.

•         If the application record was created through Order Broker or another omnnichannel application, the client ID is formatted as RGBU_OBCS_<RANDOM>_APPID, where OBCS identifies the application, and <RANDOM> is a series of 8 random characters.

•         Otherwise, if the application record was created in IDCS or OCI IAM, the client ID is a series of random characters.

This is the Name in IDCS or OCI IAM. Note that the Display Name in IDCS or OCI IAM is the Client ID without the _APPID suffix.

Alphanumeric, 255 positions. Display-only.

Note:  The client ID is similar to a user ID in that it identifies a client application to the authentication service, in this case IDCS or OCI IAM. You can create client IDs through the Manage External Application Access screen, in IDCS or OCI IAM, or through other applications, such as Customer Engagement.

Web Service Access

The list of Order Broker inbound web service to which the application has access. See Web Service, above, for a list of possible web services. You can use the Edit Web Services window to work with the inbound web services. Display-only.

Date Created

The date when the application record was created or regenerated in Order Broker, which could be when the record was received from IDCS or OCI IAM, or generated during the creation of a new record through Xstore On Prem authentication, as well as through the Generate Application Client window. Display-only.

Edit Access

Select the edit icon (edit_icon.png) for an application to open the Edit Web Services window, where you can review, select, or unselect the web services that the application can authorize.

New Secret

Select the new secret icon (NewSecretIcon.png) for an application to open the Regenerate Application Client Secret window, where you can generate a new client secret to use to request an OAuth token.

Note:  This option is available only for external application clients that were created through the Generate Application Client window in Order Broker.

 

________________________________