Export (0) Print
Expand All

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.

To authenticate with a Microsoft account, the Microsoft account user must sign up for a new Bing Ads account, be invited to manage your Bing Ads accounts, or be linked to an existing legacy Bing Ads username.

System_CLiX_note Note

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. In future versions of the API, Bing Ads will transition exclusively to Microsoft Account authentication.

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.

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.

  1. Go to https://account.live.com/developers/applications, and login with your Microsoft Account credentials when prompted.

    System_CLiX_note Note

    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.

  2. Under My apps, click Create application.

  3. Provide the application name and language, and accept the terms of use.

  4. Specify the redirect domain for a web application, and otherwise indicate that your application is a mobile or desktop application.

  5. 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.

System_CLiX_important Important

For web applications do not use implicit grant flow, and instead use a client secret with the Authorization Code Grant Flow.

  1. 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.

    https://login.live.com/oauth20_authorize.srf?client_id=CLIENT_ID&scope=bingads.manage&response_type=token&redirect_uri=https://login.live.com/oauth20_desktop.srf
    
    System_CLiX_noteNote

    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.

  2. 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.

  3. 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.

    System_CLiX_note Note

    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.

  4. Use the returned access token as the AuthenticationToken element within Bing Ads service request header.

Authorization Code Grant Flow

For repeat or long term authentication, you should follow the authorization code grant flow for obtaining an access token. This is a standard OAuth 2.0 flow and is defined in detail in the Authorization Code Grant section of the OAuth 2.0 spec.

  1. 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.

    https://login.live.com/oauth20_authorize.srf?client_id=CLIENT_ID&scope=bingads.manage&response_type=code&redirect_uri=REDIRECTURI
    
    System_CLiX_noteNote

    The scope parameter should be set to bingads.manage and the response type set to code.

    If you registered a desktop or mobile application, use https://login.live.com/oauth20_desktop.srf as the redirect URI. If you registered a web application, use the redirect URI you specified in Registering Your Application.

  2. 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.

  3. The authorization service calls back to your application with the redirection URI, which includes an authorization code if the user authorized your application to manage their Bing Ads accounts. For example the callback URI includes an authorization code as follows if the user granted permissions for your application to manage their Bing Ads accounts: https://login.live.com/oauth20_desktop.srf?code=AUTHORIZATION_CODE.

    System_CLiX_note Note

    If the user granted your application permissions to manage their Bing Ads accounts, you should use the AUTHORIZATION_CODE right away in the next step. The short duration of the authorization code, for example 5 minutes, is subject to change.

    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: REDIRECTURI?error=access_denied&error_description=ERROR_DESCRIPTION.

  4. Use the authorization code to request the access token and refresh token. Connect to the token provisioning endpoint, by using a URL in the following format.

    https://login.live.com/oauth20_token.srf?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=CODE&grant_type=authorization_code&redirect_uri=REDIRECTURI
    
    System_CLiX_noteNote

    The code parameter should be set to the value of the authorization code retrieved in the previous step, and the grant type set to authorization_code.

    The value substituted for REDIRECTURI must exactly match the redirect URI used to obtain the authorization code.

    If you registered a web application, you should replace CLIENT_SECRET with the value provisioned in Registering Your Application, and otherwise you should exclude the client_secret key and value pair from the URL.

  5. Get the access_token, refresh_token, and expires_in values from the JSON response stream.

    • Use the returned access token as the AuthenticationToken element within Bing Ads service request header.

    • The value of expires_in represents the maximum time in seconds, until the access token will expire. Before the access token expires, you should request a new access token as discussed in the next step.

  6. Use the refresh token to get a new access token and new refresh token. You should request a new token before the current access token expires, or catch the AuthenticationTokenExpired error code (109) and then request a refresh token. Connect to the token provisioning endpoint, by using a URL in the following format.

    https://login.live.com/oauth20_token.srf?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=refresh_token&redirect_uri=REDIRECTURI&refresh_token=REFRESH_TOKEN
    
    System_CLiX_noteNote

    The grant type must be set to refresh_token.

    The value substituted for REDIRECTURI must exactly match the redirect URI used to obtain the authorization code.

    If you registered a web application, you should replace CLIENT_SECRET with the value provisioned in Registering Your Application, and otherwise you should exclude the client_secret key and value pair from the URL.

    System_CLiX_noteNote

    Whereas the refresh token parameter does not have a defined expiration period, you should expect it to last several months. As a best practice the refresh token should be set to the value of the most recent refresh token retrieved.

    You may need to start again from Step 1 and request user consent if, for example the Microsoft Account user changed their password, removed a device from their list of trusted devices, or removed permissions for your application to authenticate on their behalf.

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>

System_CLiX_noteNote

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.

See Also

Concepts

Bing Ads Web Service Addresses

Community Additions

ADD
Show:
© 2014 Microsoft