Client Mastered Authentication

Overview

In this authentication type, user IDs come from your authentication system, which is considered to be the authoritative (master) source for user identification. This is also referred to as "client site-auth" because it relies on your site authentication system.

Components

The following table summarizes the components you will need to understand in order to implement client-mastered authentication. These components will be referenced throughout the rest of this documentation. Familiarizing yourself with them will make understanding client-mastered authentication easier.

Authentication scenarios

There are two authentication scenarios when using client-hosted authentication:

1. The encoded UAS has not been created in advance of submission or
2. The encoded UAS has been created in advance of submission.

Your implementation should support both scenarios.

Encoded UAS token not created in advance

In this scenario, when the author attempts to access your submission form you will not have access to a pre-created encoded UAS token. Instead, you will create an encoded UAS token based on one of following conditions:

• If the author is already logged into your site you should create the encoded UAS token, load the submission form and submit their content to Bazaarvoice.
• If the author is NOT logged into your site, you should redirect them through your login process, and then back to your submission form to complete their submission.

Encoded UAS token created in advance

In this scenario, a user with a pre-created encoded UAS token attempts to access your submission form. When this occurs you should not redirect the user to your site login or create a new encoded UAS token for the following reasons:

• The pre-created encoded UAS token may contain additional parameters that a standard token would not contain (see Data Injection below)
• Forcing authors to login unnecessarily will result in up to a 40% reduction in submissions

An example of this scenario is what Bazaarvoice refers to as a post purchase email (PPE). A PPE solicits reviews from verified purchasers (users who are known to have purchased the product) and includes a link, containing an encoded UAS token, directly to your submission form. The identity of a verified purchaser is already known so it is possible to pre-create the encoded UAS token and include additional data indicating the user is an owner of the product. Because the encoded UAS token has already been created there is no need to log in in the user.

Authentication scenarios logic

The previous scenarios are represented by the following pseudo-code, which is the recommended logic for determining when to allow users to access your submission form:

if ( Pre_Created_Encoded_UAS_Token ) {
     Render submission form
}
elseif ( user_is_logged_in ) {
    Create encoded UAS token
    Render submission form
}
else {
    redirect to the login page, after the user logs in send back
    to submission form to repeat this logic
}

Continuing the post purchase email example, consider the following URL embedded in an email sent to a consumer. The consumer's identity is already known, because they recently made purchase, so the encoded UAS token can be created in advance:

https://yourdomain.com/path/to/your/submissionform.html?usertoken=c34c38c8c308852a49e7607bc397bc824e922d446f61a35cfe91c8fd6139643f646174653d323030372d30352d3237267573657269643d49443132333435

There is no need to route this user through your authentication process. This request contains a pre-created encoded UAS token already. Instead, you should immediately render the form, collect their input, and submit it to Bazaarvoice along with the encoded UAS token.

Creating and encoding the UAS

When an encoded UAS token does not exist you will need to create a user authentication string and encode it.

A user authentication string consists of key=value pairs separated by ampersands. Prior to submission, a UAS is signed and encoded using a shared encoding key. The result is referred to as an encoded UAS token. This process allows Bazaarvoice to verify that the submission comes from a trusted source, thereby preventing bad actors from fabricating content or impersonating users.

Signing and encoding the UAS is a method of message authentication, not privacy. As the pseudo-code below demonstrates, the user ID will be communicated in an encoded format that is signed with a shared encoding key, which is reasonably secure, but also as a plain text hex string, which is intentionally reversible. Submission should performed using HTTPS if privacy is required.

To verify the source of the encoded UAS token Bazaarvoice will reverse the hexed portion, then encode the UAS with our copy of the shared encoding key and compare the result with the encoded portion of the string you created. If they match, then we can be confident the submission comes from a trusted source.

How to create a basic UAS

The following parameters should be used in all user authentication strings. See Data injection for other available parameters:

The following code sample shows the required parameters of a UAS:

date=2015-10-23&userid=ID12345

The above string will be valid the day it was created (2015-10-23) and the following day (2015-10-24), after which point it would no longer be accepted by Bazaarvoice. Use the maxage parameter to extend the life of UAS:

date=2015-10-23&userid=ID12345&maxage=30

This string will be valid for 30 days after 2015-10-23.

See Data injection below for more information

Encoding the UAS

To encode the UAS, you will do the following steps using your shared encoding key:

❗️

Encoding the UAS must be done on the server side to preserve the secrecy of the shared encoding key.

1. URL escape the values to ensure they don't collide with other characters that have special meaning
2. Generate a hex encoded HMAC-SHA256 hash of the shared encoding key and user authentication string (the result should be 64 characters long)
3. Hex encode the user authentication string
4. Append the results of step 3 to the end of step 2

If you do not know your shared encoding key, please contact Bazaarvoice Support.

Pseudo-code example

userStr = "date=" + urlescape(YYYYMMDD) + "&userid=" + urlescape(123456)
sharedKey = "SHARED_ENCODING_KEY"
encUserStr = hmac('sha256', sharedKey, userStr) + hex(userStr)

The result will look like the following:

In the example above the SHA-256 hashed portion (the first 64 characters) has been highlighted

