At any point in time, a ZofToken will be in a specific status from the following list:
Although there might be some niche cases where you can actually use the ZofToken Solution without writing almost any code (as can be seen in an example at the ZaaS site), any significant integration will require that you interact with the API.
While the API chapter of the documentation includes multiple formats and helpers to understand and easily operate the API, this section is designed to provide a high-level overview that aims to clarify what and why is required before getting into the how.
Note: before starting to enroll users, you will need to have decided what services you are going to be using and how those services will operate. As this is discussed in the installation guide of the Zoftoken server and/or the ZaaS configuration options, it will not be repeated here.
As the ZofToken Solution is designed to operate with massive numbers of users, the enrollment process is meant to be quite simple. On the client side, a single API call will create the token in the instance and return the information required for the user to enroll which consists of a deeplink that can be sent by email and after being clicked by the user will either start the smartphone app with all required information or redirect the user to the appropriate store (Android or Apple) to download it.
Alternatively, the API will also return a QR Code (which is just a representation of the deeplink) that can be scanned either by the ZofToken app or directly with the built-in camera application on most modern smartphones.
In either case, the user will then be asked to create his 4-digit PIN and the enrollment process will be completed.
Given the information above, a generic enrollment process will generally take one of the two forms detailed below.
Once the enrollment process is complete, checking the status of a particular token is obviously the most important aspect of the integration as this will be what lets the client assets make decisions based on the user’s level of authentication.
ZofToken provides two modes of operation, letting the client decide if they want to use either one or both depending on the type of integration that is being implemented.
In this mode, a client asset that needs to make an authentication decision calls the status endpoint of the ZofToken instance API with a valid authkey (that does not need to have administrative privileges) and receives a reply indicating the current token status.
This mode is best used in conjunction with a service configuration that lets the token stay open for at least a few minutes and for application sessions that possibly include transactions with different levels of sensitivity. For example, a typical banking application for normal users might set a token duration of 10 to 15 minutes (enough for most user sessions) and poll the token status when the user logs in and again on any type of transaction that affects funds. In this way, the user needs to open their token before accessing the application but can then operate easily and securely until they either close their token or the token duration expires. This is very similar to the interaction a user has with an ATM (replacing the physical card with the smartphone) which is a model the large majority of people are already very familiar with and it only introduces a minimum of extra work in consideration of modern "frictionless" design principles.
In this mode, all relevant token actions are reported to a configurable endpoint through a standard HTTPS connection sent by the ZofToken server. Each one of these webooks will include the User ID and service involved, the event and a configurable secret so whatever backend is listening for these webhooks can confirm that they actually originated from the ZofToken server.
This mode is best used for “instantaneous” decisions (i.e. waiting to perform a transaction until the user opens their token) or as a complement to the polling mode to identify and react to specific events (e.g. a token getting blocked by authentication errors or a user authenticating under duress if this is allowed by the service). Note that while it is possible to wait until a token is opened by repeatedly polling its status (and in most cases this will operate exactly as waiting for the webhook), this would be considered a bad coding practice as it needlessly taxes both the client application and the ZofToken instance.
While the two previous sections describe the majority of operations, what follows are the rest of the API endpoints provided by a ZofToken instance.
This is a straightforward operation, but it is recommended that any user that is deleted is also sent an email explaining the situation as their token will cease to function and they will have to erase it on their ZofToken app.
Using an authkey with administrative privileges, the API allows any token to be forced into the open, closed or blocked states.
There are three primary examples for why this operation might be used:
All normal interactions between the ZofToken app in the user’s smartphone and the client’s ZofToken instance are processed online through the available network (most often across the Internet, but possibly an internal network in highly secure scenarios).
If the user is unable to connect to the network (most likely because they are somewhere with no access to data services) but still wants to authenticate using their token, the client can provide a way for this to work.
In this mode, the user contacts the client (most likely by telephone) and requests an offline authentication. The client’s operator (likely through some sort of internal application) uses one of the ZofToken instance API endpoints to request a validation code and gives it to the user. The user enters this in his ZofToken app, receives another code and communicates this back to the operator, which can then send this to a different API endpoint to attempt to open the token.
There are a few comments about this type of operation which are relevant:
The ZofToken Solution was designed to provide as much flexibility as it is possible, in order to allow clients to use it for very different scenarios and purposes. This section attempts to provide a few examples of these possible scenarios in three categories ranging from standard to uncommon, just as a way to show that “one size fits all” does not hold when it comes to 2FA.
When going through these examples, it’s very important to remember that a single ZofToken instance can implement several of them at the same time. By splitting users and use scenarios in different services within the instance, you can easily target specific requirements and configure each service as needed to achieve your security and authentication objectives.
These represent what people tend to think about when they consider 2FA and we would expect most implementations of the ZofToken Solution to deal with them at least to some degree.
While these might not be “primary” issues when a client is considering a 2FA implementation, they can add a significant amount of value to the organization by mitigating what are usually very widespread risks.
These represent some of the more “out of the box” scenarios where the ZofToken solution could be used for situations typically not seen as relating to 2FA tools. We sincerely hope that clients can come up with all sorts of original integrations and that is part of the reason that we provide a free tier on ZaaS to promote trials and experiments.