Introduction

UPDATE: Sealed MPOS Installer doesn't need the activities outlined in this post because the Base Sealed MPOS Installer is signed with the certificate owned by Microsoft so the Reply Url is static and 3rd Parties don't need to setup and maintain their own AAD applications anymore, instead the Base Sealed MPOS Installer always uses the AAD Application maintained by Microsoft. You can still create your own AAD application even for Sealed Installer in case you want more control over that application, for instance if you want to leverage your branding in the login/screen or want non default token expiration.

Modern Point of Sale (MPOS) leverages Azure Active Directory (AAD) to authenticate a user while activating a device. Originally MPOS used an older ADAL V2 library which is no longer recommended way to interact with AAD from within Java Script based UWP applications. The recommended way is to use native to Windows 10 API Web Account Manager. MPOS was modified to not rely on ADAL but leverage the Web Account Manager instead, the change is available in all builds released after 2018. It is also available as a hotfix for 7.1 via the KB4051347.

This change also made MPOS closer to support some Federated AAD scenarios which were not possible to achieve with the older ADAL version.

This uptake dictates a change to the way MPOS application is registered with AAD: while doing so one has to provide Callback/Reply Uri. When ADAL was used we had a luxury to register any Uri we want but with Web Account Manager we have to use a callback Uri with very specific value - the one which is unique for any given app package (APPX) and which is generated by Windows 10 API. While shipping the MPOS we took the callback corresponding to the package we ship and registered it with corresponding AAD First Party Application. So, If the MPOS is used as is without any changes then AAD flow will work without any modifications in MPOS but if MPOS is customized in any way which leads to a different APPX ID (for instance, if you change anything in Package->Identity inside package.appxmanifest file) then such an app will have different callback Url which must be registered with corresponding AAD Application. Since it is not realistic for us to change the First Party application with each and every possible callback Uri the way to solve this is to register your own AAD application which you fully control and therefore can specify any Callback Uri you want and as many of them as you want.

If you will try to use the customized APPS package with the First Party AAD application (means without making any below mentioned changes in AAD) you will see error similar to this one while authenticating against AAD:

AADSTS50011: The reply address 'ms-appx-web://Microsoft.AAD.BrokerPlugin/...' does not match the reply addresses configured for the application

Note that it complains about the reply address used for the AppId which corresponds to the MPOS First Party Application.

The Reply Url depends on the MPOS package SID which is function of Package Family Name (PFN) therefore it depends on a Name and a Public Key so if you change a signing certificate - the SID will change. Note that SID is not changing if the package's version is changing.

The list below enumerates steps needed to create 2 AAD applications: one for MPOS and one for Retail Server. Retail Server one is needed because MPOS must specify a Web Application which contains resources needed for MPOS to work, both of those applications are used by MPOS while acquiring a security token from AAD, in other words MPOS will say to AAD something like this: "I am client application MPOS who needs to access resources protected by a server application Retail Server". You can skip the below steps 1a-1d registering Retail Server application if you already did it earlier while, for instance, setting up Service to Service authentication with Retail Server as described in Support for Service to Service authentication in Retail Server .

Register Retail Server AAD application

a) Navigate to https://aad.portal.azure.com/

b) Click the menu item (on left hand side) Azure Active Directory and then App registrations -> New registration, you will see something like this:

Provide any descriptive name you want, put there something identifying the app belongs to the Retail Server, this will help you identifying it later. Keep all other settings unchanged with their default values as shown above.

c) Once you click “Register” button at the above form, click the link “Expose an API” and then “Add a scope”, copy the value which begins with “api://…” into the clipboard, you will need it later, that is “Application ID URI” or “Server Resource ID”. Click Save and Continue:

d) In the “Add a Scope” screen provide values like, for instance, below:

And then click the button “Add scope” on bottom. This completes registering AAD application corresponding to Retail Server.

e) Click the "Overview" tab, copy the value from the field Application ID URI and paste it into the attribute value corresponding to the key AADRetailServerResourceId in the file DLLHost.exe.config

Register MPOS AAD application

