Viafoura Custom Cookie Login

This document provides an overview, configuration instructions, and best practices instructions for Viafoura's Cookie-based login integration. For help implementing and configuring cookie-based logins, please contact us

Viafoura's cookie-based login integration allows you to log your users into Viafoura automatically once they've signed in through your existing login system. Due to its flexibility, this integration approach is compatible with a broad variety of login systems. The login workflow functions as follows:

Viafoura's cookie-based login integration allows your users to automatically log into Viafoura once they've signed in through your existing login system. This flexible integration approach is compatible with a broad variety of login systems and functions as follows:

  1. Users log into your site; you set a secure random session cookie on the user's browser identifying the user's session. NOTE: This cookie must be set client-side, as our JS cannot read HTTP-only cookies.
  2. Viafoura's JS detects the cookie, and uses its value to query a login endpoint in your control.
  3. Your endpoint validates the user's session, and if valid, returns the user's login information.
  4. Upon successfully receiving the user's login information, Viafoura logs the user in.

Settings such as the cookie's name and the cookie validation endpoint can be configured by going to: → Settings → Authentication Providers → Viafoura.

Once the cookie name and validation endpoint values are saved, Viafoura's javascript widgets installed on your site will automatically detect the cookie and, if found, will send it to your defined end point to verify.

Login Flow
You need 3 things:

  • The name of the session cookie you want Viafoura to check with
  • The URL of the endpoint you want Viafoura to check the cookie against
  • A well-defined JSON output from that URL endpoint

Here's what the 6 step process looks like:

