Security Considerations for Developers

3 Security Considerations for Developers

This chapter describes security considerations for developers.

Creation of Users

A Customer Administration User will be created as part of the Xstore Office Cloud Service provisioning process. Before end users can access the Xstore Office Cloud Service application it is necessary to create and provision users. This includes provisioning access to the system, assigning organizations, a role and org nodes to each user to control what functionality will be available to them. This will need to be done by the Customer Administration User.

IDCS or OCI IAM

Note:

While users can be created using the IDCS or OCI IAM UI, it is important to note that they must still be provisioned through the Xadmin UI. This includes provisioning access to the system, assigning organizations, a role and org nodes to each user to control what functionality will be available to them.

Manual Creation

Users can be created manually (that is, one at a time) in IDCS or OCI IAM by following the instructions on how to create user accounts in the Oracle Cloud Administering Oracle Identity Cloud Service Guide for IDCS or the Oracle Cloud Infrastructure Documentation for OCI IAM.

Bulk Import

Users can be bulk imported into IDCS or OCI IAM by following the instructions on how to import user accounts in the Oracle Cloud Administering Oracle Identity Cloud Service Guide for IDCS or the Oracle Cloud Infrastructure Documentation for OCI IAM.

REST APIs

Users can also be imported (either individually or in bulk) into IDCS or OCI IAM by invoking IDCS or OCI IAM REST APIs. For more information about the REST APIs, see the Oracle Cloud REST API for Oracle Identity Cloud Service Guide for IDCS or the Oracle Cloud Infrastructure Documentation for OCI IAM.

User Access AppRole

When a user is created using IDCS or OCI IAM (either manually or via bulk import, or via REST APIs), it is the Customer Admin's responsibility to grant the User the User Access AppRole. This can be done in the IDCS or OCI IAM UI as follows:

Click on Oracle Cloud Services in the menu/left frame.
Click on the Xstore Office App:
- For XOCS 20.x environments:
  
  The App will typically be of the format RGBU_XTROFFCS_{ENV}_XOFFICE:
  - where {ENV} can be PRDXX or STGXX or DEVXX (or UATXX)
  - where XX represents an index number
    
    For example, RGBU_XTROFFCS_PRD1_XOFFICE or RGBU_XTROFFCS_STG2_XOFFICE and so on.
- For XOCS 19.x environments:
  
  The App will typically be of the format RGBU_XTROFFCS_{ENV}_XOFFICE.
  - where {ENV} can be PRD, UAT or DEV
Click on the Application Roles tab.
Select the menu icon on the far right of the User Access AppRole.
Select Assign Users and select the Users in the popup to be granted this AppRole.

Xadmin

Refer to the Oracle Retail Xstore Office/Xstore Office Cloud Service User Guide for details on how to provision users via the Xadmin User Management UI.

Xoffice OAuth Client AppRoles

AppRoles have been created in Xoffice OAuth Clients in order to perform additional App Level Authorization.

User Access

Typically, the IDCS or OCI IAM tenant will represent several applications which are independent of each other. The User Access AppRole has been created in the Xstore Office App.

For XOCS 20.x environments:

The Xstore Office App typically has a display name of either RGBU_XTROFFCS_PRDXX_XOFFICE or RGBU_XTROFFCS_STGXX_XOFFICE or RGBU_XTROFFCS_DEVXX_XOFFICE (or RGBU_XTROFFCS_UATXX_XOFFICE) depending on the environment where XX represents an index number.

For XOCS 19.x environments:

The Xstore Office App typically has a display name of either RGBU_XTROFFCS_PRD_XOFFICE or RGBU_XTROFFCS_UAT_XOFFICE or RGBU_XTROFFCS_DEV_XOFFICE depending on the environment.

The User Access AppRole is used to link IDCS or OCI IAM users with the Xstore Office Cloud Service Application.

When Xadmin performs a user sync against IDCS or OCI IAM, it will do the sync based on the users that have been granted this User Access AppRole. Refer to the Oracle Retail Xstore Office/Xstore Office Cloud Service User Guide for details on the user sync between Xadmin and IDCS or OCI IAM.

When a user is created using the IDCS or OCI IAM UI (either manually or via Bulk Import), it is the Customer Admin's responsibility to grant the user the User Access AppRole. This can be done as follows:

Click on Oracle Cloud Services in the menu/left frame.
Click on the Xstore Office App:
- For XOCS 20.x environments:
  
  The App will typically be of the format RGBU_XTROFFCS_{ENV}_XOFFICE:
  - where {ENV} can be PRDXX or STGXX or DEVXX (or UATXX)
  - where XX represents an index number
    
    For example, RGBU_XTROFFCS_PRD1_XOFFICE or RGBU_XTROFFCS_STG2_XOFFICE and so on.
