Authorization Guide

Overview

The Adform API endpoints require authorization. Most of the services have need a valid Adform user account, as this is how access to the data is controlled. Adform uses OAuth 2.0 as the authorization standard. Therefore, the application (OAuth client) must be registered and used in the API workflows.

Access token is generated and issued to the application using credentials and, ins some cases, involving end-user. The application, in turn, includes the token in every API request. As the result, API services are able to:

  • Authorize the application and end-user from this token;
  • Execute the request;
  • Return the resources to the application.


OAuth is an open authorization standard for securing APIs.

The key points of OAuth are:

  • User credentials are not passed to the application.

  • User allows applications to access the limited scope of functionality.

  • APIs can identify their consumers.

OAuth 2.0 has multiple authorization flows that backing different uses and types of applications.

Adform supports a part of OpenID Connect: discovery document, ID tokens, JWT token structure with OIDC-preferred syntax, UserInfo endpoint.

OpenID Connect (OIDC) protocol, that stands on top of OAuth 2.0, can be used for authentication purposes and obtaining user's information.

 

Discovery Document

The OpenID Connect protocol requires multiple endpoints for authenticating users and requesting resources, such as tokens, user information and public keys.

To simplify implementations OpenID Connect supports "Discovery document". It's a JSON document containing key-value pairs with details about the OpenID Connect provider's configuration. That includes the URIs of the authorization, token, user info and public-keys endpoints. The URI of "Discovery document" is: https://id.adform.com/sts/.well-known/openid-configuration .

The authorization and token endpoint meant further in the documentation should be the value used from the discovery document and cached for the certain amount of time.


        {
"authorization_endpoint": "https://id.adform.com/sts/connect/authorize",
"token_endpoint": "https://id.adform.com/sts/connect/token",
}
    

OAuth terminology

The OAuth uses the following terms:

  • An OAuth client is a piece of software (application) that requests tokens from IdentityServer - either for authenticating a user or for accessing a resource (also often called a relying party or RP). An OAuth client (application) must be registered with the authorization server. Examples of clients are web applications, native mobile and desktop applications, SPAs, server processes.

  • User (resource owner) is a person who is using a registered client (application) to access his or her data.

  • Scopes are identifiers for resources that a client (application) wants to access. This identifier is sent to the authorization server during an authentication or token request.

  • Authorization server/Identity provider - the OAuth and OpenID Connect service that allows users and clients to access resourses via API by:
    • authenticating the user;
    • authenticating the client (application);
    • issuing tokens for the client (application).

Prerequisites

An OAuth client must be registered to consume Adform APIs. Client credentialsauthorization code and implicit authorization flows are supported.