Step 1
A logged out user clicks on login in your system (or you respond to a Viafoura event triggering authentication (see Step 6)

Step 2
You log the user in and give them a cookie (i.e. loggedinCookie_sid) with a temporary session-id i.e. someKindaSessionID456745674567456745674567



It is important that this session-id value to be regenerated every time a user logs in and be a long enough (recommended more than 256 bits) secure random string.

You can define your cookie name in → settings → Authentication Providers → Viafoura under "Viafoura Defined Custom Cookie Name"

Step 3
Viafoura looks at the cookie loggedInCookie_sid and verifies it against an endpoint on your system eg.



Viafoura will make an HTTP GET request and appends the sessionId as a query parameter. Make sure that your cookie login endpoint in your Viafoura settings can accept this format.




Additional Security

To add additional security to the API endpoint that will manage the validation, you can restrict traffic to that endpoint to only allow requests from Viafoura's servers IP addresses. Please contact our support team for more details.

  • The Viafoura widget would append the stringified, URL encoded content of the cookie with the name loggedinCookie_sid to your endpoint.
  • You can define your cookie verification endpoint in → Settings → Authentication Providers → Viafoura under "Viafoura Defined Custom Cookie Endpoint". This must be accessible to the public (i.e. if it is in your dev environments, please ensure Viafoura can reach this endpoint)

Here is a PHP code example of how your endpoint could return the data

Step 4
Your server checks the cookie session someKindaSessionID4567 and if it is valid, returns the user data in this JSON format:

    "uid": "75453",
    "displayName": "Ironman",
    "email": "[email protected]",
    "error": "",
    "photoURL": "",
    "socialData": [{"social": "data"}]


Required Fields

The following three fields are required for the login process to work:

  • uid
  • displayName
  • email



The information provided in the JSON response, including the uid are assumed to be the user's public profile data and will be visible to other users. Do not include any private data in the response.

Step 5
If the user clicks on a "logout" call to action in your authentication system, or their session expires, ensure that a call in javascript is made to window.viafoura.session.logout() to complete the user log out in Viafoura.

You can see our JavaScript API here.

Step 6
Viafoura's user interface includes several triggers to the authentication process. For example, any action that requires the user to be logged in (posting or liking a comment, following a user or a conversation, etc.) is meant to trigger Viafoura's default log in workflow if the user is not logged in.

To complete the integration and ensure a cohesive user experience, we recommend that you intercept the default Viafoura login workflow to trigger your custom authentication. The code snippet below is an example of how you can achieve this:

window.vf.$prepublish((channel, event, ...args) => {
    if (channel === 'authentication' && event === 'required') {
        // add here the handler to trigger your authentication login flow
        return false;
    else {
        return { channel, event, args };

Lastly, you should ensure that if the user logs out of Viafoura, that action is passed to your authentication system to complete the user logout:

window.vf.$subscribe('authentication', 'logout', () => {
    // add here the handler to trigger your authentication logout flow

Important Notes

  • You will need to disable the viafoura handling of the login process. To do this, go to → Settings → General and check these three settings:

  • Disable login, logout and account handling via widgets.

  • Disable Avatar management via widgets.

  • Disable Display Name management via widgets.

  • All fields in the returned JSON data are required except the photoURL fields.

  • uid field MUST BE UNIQUE TO YOUR SYSTEM. If it is not, we will create a new user each time we see a new uid

  • The cookie value must be regenerated from each user session to the other, must be random and long enough. It also must be different from uid, since uid value is visible to other users.

  • If a blank displayName is passed in, Viafoura will use the first part of the provided email field. So if the email is [email protected] and the displayName is blank, we will populate the displayed name automatically with pparker. The minimum length for a displayName is 1 character, and the maximum length is 255 characters. If the displayname is greater than 255 characters, the remainder will be truncated.

  • error is to be sent as blank when there is no error, and populated with a message if there is an error. The message can be anything you wish to send to Viafoura for debug purposes; it will be visible through the browser's developer console but will never be shown on the page.

  • If a user is banned from the system (i.e. not allowed to post comments), you will want to handle that case on your login flow as well. We will send back that the user is banned and any notes your moderator has made to show to the user in this API call: You can look for the ban_level JSON value. Alternatively, this can be done through Javascript on the page. Once Viafoura detects a login request, it will attempt to log the user into Viafoura, and if this fails Viafoura will publish an onLoginFailevent, containing the fact the user has been banned and the "Message to user" set by the moderator at the time of banning. You can find more information on how to detect and work with this event here:

  • photoURL is optional, and must be publicly accessible. Viafoura will download that image and use it as a commenting avatar. Each time the user logs in, we will update their Avatar according to the data passed by your endpoint, if it has changed. Alternately, if "Disable Avatar management via widgets" is not selected, the user will be able to change their Avatar through the Viafoura interface as well.

  • socialData is a field where you pass along any social media data the user has provided your login system. This data allows Viafoura to better curate content and provide richer analytics. You can pass the data in the same format that your social provider gives you (i.e. gigya, janrain, or the social network) directly.

  • The value in the cookie and the uid you pass back from your verification endpoint are not the same thing. The uid is the ID of the user in your system, and the cookie session ID SHOULD be a temporary value.

  • You should destroy any existing session ID after a user has been logged out.

  • If you do a redirect once a user gets logged out, please make sure that the viafoura.session.logout() JavaScript code has an opportunity to execute before a redirect happens

  • Viafoura's social login capabilities (Facebook, Twitter, etc.) available through our javascript-based login typically become unavailable once a cookie-based login integration is in place. If you'd like to offer social login and continue to use your existing login system through a cookie integration, we can help. Reach out to your account manager for more information.

  • Viafoura will call your API any time a user logs in. If their session with Viafoura has expired but they still have a valid cookie login token available, we will update their session via your API (roughly once per day).

  • If a user updates their profile on your system, Viafoura will pick up the updates on the next time the user loads viafoura comments, and Viafoura will update its own records.

  • Please ensure that any updates made to your cookie name or endpoint are also updated in Viafoura's admin.

  • In our JSON mapping, we support utf8mb4_unicode_ci and varchar(255).

Using Custom Mapped Fields
You may already have an endpoint that verifies cookies and returns user data - however the chances of their fields lining up with the fields Viafoura expects are slim. This is why we allow you to map your fields to our fields. So for example if your endpoint (, using a cookie named loggedInCookie_sid returns:

    "unique_member_id": "75453",
    "address": "123 Fake Street",
    "username": "Ironman",
    "email_address": "[email protected]",
    "avatar_picture": "http:\/\/\/mdipQYd.jpg",
    "phone_number": "555-555-1212",
    "regdate": 1369418233

You would fill in the Viafoura admin section to look like this:

Did this page help you?