Introduction

Cloud hosted Commerce Scale Unit (CSU) includes a Cloud POS which is automatically setup to work with Azure AD Application managed by the Microsoft team hosting the CSU. This applies to both types of Cloud based CSUs: Sandbox and Production.

In case you plan to use Cloud POS in any other CSU deployment topology, you need to register an AAD application in your tenant and set it up with your instance of Cloud POS and F&O. These topologies include:

• On-Prem Scale Unit Installer
• IaaS based Sandbox/Dev/Test/Demo environments

The High Level steps are:

a) Create a pair of AAD Applications (Cloud POS and Retail Server) in your AAD Tenant

b) Modify Cloud POS configuration to point to the above AAD applications

c) Modify HQ Config so the associated Retail Server instance will accept those AAD applications.

Below are the detailed instructions for every step. Vast majority of them are needed to be done just once, then, with every addition/deletion of a CSU, the only action you need to do is to add/remove Reply Urls stored at the Cloud POS AAD application level.

1. Create Retail Server AAD application

1. Login into AAD Portal by using any account in your AAD - the user doesn't have to be an Administrator of any kind.

2. Click Azure Active Directory

3. Click on the tab App registrations then click New registration. Provide values for the fields:

- Name put anything you want here which will help you identify the purpose of the application later, for instance: Customized Retail Server

- Supported account types/Who can use this application or access this API? Leave the default option - Accounts in this organizational directory only

- Redirect URI (optional) - do not add any and leave it as is

4. Click Register button.

5. Click the link Add an Application ID URI. At the top of the page click Set near Application ID URI. Accept the suggested value by clicking the Save button. Take a note of this value - you will need it later while registering this Retail Server application within HQ.

6. Click Add a scope and provide values for the scope:

- Scope name type the desired name, it is up to you what the value will be, for instance: Legacy.Access.Full

- Who can consent? Decide, according to your security policies, if both Admin and Users can accept or only Admins and then make proper selection. In this demonstration I will select Admins and users 

- Admin consent display name type the consent's display name, for instance: Access Retail Server

- Admin consent description type the description to be displayed to end users during the consent, for instance: Gives an access to Retail Server's APIs.

At this time you should see something similar to:

Complete the scope's creation by hitting the Add scope button.

2. Create Cloud POS AAD Application

1. Click "Azure Active Directory"

2. Click on the tab App registrations then click New registration. Provide values for the fields:

- Name put anything you want here, for instance: Customized Cloud POS

- Supported account types/Who can use this application or access this API? Leave the default option - Accounts in this organizational directory only

- Redirect URI (optional) Select Single-page application (SPA) in the Drop-down and *your* Cloud POS Url in the textbox. Note, the value of the reply Url is case sensitive, therefore make sure to copy here the same value which will be used by the users accessing Cloud POS in their Web Browsers. In some cases the browser might append the trailing slash to the Url and in some not, to provide your users a better experience, register both of the Urls - one with the trailing slash and one without it.

You should have something similar to:

3. Click Register button.

4. Click Token configuration and then Add optional claim. In the radio button select ID then set a checkbox corresponding to sid claim and hit Add button. Click Add optional claim again and add the same claim to Access token.

5. Click API permissions and then Add a permission and switch to the tab APIs my organization uses

6. Type the name of the Retail Server application you created at the step 3(a), in my case that is Customized Retail Server. As a result the search results will be narrowed down to that application, click on it.

7. You will see the delegated permission corresponding to the scope created while setting up the application for Retail Server, in my case that is Legacy.Access.Full. Check the checkbox near the permission and hit the button Add permissions. You should see a screen similar to:

3. Update Cloud POS configuration

Now, let's update Cloud POS's config to point to the newly created AAD application

1. Click Overview link of the just created Cloud POS AAD application and copy to the clipboard the value from the field Application (client) ID

2. Open CPOS's config.json and locate there the key AADClientId. Replace its value with the one stored to the clipboard at the previous step. 

3. In the same file find the key AADRetailServerResourceId and replace its value with the value corresponding to Retail Server's Application ID URI created in the step 1.5.

