Integrating the ZofToken solution

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.

Enrolling users

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.

Mass enrollment, client initiated

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.)

Individual enrollment, user initiated

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.

Specific cases for enrollment

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.

Checking a token status and reacting to token changes

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.

Poll mode, client initiated

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.

Webhook mode, ZofToken server initiated (“on behalf” of the user)

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.

One-time use codes mode

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.

Additional operations

While the two previous sections describe the majority of operations, what follows are the rest of the API endpoints provided by a ZofToken instance.

Deleting users

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.

Forcing user status

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:

  • If the user has blocked their token by repeatedly entering an incorrect PIN and gets in touch with the client to fix this situation the client has two alternatives, either re-enrolling the user or forcing the token from the blocked to the closed position (which reenables the token in the user’s ZofToken app).
  • Conversely, if the client receives a credible report that a token has been compromised, it can choose to either block it or delete it. As blocking is a reversible operation that still ensures the token can’t be used, it might be preferable to use this as a quick first option for less trusted reports (for example, a telephone call by the user) and later move to deletion or a new enrollment if the compromise is confirmed.
  • Finally, this operation can be used to forcibly close a token (and therefore making the user open it again with their PIN) before a highly sensitive transaction is performed. In this way, a client application can remain user-friendly, by providing a reasonable period after the token is opened that needs no further action by the user, but still go to a more restrictive mode (specifically waiting for a token to be open) if needed.
Offline mode

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:

  • Offline mode only provides a way to open a token.
  • If the user has the duress feature enabled they can use it with offline mode and the operator will be informed by the ZofToken server that the user is authenticating as under duress.
  • The same blocking policy is in effect for offline mode, if the operator tries three consecutive invalid codes against the server, the token will go into blocked status.
  • The API endpoint that provides the validation code to send to the user has a parameter that sets the length of this code between 4 and 32 alphanumeric characters (in groups of 4) – considering the blocking policy, a length of 4 will be sufficient for the vast majority of applications and anything above 8 (considering both user friendliness and potential errors while entering and reading long codes) should only be used when there are extremely stringent security requirements.
  • Notice tha this feature is very similar to using the one-time use codes described above and, in the vast majority of cases, using those codes will be simpler. However, since the offline mode is always available (even considering a complete lose of synchrony between the smartphone and the ZofToken instance), the feature is included to ensure operational resilience.

Use case examples

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.

Common scenarios

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.

Adding an extra layer of security to a standard authentication protocol

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.

Securing sensitive transactions during a user session

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.

Less common scenarios

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.

Adding an extra layer of security to call center operations

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.

Integrating 2FA to any significant infrastructure/software changes

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.

Uncommon scenarios

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.

Integrating 2FA with IoT components

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.

Building occupancy / Working hours

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.