Integrate with Yahoo ConnectID: Server-to-Server Method

Integration Overview

A ConnectID integration consists of 2 high-level steps:

• Obtain a ConnectID by sending a hashed email along with several other parameters described below

• Include the ConnectID in the ad request

Sellers integrating with Yahoo ConnectID via the server-to-server method must follow the process outlined in this article. A seller must first obtain Yahoo credentials to generate an access token at run time in order to obtain a ConnectID.

Obtain Yahoo Credentials

The ConnectID Server-to-Server API is secured by OAuth2 authentication. Each request for a ConnectID must contain an access token derived from the Yahoo OAuth2 credentials. OAuth Credentials consist of a Client ID and Secret. An Account Manager will send the credentials securely. A seller must create both a private and public key using Openssl following the process below so Yahoo can encrypt the OAuth Secret.

Once the “Obtain Yahoo Credentials” process below is completed, work with your Account Manager or reach out to [email protected] to obtain the information necessary for the next step.

Create both a Private and Public Key using Openssl

1. Install Openssl from a trusted source.

2. Generate a private key using the following command line.

   >> openssl genpkey -aes256 -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private_key.pem

3. Generate a public key using the following command line and the private key generated in step 1.

   >> openssl rsa -in private_key.pem -out public_key.pem -outform PEM -pubout

4. Email the public key to the Account Manager.

   An Account Manager will respond via email with a Publisher ID, OAuth client ID and a file that is encrypted with the above public key containing your account password.

5. Decrypt the file containing your OAuth credentials with the private key by entering the following command line.

   >> openssl rsautl -decrypt -inkey private_key.pem -in credential.enc -out my_credentials.txt

   Security Considerations

   OAuth credentials must be protected and NEVER exposed. They should also be reset periodically. All interactions MUST be protected by Transport Layer Security (TLS). Do not embed credentials directly in code to avoid being accidentally exposed to the public. Instead, store your credentials in environment variables or in files outside of the application's source tree. If your credentials are compromised at any point, it is very important to reset them.

   To reset or get a new Secret, repeat the instructions above.

Generate Yahoo Access Token

The ConnectID Server-to-Server API integration method requires an OAuth2 access token for every request. The following process details how to generate a Yahoo access token by obtaining a valid token, then submitting a POST request to the ID-B2B endpoint.

Important

The body of the POST request must contain a JSON Web Token containing the OAuth2 credentials obtained above. To obtain an access token, generate a JWT first.Important: The body of the POST request must contain a JSON Web Token containing the OAuth2 credentials obtained above. To obtain an access, token generate a JWT first.

Note

The sample Code for Token Generation is supplied on request. Please reach out to your account manager.

Generate JSON Web Token (JWT)

A JSON Web Token is composed of three main parts:

1. Header - normalized structure specifying how the token is signed (generally using HMAC SHA-256 algorithm)

2. Claims - a free set of your choice: client_id, aud, expiration date, etc.

3. Signature - to ensure data integrity.

The signature mechanism is HMAC_SHA256 as defined by the JOSE specifications (https://tools.ietf.org/html/draft-ietf-jose-json-web-signature-31).

Example JWT Header

{
   "alg": "HS256",
   "typ": "JWT"
}

Example JWT Claims

{
"aud": "https://id.b2b.yahooinc.com/identity/oauth2/access_token?realm=ups",
"iss": "{client_id}",
"sub": "{client_id}",
"exp": {expiry time in seconds},
"iat": {issued time in seconds},
}

NOTE: "exp" and "iat" values should be numeric. Do not set them as strings.
            "exp" value should be less than 24 hrs. Preferable time is currentTime + 600 (ie 10 minutes). Do not use currentTime + (24 * 60 * 60) as this may produce the "JWT is has expired or is not valid" error.
            "urn:vm:claims:fedidp_tenant" is an optional value. Pass this only if exchanging a federated token.

Example JWT Signature

jwt_signing_string = base64url_encode(jwt_header) + '.' + base64url_encode(jwt_body);
jwt_signature = base64url_encode(hmac_sha256(jwt_signing_string, client_secret)) 
JWS = jwt_signing_string + '.' + jwt_signature

Example manual steps to build the JWT value

jwt_header = '{"typ":"JWT","alg":"HS256"}';
jwt_body = '{
  "iss":"client_id",
  "sub":"client_id",
  "aud":"https://id.b2b.yahooinc.com/identity/oauth2/access_token?realm=ups",
  "exp":<expiry-time-in-seconds>,
  "iat":<issued-time-in-seconds>}';
