Integrate with ConnectID: Server-to-Server Method

The Yahoo ConnectID is designed to enable ad tech platforms to recognize and match users consistently across the open web. ConnectID is built on top of the robust and proprietary Yahoo ID Graph and enables publishers to thrive in the cookieless world.

Server-to-Server method is only one of the ConnectID integration methods. It is most appropriate in the following situations:

• When a Publisher is integrated with Yahoo SSP via several methods such as prebid, tags or S2S.

• When a Publisher is integrating ConnectID as an identity solution for their CTV supply

Sellers integrating with 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. This integration method uses a web service that returns ConnectIDs (cookieless user identifiers) when a seller sends us a hashed email address.

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 connectid.support@yahooinc.com 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 -outmy_credentials.txt

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 (JWT) containing the OAuth2 credentials obtained above. To obtain an access token generate a JWT first.

Note: Sample Code for Token Generation 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).

 

JWT Header

{

"alg": "HS256",

"typ": "JWT"

}

 

JWT Claims

 

JWT Signature

 

Manual steps to build the JWT value

 

Example of the final JWT token

 

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 or regenerated at around 8-9 minutes instead of waiting the full 10 minutes.

1. Set the Body of the Request

Sample

 

Required Body Request Fields

Field Name	Required	Description
grant_type	required	MUST be 'client_credentials'
client_assertion_type	required	MUST be 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
client_assertion	required	JWS value (varies for each client request)
scope	required	MUST be ‘connectId’
realm	required	MUST be ‘ups’

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.

Sample

 

If errors occur while obtaining the access token, see the Access Token Troubleshooting document or reach out to an 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

 

Endpoint

https://connectId.s2s.analytics.yahooinc.com/s2s/connectId

 

Query Parameters

Parameter Name	Type	Required	Description
he	String	required	Hashed version of the user’s email address
pi	Integer	required	Publisher ID, supplied by your account manager during onboarding.
gdpr	Integer	optional	=0 if the user is NOT subject to GDPR rules =1 if the user is subject to GDPR rules
gdpr_consent	String	optional	IAB TCF2.0 consent string, if gdpr=1
ipaddr	String	optional	End-user's IP address is used to determine their location
us_privacy	String	optional	IAB CCPA/us-privacy, end-user's CCPA selections. Applied to users from all US states as determined by the IP parameter.
gpp	String	optional	IAB GPP consent string.
gpp_sid	String	optional	IAB GPP applicable section ID, comma-separated list of integers .
ipaddr	String	optional	ipaddr String optional IP address of the end user. Used for optional geo-blocking by specified country.
att	String	optional	Apple App Tracking Transparency 1-char code
ifa	String	optional	Identifier for Advertising, use this identifier in ad requests.
app	String	required if ifa is present	Name of the app.

 

Request Header

Header Name	Type	Description
Authorization	String	Bearer <access token> Where access token is the token received from the ID-B2B endpoint

 

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

 

HTTP Status Return Codes

Status Code	Status	Description
200	Success	The response contains a JSON object Important! If gdpr=1 was specified on the request and the gdpr_consent is not present or does not have Yahoo consent enabled, the response will be 200 OK with an empty JSON response.
400	Bad Request	Missing required parameters
401	Unauthorized	The access token does not grant access to ConnectID S2S API
403	Forbidden	The app parameter value in the ConnectID request is from an unauthorized app

 

Include ConnectID in Ad Requests

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

For CTV sellers, ConnectID does not need to be passed in the ad request. Instead, a match table is established using the server-to-server integration method between the IFAs (Identifier for Advertising) and ConnectIDs derived from hashed emails passed via this integration. This match table is used by Yahoo to look up the ConnectID corresponding to the IFA passed in the ad request. Thus, it is crucial to ensure that the IFA passed via the server-to-server ConnectID integration method is the same as the one passed in the ad request.

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., CCPA 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.