When an user logs in to QueueMetrics, QM checks to see if there is an auth source defined. QueueMetrics will execute a query to that third-party server passing along the user-id and the password given for authentication, plus a given service-id that will be defined in the configuration file.

The server will respond passing along a fixed set of data:

If the class passed along is empty, only the user keys will be computed. If the class is not empty, it will be searched by name on the QueueMetrics storage and it will be loaded. Trying to load a non-existent class will result in auth failure.

The auth server may return four different responses:

The following table explains the relationship between those states:

If auth is SUCCESSFUL, the local QM database is checked for that user name. If such a user is present, the user details, class and key information are loaded from QM. If such a user is not present, the details are taken from the ones supplied by the service.

If auth is AUTHORITATIVE, the details are taken from the ones supplied via RPC. Then they are copied to the local user database (with a random password) so that although the user cannot login manually, it is possible to decode the user name for all logged operations (e.g. Updating a queue). If a user with the same name is present, credentials are forcibly updated with the authoritative credentials.

The following values are implied in authoritative replies:

The actual user data sent by the auth server is only read by QM in case "A"; otherwise it’s ignored, whatever is passed.

If auth is FORBIDDEN, no other check is done and the user is rejected access.

If auth is DELEGATED, the standard QM logon procedure is done; so the remote auth source is basically telling QM to repeat the log-on process as if there was no external auth involved. This way, you can first check on the remote system, and you delegate any failing user to QM, so you can have a mix-and-match situation. Some drivers let you input a list of ignored users that are in any case delegated, effectively bypassing them.

The whole procedure is totally transparent to the user, so they do not need to know which is the authority that grants or denies access.

By setting the properties:

A request will be sent to the URL specified, with a JSON payload in parameter query, as below:

The result must have the following shape:

In the case of "A" (Authoritative) you need to fill all parameters, while in all other cases the response will be enough.

If there is a login field in the reply, then the returned login will be used on QM - this is espeecially useful for agents, where QM demands a format like Agent/123 while you might use a free form, and return the correct agent code if authentication is successful.

The ignore parameter is useful for JSON services / web loading, to avoid hitting the server on each request, or if you don’t want to have QM-specific users on your server (eg. a company’s LDAP server you don’t manage).

The LDAP driver lets you query an external LDAP/LDAPS server; you define both the server and the user query to be checked.

All strings can be expanded with the following placeholders:

The ldapBind parameter is the log-in that lets your user access LDAP; it is usually the Distinguished Name (e.g. CN=John Doe,CN=Users,DC=example,DC=com) or the Account Name or the user’s e-mail, depending on system configuration.

LDAP can be used in two ways:

In this second case you need to specify an attribute on your users to contain the login that will be used in QM for them. In ActiveDirectory, for example, the default schema has a set of empty Extension Attributes that may be set freely. They do appear in LDAP with a name like msDS-cloudExtensionAttribute7. In one of them, you should specify the QM login to use.

To use them, you need to set ldapLoginAttr to the attribute to use, the ldapBase to where to start searching in the LDAP tree (typically, Users), and a LDAP query that is supposed to return only one record that finds the right user on the basis of the user-supplied login. Missing attributes, users, or multiple results will be logged on the system log.

At the end of your LDAP authentication, the only positive auth will be SUCCESS - so a user with the same name is supposed to be present in the database.

If the auth fails, we check auth.ldapFailureDelegates: if true, auth fails with DELEGATES; if false, as by default, it is FORBIDDEN.

As for JSON, it is possible to have a set of users that are ignored for LDAP and effectively checked only on the local database; this is helpful for webservices or data loaders, especially when you cannot create service users in LDAP for third-party applications.

This driver is obsolete, see the XML-RPC manual for more details.

Prerequisites

Flow

In practice: a Google flow

To enable a QM user to log in with SSO:

As this is sometimes unwieldy, you can have QM automatically create a template user when someone accesses QM through SSO.