- For XOCS 19.x environments:
  
  The App will typically be of the format RGBU_XTROFFCS_{ENV}_XOFFICE.
  - where {ENV} can be PRD, UAT or DEV
Click on the Application Roles tab.
Select the menu icon on the far right of the User Access AppRole.
Select Assign Users and select the Users in the popup to be granted this AppRole.

Xstore Access

The Xstore Access AppRole is used for additional App Level Authorization. This authorization is done when Xstore Office REST APIs are invoked. Therefore, if the Xstore Office REST APIs are to be invoked, then they must be done by using an OAuth Client (App) that has been granted the Xstore Access AppRole. For instance, refer to Xstore Office Setup App in the Creation of the Setup OAuth Client in IDCS or OCI IAM section. This AppRole should not be granted to any users, groups or apps. Any granting that is required will be done automatically by the system.

Data Privacy Access

The Data Privacy Access AppRole is used for additional App Level Authorization. This authorization is done when the Data Privacy REST APIs are invoked. Therefore, if the Data Privacy REST APIs are to be invoked, they must be done by using an OAuth Client (App) that has been granted the Data Privacy Access AppRole. Refer to the Creation of the Setup OAuth Client in IDCS or OCI IAM section. This AppRole should not be granted to any users, groups or apps. Any granting that is required will be done automatically by the system.

Enhanced Email Access

The Enhanced Email Access AppRole is used for additional App Level Authorization. This authorization is done when the Email Receipt REST API is invoked. Therefore, if the Email Receipt REST API is to be invoked, it must be done by using an OAuth Client (App) that has been granted the Enhanced Email Access AppRole. Refer to the Creation of the Setup OAuth Client in IDCS or OCI IAM section. This AppRole should not be granted to any users, groups or apps. Any granting that is required will be done automatically by the system.

Service Access

The Service Access AppRole is used for internal manipulation of the OAuth Clients. This is also needed in case OAuth Clients need to be deleted. This AppRole should not be granted to any users, groups or apps. Any granting that is required will be done automatically by the system.

Cloud Enrollment of Xstore Clients

Any Xstore register (desktop, thin client, tablet, or mobile) or other client (like Xenvironment or Xservices) that communicates with Xstore Office Cloud Service must first be enrolled in IDCS or OCI IAM via Xstore Office Cloud Service. This can be done either via Xadmin or Xenvironment. The sections below contain information about the steps to be followed for Cloud Enrollment of Xstore Clients.

For more information about how to configure web service authentication for the Retail Omnichannel products, see the Oracle Retail Omnichannel Web Service Authentication Configuration Guide (Doc ID 2728265.1) on My Oracle Support.

Xadmin

Xstore Stores can be enrolled in Xstore Office Cloud Service via Xadmin On-Premise, if the retailer has an existing Xadmin On-Premise application 18.0.1 or higher. Refer to the on-premise Oracle Retail Xstore Office User Guide for these steps.

Xenvironment

Xstore stores can be enrolled in the Xstore Office Cloud Service via Xenvironment by following these steps.

Note:

Collect the following data prior to starting the Cloud Enroll process via Xenvironment.

Xstore Office Cloud Service hostname, port and tenancy ID. The Customer Administrator can look this up by logging into their Cloud Service Account.
IDCS or OCI IAM User credentials: Username and password of any IDCS or OCI IAM user belonging to the provisioned IDCS or OCI IAM tenant.

Note that the user whose credentials are used here MUST NOT have Multi Factor Authentication (MFA) enabled. This same user's credentials can then be used for all Store Enrollments. Whenever Store Enrollments are completed, MFA can be enabled for this user.

Once the Xenvironment installation is complete, open a web browser on the same system where Xenvironment is installed, that is on the lead register. The enrollment process only works when performed on the lead register. Go to the following URL: https://<lead_register_hostname>:9096/cloudenroll.
Log in as the user that runs Xstore Point of Service.
In the form that is presented, enter the Xcenter Application Server Settings for Xstore Office Cloud.
- Host: Xstore Office Cloud Hostname
- Port: Xstore Office Cloud Port
- Username: Username of an IDCS or OCI IAM user (This is typically an email address)
- Tenancy ID: References the prod, stage or dev (or uat) environment. It will be of the format rgbu-omni-<cust>-<env><num>-xocs and is part of the application url.
- Password: Password of an IDCS or OCI IAM user
Click Enroll Location. This will validate the user credentials and enroll the location.
Once the enrollment is complete the systems will be restarted. When the registers start up again they will be configured for Xstore Office Cloud Service.
At Store close all the registers, Xenvironment, and Xservices will be enabled with Xstore Office Cloud Service configurations and all systems will be restarted.