jwt_signing_string = base64url_encode(jwt_header) + '.' +                       
        base64url_encode(jwt_body);
jwt_signature = base64url_encode(hmac_sha256(jwt_signing_string, 
        client_secret))
JWS = jwt_signing_string + '.' + jwt_signature

Example of the final JWT token

ew0KICAiYWxnIjogIkhTMjU2IiwNCiAgICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYXVkIjogIntwcm90b2NvbH06Ly97YjJiLmhvc3R9L2lkZW50aXR5L29hdXRoMi9hY2Nlc3NfdG9rZW4/cmVhbG09PHlvdXItcmVhbG0+IiwNCiAgImlzcyI6ICJ7Y2xpZW50X2lkfSIsDQogICJzdWIiOiAie2NsaWVudF9pZH0iLA0KICAiZXhwIjog4oCce2V4cGlyeSB0aW1lIGluIHNlY29uZHN94oCdLA0KICAiaWF0Ijog4oCce2lzc3VlZCB0aW1lIGluIHNlY29uZHN94oCdDQp9DQo.uKqU9dTB6gKwG6jQCuXYAiMNdfNRw98Hw_IWuA5MaMo


<base64url-encoded header>.<base64url-encoded claims>.<base64url-encoded signature> (They are separated by a “.”)

Sample code blocks for generating a JWT and access token are provided below.

Request An Access Token

Request an access token from the ID-B2B endpoint using the JWT generated from the client ID and secret. Include the token in the requests to our ConnectID S2S endpoint.

Important!

The token remains active for 10 minutes, and may be re-used instead of requesting a new token for every postback. Also, the token can be refreshed/regenerated at around 8-9 minutes instead of waiting the full 10 minutes.

1. Set the Body of the Request

   Example

   POST /identity/oauth2/access_token HTTP/1.1 
       Host: https://id.b2b.yahooinc.com 
       Content-Type: application/x-www-form-urlencoded 
       Accept: application/json grant_type=client_credentials&scope=connectid&realm=ups&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc 3MiOiJkNjI0YmI4My03MzViLTRmNTMtYjU1Ni03YTEzMGM5YzAxZjMiLCJzdWIiOiJkNjI0YmI4My03Mz ViLTRmNTMtYjU1Ni03YTEzMGM5YzAxZjMiLCJhdWQiOiJodHRwczovL2lkLXVhdDIuY29ycC5hb2wuY 29tL2lkZW50aXR5L29hdXRoMi9hY2Nlc3NfdG9rZW4_cmVhbG09YjJiIiwiaWF0IjoxNDc1MDk1Mjg1Ljk 1NCwiZXhwIjoxNDc1MDk1NTg1Ljk1NCwicmVhbG0iOiJiMmIifQ.JzeW4YvrN7HC1nAcrj21_9yn2i3Iq9b abpTmbNuPfcM

Required Body Request Fields

2. Submit a POST Request to https://id.b2b.yahooinc.com/identity/oauth2/access_token

   Note

   Make sure the Content-Type is set to application/x-www-form-urlencoded.

   Example

   Format: json Status: 200 Headers: Content-Type: application/json
   {
      "access_token": "0bed77b1-435e-4b51-9ff0-f087a75941de",
      "scope": "connectId",
      "token_type": "Bearer",
      "expires_in": 599
   }

   If errors occur while obtaining the access token, refer to the Access Token Troubleshooting document or reach out to your Account Manager.

