Viafoura

The Viafoura Documentation Hub

Welcome to the Viafoura documentation hub. You'll find comprehensive guides and documentation to help you start working with Viafoura as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

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 send an email to [email protected].

Overview
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:

  1. User logs into your site; you set a cookie on the user's browser identifying the user's session.
  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:

admin.viafoura.co → 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 on your site 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 5 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. someKindaSessionID4567

You can define your cookie name in admin.viafoura.co → 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. http://example.com/users/validate?loggedInCookie_sid=someKindaSessionID4567

🚧

Note

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.

Good:
https://example.com/users/validate?loggedInCookie_sid=

Bad:
https://example.com/users/validate

📘

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 verfication endpoint in admin.viafoura.co → 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 https://github.com/viafoura/Viafoura-Examples/blob/master/cookie-login/client_endpoint.php

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": "http://i.imgur.com/mdipQYd.jpg",
    "socialData": [{"social": "data"}]
}

🚧

Required Fields

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

  • uid
  • displayName
  • email

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 does include 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 instead 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 };
    }
});

Last but not least, you should also 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 admin.viafoura.co → 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
  • 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:https://documentation.viafoura.com/rest_api_v2.php#login. 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 a 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:https://documentation.viafoura.com/javascript.php#events
  • 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 or to [email protected] 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.

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 (http://example.com/users/validate), using a cookie named loggedInCookie_sid returns:

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

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

Updated 3 days ago


Viafoura Custom Cookie Login


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.