Integrate with ConnectID: Server to Server Integration Method

Sellers wanting to integrate with ConnectID via the Server to Server integration method must follow the processes 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 is a web service that returns ConnectIDs (cookieless user identifiers) when a Seller sends us a hashed email address from a logged-in user on their site.

1 Obtain Yahoo Credentials

The ConnectID Server-to-Server API is secured by OAuth2 authentication, it requires that each request for a ConnectID contains 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 a private/public key using openssl following the process below so that Yahoo can encrypt the OAuth Secret.

Create a Private/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

  1. Generate a public key using the following command line. Use the private key above to generate a public key.

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

  1. Email the public key to the Account Manager.

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

  1. 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

Security Considerations

OAuth credentials must be protected and NEVER exposed and 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 your credentials.

 

To reset or forget your Secret, follow the instructions above to get new credentials.

Then use the credentials to generate an access token.

2 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 Yahoo 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.

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 token is signed (generally using HMAC SHA-256 algorithm)

2. Free set of claims for you want: client_id, aud, expiration date, etc.

3. Signature ensuring 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

{

"aud": "https://id.b2b.verizonmedia.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). You may get the "JWT is has expired or is not valid" error.

"urn:vm:claims:fedidp_tenant" is an optional value. Pass this only if a token exchange is needed using federated token.

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

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.verizonmedia.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 A Final JWT token

ew0KICAiYWxnIjogIkhTMjU2IiwNCiAgICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYXVkIjogIntwcm90

b2NvbH06Ly97YjJiLmhvc3R9L2lkZW50aXR5L29hdXRoMi9hY2Nlc3NfdG9rZW4/cmVhbG09

PHlvdXItcmVhbG0+IiwNCiAgImlzcyI6ICJ7Y2xpZW50X2lkfSIsDQogICJzdWIiOiAie2NsaWVud

F9pZH0iLA0KICAiZXhwIjog4oCce2V4cGlyeSB0aW1lIGluIHNlY29uZHN94oCdLA0KICAiaWF

0Ijog4oCce2lzc3VlZCB0aW1lIGluIHNlY29uZHN94oCdDQp9DQo.uKqU9dTB6gKwG6jQCuXY

AiMNdfNRw98Hw_IWuA5MaMo

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

Sample code to generate JWT and get an 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 for the 10 minutes.

  1. Set the Body of the Request

Sample Request

POST /identity/oauth2/access_token HTTP/1.1

Host: https://id.b2b.verizonmedia.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

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’

  1. Submit a POST Request to https://id.b2b.verizonmedia.com/identity/oauth2/access_token

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

Sample Response

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, see the Access Token Troubleshooting document or reach out to an Account Manager.

3 GET Yahoo ConnectID

The ConnectID server-to-server API accepts a 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 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=20cdc60e06efd975906d99273f

ea7e63030cf1cb5b2b3c14bfdae00e3exxxxxx&pi=1001' --header 'Authorization: Bearer

0bed77b1-435e-4b51-9ff0-f087a75941de'

 

Endpoint

https://connectid.s2s.analytics.yahoo.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

 

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

{

"connectId": "P8XXUtgxNktZDDRg0FSPZXanjlpNCyRsMeZBr9pK_N6UwNkzCpbIeDQa3vx8Ekqv6KhRlhli5xN-TP0hZufwLw"

}

 

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