📘

We will continue to accept previous methods of creating the encoded user string, but you should switch to the method described above as soon as possible. New applications should use the method described above.

Data injection

Data injection refers to the act of submitting data to Bazaarvoice in the user authentication string instead of using the standard submission form fields.

Data injection isn't typically necessary when you host the submission form and submit via the Conversations API. This technique is primarily useful to clients using our JavaScript based integration. In that integration Bazaarvoice controls the form, but by using data injection our clients can submit data on the user's behalf.

However, there are scenarios when you, as a developer building an API application, might need to use data injection. For example, the API application you are building may share Bazaarvoice client configurations with a JavaScript based integration. In that case your API application would need to use data injection because that is how your Bazaarvoice client instance is already configured.

The following is a list of parameters and values that may be injected in a UAS.

🚧

Data injection must be enabled before the Bazaarvoice platform will accept any of the following parameters. Contact our Support team for assistance.

Standard parameters

These parameters are available to all clients as shown below, although they must be enabled prior to usage.

Custom parameters

The following field types may also be injected. These fields must be configured for your client instance and the exact parameter keys and values may vary.

• Tags
• Additional fields
• Context data questions

The parameters used in the UAS for these fields is completely customizable. The following examples demonstrate what it could look like to inject these fields. The actual parameter keys and values will depend on your client configurations.

Examples only. Custom parameters are configured on a per client basis.

Submitting to Bazaarvoice

Submit an encoded UAS token with the user parameter:

The following is an example of a submission with the user parameter:

📘

This following code applies to full submission only. It does not apply to progressive submission.

POST /data/submitreview.json HTTP/1.1
Host: [stg.]api.bazaarvoice.com
Content-Type: application/x-www-form-urlencoded
X-Forwarded-For: [AuthorIPAddress]
...
ApiVersion=[latestApiVersion]&ProductId=[productId]&Action=submit&Rating=[rating]&ReviewText=[reviewTxt]
&Title=[title]&UserNickname=[nickname]&PassKey=[yourKey]&fp=[deviceFingerprint]&user=c34c38c8c308852a49e
7607bc397bc824e922d446f61a35cfe91c8fd6139643f646174653d323030372d30352d3237267573657269643d4944313233343

Ellipses (...) in above example indicate that your app may generate other headers.

Appendix

Troubleshooting ERROR_PARAM_MISSING_USER_ID

The error code ERROR_PARAM_MISSING_USER_ID means that the Conversations API could not identify a valid user ID. Common causes of this error are:

Missing user or userid parameter

Be sure that the user or userid parameter is included in your request and that the request is syntactically correct. For example, the following request appears to include user, but it will not be parsed as expected because the URL is malformed (there is no ampersand before user).

📘

This following code applies to full submission only. It does not apply to progressive submission.

POST /data/submitreview.json HTTP/1.1
Host: [stg.]api.bazaarvoice.com
Content-Type: application/x-www-form-urlencoded
X-Forwarded-For: [AuthorIPAddress]
...
ApiVersion=[latestApiVersion]&ProductId=[productId]&Action=submit&Rating=[rating]&ReviewText=[reviewTxt]
&Title=[title]&UserNickname=[nickname]&PassKey=[yourKey]&fp=[deviceFingerprint]user=c34c38c8c308852a49e7
607bc397bc824e922d446f61a35cfe91c8fd6139643f646174653d323030372d30352d3237267573657269643d4944313233343

Ellipses (...) in above example indicate that your app may generate other headers.

Shared encoding key is incorrect

Be sure you are using the correct and full shared encoding key when creating the encoded UAS token. You can contact our Support team to verify you are using the correct value.

UAS is expired

A common problem with an otherwise correctly made encoded UAS token is that it has expired. By default tokens are good the day they are created and the following day (equivalent to maxage=1). To extend their life you can use the maxage parameter. Refer to How to create a basic UAS above for more details.

There are required fields that must be injected

If your Conversations API based application is sharing configurations with an integration using our JavaScript based solution, you may be required to perform data injection. Our Support team can help you verify your configurations. If this is the case it is important not to change the configurations, because by doing so the other, JavaScript based, integration will cease to function correctly.

Submitting with userid

Submitting a user ID without encoding it in a UAS token is possible. This is accomplished by using the userId parameter to submit the user ID in plain text instead of using an encoded UAS token. You might find this method useful while experimenting with the Conversations API, but it is not recommended because there is no way for Bazaarvoice to verify the submission came from a trusted source.

The following is an example of a submission using the userid parameter:

📘

The following code applies to full submission only. It does not apply to progressive submission.

POST /data/submitreview.json HTTP/1.1
Host: [stg.]api.bazaarvoice.com
Content-Type: application/x-www-form-urlencoded
X-Forwarded-For: [AuthorIPAddress]
...

 




 




ApiVersion=[latestApiVersion]&ProductId=[productId]&Action=submit&Rating=[rating]&ReviewText=[reviewTxt]
&Title=[title]&UserNickname=[nickname]&PassKey=[yourKey]&fp=[deviceFingerprint]&userid=1234567890

Ellipses (...) in above example indicate that your app may generate other headers.