Retail Federation Program: How To Guide

Last updated August 26th, 2024

Change Log

8/13/2024 Step 3.e • Updated language to indicate ‘first radio button’ instead of ‘third
radio button’
• Added clarification for differences in ESD/POSA capabilities
8/13/2024 Step 7.b • Minor update to language
8/13/2024 Appendix A • Added steps to create new Certificates if required.
8/19/2024 Summary 5 • Update BillToAccountID to BillToAccountID / Channel Guid
8/19/2024 Step 5 • Update reseller id to BillToAccountID / Channel Guid
8/19/2024 Step 3.e • Corrected description of first radio button.
8/19/2024 Summary 5 • Updated ‘Existing MS Provided App ID’ field with alternative name
‘Client_ID’ for clarity
8/26/2024 Step 3.h • Clarified URI requirements
8/26/2024 Step 1 • Instructions modified to direct partner to P0 Entra account
creation. P2 Entra account creation steps removed.
8/26/2024 Step 2 • Instructions modified to detail payment instrument removal
process for P0 Entra accounts. P2 Entra steps removed.

Summary

Timeline Action needed

Before 15th of 1. Email DigitalOnboardTeam@microsoft.com and acknowledge receipt of
August this communication and provide updated contact information including
name, phone number, and email address.
 By 30th August 2. Create a test Entra tenant or identify existing test tenant for testing
transaction and in parallel create or identify your production tenant
(before 30th August). (Expected time to complete 30 mins)
3. Register new app ID on your test and production Microsoft Entra tenant
(before 30th August).
4. Create Enterprise Application
5. Email DigitalOnboardTeam@microsoft.com with completed information
in below table for each impacted channel. (before 30th August).

Existing Existing Existing New New New New

Partner BillToAccountID MS Test Test Prod Prod
Channel /Channel Guid Provided Entra Entra Entra Entra
Name Prod Tenant App Tenant App ID
App ID / ID ID ID
Client_ID

By 15th September 6. API access token change: update app ID, tenant ID, and Microsoft app
ID
Between 15th and 7. Test new app ID to generate access token to call Retail Federation APIs
30th September
From 15th 8. Begin using new production Entra ID and production app ID to generate
September onwards access token to call Retail Federation APIs
Detailed Steps:

1. Email DigitalOnboardTeam@microsoft.com and acknowledge receipt of this communication and

provide updated contact information including name, phone number, and email address (before
16th August).
 P0 Instructions

1. If you already have an existing test Entra and production Entra tenant skip to step 3. If not,
follow bellow steps:
a. Start here and provide work email address.
b. Enter the required company information:
c. Verify your phone number:
d. Set password
e. Add payment information – NOTE YOU CANNOT DELETE THIS PAYMENT METHOD
FROM THE ACCOUNT UNTIL 72 HOURS AFTER SUBSCRIPTION DELETION (STEP 2
BELOW) BUT IT WILL NOT BE CHARGED
f. Your Account is now ready

g. To confirm account creation navigate to: https://entra.microsoft.com/

h. Select your Microsoft account
i. Your test Entra tenant has now been created
2. [OPTIONAL] Remove your payment instrument.
a. You will need to delete the subscription that you just created to be able to remove your
payment instrument.
i. This process will take 72 hours to complete and can be done in parallel with
Step 3 below.
ii. The removal of this subscription will not prevent you from creating new
Application IDs in Step 3 below but will limit additional Azure capabilities
not required for ESD/POSA authorization.
b. Go to Azure.Microsoft.com and login with your newly created tenant.
c. Navigate to the ‘Subscriptions’ page in Azure.

d. Select your Subscription and click on the blue text.

e. Click Cancel Subscription and confirm cancellation on the subsequent screen.

f. You will see confirmation that cancellation is complete.

g. As a security precaution there is a 72 hour wait period before your ‘Cancelled’

subscription can be deleted. Repeat steps 2.c through 2.f selecting the newly
available ‘Delete’ option. Once you have received confirmation of deletion continue
to step 2.h below.
h. On the left hand navigation (three horizontal lines at top of the screen), Click ‘Cost
Management + Billing’, then Click ‘Billing scopes’.
i. select your Company name under Billing scope

j. Click Payment Methods on the left hand navigation bar

k. Click ‘Detach’ on your payment method

l. Confirm that you intend to detach the card by pressing ‘Detach’

i. If you have not complete step 2.g above you will see an error here.
m. Your payment method screen will now update to show the card has been detached.
The stored card details may now be deleted from the account under ‘Your cards and
debit cards’ if desired.
3. Register new test app ID and production app ID (before 30th August).
a. Go to https://entra.microsoft.com
b. Select your Microsoft account

c. On left side, click Applications, App registrations

d. Click New registration

e. Provide app name (we recommend capturing the following in the name: ESD or POSA and
the Name of your organization e.g.“ESD_Partner Name”) and select the first radio button
“Accounts in this organizational directory only”, click register.
i. POSA: Only a single App Id and Certificate will need to be created for the Parent
Channel.
ii. ESD: An App ID and Certificate will need to be created for each Channel/Billing
Account.

