Managing User Authentication with OAuth
Bing Ads implements the implicit and authorization grant flows of the OAuth 2.0 protocol to enable authentication of Microsoft Accounts that are linked to Bing Ads accounts. You may authenticate for Bing Ads production services with a Microsoft Account, instead of providing the Bing Ads username and password set. Authentication with a Microsoft Account is currently not supported in Sandbox.
In the near future, Bing Ads will transition exclusively to Microsoft Account authentication. New customers are required to sign up for Bing Ads with a Microsoft Account, and to manage those accounts you must use OAuth. Existing users with legacy Bing Ads credentials may continue to specify the UserName and Password header elements.
The DeveloperToken header element is always required. For information on how to get a DeveloperToken, see Getting Started With the Bing Ads API.
User Consent Flows
A Microsoft Account is an email address and password alias that an advertiser and other users may use to manage multiple services, including Bing Ads. Advertisers may associate a Microsoft Account with their Bing Ads account through the Bing Ads web application. To authenticate with each application using the Bing Ads API, advertisers must grant your application access to manage their accounts. When the user successfully provides consent, your application is able to obtain an access token that it then used to authenticate against the Microsoft account service on behalf of the user.
To take advantage of advanced security, users should turn on two-step verification within the Security Info section of their Microsoft Account settings. Opting in for two-step verification ensures the user is prompted for a security code when they sign in on a device not previously designated as trusted by the user. The Microsoft Account authentication service provisions and verifies the security code after your application connects to the authorization endpoint, and before user consent is requested for your application to manage their Bing Ads accounts. For more information, see Managing OAuth Tokens.
Link Managed Users to Microsoft Account
To manage user authentication with OAuth, users of your application should first link their Bing Ads managed user credentials to a Microsoft Account. Users should go to the Bing Ads sign-in page, click Link in the section below the sign-in box, and follow the onscreen instructions here.
Linking gives the Microsoft Account credentials identical access and permissions as the corresponding Bing Ads managed user. For example if a Bing Ads managed user has the Campaign Manager role and access to all accounts for one customer, the linked Microsoft Account has the same role and permissions. For more information, see User Roles and Available Service Operations.
Registering Your Application
Before you can manage authentication for users of your Bing Ads application, you must register your application and get the corresponding client ID and client secret.
Go to https://account.live.com/developers/applications, and login with your Microsoft Account credentials when prompted.
You may use any of your Microsoft accounts to manage authentication for your application. Using a Microsoft Account which is linked to your Bing Ads user credentials is optional for managing your application.
Under My apps, click Create application.
Specify the redirect domain for a web application, and otherwise indicate that your application is a mobile or desktop application.
Save your changes and take note of your client ID. Also take note of your client secret and redirect URI if you have a web application. You will use these values to manage authentication with OAuth.
Managing OAuth Tokens
Once you have registered your application you can manage the access token for a Microsoft Account user already linked or registered with Bing Ads. For one time or short term access to manage a user's accounts, see Implicit Grant Flow. The access token is short lived and will expire in minutes or hours as determined by the authentication service. Additionally, the Microsoft Account user may change their password or remove permissions for your application to authenticate on their behalf. For repeat or long term access to manage a user's accounts, see Authorization Code Grant Flow.
For a code example that demonstrates authorization code grant flow for desktop and mobile applications, see Authorization Code Grant Flow in C#.
Implicit Grant Flow
For one time or short term authentication, you should follow the implicit grant flow for obtaining an access token. This is a standard OAuth 2.0 flow and is defined in detail in the Implicit Grant section of the OAuth 2.0 spec.
For web applications do not use implicit grant flow, and instead use a client secret with the Authorization Code Grant Flow.
Request user consent through a web browser control. Connect to the authorization endpoint, by using a URL in the following format. Replace CLIENT_ID with the value configured in Registering Your Application.
The scope parameter should be set to bingads.manage and the response type set to token.
For a desktop or mobile application, use https://login.live.com/oauth20_desktop.srf as the redirect URI.
The user will be prompted through the Microsoft Account authorization web browser control to grant permissions for your application to manage their Bing Ads accounts.
The authorization service calls back to your application with the redirection URI, which includes an access token if the user authorized your application to manage their Bing Ads accounts. For example the callback URI includes an access token as follows if the user granted permissions for your application to manage their Bing Ads accounts: https://login.live.com/oauth20_desktop.srf?vv=1550&lc=1033#access_token=ACCESS_TOKEN.
If the user denied your application permissions to manage their Bing Ads accounts, the callback URI includes an error and error description field as follows: https://login.live.com/oauth20_desktop.srf?vv=1550&lc=1033#error=ERROR&error_description=ERROR_DESCRIPTION.
Use the returned access token as the AuthenticationToken element within Bing Ads service request header.
Service Request Header
When making a service call, you still have the option of specifying the UserName and Password header elements along with your DeveloperToken as follows.
<DeveloperToken i:nil="false"></DeveloperToken> <Password i:nil="false"></Password> <UserName i:nil="false"></UserName>
You may specify the AuthenticationToken instead of the UserName and Password for a given user. Set the AuthenticationToken element to the value of the access token returned via OAuth, as described in the sections above. The DeveloperToken is still required as follows.
<AuthenticationToken i:nil="false"></AuthenticationToken> <DeveloperToken i:nil="false"></DeveloperToken>
If you specify UserName, Password, and AuthenticationToken, the UserName and Password are not validated. Authentication would succeed or fail based solely on the value of the AuthenticationToken, even if the UserName and Password represent valid credentials.