Authorization Guide

Overview

The Adform API endpoints require authorization. Most of the services require 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.

Using the credentials of the application, and optionally involving end-user, access token is generated and issued to the application. The application then includes this token in every API request, so API services are able to authorize the application and end-user from this token, execute the request and return the resources to the application.

OAuth is an open authorization standard for securing APIs.

The key points of OAuth:

  • The user credentials are not passed to the application

  • The user allows applications to access limited scope of functionality

  • The API services know which applications consume their APIs

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

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

OpenID Connect (OIDC) protocol, that stands on top of OAuth 2.0 can be used for authentication purposes and obtaining the information about the user in a standard way.

 

Discovery Document

The OpenID Connect protocol requires the use of multiple endpoints for authenticating users, and for requesting resources including tokens, user information, and public keys.

To simplify implementations OpenID Connect supports "Discovery document" - JSON document containing key-value pairs which provide details about the OpenID Connect provider's configuration, including the URIs of the authorization, token, userinfo, and public-keys endpoints.

The URI ot the 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.


        authorization_endpoint:"https://id.adform.com/sts/connect/authorize",

  token_endpoint:"https://id.adform.com/sts/connect/token",
    

And cached for the certain amount of time.

 

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 for clients are web applications, native mobile or desktop applications, SPAs, server processes etc.

  • The user (resource owner) is a human that 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 allows users and clients to access recourses via API services by:
    • authenticating the user
    • authenticating the client (application)
    • issuing tokens for the client (application)

Prerequisites

Registering OAuth client (application)

The OAuth client must be registered to consume Adform APIs. The client credentials, authorization code and implicit authorization flows are supported.

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

  • Short description of your application

  • Authorization flow

  • Scopes the application needs to access

  • In case the application uses client credentials flow, the following information is needed:
    • Username of the user account on which behalf the application will be working.

The email address of this account must be valid, as the application credentials will be sent there.

It is advised to have a special non-human user account for this workflow.

  • In case the application uses authorization code or implicit flows, the following information is needed:
    • Return URLs of the application. The user will be allowed to get redirected to one of the provided URLs after successful authentication.

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

 

Adform user account

The 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 flow and implicit flow.
  • In client credentials flow user account should be automatically mapped to the client (application).

User account can be created by the administrators of the agencies or publishers and also by Adform client support on demand from the authorized customer personnel.

Authorization flows

In order to access resources via API services, the client must obtain access token. This is done using one of the 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. The user is hardwired to the client (application).

The typical use cases are:

  • Automated reporting data retrieval

  • Automated campaign data management

  • Automated tracking URL modifications

  • Etc.

Even if user account is disabled, the authentication will succeed, that is access token for the particular user will be issued. However it will result in unexpected behavior when consuming API services.

The access token is obtained by making the HTTP POST request to the token endpoint:


        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

 

When providing the client_id and client_secret in the Authorization header it is expected to 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 success response contains a JSON OAuth2 response with the following parameters:

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

  • expires_in - Time in seconds how long the access token is valid for.

  • token_type - Identifies the type of token returned. At this time, this field always has the value “Bearer”.

 

Authorization code flow

This flow should be used when the application has a backend, and can have multiple users using this application. User consent is given for the particular application to access the resources belonging to the user.

User can also give the consent for the application to access its resources offline.

The authorization code request is initiated by redirecting the user to the authorization 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 the user will be redirected after the successful authentication. URIs must be registered (assigned) with the client. Must use HTTPS scheme

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

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


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


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

The application then must validate the state value and to exchange the authorization code to the access token by making the POST request in the backend to the token endpoint:


        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"
}
    

 

The access_token value must be included oneach header of further API request as in the example:

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

 

Implicit flow

This authorization flow should be used when the application is a front-end only and does not have a backend. User consent is given for the 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 done by redirecting the user to authorization 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 (for OpenID Connect workflow id_token of id_token token should be used)

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

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

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

  • Nonce - (required for OpenID Connect) - random client-generated string, which is included in returned id_token, used to mitigate replay attacks

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

After the successful authorization the user is redirected to the redirect 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>
    

In case, the OpenID Connect is used (requested any of the scopes: openid, profile, etc. or id_token is requested in response_type): the id_token will be included in the response. The id_token is the OpenID Connect JWT identity token. The id_token must 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

Generating requests

Once access_token is received, it has to be included in all further requests to the API by adding HTTP request header:

Dealing with the expired tokens, refreshing token

The access token is a short-lived token. It typically expires after 1 hour of issuing it.

After this time the API services will respond with HTTP 401 code. The new access token must be issued in order to further consume APIs. This can be done in the following ways depending on the flow used:

  • Client credentials flow: simply obtain new access_token

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

  • Authorization code flow:

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

    • Exchange refresh token to the access token

The expired token can be exchanged to the new valid access token by making a post request to the token endpoint:


        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

Currently 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 (openid, profile etc.) are supported.

Other scopes can be found when navigating our "For developers" section and are shown under respective endpoints (as shown in the screenshot below).

In case there is no circular red icon under a particular endpoint - 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