f. Click Authentication
g. Click Add a platform, select Web

h. Enter the redirect URI of the application, this will not be used as this is a Service-To-
Service connection but is required. The value can be any valid URI including localhost.
Check box ‘Access tokens’ and ‘ID tokens’, click Configure
i. Select Certificates & secrets, click Certificates, click upload certificates, select a file (see
support document for details: Certificate Guidelines), enter description, click add.
i. IMPORTANT: YOU WILL NEED TO MONTIOR YOUR CERTIFICATE EXPRIATION DATE
AND RENEW YOUR CERTIFICATE BEFORE IT EXPIRES

j. Click Overview, note your application ID and Directory tenant ID, these will be needed
for step 4.
4. Create Enterprise Application. Follow steps for your production and test tenant.
a. Install the Microsoft Graph PowerShell SDK | Microsoft Learn
b. Run: connect-MgGraph -Scopes "Application.ReadWrite.All" and sign in with a Cloud
Application Administrator role or Global Administrator Role in Microsoft Graph
PowerShell
c. Create an enterprise application for Microsoft Retail Application (see Create an
enterprise application from a multitenant application - Microsoft Entra ID | Microsoft
Learn for details) by running the following in Microsoft Graph PowerShell
Run when connect to
Sandbox Tenant in
az ad sp create --id 6e1969c8-2219-4c50-8509-92d25961c1a5
Microsoft Graph
PowerShell

Run when connect to

Production Tenant in
az ad sp create --id c18f7ce5-2515-4ba5-ae22-9ba7e7a623c7
Microsoft Graph
PowerShell
This is for Provisioning Microsoft App Service Principal in Partner's Tenant

5. Email DigitalOnboardTeam@microsoft.com and provide partner name, BillToAccountID /

Channel Guid, Directory tenant ID (aka Entra tenant), application client ID, and specify test or
production tenant. (before 30th August). Expected 5 minutes.
6. API access token change: update app ID, tenant ID, and Microsoft app ID (before 15th
September). Expected 1 day.
a. You will need to make changes in your config interface or code depending on your
implementation
b. Microsoft App ID:
PPE (Sandbox) PROD (Production)
MS App ID 6e1969c8-2219-4c50-8509-92d25961c1a5 c18f7ce5-2515-4ba5-ae22-9ba7e7a623c7

7. Test new test app ID to generate access token to call Retail Federation APIs (between 15th
September and 30th September). Expected 2 weeks.
a. If you are having any issues with testing, then register for weekly office hours: Register
here.
b. Once your testing is complete, move to step 8.
8. Create a production Entra tenant or use existing production tenant and register a production
app ID (repeat steps 3 – 5).
9. Begin using new production Entra tenant and production app ID to generate access token to call
Retail Federation APIs (from 15th September onwards).
 Appendix A

Create a certificate (updated with specific 2048-bit length)

1. Install Visual Studio 2015 and also the Windows 10 SDK

2. Run PowerShell command prompt (Visual Studio Command Prompt as Administrator) and
type or Run Windows PowerShell ISE(x86), under file run “Start PowerShell.exe” then enter
into “Windows PowerShell (x86)” window, run following command lines:

makecert -r -pe -n "CN=CISESD Partner Name" -b 08/13/2024 -e 08/12/2025 -sky

exchange -ss my -a sha256 -sr localmachine -len 2048

* replace highlighted in yellow text with your desired cert name and valid time windows.

3. Run in batch: (change PartnerName, password below as required)

set PartnerName "_PartnerName"

makecert -r -pe -n "CN=CIS$PartnerName" -b 08/13/2024 -e 08/12/2025 -sky exchange

-ss my -a sha256 -sr localmachine "CIS$PartnerName.cer" -len 2048

certutil -exportpfx -p "enter your password here" "CIS$PartnerName"

"CIS$PartnerName.pfx"

Ren "CIS$PartnerName.pfx" "CIS$PartnerName.pfx.txt"

Copy "CIS$PartnerName.cer" "CIS$PartnerName.cer.txt"

For multiple certs generation:

$countries = ("DE", "DK", "DEAGency","EE", "FR","FI", "LV","LT","PL","CH")

$countries | foreach {

set PartnerName "PartnerName_$_"

Echo "working on $PartnerName"

makecert -r -pe -n "CN=CISESD_$PartnerName" -b 08/13/2024 -e 08/12/2024 -sky

exchange -ss my -a sha256 -len 2048 -sr localmachine "CISESD_$PartnerName.cer"

certutil -exportpfx -p "enter your password here" "CISESD_$PartnerName"

"CISESD_$PartnerName.pfx"

Ren "CISESD_$PartnerName.pfx" "CISESD_$PartnerName.pfx.txt"

Copy "CISESD_$PartnerName.cer" "CISESD_$PartnerName.cer.txt"

}
4. You can find certificates created in folder C:\Users\your alias

• Send public key file with suffix .cert to DigitalOnboardTeam@microsoft.com

• Install private key file with suffix .pfx in your system