BV- Mastered Authentication
This tutorial will show you the components you will need to implement Bazaarvoice-mastered authentication via the Bazaarvoice Conversations API and how the process works.
Overview
Bazaarvoice-mastered authentication allows users to submit content without prior authentication. This is useful for sites whose logins are difficult to customize or for sites that don't have account creation capabilities. Further our experience has shown that up to 40% of potential content authors will not complete the submission process if they are required to login first. Bazaarvoice-mastered authentication can raise your submission rate.
Components
The following table summarizes the components you will need to understand in order to implement Bazaarvoice-mastered authentication. These components will be referenced throughout the rest of this documentation. Familiarizing yourself with them will make understanding Bazaarvoice-mastered authentication easier.
| Component | Description | Responsiblity |
|---|---|---|
| Submission form | This a web form you build and host. Authors will use it to submit content (reviews, questions, etc). | client |
| Authentication email | This email, which is typically sent by Bazaarvoice, asks the user to confirm they submitted the content by clicking on a link including a unique auth token. Clicking on the link opens a URL to your verification service. | Bazaarvoice or client (see below) |
| Auth token | This is a unique string created by Bazaarvoice for the purpose of confirming an author has access to the email address they submitted along with their content. It is used by your authentication service and should not be confused with the encoded UAS. | Bazaarvoice |
| User authentication service | You will make a service that will perform an API request to submit the authentication token from the email to the Bazaarvoice Conversations platform. A successful authentication with return an encoded user authentication string (UAS). | client |
| Encoded user authentication string (UAS) | An encoded UAS communicates user ID as well as other user attributes to Bazaarvoice and can be used to identify the author during submission in place of an email address. The encoded UAS is not the same as the auth token. | Bazaarvoice |
| An encoded UAS persistence mechanism | A mechanism to persist the encoded UAS for use in future submissions. This is commonly achieved by storing a cookie in the user's browser. | client |
Walk-through
How it works
- Submit content
The process starts with a content submission to the Bazaarvoice Conversations platform. - Authentication email sent to content author
Next, the Bazaarvoice platform triggers an email to the user that submitted the content. - Author clicks authentication link in email
The verification email contains a link with a token that you will use in your user authentication service. - User authentication
Your authentication service will make an API request to submit the authentication token from the email to the Bazaarvoice Conversations platform. - Persist User ID
Finally, if the user is verified, the API will return the user ID that you must use in subsequent submission for that user.
Step 1: Submit content
For content submission with Bazaarvoice-mastered authentication you will need to submit two parameters, HostedAuthentication_AuthenticationEmail and HostedAuthentication_CallbackURL.
Bazaarvoice-mastered authentication parameters
| Name | Value | Description |
|---|---|---|
HostedAuthentication_AuthenticationEmail | Email address | This parameter tells the Bazaarvoice platform where to send the email that will contain the authentication link. It overrides anything submitted in the useremail field. |
HostedAuthentication_CallbackURL | URL | This URL will be used in Step 4 as the front-end to your authentication service. This parameter does not appear in the API response because it does not represent a user facing question. You should submit this value with no input from content authors. This URL must be allowlisted. See the appendix to learn more about allowlisting. |
Here is an example of a submitreview.json POST request that has these two parameters:
POST request
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] ... PassKey=g7vxnm884jj26knrkvmxpjph&ApiVersion=5.4&ProductId=test1&Rating=5&ReviewText=api+hosted+auth+
submission+test+api+hosted+auth+submission+test+api+hosted+auth+submission+test+&Title=api+hosted+auth+
submission+test+2&UserNickname=apihostauthsubtester&HostedAuthentication_AuthenticationEmail=test.user
%40bazaarvoice.com&HostedAuthentication_CallbackURL=http%3A%2F%2F[www.example.com%2Fyour%2Fauth-service](http://www.example.com%2Fyour%2Fauth-service)
Ellipses (...) in above example indicate that your app may generate other headers.
Step 2: Authentication email sent to content author
The Bazaarvoice platform triggers an email to the user with a authentication link that is made up of the URL you submitted in the HostedAuthentication_CallbackURL parameter. Here's an example:
http://www.example.com/your/authentication-service?bv_authtoken=a7a4278ff33887d352fcdef30edd143f487dc881
The bv_authtoken found at the end of the authentication URL is not the same as the AuthorSubmissionToken that is found in the response of a successful submitreview.json request.
The last part of that URL is the token you use in the authenticateuser.json request to verify the user.
Who sends the authentication email?
Our Conversations platform is designed to use the Bazaarvoice white label email service provider (ESP) to send the emails. Clients on our Conversations PRR platform can be configured to use either their ESP or our white label ESP. If you have any questions about which one your instance uses, contact Bazaarvoice Support.
Step 3: Author clicks authentication link in email
Once the user gets that email they should click on that authentication link to your site's authentication page. Here is an example of the message the platform would send:
The link that the red arrow is pointing at will direct the user to the web page on your site that exposes your user authentication service.
Step 4: User authentication
When using the Conversations API you will construct and host an authentication service consisting of a server side component that executes the authenticateuser.json request and a client side component that displays the results as well as persists the users identity for future submissions (see step 5)..
Your authentication service page must be allowlisted. See the appendix to learn more.
Upon clicking the authentication link from Step 3 the user will be sent to your user authentication service along with a token added by the Bazaarvoice platform. Your service will then submit that token to Bazaarvoice to verify the user. Here's an example of that request
POST request
POST /data/authenticateuser.json HTTP/1.1 Host: stg.api.bazaarvoice.com Content-Type: application/x-www-form-urlencoded X-Forwarded-For: [AuthorIPAddress] ... PassKey=g7vxnm884jj26knrkvmxpjph&ApiVersion=5.4&authtoken=a7a4278ff33887d352fcdef30edd143f487dc881
Ellipses (...) in above example indicate that your app may generate other headers.
Response
Highlighted in the response is the User Authentication String that the Bazaarvoice platform returns.
{
"Data": {},
"HasErrors": false,
"Form": [],
"AuthorSubmissionToken": null,
"FormErrors": {},
"TypicalHoursToPost": null,
"SubmissionId": null,
"Locale": "en_US",
"Errors": [],
"Authentication": {
"User": "6ed12da604cc75b8613f7e209d07987b696e7465726e616c5f7375626d7373696f6e3d74727565267573657269643d616a6d66716176737836786f7068626e7571656474726a347a26757365726e616d653d617069686f73746175746873756274657374657226686f737465643d564552494649454426646174653d3230313430353036266d61786167653d333635"
}
}
That is the UAS that the Bazaarvoice platform assigns to this verified user.
Step 5: Persist user ID
You can make submission for your users convenient by cookieing that user's browser with the User Authentication String from the response example in step 4. Then you can use that value in subsequent content submission requests and omit the HostedAuthentication_AuthenticationEmail and HostedAuthentication_CallbackURL parameters.
This example uses the token returned from the authenticateuser.json request as a submitreview.json request:
POST /data/submitreview.json HTTP/1.1 Host: stg.api.bazaarvoice.com Content-Type: application/x-www-form-urlencoded .. PassKey=g7vxnm884jj26knrkvmxpjph&ApiVersion=5.3&ProductId=test1&Rating=5&ReviewText=api+hosted+auth+
submission+test+api+hosted+auth+submission+test+api+hosted+auth+submission+test+&Title=api+hosted+auth+
submission+test+&UserNickname=apihostauthsubtester&action=submit&User=6ed12da604cc75b8613f7e209d07987b69
6e7465726e616c5f7375626d7373696f6e3d74727565267573657269643d616a6d66716176737836786f7068626e757165647472
6a347a26757365726e616d653d617069686f73746175746873756274657374657226686f737465643d5645524946494544266461
74653d3230313430353036266d61786167653d333635
By persisting that value with that user (via the browser) all the content submitted on that device can be tied to that user ID. This way you get all the benefits of your users having a profile without the cost of maintaining those user profiles.
Appendix
Authentication service allowlisting
During the authentication process Bazaarvoice will send an email to your users soliciting them to click a link to your authentication service...or is it?
The link to your authentication service is communicated to Bazaarvoice during the content submission process using the HostedAuthentication_CallbackURL. This means it is possible to perform a submission using somebody else's email address and a URL to a malicious page. That somebody else would then receive an email with the malicious URL represented as a authentication link. This is referred to as an unvalidated redirect.
To protect against unvalidated redirects Bazaarvoice requires that the domain hosting your authentication service be validated by being allowlisted in our system. Content submissions including a HostedAuthentication_CallbackURL with an unvalidated domain will be rejected with an error:
{
"Data":{},
"HasErrors":true,
"Form":[],
"AuthorSubmissionToken":null,
"FormErrors":{},
"TypicalHoursToPost":null,
"SubmissionId":null,
"Locale":null,
"Errors":[
{
"Message":"Invalid domain name: example.com",
"Code":"ERROR_PARAM_INVALID_PARAMETERS"
}
]
}
Contact Bazaarvoice Support to allowlist your authentication service domains.
Updated about 1 month ago