Support for Service to Service authentication in Retail Server

Starting AX7 FallUpdate CTP2 Retail Server supports Service to Service authentication which makes it possible to have services capable of communicating with Retail Server without a need of a user in front of a screen to provide credentials at some point in time. This enables scenarios when you need to create processes to periodically contact Retail Server to perform different kind of tasks, for instance, synchronizing customers, orders, publishing products for eCommerce functionality and so on.

That feature leverages Azure AD with OAUTH 2 Client Credentials Grant, the details of this authentication flow can be found in Daemon app that calls a web API in the daemon's name. To setup the feature register 2 AAD applications in your tenant, one app will represent Retail Server's identity and another one the Client application making calls to the Retail Server. These are detailed steps:

Note: The values you will provide for the Issuer, Client ID and Server Resource ID will be compared against values in the Security Token by leveraging case sensitive strings comparisons, so, even if something is looking as a Url don't make an assumption that let's say https://contoso.com and https://contoso.com/ (note the trailing slash in the second one) are identical - they are not in fact.

1. Create AAD applications

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) Now initiate another App Registration, this time for the Client (if you don’t’ have one already). To do this proceed with the step (b), with only change by providing a different name. Once the app is created click the link “API permissions” and then click a button “Add a permission”. In the window opened select “APIs my organization uses” and then paste the name of the RS app created in previous step, in my case it is D365RetailServerSergTest:

f) Click on the application and you will see another windows opened, select the checkbox near the Permission name and click “Add Permission”:

g) Once you save the changes you should see something like this:

h) Now create the secret (or assign a certificate) for just setup Client application, for details please see Authentication: Two options

2. Add the applications' details into RS's authentication allowed list

a) In AX UI navigate to the form Commerce Shared Parameters, if you don't know where it is located you can type that name in the search box and once found click [ENTER]. Once on that form click Identity Providers tab, you will see a pane displaying 3 grids.

b) In the first grid (Identity Providers) select a row with type Azure Active Directory, this selection will result in the 2nd grid (Relying Parties) displaying list of client applications registered for the given identity provider. Click Add button in that 2nd grid and paste there the following values:

 - for the ClientId field specify the ID of the application  you created in the step #1, that is the GUID you can find in Azure portal for the Client (not Retail Server) AAD application you created above. Specific location is in the section Overview, the parameter Application (client) ID.

 - for the Type select Confidential

 - for the UserType specify Application

  To save this row's changes click on any other row in this grid and then click back the row you just added.

c) Scroll down to the Server Resource IDs grid, this one contains RS Uris allowed to be accessed by the application in Relying Parties grid. Click Add in the Server Resource IDs grid and add/fill out the cell Server Resource ID with the value corresponding to the Server Resource ID of your Retail Server (not Client) application which can be seen in the Azure Portal once you navigate to your Retail Server application's Overview section:

As a result you should have something like this:

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 IT->Distribution schedule and then execute the job 1110 (Global configuration). Wait until the job finishes its work, then, in addition, if you don't want to wait until cache expires, and if that is not production environment - you can execute iisreset

You have setup everything on AAD and AX sides, now it is time to test it in action. The LCS VM is shipped with Retail SDK which includes sample eCommerce Publishing client which leverages Service To Service authentication while contacting RS. So, open the project J:\RetailSDK\SampleExtensions\OnlineStore\Publishing\Storefront.Publishing.csproj in Visual Studio (Run Visual Studio as Admin and then load that project), once solution is loaded set the project Storefront.Publishing as Startup one, then open its app.config and provide values for the 4 parameters: 

aadClientId - specify the CLIENT ID corresponding to the Client AAD application you created earlier.

aadClientSecret - specify the client secret corresponding to the above Client AAD application. NOTE that password is accepted/stored here in clear text, this should never be done in PROD system.

aadAuthority - put here the value seen in the column Issuer of the grid Identity Providers, that value should look like https://sts.windows.net/<YourTenantGuidIsHere>/

Make sure to have the guid corresponding to your tenant instead of <YourTenantGuidIsHere>

retailServerUrl - substitute the value there with the one corresponding to the instance of your Retail Server, you can see that Url in LCS portal or just go to IIS, select the site RetailServer and then click Browse, you will see your browser opens with the url something like this: https://<ValueUniqueToYourDeploymentIsHere>.cloudax.dynamics.com/

Add there the suffix Commerce and as a result you have Retail Server url to be stored in the app.config

Now run the application and watch its console output - it will print out details while communicating with AAD and Retail Server.

While building your own client application it makes sense to leverage Retail Server Proxy which hides from you all the details related to transport and authentication. The method CreateManagerFactory located in the file J:\RetailSDK\OnlineStore\Ecommerce.Sdk.Core\Publishing\Publisher.cs shows how to get a token from AAD and then instantiates the proxy.

If you are customizing Retail Server and going to allow the Controller's method to accept calls with this authentication type you need to decorate the method with CommerceAuthorization attribute and role Application, you can also add as many roles as needed in your specific case, for instance the method below accepts calls from all supported by RS types: Employee, Anonymous, Customer, Application.

[CommerceAuthorization(CommerceRoles.Employee, CommerceRoles.Anonymous, CommerceRoles.Customer, CommerceRoles.Application)]
        [HttpPost]
        public ChannelConfiguration GetOrgUnitConfiguration()
        {
            return this.channelManager.GetChannelConfiguration();
        }