Microsoft Advertising User Authentication

Creating Application in Microsoft Azure

Navigate to the Azure Portal.
Select App registrations:
Add a New registration:
Type the name and select the applicable application tenancy, depending on your configuration. For this setup, we select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).
Set the platform to Web.
Next, we need to simulate the web flow of the application security. For that, enter a non-existent server location for the redirect URI. One may usually set a localhost-based link. We use https://localhost.local/redirect.html.
Click Register:
Save the Application (client) ID value, as we will need it for further steps.
Now create an application secret. Click Add a certificate or secret:
Click New client secret:
Add a secret description and set the expiration date. The maximum allowed expiration is 24 months. Set this according to your desired security policy. You will need to re-generate the application tokens by following this process when the secret expires:
Save the client secret, when you create it. This is the only time the secret is displayed to you. You will not be able to read the secret after you navigate away from this page. We need the Value - do not confuse it with the Secret ID (which is not used in the authentication process). You can copy the secret value to the clipboard by clicking the appropriate icon:
When you return to this page, you will only be able to see the first three characters of the secret value. If the value is lost, you must delete and re-generate the client secret, and follow this guide to re-generate the refresh token.
This completes the application setup in Azure Portal.

Generating Tokens

To generate the refresh token, we first need to link the application to the Microsoft Advertising account, by authenticating access by the user who has Microsoft Advertising access. To achieve that, we generate the authentication URL.
The URL follows this pattern (remove newline characters):
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=...
&scope=offline_access%20https://ads.microsoft.com/msads.manage
&response_type=code
&redirect_uri=...
&state=stateVerifier
When using Active Directory-based authentication, replace the keyword common (marked in bold) with the Tenant ID of your Active Directory. Depending on your Active Directory configuration, you may need to specify the active directory domain name instead:

As such, the authentication endpoint may look like one of the following:
CODE
```
https://login.microsoftonline.com/common/oauth2/v2.0/authorize...
https://login.microsoftonline.com/<000000-abcd-efgh-1234-567890>/oauth2/v2.0/authorize...
https://login.microsoftonline.com/<sub_domain>.onmicrosoft.com/oauth2/v2.0/authorize...
```
Paste the values into the authentication URL: the redirect URI (step 6), client ID (step 8), and the tenant ID instead of common (if necessary).
Refer to the official documentation if you encounter issues on this step.
Submit the generated URL to the user with Microsoft Advertising access. When the user follows the URL, he will be prompted to authenticate with his Microsoft Account (or Active Directory username). Note: remove all newline characters (which are in this document for readability reasons) to acquire a single-line URL:
If the URL is incorrect, you will be redirected back to the submitted redirect URI, with the error message being readable in the redirect parameters. This will look like a browser error, however the error text will be sent in the URL parameters. Refer to the address bar of your browser to identify the error. Here is a sample error:
CODE
```
https://localhost.local/redirect.html?error=invalid_client&error_description=AADSTS650052%3a+The+app+is+trying+to+access+a+service+%27d42ffc93-c136-491d-b4fd-6f18168c68fd%27(Microsoft+Advertising+API+Service)+that+your+organization+%27000000-abcd-efgh-1234-567890%27+lacks+a+service+principal+for.+Contact+your+IT+Admin+to+review+the+configuration+of+your+service+subscriptions+or+consent+to+the+application+in+order+to+create+the+required+service+principal.%0d%0aTrace+ID%3a+00000000-0000-0000-0000-000000000000%0d%0aCorrelation+ID%3a+00000000-0000-0000-0000-000000000000%0d%0aTimestamp%3a+2023-03-01+12%3a23%3a47Z&error_uri=https%3a%2f%2flogin.microsoftonline.com%2ferror%3fcode%3d650052#
```
In many cases, such errors are caused by the mismatch between the Active Directory configuration and the Tenant ID used to generate the authentication URL. In this case, return to the previous step and use an alternative authentication URL, that matches the Active Directory configuration. As authentication may be cumbersome, a good idea would be to try an alternative authentication URL. Our experience shows this to be pretty quick.
Normally, if authentication is successful, you are prompted to grant access to the application on the next page. Answering yes would grant access, and the token will be generated:
The short-lived authentication token is returned to the submitted redirect URI under the name code. Save this value. What you normally see, is an error, however the value, which we need on this step, is in the address bar of the browser. Note that the value is valid for a few minutes only, so, be sure to follow the next steps as quickly as possible (within a few minutes). Additionally, this value is disposable, as such if it is used once, and the refresh token is not saved, the authentication process has to be repeated. As the value on the screenshot has already been used, it is not a security breach to openly publish it:
Be sure to have the client ID, client secret, redirect URI, authentication code from the previous step, and, optionally, a tenant ID, if you are using Active Directory authentication. Note that the tenant Id should be be a GUID on this step, independent of whether the GUID or the domain name were used on the first step. Generate a POST request using Postman ) or any other tool capable of making HTTP requests. Feel free to use the provided curl to import it into Postman or use it directly. Replace star combinations ********** with the actual values. For the scope parameter, note the space between the scopes (as opposed to the URL-encoded value of %20 on step 1. When using Active Directory authentication, replace common with the tenant ID value in the web URL.
BASH
```
curl --location --request POST 'https://login.microsoftonline.com/common/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=**********' \
--data-urlencode 'scope=offline_access https://ads.microsoft.com/msads.manage' \
--data-urlencode 'code=**********' \
--data-urlencode 'redirect_uri=**********' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_secret=**********'
```

Submit the HTTP request, and save the refresh token, provided in the response.

JS

{
    "token_type": "Bearer",
    "scope": "https://ads.microsoft.com/msads.manage",
    "expires_in": 3600,
    "ext_expires_in": 3600,
    "access_token": "eyJhbGciO...",
    "refresh_token": "M.R3_BAY.-CVtUf!0S..."
}

Acquiring Developer Token

Details can be found in the official documentation.

Request the developer token.
Sign in with Super Admin credentials at the Microsoft Advertising Developer Portal account tab.
Choose the user that you want to be associated with the developer token. Typically an application only needs one universal token regardless of how many users will be supported.
Click on the Request Token button.
You will be able to use the developer token from the user, who already has one issued.

Acquiring Customer ID and Account ID

Navigate to https://ui.ads.microsoft.com/campaign/vnext/accounts. Select the account you want to connect via the API. Here you can choose between the manager account and an ad account. To acquire the data for all connected accounts you may omit the Account Id property. However, to retrieve data for a particular ad account, its Id should be specified. To get a user's customer ID and account ID, you can sign in to the Microsoft Advertising web application and click on the Campaigns tab. The URL will contain a cid key/value pair in the query string that identifies your customer ID, and an aid key/value pair that identifies your account ID. For example, https://ui.ads.microsoft.com/campaign/Campaigns.m?cid=FindCustomerIdHere&aid=FindAccountIdHere#/customer/FindCustomerIdHere/account/FindAccountIdHere/campaign.

Copy the "Account ID" (later referred to as "Customer Account ID") and the "Customer ID".

More details can be found at https://learn.microsoft.com/en-us/advertising/guides/get-started?view=bingads-13#get-ids

Generating Data Virtuality Installation Script

To do so, paste the values, obtained in the previous steps into the following snippet.

SQL

call SYSADMIN.createConnection(
	name => 'BingAds', 
	jbossCliTemplateName => 'ws', 
	connectionOrResourceAdapterProperties => 
	'ClientId=<client_id>,ClientSecret=<client_secret>,RefreshToken=<refresh_token>,redirectUri=<redirect_uri>,Scope=https://ads.microsoft.com/msads.manage'
);;
 
call SYSADMIN.createDatasource(
	name => 'BingAds', 
	translator => 'bing_ads', 
	modelProperties => 'CustomerId=<customer_id>,DeveloperToken=<developer_token>,TenantId=<00000000-0000-0000-0000-000000000000>'
);;

While the redirect URI is not needed for authentication, it still should be specified, for the connector to indicate which authentication method to use. The Tenant Id can be omitted, if no custom Active Directory is used (i.e. if you used the common endpoint, please omit the Tenant Id). Scope should correspond to the Microsoft Advertiser API, thus it is provided as a literal, rather than a parameter.

Microsoft is introducing changes to the authentication model, and in order to support legacy authentication methods, we provide some parameters as being editable by the user, to ensure backwards compatibility. As such, leave the parameters unchanged if the connector operates normally, but submit those parameters for any new app registrations.

Note: if you are refreshing the credentials due to the expired refresh token, you can reuse all other parameters from the existing data source, except the new refresh token (provided that there was no major-reconfiguration in the Active Directory).