Viafoura Custom JWT Login

DEPRECATED

This document provides an overview, configuration instructions, and best practices instructions for Viafoura's JWT-based login integration. For help implementing and configuring JWT-based logins, please send an email to [email protected].

Overview
Viafoura's JWT-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 registers with your site; in the backend you register the user with Viafoura via the API using the same email provided for your account and a password. (View registration API documentation).
2. User logs in to your site; pass the correct email and password to Viafoura's login API (view login documentation)
3. Save the access token, refresh token, and session ID and once page has loaded, pass them to the window.vf.session.login.jwt method (View JS API docs for JWT login).

Once the promise resolves, it will return to you the user who is now logged in (or an error object in the case of failure) and the User will be fully logged in through Viafoura's APIs with a persistent session as if they had logged in through Viafoura's own login flow.

Login Flow

Step 1
A logged out user clicks on login in your system (or you respond to a Viafoura event onLoginRequired in javascript)

You can see how to listen to JS events here.

First, ensure that the user is logged out by using the Viafoura JS API.

Step 2
The user fills out a form which makes a call to your backend API.

Step 3
You do any work you need to in the backend processing the data and then you make an API call to a supported vf login endpoint (eg: /v2/users/login endpoint. view v2 login API documentation).

If you do not expect to log in moderators or administrators, you can pass thirdparty_enabled=false in the login call which will simplify response processing (see below).

Step 4
You will process the response from the API. This will be different depending on whether you passed thirdparty_enabled as true or false in Step 3.

4A. thirdparty_enabled=false

If you passed thirdparty_enabled=false, and the user is not an admin or moderator you will receive a JSON response similar to the following:

{
    "http_status": 201,
    "message": "Session created",
    "result": {
        name: etc...
    },
    "session": "SESSION ID",
    "access_token": "ACCESS TOKEN",
    "refresh_token": "REFRESH TOKEN"
}

The session, access_token, and refresh_token properties can be extracted and passed to step 5.

4B. thirdparty_enabled=true

If you passed thirdparty_enabled=true the tokens and session will be returned in the setcookie headers in the following format:

Set-Cookie VfAccess_00000000-0000-4000-8000-0831e5b0f800=ACCESS TOKEN HERE; expires=Tue, 13-Nov-2018 15:26:05 GMT; Max-Age=285; path=/; domain=viafoura.co; secure; HttpOnly
Set-Cookie VfRefresh=REFRESH TOKEN HERE; expires=Mon, 04-Nov-2019 15:21:20 GMT; Max-Age=30758400; path=/; domain=viafoura.co; secure; HttpOnly

The session ID is always returned on the response object.
You will need to parse the headers top extract the token values.

Step 5
In the response to the user's login call pass back the tokens extracted in step 4 and pass them to the Viafoura javascript API on the frontend:

window.vfQ = window.vfQ || [];
window.vfQ.push(function() {
    window.vf.session.login.jwt(access, refresh, session)
        .then((user) => alert(`You are now logged in as ${user.name}`))
        .catch((e) => alert(e.message));
});

If the user is an admin, and has cookies disabled, this promise will reject. Please make sure the handle the rejection appropriately in your UI layer.
Once the promise has resolved, the user will be fully logged in via Viafoura's APIs and all cookies/and localstorage data will be set and managed by Viafoura allowing the user's session to persist normally without any need for additional login calls.