Configuring an SQL directory

Introduction

There are several types of directories built on an SQL database:

 

• Guest database (SQL): Watchdoc^® configures a Guest database by default that is built on a table in the SQL database. This directory allows referencing users that are not present in the organisation directory but who are permitted to use the organisation's printer base, but to do so they need to be recognised by Watchdoc: These users include partners visiting, interns, contractors brought in for a set period of time, for example.

• User database (SQL): In the rare cases when the organisation does not have an LDAP directory and does not wish to distinguish between their own users and guest users, it can use an SQL table as a user directory.

• Print codes (PUK code): this directory can be used to generate PUK print codes for users registered in the Entra ID directory (Microsoft Azure).

Connection

The information entered in this subsection is used to locate the directory and establish communication between it and Watchdoc:

• Type: From the list, select the type of SQL database (SQL Server, Postgresql, SQLite)

• SQL server: Use this field to state the server where the SQL database hosting the directory is located. Click on the Browse button to browse your workspace to select the server from among the SQL servers detected on your network.

• Authentication: In the list, select the SQL Server authentication mode : SQL Server or Windows SSPI;

• Username: Use this field to state the user account name permitted to manage the SQL database,

• Password: Use this field to enter the password for the user account permitted to manage the SQL database,

• Database: Use the database field to state where the statistics on the newly created SQL database should be saved. Click on the Browse button to browse the previously declared SQL server to select the statistics tables declared there.

 

Options

The information entered can be used to specify the settings for generating PUK codes associated with users of an Entra ID directory:

• Seed: enter a number used as a "random seed" to initialise the user PUK code generator. This number is a 32-bit integer between 1 and 2,147,000,000;

• Algorithm: from the list, select the level of algorithm used to generate your users' PUK codes (6 or 10 digits);

• Variability: in the list, select (if necessary) the frequency with which the directory of PUK codes will be regenerated. By default, the directory does not change. Regenerating PUK codes increases the security of this authentication mode.

Logs

• Recording SQL requests in the application log: Tick this box if you wish to retain a trace of SQL requests in a dedicated file.

   

SQL requests

In special cases, where the SQL database is structured according to specific needs, it may be necessary to indicate to Watchdoc the SQL queries necessary to query this database. In this case, the requests are entered in the appropriate fields:

In each SQL Queries field, enter the user groups, SQL Query allowing the access each item (users properties, user group, and groups) in the SQL database:

 

PUK Code

In Watchdoc^®, the user has several authentication means:

• PUK Code: chekc this box if the user authenticates with a PUK code;

• Attribute: indicate in this field the LDAP directory attribut in which the PUK code is stored;

• Algorithm: select in the list the algorithm type on which the code is based (information given by the directory administrator);

• Variability: select in the list the frequency with which the encryption algorithm of the PUK Code is renewed of the algorithm;

• Prefix: enter in this fiel the prefix (digit between 2 and 8) that precedes the PUK code.

 

PIN Code

In Watchdoc, the user has several authentication means:

• Code PIN Code: check the box if the user authenticates with a PIN Code PIN (Personal Identification Number) is a code comprising of at least four digits. It is used, for example, on a mobile or smartphone with a SIM card. The term PIN is not exclusively used by mobile phones as a PIN is also used for banking and may refer to any Personal Identification Number comprising of four or more digits. code;

• Attribute: indicate in this field the LDAP directory attribut in which the PIN code is stored;

• Algorithme: select in the list the algorithm type on which the code is based (information given by the directory administrator);

• Variability: select in the liste the frequency with which the encryption algorithm of thtePIN Code will be renewed.
  
  

 

Cache lifetime

Watchdoc^® can retain a data cache that is specific to users to accelerate processing times. The data entered is used to define how long the caches are retained:

• TTL Info: Enter the time (in seconds, minutes, hours or days) for retaining user data.

• TTL NotFound: Enter the time (in seconds, minutes, hours or days) for retaining data relating to users authenticated in the Watchdoc application when the latter did not find them in the directory.

 

