The objective of this chapter is describing in detail two central elements of the ZofToken configuration (services and authkeys) and some recommendations about their use. Except for the specific cases listed below, everything in this document applies to both private ZofToken Server installations and ZofToken as a Service (ZaaS).
Every ZofToken instance can have any number of services configured.
Any token belonging to a service will have the same configuration and therefore services can be used to group users in any way that fits the business requirements. API access to the services (for example, being able to query the status of a token or enrolling a new token) is granular and can be configured through the authkeys introduced in the next section.
The minimal configuration has a single service to which every token belongs to, while a more complex one could include for example four services: one for regular internal users (used to secure their access to some of the organization’s systems), one for internal IT users (used to secure administrative access to critical assets), one for the majority of external users (used to secure access and/or transactions to a web application like a Home Banking system) and one for “premium” external users (also used to secure access and/or transactions but with a different configuration to allow the duress function).
Every service has the following parameters:
| Parameter | Description |
|---|---|
| Name | This is the internal name of the service as used in the API. |
| Token duration (or window) | To make the tokens more user friendly, once the user opens their token, the ZofToken instance will consider it open for a number of seconds defined by this parameter. This allows the user to open their token before they login to a web application and not needing to interact further with it for an amount of time that is reasonable for a normal session (for example, 10 to 15 minutes). Setting this parameter to 0 removes this functionality and every interaction with the tokens will have to be handled through a webhook. As this configuration limits the simplicity of integrating ZofToken with your systems, it is recommended that this is done only for specific business reasons. |
| Webhook | This optional parameter instructs the ZofToken server to call a specific webhook at several instances of the token lifecycle. There are three components of a webhook configuration:
|
| Duress mode | This flag indicates whether the duress function is enabled for this service. As this is an important decision with potentially significant implications (particularly for external users), it is recommended to read the general description and recommendations regarding this function in the documentation. |
| Details |
Note: this parameter is used exclusively by ZofToken Universal App and is provided automatically by ZaaS so the following description applies only to private ZofToken Server installations that use the reference app. This optional parameter is a URL that needs to return a JSON object that configures how the service will appear to the user in ZofToken Universal App. The format of the JSON object is as follows:
{
The first property is a BASE64 representation of a PNG image file that will be shown as the logo for the token in ZofToken Universal App, and the rest of the fields should be self-explanatory. As described in the installation documentation, creating a free ZaaS account for experimentation and testing can also help create this object as there is a simple user interface for it.
"logo": logo image,
}
|
| Endpoints |
Note: this parameter is used exclusively by ZofToken Universal App and is provided automatically by ZaaS so the following description applies only to private ZofToken Server installations that use the reference app. This parameter consists of a list of hostnames and UDP port numbers that will be passed to the ZofToken app when a token enrolls to this service. Each hostname and port combination needs to be a ZofToken server that is part of the same instance (that is, connected to the same database) and this provides load balancing to those servers for either performance or resilience purposes. It’s important to note that this load balancing is implemented entirely on the client side as each ZofToken app will pick a random endpoint to contact on each token operation and retry on different endpoints if needed. Each service needs to have a minimum of one endpoint and configuring additional ones is optional. |
For ZaaS, all the configuration is done through a simple user interface, just use the information in this document and the help reminders on each page to configure all needed services.
For private ZofToken Server installations there are two ways to configure services:
The config.yaml file described in the installation guide includes a section where you can configure all services and their parameters. As services most likely do not change a lot, this is the easiest and probably most common configuration.
If the config.yaml file indicates that the configuration should be handled through the database, the ZofToken installation includes a command line tool to create, configure and edit services. Directly editing the database would be technically feasible (as the internal structure is fairly simple) but this is strongly unadvisable due both to the chance to introduce mistakes and the security objective of preventing all access to this database outside of normal operation.
Internally, ZofToken uses a hash of the combination of username and service as the actual token id, which means there are no real restrictions to service naming (including using UTF-8 characters as required by many languages). Nonetheless, it is recommended that service names are kept short and descriptive in order to simplify API interactions.
PFor ZaaS, to guarantee that each service name is unique, they will be prefixed with the name of the subscription. Therefore, for a subscription called “example” that has services named “alpha” and “bravo”, the actual names you will be using to interact with the API for these services are “example_alpha” and “example_bravo”.
Every interaction with the ZofToken API requires the use of an authkey which is checked before allowing any queries or actions. An authkey with the administrative flag can perform all API operations, while one without is limited to just querying a token status.
For ZaaS, two authkeys (one with the admin flag and the other without) are randomly assigned when the service is originally created and cannot be changed. For private ZofToken installations, any number of authkeys with a high degree of granularity in their access can be configured.
This design allows for very different security scenarios, from a simple installation with one internal authkey with complete access to all tokens to very complex variants with multiple authkeys with different levels of access to different services and users. These specific authkeys could be assigned to particular assets in order to implement good security practices – for example, two backends that handle two different applications could easily use tokens assigned to different services and have authkeys that limit access to only their own service, in a way that even a compromise of one of the applications doesn’t affect the security of the other.
Every authkey has the following parameters:
| Parameter | Description |
|---|---|
| Authkey | The actual (character string) secret that is passed to the API to authorize an operation. |
| Admin | A flag that indicates if the authkey will have unrestricted access to all API functions or just a read only access to the status of tokens. |
| Service mask | This is a regular expression that indicates which services the authkey will be able to access. Notice that this works in tandem with the next parameter. |
| User Mask | This is a regular expression that indicates which usernames the authkey will be able to access. Notice that this works in tandem with the previous parameter. |
As mentioned in the description, authkeys can’t be configured in ZaaS and are randomly provided for each service created.
For private ZofToken Server installations there are two ways to configure authkeys:
The config.yaml file described in the installation guide includes a section where you can configure all authkeys and their parameters. As authkeys most likely don’t change a lot (unless they become compromised), this is the easiest and probably most common configuration.
If the config.yaml file indicates that the configuration should be handled through the database, the ZofToken installation includes a command line tool to create, configure and edit authkeys. Directly editing the database would be technically feasible (as the internal structure is fairly simple) but this is strongly unadvisable due both to the chance to introduce mistakes and the security objective of preventing all access to it outside of normal operation.
Be aware that both the service and user masks are validated before allowing access, so you could configure a specific service access limitation and an unlimited user name access and this would not allow access to tokens outside of the service (this is, in fact, the configuration of the ZaaS-provided authkeys).
While the secret used as the authkey can be any UTF-8 string (particularly when configured manually through the config.yaml file), it is strongly recommended not to think of authkeys as passwords and use secure strings.
A good approach is generating a random binary string and then converting this to an hexadecimal or BASE64 representation. The command line tool included in the ZofToken Server installation does this with a 256-bit random binary string.