In order to register a client (application), please contact Adform API support ( api@adform.com ) and provide the following information:

  • Short description of your application (Adform's API use case).

  • Authorization flow.

  • List of Scopes which application needs to access.

If application uses client credentials flow, provide the following information as well:

  • User account's username on which behalf the application will be working.

That account should have a valid email address, as the application credentials will be sent there.

We also reccomend to have a separate non-human user account for this workflow.

If the application uses authorization code or implicit flows, provide the following information:

  • Return URLs of the application. User will be redirected to one of the provided URLs after successful authentication.
  • Name of the application which will be shown on Login page.
  • URL to a logo of your application (50x50 pixels).
  • Client URL - page that contains information about your application (similar to "About us" page).

The client_id and client_secret are the credentials that identify the client (application).

Adform user account

Valid Adform user account is needed to access all APIs. The issued access token for the application must be bound to the specific user account, so it could be validated in the API service.

  • User authenticates himself In the authorization code and implicit flows.
  • User account should be automatically mapped to the client (application) in client credentials flow.

User account can be created by: 

  • Agencies administrators;
  • Publishers administrators;
  • Adform client support on demand from the authorized customer personnel.

Authorization flows

Every client must obtain access token to use API services. It can be done via one of authorization flows, depending on the nature of the application.

 

Client credentials flow

Use case: for service-to-service integrations that do not involve end-user into the authentication process. User is hard-wired to the client (application).

The most common use cases are:

  • Automated reporting data retrieval.

  • Automated campaign data management.

  • Automated tracking URL modifications.

Even disabled user account will lead to succesfull authentication via that workflow. However, it might result in unexpected behavior. 

The access token is obtained by HTTP POST request:


        POST https://id.adform.com/sts/connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=<CLIENT_ID>&
client_secret=<CLIENT_SECRET>&
scope=<SCOPES>
    

Params:

  • grant_type (required) - client_credentials;

  • client_id (either in the POST body, or as a basic authorization header);

  • client_secret (either in the POST body, or as a basic authorization header);

  • scope - one or more scopes that service needs access to.

 

Regarding client_id and client_secret in Authorization header, it should be:

  • client_id: client_secret;

  • Base64 encoded.

 

The response is JSON-encoded object:


        {
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": <EXPIRATION_TIME>,
  "token_type": "Bearer"
}
    

A successful response contains a JSON OAuth2 with the following parameters:

  • access_token - the requested access token. The application can use it to access to the secured resource, such as a web API.

  • expires_in - token's duration in seconds. You'll need to request it again after expiration.

  • token_type - token's type. In our case, it will be “Bearer” all the time.

 

Authorization code flow

The flow should be used when the application has a back-end and, optionally, multiple users. User consent is given to particular application to access user's resources.

User can also give the consent to access application's resources offline.-

The authorization request is initiated by redirecting a user to the proper endpoint:


        https://id.adform.com/sts/connect/authorize?scope=<SCOPES>&state=<STATE>&response_type=code&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>
    

Params:

  • Client_id - client (application) identifier.

  • Scope - space-separated OAuth scopes. Client must be allowed to use these scopes.

  • Redirect_uri - URI where user will be redirected after authentication. URIs must be registered (assigned) with the client and use HTTPS.

  • State - random client-generated string for verifying that a returning user is the same who initiated the authorization. It is used to verify the integrity between request and response and to prevent CSRF attacks. It can be stored in the session storage prior to redirecting a user, and validated after user is returned.

User will be asked to authenticate and to authorize the application (give the consent).

After successful authentication user will be redirected to the URI defined in redirect_uri param:


        https://<REDIRECT_URI>?code=<AUTHORIZATION_CODE>&state=<STATE>
    

After that, an application should:

  1. Validate the state value. 
  2. Exchange the authorization code to the access token. It should be done via POST request in the back-end:

        POST https://id.adform.com/sts/connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=<AUTHORIZATION_CODE>&
client_id=<CLIENT_ID>&
client_secret=<CLIENT_SECRET>&
redirect_uri=<REDIRECT_URI>
    

Params:

  • Grant_type - authorization_code.

  • Code  - authorization code received from query parameters.

  • Client_id - client (application) identifier.

  • Client_secret  - client secret (application password).

  • Redirect_uri - redirect URI used in the authorization step.

The response will be JSON-encoded object with the following structure:


        {
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": <TOKEN EXPIRATION TIME IN SECONDS>,
  "token_type": "Bearer"
}
    

Every header of following API requests should contain an access_token value.
 

If authorization request includes offline_access scope, refresh_token will be included in the response. The refresh_token can be converted to the new valid access_token.

 

Implicit flow

That flow should be used when the application is a front-end only (does not have a back-end). User consent is given to particular application to access the resources belonging to the user. The application receives the access token via URL fragment (hash), which is obtained by Javascript.

Implicit flow supports both OAuth and OpenID flows.
 

The authorization request is initiated by redirecting a user to the proper endpoint:

 


        https://id.adform.com/sts/connect/authorize?response_type=token&client_id=<CLIENT_ID>&state=<STATE>&redirect_uri=<REDIRECT_URI>&scope=<SCOPES>[&nonce=<NONCE>]
    

Params:

  • Client_id - client (application) identifier.

  • Response_type - token (id_token should be used for OpenID Connect workflow).

  • Scope - space-separated OAuth scopes. Client should be allowed to use these scopes.

  • Redirect_uri - URI where user will be redirected after authentication. URIs must be registered (assigned) with the client and use HTTPS.

  • State - random client-generated string for verifying that a returning user is the same who initiated the authorization. It is used to verify the integrity between request and response and to prevent CSRF attacks. It can be stored in the session storage prior to redirecting a user, and validated after user is returned back.

  • Nonce - (required for OpenID Connect) - random client-generated string in returned id_token used for reducing replay attacks.

User will be asked to authenticate and to authorize the application (give the consent).

After successful authorization user will be redirected to the URI with the parameters defined in the URI fragment:


        https://<REDIRECT_URI>#access_token=<ACCESS_TOKEN>&token_type=Bearer&expires_in=<EXPIRATION_TIME>&scope=<SCOPES>&state=<STATE>
    

If OpenID Connect is used, id_token will be included in the response. The id_token is OpenID Connect JWT identity token which should be validated according to the specification: http://openid.net/specs/openid-connect-implicit-1_0.html#IDTokenValidation

The refresh_token is never returned for implicit flows.

Consuming APIs

Postman's chrome extension is not fully compatible with OAuth and will return { "reason": "https_required" }

Please, use Postman's standalone desktop version. 

Generating requests

Once access_token is received, it has to be included in all future API requests by adding HTTP header.

 

Dealing with the expired tokens, refreshing token

The access token is a short-lived. Typically it expires after 1 hour. After that, API services will respond with HTTP 401 code. If that happens, new access token must be issued than. It can be done differently depending on the flow used:

  • Client credentials flow: obtain new access_token.

  • Implicit flow: perform authorization flow (by redirecting user to authorization server). Also, access tokens issued for this flow might have a longer validity period.

  • Authorization code flow:

    • Perform authorization flow (by redirecting user to authorization server).

    • Convert refresh token to the access token.

The expired token can be converted to the new valid access token by POST request:


        POST /sts/connect/token HTTP/1.1
Host: id.adform.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=<REFRESH_TOKEN>&
client_id=<CLIENT_ID>&
client_secret=<CLIENT_SECRET>
    

OAuth Scopes

Most of Adform's APIs are covered with OAuth scope  "https://api.adform.com/scope/eapi".

The scope for retrieving refresh token is "offline_access" (used in authorization code flow only).

In order to use OpenID Connect (obtain id_token, access UserInfo endpoint etc.), standard OpenID Connect scopes (openidprofile etc.) are supported.

Other scopes can be found in "For developers" section under relevant endpoints (as shown in the screenshot below).
 


In case if particular endpoint doesn't have a circular red icon, it requires "https://api.adform.com/scope/eapi" scope.

 

Please provide the needed scopes when registering your OAuth client.

Help

Still have questions?

If you can't find an answer to your question here, email our Support team