Both of those parameters will be used by Cloud POS when it sends a request to AAD to acquire a security token. This is how my file looks like after making the changes:

By now we completed the changes on AAD and CPOS sides, next step is to add info corresponding to just created AAD applications into an allow list in HQ so RS will be able to successfully authenticate requests coming from your CPOS.

4. Update F&O HQ configuration

1. In HQ UI go to Commerce Shared Parameters form (I think the fastest way to go there is to type that name in the search box and hit [ENTER]) then click there Identity Providers tab, then locate a row with the provider type Azure Active Directory and the issuer pointing to *your* AAD tenant.

If you don't see the issuer corresponding to your tenant ID then you first need to add one click the "+" button in the topmost grid and then specify these values:

Issuer: https://sts.windows.net/ReplaceThisWithTheGuidCorrespondingToYourAadTenant/

Name: put there anything you want which will help you identifying this record, you can put, for instance, name of your Azure Active Directory

Type: Azure Active Directory

Note that value of the issuer is case sensitive and everything there must be lower cased, also make sure to specify the trailing slash

Once you located/added the issuer, select that row. By selecting it you are "declaring" that you are going to work with child grids containing the data related to the Identity Provider corresponding to your AAD Tenant. It is important, while executing the below steps to first select correct row in the top most grid.

2. In Relying Parties grid click Add button and fill out the ClientId cell with the value corresponding to the CPOS Client ID created in the step #4 (that is the same Guid you stored in the config.json). For the Type cell select Public, for the UserType select Worker. To save changes click on any other row in this grid and then click back the row you just added.

3. Make sure just added Relying Party is selected and then navigate to the grid Server Resource IDs, this one contains RS Application IDs allowed to be accessed by the application in Relying Parties grid. Click Add in the Server Resource IDs grid and fill out the cell Server Resource ID with the value corresponding to Retail Server's Application ID URI created in the step 3.3.

Note that all the values, except in the columns Name, in these grids, are case sensitive and must match exact values seen in Azure AD Portal. So, there should be no spaces or any characters/slashes before/after the values if they don't present in the Azure Portal. This is how the registration looks in my environment:

To save the changes either click on any other tab in the form or just close the form.

To bring the changes into the Channel DB go to Retail and commerce->Retail and Commerce IT->Distribution schedule and then execute the job 1110 (Global configuration). Wait until the job finishes its work, by monitoring the job's status in the Download Sessions form, once the job is successfully processed its status will change from Available to Applied. Then, if you don't want to wait until a memory cache on Retail Server side expires, and if that is not production environment - you can recycle the app pool corresponding to Retail Server (preferred way) or execute iisreset from the command line.

This completes all the changes and you should now be able to Activate a Device in your Cloud POS instance associated with your own AAD Applications.

5. Installing additional CSU

Once you done the above steps and in case you need to deploy an additional CSU, you need to only perform a small subset of the previously described steps to add your new Cloud POS's Url into the list of allowed Reply Urls. No changes are needed in any other places. To do that:

1. Navigate to AAD Portal 

2. Click Azure Active Directory

3. Click on the tab App registrations then click All applications. 

4. In the search box type the name of the application, in case of this demonstration that is Customized Cloud POS and then click on the found application

5. Click the link next to the Redirect URIs with the label similar to 0 web, 1 spa, 0 public client

6. Under the section Single-page application add the button Add URI and add the Url corresponding to  your additional Cloud POS. Hit the Save button.

6. Removing CSU

When you no longer need a Cloud POS, it is good idea to remove a Reply Urls corresponding to that Cloud POS from the AAD Application. If you are not deploying lots (hundred) of Cloud POS you might need to never do that but if you do deploy/remove lots of them then keep only those Urls which you need to not exceed the limit of 256 Reply Urls per the application.

To remove the Cloud POS Reply Url follow the steps from the previous section with the only difference in the step # 6 - locate the Url you want to delete and hit the button with the Recycle Bin's icon next to the Url and finally hit the Save button.