a). Create AAD MPOS application by leveraging Azure Active Directory -> App registrations -> New registration, use these values
Name - specify Customized MPOS (again, you can put here any name you want)
Supported account types - Keep default option Accounts in this organizational directory only
Redirect URI (optional) - select Public client/native (mobile & desktop) . Now the time to specify the callback/reply Url, you need to use the value which might be shown in the error seen in the very first screenshot of this article, the reply address starts with ms-appx-web://Microsoft.AAD.BrokerPlugin/

That reply/callback Url can also be seen in the Event Viewer (Microsoft-Dynamics-Commerce-ModernPos/Operational) in one of the first events once MPOS is started. The event's ID is 40619, it is logged with the text which starts with:

"This UWP application was assigned the following callback Uri to be used while interacting with AAD: ms-appx-web://Microsoft.AAD.BrokerPlugIn/S-1-15-2-"

Just copy the value of the Url from your event and use it for the above Redirect URI parameter.

Note that once you created the AAD Application you can specify as many callback URLs as you want which means that, if, by any reason, while developing or for Production, you have multiple packages with different Callback Urls, you then could just keep this one single AAD Application and maintain all your CallbackUrls in this single AAD application until you reach the limit of 255 of them, if you hit the limit - you would need to register a new application.

If, by any reason, you cannot find that above mentioned event in the event log use this alternative:

   - Run MPOS and press a key F12 on your keyboard

   - This will open Developer Tools window. Navigate to the tab "Console" copy paste there the line below 

      Commerce.StringExtensions.format("ms-appx-web://Microsoft.AAD.BrokerPlugIn/{0}",         Windows.Security.Authentication.Web.WebAuthenticationBroker.getCurrentApplicationCallbackUri().host.toUpperCase());

      and then hit the green arrow key in bottom left corner:

   - The console output would then print the callback Uri, remove the quotes prior to using it.

b) Click Register button and wait until the operation completes successfully.

c). Copy the Application (client) ID and paste it into the attribute value corresponding to the key AADClientId in the file DLLHost.exe.config
d) While in AAD Portal's page displaying the MPOS details click "API Permissions" -> "Add Permission" -> "My APIs" then locate and click the Retail Server application registered in Step 1, i. e. Customized Retail Server if you followed the sample name.

e) Click on the the line displaying AccessRetailServer permission, then click "Add Permission" button and finally the button "Grant admin consent for <your AAD name>" and then select "Yes" button effectively granting the consent:

You should now see "Granted" in the column Status next to the AccessRetailServer permission.

Granting the consent is not mandatory and is only needed if you want to consent in advance for all users in your tenant and you an Admin in the tenant. If this step is not done, then each user will be asked for the consent they first time try to activate MPOS.

This completes setup on MPOS side.

Enable newly created AAD applications on AX side

Once this step is completed, an AAD issued security token would be accepted by a Retail Server

a) In AX go to Commerce Shared Parameters->Identity Providers

b) In the grid "Identity Providers" select a row corresponding to your Azure Active Directory tenant, once you select it the 2 below grids will be refreshed with the applications setup for that tenant

c) In the grid "Relying Parties" click "Add" and add new row with the following parameters:

  - ClientID - specify the one you used in the step #10 above

  - Type - Public

  - UserType - Worker

  - Name - type anything you want there, I recommend something meaningful so you could realize this is your customized MPOS application registered in your tenant.

d) Click button "Save"

e) Keep newly added into Relying Party grid record selected and click "Add" in the Server Resource IDs, specify:

  - Server Resource ID - specify the value you used in step #6 above.

  - Name - anything meaningful indicating this is the Retail Server registered in your AAD tenant.

f) Click Save button. Make sure all your newly created records are stored as expected - to check that you can navigate between different rows in those grids.

g) Execute the job 1110 and wait until it is completed by verifying "Download Sessions" form to check that the job's status is Applied.

h) At this time the data will be synced to the channel DB but CRT/RS employs a cache which is around 5 minutes, if you don't want to wait until the cache expires and your are not dealing with PROD environment you can consider explicitly recycling app pool of the Retail Server's Web Site.

i) Close MPOS and kill, by using a Task Manager for instance, all instances of the process DllHost.exe

Now try to activate device in MPOS again, if you will still experience issues look into Windows Event Viewer logs corresponding to MPOS and Retail Server for warnings/errors which would be helpful in the investigation.