To create a new user, the sysadmins must know not only the email, but also the service and possibly the exact reference id for the user in the exact auth provider.

To make their life easier, we automatically create unknown users into a placeholder class, usually AGENTS. Therefore in the example above, to enable Alice for proper access, the sysadmin will only have to change her class and possibly the log-in name (for agents), but the full name and the identity assertions will already be present.

When a user tries to log in with a user that is correct on the OAuth side but does not exist in QM:

An OAuth user exist on the QM database, but cannot be used for log ins as their password is invalid. Therefore, if a user has the grants to set their own password they can bypass the OAuth flow entirely. Therefore we strongly recommend removing the key CHPASSWD before allowing direct log-ins.

On the other hand, this can be used by an administrator in an emergency where the OAuth server is unavailable to allow access to QM by setting ad-hoc passwords and changing them after the event.

It is strongly advisable to keep at least an admin user as QM-only to allow emergency access in case the OAuth service should be unavailable.

The following items are logged on the Audit logs:

As OAuth users depend on human interaction, such users won’t work for webservices (unless a password is set). This is not a major limitation, as you would usually create local users for webservice acces.

OAuth users can be instead users to run scheduled reports, as QM impersonates them without the need of password authentication.

In order to "jump back" from the auth flow, QM creates a return URL, that is basically the public name of the server QM instance plus the string "/qm_sso_return.do": for example, it might be https://test.loway.ch:443/queuemetrics/qm_sso_return.do.

As most SSO providers will require this to be an HTTPS URL, QM rebuils the public name based on the headers it receives from its upstream proxy implementing HTTPS, e.g. NGINX.

To see the current URL, as an administrator, go to "Diagnostics" → "View configuration" → "HTTP Configuration" and check the value that appears in "Q: getPublicQmBaseUrl".

The driver is called google, and will work in the case you use Google to manage your organization’s credentials.

The driver is called microsoft, and will work in the case you use Microsoft (e.g. Teams) to manage your organization’s credentials.

By using the ROBOT profile is possible to generate PDF and XLS reports and send them to a list of e-mail recipients. The report parameters, like queue, period, report set and the list of recipients should have been already defined in the Report ExportConfiguration pages.

You will usually run these jobs automatically by setting up a Scheduled job, though you can have reports generated on-demand by downloading the following URL (you will probably use wget or a similar tool, and will script this as a cron job so that it will be run daily or weekly):

http://server:8080/queuemetrics/qm_export_stats_run.do?username=robot&password=robot&exportId=X

where the exportId X parameter is the job number identifier that could be found on the Report ExportConfiguration pages.

The server generates the required report and send it to a list of recipients. It also returns a copy of the generated document.

If you don’t want QueueMetrics to send e-mails but just need to retrieve the file, avoid configuring any e-mail recipients.

If there is an error during the document generation or e-mail sending phase, then an error message is returned instead.

By using the ROBOT profile in conjunction with reloads=1, it is quite simple to set-up an unattended wallboard for QueueMetrics.

First of all set up a low-cost Linux box to boot in its graphical environment, automatically launch a web browser and go to the following URL:

http://server/queuemetrics/qm_wab.do?user=robot&pass=xxx&reloads=1&queues=q1|q2

or, for the ajax based page version

http://server/queuemetrics/qm_wab_ajax.do?user=robot&pass=xxx&reloads=1&queues=q1|q2

This command will show an auto-reloading wallboard showing the real-time status of queues Q1 and Q2.

If you connect the new Linux box to a large screen or a video beamer and set it in your call-center where it will be visible by your agents, you have just set-up a wallboard at a very low cost using commodity hardware and requiring no human intervention but turning it on in the morning and turning it off in the afternoon.

You can do the same with the real-time screen by using the qm_rt.do or the qm_rt_ajax.do commands to create a very simple real-time monitor running all day long for your supervisors.