GET Yahoo ConnectID

The ConnectID server-to-server API accepts an HTTPS GET request with a hashed user email and the Publisher ID as parameters and returns a JSON object containing the ConnectID associated with the hashed email.

GET Request

Put the access token in the request header to invoke the Yahoo ConnectID Server-to-Server API. The header name is Authorization and the value is the access token.

Example

curl 'https://connectid.s2s.analytics.yahoo.com/s2s/connectid?he=20cdc60e06efd975906d99273fea7e63030cf1cb5b2b3c14bfdae00e3exxxxxx&pi=1001' --header 'Authorization: Bearer 0bed77b1-435e-4b51-9ff0-f087a75941de'

Endpoint

https://connectid.s2s.analytics.yahoo.com/s2s/connectid

Query Parameters

Request Header

GET Response

The ConnectID Server-to-Server API will respond with a 200 OK and a Content-Type Header value of “application/json”. A JSON object in the body of the response contains one field consisting of 2 strings, the name of the field and the ConnectID value.

Example

{
   "connectId": "P8XXUtgxNktZDDRg0FSPZXanjlpNCyRsMeZBr9pK_N6UwNkzCpbIeDQa3vx8Ekqv6KhRlhli5xN-TP0hZufwLw"
}

{

"connectId": "P8XXUtgxNktZDDRg0FSPZXanjlpNCyRsMeZBr9pK_N6UwNkzCpbIeDQa3vx8Ekqv6KhRlhli5xN-TP0hZufwLw"

}

HTTP Status Return Codes

Caching

ConnectIDs can be stored for a period of time such that a request for a ConnectID doesn’t have to be sent continuously for the same user. We recommend a cache of 24 hours.

Opt-Out Handling

If the user has opted-out (refer to Honoring Privacy Choices), ConnectID Server-to-Server API will respond with the HTTP status 200 OK and an empty JSON with opening and closing curly braces with nothing in between (“{}”).

Include ConnectID in Ad Requests

For Sellers Using Prebid

For sellers using Prebid, follow the example below to include ConnectID in ad requests. Refer to additional Prebid documentation.

pbjs.setConfig({
    userSync: {
        userIds: [{
            name: "connectId",
	        value: {
		       connectId: "example-value"
            }
        }]
    }
})

For Sellers Using Publica

For sellers using Publica, ConnectID value should be sent in the endpoint request as a macro in the query parameters with the structure of connect_id=[ID_VALUE]. Please note that the query parameters are case sensitive, and need to be all lower case.

Example

https://endpointurl.com/site_id=123&app_bundle=example_app_bundle&format=vast&connect_id=connect_id_value

Once Publica identifies the ConnectID value in the query parameter, it will pass the value to Yahoo in the bid request “user.ext.eids” object.

ConnectID in OpenRTB

In general, Yahoo DSP expects to receive ConnectID in adherence to the OpenRTB Extended Identifiers specification. Currently, Yahoo DSP supports OpenRTB 2.5 and expects to receive ConnectID in the “user.ext.eids” object portion of the bid request.

UIDs object

Example Bid Request

user: {
    ext: {
        eids: [{ 
            source: "yahoo.com",
	        uids: [{
		       id: "connectId_value_here"
            }]
        }]
    }
}

Honoring Privacy Choices

Yahoo ConnectID provides multiple mechanisms for users to manage their privacy choices. Users can manage their choices via the ConnectID Control Portal, on the Yahoo Privacy Dashboard and NAI’s Audience Matched Opt Out page. Additionally, Connect ID also respects industry-standard privacy signals (e.g., CPRA Do Not Sell), when passed through the applicable API endpoints.

Once users are opted-out, no further actions are required by sellers as Yahoo ensures that privacy choices selected by users via any one of these methods are honored. We automatically stop generating ConnectIDs for users who have opted-out.