Definitions
ZofToken
- The ZofToken Solution is comprised of a ZofToken Instance (which is usually implemented
with a single ZofToken Server but could include several servers) and any number of ZofToken
Apps installed on Android or Apple smartphones.
- A single ZofToken (or simply token) is one User ID enrolled to a service (see definitions below)
of a specific instance.
- The Zoftoken App can store and handle any number of ZofTokens.
ZofToken As A Service (ZaaS)
- While we recommend that you do not outsource critical security protocols and therefore run a
private instance, for technical tests, enthusiasts or organizations whose business requirements are
compatible with this model, we provide ZaaS as a way to quickly spin up a cloud-based instance.
Clients and users
- A client is an organization who operates a ZofToken instance (either private or through ZaaS)
while a user is somebody with the ZofToken app installed on their smartphone.
Services
- Each ZofToken instance can handle any number of Services which can be used for many different
objectives including grouping users, representing access to different assets or providing different
configurations.
User IDs
- Each User ID is a client-selected unique identifier for a user. Reasonable User IDs include
existing usernames for specific assets, email addresses or passport numbers but there are no technical
limitations to what can be used.
Enrollment
- This is he process by which a client and a user agree on the use of a token to secure access to some
asset. It
has two phases: first the client creates a request on their ZofToken instance and provides the user with
the enrollment data and then the user sets up the token in their ZofToken App (either by scanning a QR
code or clicking on a deeplink).
PIN and Duress PIN
- During the enrollment process, the user will need to select a 4-digit PIN to authorize token operations.
- If allowed by the service (as configured by the client), the user will optionally be able to select a
different 4-digit PIN to indicate that the token operation is being performed under duress.
Status
At any point in time, a ZofToken will be in a specific status from the following list:
- Awaiting Enrollment – the token has been created on the ZofToken instance, but the user hasn’t finished
the enrollment process yet.
- Closed – the user has their token in a closed state.
- Open – after the user opens their token, and during a period of time configured in the service, the
token will be in the open state.
- Duress – (only possible if enabled by the service configuration) the last token operation performed by
the user (either opening or closing) was performed with the Duress PIN.
- Blocked – the token has been blocked either by failing to authenticate 3 consecutive times or manually
by an
instance administrator.
Authentication Keys
- Each instance can have any number of authkeys that allow access to the API.
- These keys can be configured to apply to specific services and/or User IDs and to allow administrative
access (needed to generate new tokens or force changes in token status) or not (allowing access only to
reading a token status).
Integrating the ZofToken solution
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.
Enrolling users
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.
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 requested to install the ZofToken app if they
don’t have it already.
- 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 to complete the
enrollment immediately) and alternatively is also sent the deeplink through email as a backup.
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 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.
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
it 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 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.
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 a Duress PIN 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.
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, you 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 or wait for the appropriate webhook 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 (again, by polling or
waiting for a webhook).
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/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 ZofToken. 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.