OAuth 2.0 Integration for Real-Time Outbound Transfers oauth-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 auth-flow
The Adobe Audience Manager OAuth 2.0 authentication implementation is based on the Client Credentials grant flow and follows these steps:
-
You must provide us with:
- The OAuth 2.0 endpoint that generates the authentication token.
- The credentials used to generate a token.
-
An Audience Manager consultant sets up the destination using the information you provided.
-
Once a segment is mapped to this destination, our real-time data transfer system, IRIS, makes a
POSTrequest to the token endpoint to exchange the credentials for a bearer token. -
For each segment publishing request to the partner endpoint, IRIS uses the bearer token to authenticate.
Requirements auth-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 POSTrequests. - 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"
}
]
}]
}
Important Considerations 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.