Creation of OAuth Clients in IDCS or OCI IAM

OAuth Clients (also called Apps) are required in order to invoke REST Services exposed by Xstore Office.

A new REST API has been exposed for creating OAuth Clients to be able to perform initial setup of the Xstore Office Cloud Service.

Note:

While OAuth Clients can be created via the IDCS or OCI IAM User Interface, the resulting OAuth Clients do not have all the needed properties in order to be able to function accurately. Instead, follow the steps detailed below in order to create the OAuth Clients using the IDCS or OCI IAM REST APIs.

Prerequisites

It is very helpful to understand tools and terminologies such as Basic Auth, OAuth, curl, json and their usage.
For example, knowing that OAuth uses Bearer Tokens in the HTTP Authorization Header whereas Basic Auth uses Base 64 encoded credentials will help you understand the commands below.
Authorization Header for an OAuth Token would look like this: "Authorization: Bearer <token>"
Authorization Header for a Basic Auth Token would look like this: "Authorization: Basic <Base64_encode(client_id:client_secret)>"

Note:

OAuth Clients are also called Apps. These terms are used interchangeably.
Be sure to use the correct App Client IDs and Client Secrets based on the environment. These steps will have to be repeated for each environment. Using the artifacts from one environment in another environment can lead to unexpected results.

Required Data

Collect the following data prior to creation of the OAuth Clients.

IDCS_TENANT_HOST: The Customer Administrator can look this up by logging into their Cloud Service Account.
IDCS or OCI IAM User credentials: Username and Password of an IDCS or OCI IAM user belonging to the provisioned IDCS or OCI IAM tenant who is either an Identity Domain Administrator or an Application Administrator, or both. An IDCS or OCI IAM user who is neither an Identity Domain Administrator nor an Application Administrator will not be authorized to invoke this API.

Tools

The following steps are executed using curl. However, any similar tool such as SoapUI or Postman can be used.

Creation of the Setup OAuth Client in IDCS or OCI IAM

Xstore Office Setup App

Before the newly provisioned Xstore Office Cloud Service can be used, some initial setup is required. For instance, the Xstore Office database needs Tax Location data to be present in order to be able to setup new stores or organization hierarchy via the Xadmin UI. This can be achieved by using the Xcenter auto deployment functionality via REST services. In order to utilize the Xcenter REST services, an OAuth Client is required. This client can also be used to insert any other seed Xstore Office data that needs to be present in the database besides the Tax Location data.

This Xstore Office Setup OAuth Client can be created by invoking the Enroll Client API as described below.

Note:

This OAuth Client can also be used to invoke RTLog Generator REST APIs.
This OAuth Client credentials can also be used to configure the Data Migration Utility.
This OAuth Client can also be used to invoke Data Privacy APIs.
This OAuth Client can also be used for any additional recurring customer operations where Xcenter REST Services need to be invoked.

Note:

The intent of this API is to create an OAuth Client for the setup of Xstore Office Cloud Service, primarily for Data Migration purposes, uploading "seed" data and for invoking the Data Privacy API. It is not intended to be used for integration with other systems.

Request creation of the Setup OAuth Client. The response will contain the client id, client secret of the OAuth Client as well as the IDCS_TENANT_HOST (which is already known to the Customer Admin).

Replace the <IDCS_username> and <IDCS_password> with those of an IDCS user who is either an Identity Domain Administrator or an Application Administrator or both.

Note that the user whose credentials are used here MUST NOT have Multi Factor Authentication (MFA) enabled. If it is enabled, please disable MFA for only this user temporarily in order to invoke this API. Once the API returns the OAuth Client credentials, please re-enable MFA for this user. If the API needs to be invoked at a future time, please follow the same MFA disable/enable process described above for the user.

curl -i -H "Authorization: Basic <Base64_encode(<IDCS_username>:<IDCS_password>)>" "https://<XSTORE_OFFICE_HOST>/<tenancy_id>/xcenter/rest/Default/21/enrollclient?type=setup"

where <tenancy_id> references the prod, stage or dev (or uat) environment.
Request an Access token using the Setup OAuth Client credentials (from the previous step).

Replace the <client_id> and <client_secret> with those of the Setup OAuth Client (App).

