Show Menu
TOPICS×

OAuth 2.0 Integration for Real-Time Outbound Transfers

When publishing segments to the partner destination via a realtime server-to-server integration, Audience Manager can be set up to authenticate using OAuth 2.0 when making the requests. This presents the ability to issue authenticated requests from Audience Manager to your endpoint.

Authentication Flow

The Adobe Audience Manager OAuth 2.0 authentication implementation is based on the Client Credentials grant flow and follows these steps:
  1. You must provide us with:
    • The OAuth 2.0 endpoint that generates the authentication token.
    • The credentials used to generate a token.
  2. An Audience Manager consultant sets up the destination using the information you provided.
  3. Once a segment is mapped to this destination, our real-time data transfer system, IRIS , makes a POST request to the token endpoint to exchange the credentials for a bearer token.
  4. For each segment publishing request to the partner endpoint, IRIS uses the bearer token to authenticate.

Requirements

As an Audience Manager partner, the following endpoints are needed to receive authenticated requests:

Endpoint 1 used by IRIS to obtain a bearer token

This endpoint will accept the credentials provided at step 1 and generate a bearer token which will be used on subsequent requests.
  • The endpoint must accept HTTP POST requests.
  • The endpoint must accept and look at the Authorization header. The value for this header will be: Basic <credentials_provided_by_partner> .
  • The endpoint must look at the Content-type header and validate that its value is application/x-www-form-urlencoded ; charset=UTF-8 .
  • The body of the request will be grant_type=client_credentials .

Example request made by Audience Manager to the partner endpoint in order to obtain a bearer token

POST /oauth2/token HTTP/1.1
Host: api.partner.com
User-Agent: Adobe Audience Manager Iris
Authorization: Basic zq2LOO1CcYGrODS5nXiNHpEz97eCpVHAoMF8pAgCntXAzxp5uRV7DTAE2qtPLjhMQwrEX3O6MHV4S
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 29
Accept-Encoding: gzip
  
grant_type=client_credentials

Example response from the partner endpoint

HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/json; charset=utf-8
...
Content-Encoding: gzip
Content-Length: 121
  
{"token_type":"Bearer","access_token":"glIbBVohK8d86alDEnllPWi6IpjZvJC6kwBRuuawts6YMkw4tZkt84rEZYU2ZKHCQP3TT7PnzCQPI0yY"}

Endpoint 2 used by IRIS to publish segments using the bearer token

Audience Manager sends data to this endpoint in near real-time as users qualify for segments. Additionally, this method can send batches of offline or onboarded data as frequently as every 24 hours.
The bearer token generated by endpoint 1 is used to issue requests to this endpoint. The Audience Manager real-time data transfer system, IRIS , constructs a normal HTTPS request and includes an Authorization header. The value for this header will be: Bearer <bearer token from step 1> .

Example response from the partner endpoint

GET /segments/aam HTTP/1.1
Host: api.partner.com
User-Agent: Adobe Audience Manager Iris
Authorization: Bearer glIbBVohK8d86alDEnllPWi6IpjZvJC6kwBRuuawts6YMkw4tZkt84rEZYU2ZKHCQP3TT7PnzCQPI0yY
Content-Type: application/json
Accept-Encoding: gzip
   
{
"ProcessTime": "Wed Jul 27 16:17:42 UTC 2016",
"User_DPID": "12345",
"Client_ID": "74323",
"AAM_Destination_Id": "423",
"User_count": "2",
"Users": [{
   "AAM_UUID": "19393572368547369350319949416899715727",
   "DataPartner_UUID": "4250948725049857",
   "Segments": [{
            "Segment_ID": "14356",
            "Status": "1",
            "DateTime": "Wed Jul 27 16:17:22 UTC 2016"
         }
      ]
   }]
}

This request contains a standard payload (request content).

Important Considerations

Tokens are passwords

The credentials presented by the partner and the tokens obtained by Audience Manager when authenticating using the OAuth 2.0 flow, are sensitive information and must not be shared with third parties.

SSL is required

SSL must be used in order to maintain a secure authentication process. All requests, including the ones used to obtain and use the tokens must use HTTPS endpoints.