Although there might be some niche cases where you can actually use the ZofToken solution without writing almost any code (see an example at the ZaaS site), any significant integration will require that you interact with the API. While the API 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.
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 so that the user can complete the enrollment in one of three ways.
First, there's a deeplink available that can be mailed to the user and, if the app supports it (as is the case with ZofToken Universal App) after being clicked will either start the smartphone app with all required information or redirect the user to the appropriate store (Android or Apple) to download it.
Second, the API will return a QR Code (which is just a graphical representation of the deeplink) that can be scanned either by the app or directly with the built-in camera application on most modern smartphones.
Finally, the API will provide a one-time use code that can be used for manual enrollments in applications that have integrated the ZofToken SDK.
In either case, at that point the user will then be asked to create his PIN, authenticate with a biometry feature or any other mechanism that was selected to protect the authentication secret and the enrollment process will be completed.
Given the information above, a generic enrollment process will generally take one of the forms detailed below.
For each current user in whatever asset is being secured (for example, a web application), obtain the user’s email and a valid User ID (for example, the current username, document number or even the same email).
Call the enrollment endpoint of the ZofToken instance API with a valid authkey with administrative privileges.
Email the user with the deeplink returned by the API and whatever additional information is required (an explanation of why the client is now offering or requiring 2FA, any relevant terms and conditions, etc.)
Assuming the user is currently logged in to the asset that is being secured (for example, a web application), they click on some interface element that offers to setup 2FA.
The user is presented with any relevant information and, if needed, is asked to install the required app.
After the user accepts the information and confirms that they have the app available, the client application calls the enrollment endpoint of the ZofToken instance API with a valid authkey with administrative privileges.
The user is then shown the returned QR Code in their browser (which they can scan with their smartphone to complete the enrollment immediately) and alternatively is also sent the deeplink through email as a backup.
It's important to notice that the two previous approaches are not the only options and specific cases can be considered depending on the business requirements.
As an example, if ZofToken were used as a second factor for credit card operations, the user could receive a one-time use enrollment code along with the physical card and related documentation, and then just enter it manually on the app that is being used.
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 three modes of operation, letting the client decide if they want to use any of them separately or at the same time 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 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 ZofToken.
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, in general, this is the mode of operation that permits fewer use cases and is the most annoying and difficult for the user, the ZofToken solution still supports a mode in which each token generates codes (that change every 30 seconds) and can be validated against the API.
In this mode, an asset that needs that authenticate the user or an operator that is using an insecure channel to communicate with the user (e.g. a telephone call) can ask the user to enter or read the current code being shown on their token. The code can be 4 to 32 characters in length and there are mechanisms in place to guarantee the synchronization between the token and the ZofToken instance.
One potential advantage of this mode, for certain scenarios, is that it requires no connectivity between the smartphone and the ZofToken instance, thus operating like a traditional physical token.
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, an organization 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.
In any situation where an application needs to authenticate a user (particularly across insecure networks), in addition to requesting typical access credentials (like a username and password) the application can poll the ZofToken instance, wait for the appropriate webhook or requrest a one-time use code to check for the token status before actually granting access.
A specific variant of this scenario is when a user first logs in to an operating system, whether that’s a personal or corporate computer. The ZaaS site provides a complete example in this situation for personal computers running Windows 10 PRO, but in general, most operating systems support the concept of “logon scripts” that run when a user authenticates for the first time and it should be trivial to configure a script that checks the status of the token and logs off the user if it isn’t open.
Most applications, after a user authenticates to it, establish a session during which the user can perform many different operations. When the operation or transaction to be executed is sensitive in any way, the application can add an extra layer of security by checking the token status.
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.
When a user communicates with a call center, it’s common for the operators to ask a number of, typically fairly insecure, questions to authenticate the client before executing whatever requests the user has. If the operator can instead (or in addition to) see the user’s token status in their screen (integrated into their CRM or as a specific interface to the ZofToken instance), the process can not only be significantly more secure but also more user friendly.
Ensuring that any software changes in the production environment or configuration changes to the operating platform are properly controlled is a basic security control for any organization. For organizations that have reached a maturity level where these changes are not entirely manual but use some form of automation, integrating 2FA can go a long way both in improving security and generating evidence for future reviews or audits. In particular, organizations that implement CI/CD through standard tools can easily integrate ZofToken’s webhooks or token checks to perform or validate critical operations (for example, merging code into master branches or installing new versions in the production environment).
Note that this is a very clear example of how a single ZofToken instance could serve multiple purposes as a client whose primary objective is adding 2FA for their users can still implement this additional functionality for their internal or external IT personnel.
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.
Most IoT systems connect to some sort of hub that allows for both local and remote operations, and the remote operations typically require that the hub is connected to some sort of cloud service. As these cloud services might not be particularly secure or even have good reliability, an option would be to have a software component in the local network as the only thing that communicates with the IoT hub and maintain remote operations by using a secure component like a token. This would be particularly useful for operations with IoT devices that are part of the security infrastructure (for example, alarm and sensor activation or opening and closing smart locks) where having a token’s webhook fire a local event to open a door would be a significant improvement over a third party app sending a request to a third party cloud service and the IoT hub constantly connected to the internet to interact with that cloud service.
A ZofToken instance accessible only through a local Wi-Fi network that spans a building or office could be used to record when personnel arrive or leave, and who is present at the moment. Once the user arrives to the location, their smartphone would connect to the network and when they open their token, the webhook could be captured by a system that logs the time, with the opposite happening when the user closes the token as they leave.