curl -i -H "Authorization: Basic <Base64_encode(<client_id>:<client_secret>)>" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" https://<IDCS_TENANT_HOST>/oauth2/v1/token -d "grant_type=client_credentials&scope=urn:opc:idm:__myscopes__"
This token can now be used to invoke Xoffice REST APIs in order to configure Xstore Office Cloud Service.
RTLog Generator REST APIs:
1. The credentials (Client Id and Client Secret) of the Setup OAuth Client (App) can be similarly used to obtain a token in order to invoke RTLog Generator REST APIs.
Data Migration Utility:
1. The credentials (Client Id and Client Secret) of the Setup OAuth Client (App) can be used when configuring the Data Migration Utility (to update idp.properties) in order to migrate data from an existing Xstore Office to Xstore Office Cloud Service.
Data Privacy API:
1. The credentials (Client Id and Client Secret) of the Setup OAuth Client (App) in conjunction with an IDCS or OCI IAM user's userid/password can be used in order to request an Access token to invoke the Data Privacy REST API.
  
  Replace the <client_id> and <client_secret> with those of the Data Privacy OAuth Client (App).
  
  Replace the <IDCS_username> and <IDCS_password> with those of an IDCS user.
  
  Note that the user whose credentials are used here MUST NOT have Multi Factor Authentication (MFA) enabled. If it is enabled, please disable MFA for only this user temporarily in order to invoke this API. Once the API returns the OAuth token, please re-enable MFA for this user. If the token API needs to be invoked at a future time, please follow the same MFA disable/enable process described above for the user.
  
  curl -i -H "Authorization: Basic <Base64_encode(<client_id>:<client_secret>)>" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" https://<IDCS_TENANT_HOST>/oauth2/v1/token -d "grant_type=password&username=<IDCS_username>&password=<IDCS_password>&scope=urn:opc:idm:__myscopes__"
2. Invoke the Data Privacy endpoint (example – replace with appropriate data).
  
  Replace <token> with the token from the previous step.
  
  curl -i -H "Authorization: Bearer <token>" "https://<XSTORE_OFFICE_HOST>/<tenancy_id>/xcenter/rest/privatedata/1000::100?type=employee"
  
  where <tenancy_id> references the prod, stage or dev (or uat) environment.

Creation of the Enhanced Email OAuth Client in IDCS or OCI IAM

Xstore Office Enhanced Email App

The Enhanced Email App is intended to be created by the Retailer and the credentials are to be given to a third party to invoke the Email Receipt REST API. This Xstore Office Enhanced Email OAuth Client can be created by invoking the Enroll Client API as described below.

Note:

A pre-requisite here is that the Setup OAuth Client must have already been created because those credentials are needed to retrieve a token to invoke the Enroll Client API. In other words, while the Setup OAuth App is created using the Enroll Client API secured via Basic Auth, the Enhanced Email App is also created using the Enroll Client API but it is secured via OAuth (using a token obtained by using the Setup OAuth App credentials).

Note:

The intent of this API call is to create an Enhanced Email OAuth Client to invoke the Email Receipt REST API and cannot be used to invoke any other APIs.

Request creation of the Setup OAuth Client as described in the previous section. The response will contain the client id, client secret of the OAuth Client as well as the IDCS_TENANT_HOST (which is already known to the Customer Admin).
Request an Access token using the Setup OAuth Client credentials (obtained from the previous step).

Replace the <client_id> and <client_secret> with those of the Setup OAuth Client (App).

curl -i -H "Authorization: Basic <Base64_encode(<client_id>:<client_secret>)>" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" https://<IDCS_TENANT_HOST>/ oauth2/v1/token -d "grant_type=client_credentials&scope=urn:opc:idm:__myscopes__"
This token can now be used to invoke the Enroll Client API to request creation of the Enhanced Email OAuth Client. The response will contain the client id, client secret of the OAuth Client as well as the IDCS_TENANT_HOST (which is same as what was used/returned earlier).

curl -i -H “Authorization: Bearer <token>” "https://<XSTORE_OFFICE_HOST>/<tenancy_id>/xcenter/rest/Default/21/enrollclient?type=email"

where <tenancy_id> references the prod, stage or dev (or uat) environment.
Request an Access token using the Enhanced Email OAuth Client credentials (from the previous step).

Replace the <client_id> and <client_secret> with those of the Enhanced Email OAuth Client (App).

curl -i -H "Authorization: Basic <Base64_encode(<client_id>:<client_secret>)>" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" https://<IDCS_TENANT_HOST>/ oauth2/v1/token -d "grant_type=client_credentials&scope=urn:opc:idm:__myscopes__"

This token can now be used to invoke the Email Receipt REST API once the Email Receipt Service Broadcaster has been correctly setup via the Xadmin UI.