During the specified time, Watchdoc^® will not call on the directory but only its cache. Setting an excessively long retention period is not recommended, especially for users who are not found.

 

Cache

 

Watchdoc can retain the requests for cache in its memory to accelerate their execution. Tick the boxes for the caches you wish to enable:

• User Infos: Tick this box to enable the user information cache.

• Not found: Tick this box to enable the cache covering users whose accounts have not been found.

• Cold Cache: Tick this box to retain "cold" data cache, i.e. already checked but now expired data..

• Persistence: Tick this box to allow retaining the cache on disk so that it can be retrieved if the Watchdoc service is restarted..

• Compression: Tick this box to enable cache compression on disk. We strongly recommend enabling this setting to reduce the size of the file when persistence is enabled.

• Encryption: Tick this box to encrypt the cache file on disk, to secure its content.

 

Cards

If the user is to be Cards stored in a directory, select this directory in the drop-down list following:

 

E-mail

To communicate with users (when e-mail notifications are enabled), Watchdoc^® needs to have their e-mail address. This setting is used to define how Watchdoc^® determines a user's e-mail address:

• Stored in the directory: Opt for this choice if the directory has an attribute that is specific to the e-mail address,

• The user account is also used as the e-mail address: Opt for this choice so that Watchdoc^® will create the e-mail address by linking the user account name with a DNS domain name. In this case, state:

  • The DNS domain name to add when linking.

• Find the address in an alias directory: Opt for this choice if the e-mail address is stored in an Alias directory.

  • Search: Select the Alias directory where the e-mails are stored.

 

Circuit Breaker

User directories are usually hosted on a remote domain controller or server, accessible via the local network. In the event of a network failure or severe slowdown, this can cause a cascading effect that can cause the print server to freeze or slow down.

In this case, it may be useful to activate a "logic fuse", which trips in the event of a major system slowdown, to stop requests being sent to the faulty server.

Warning: it is important to consider the impact of the fuse activation on the service's good functioning!
In order to effectively protect the server from any malfunction of the remote directory, it is important to calibrate the fuse correctly. It is recommended to test the fuse setting before configuring it in a production environment.

Enter in the fields the values beyond which Watchdoc stops sending queries to the directory server to avoid overload:

1. Acces the Watchdoc^® administration interface as an administrator.

2. From the Main Menu, Configuration section, click on Users directories.

3. In the list of declared directories, click on the button to access the directory settings ;

4. or click on the button to Register a new directory (in the top banner).

5. In the Register a directory interface, go to the Circuit breaker section.

6. In the fields, enter the values beyond which Watchdoc stops sending queries to the directory server to avoid overload:

• Max. errors: it's the number of "serious" successive errors. A "serious" error is, for example, a network communication problen, a timeout, a malfunction or the remote server.  These errors are generally rare and can sometimes be resolved automatically (end of a peak period, restart of the remote server, etc.). Logical errors (such as authentication failure, syntax error or directory setting error) are ignored.

• Max. Requests: this is the maximum number of parallel requests allowed. In case of heavy workload, the remote server may not be able to respond to a large number of simultaneous requests.

• Max. duration: it is the maximum average time for the execution of the 10 last requests. In case of a strong slowdown of the remote server (peak period, network timeout,...), this time is extended.

• Retry Delay: after starting the circuit breaker, waiting time before reactivation. At the end of this delay, Watchdoc restarts the requests in order to "probe" the state of the server. If the requests are successful, the fuse is reactivated, otherwise it waits for the timeout to expire again.
  The administrator can manually deactivate the fuse at any time. The fuse then remains switched off until it is manually reactivated. Consider using this feature to test the impact of a failure on the print server.

   

  

   

The values frequently entered to activate the circuit breaker in a a large multi servers environment are the following:

• max. errors: 5

• max. requests: 5

• max. duration: 30 secondes

• retry delay: 120 secondes

 

Validating the configuration

Click on the Create button to validate the configuration for your directory.