Prev   Next

5. Using an external auth source for QueueMetrics

It is possible for QueueMetrics to accept an external authentication source. By using a simple XML-RPC interface, it is be possible to write easily third party scripts that are able to authenticate against a chosen authentication system (e.g. Kerberos, LDAP, a Microsoft domain server, etc).

5.1. Log on procedure

When an user logs in to QueueMetrics, QM checks to see if there is an XML-RPC 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:

  • An auth response (see below)
  • A set of login information for that user (e.g. real name, email)
  • The current class and user keys for that user

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:

  • Access allowed
  • Access allowed with supplied user data
  • Access is forbidden
  • Access is fully delegated to QM

The following table explains the relationship between those states:

Auth OK Auth KO
User data from RPC AUTHORITATIVE FORBIDDEN
User data from QM SUCCESSFUL DELEGATED

If auth was 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 via XML-RPC.

If auth was AUTHORITATIVE, the details are taken from the ones supplied via XML-RPC. Then they are copied to the local user database (with a random password) so that though 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, its credentials are forcibly updated with the authoritative credentials.

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

If auth was DELEGATED, the standard QM logon procedure is done.

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

5.2. XML-RPC call parameters

5.2.1. Method: QMAuth.auth

Input parameters

Pos Name Type Comment
0 System ID String As set in QM; if not set: blank
1 Username String
2 Password String

Output block

Pos Name Type Comment
0 Status code String One of:
A (authoritative)
S (success)
F (forbidden)
D (delegate)
If other, behaves as D.
1 Real name String
2 Email String
3 Class name String Must match an existing class
4 User keys String

The following values are implied in QM:

  • Enabled = yes
  • Masterkey = no

The actual user data is only read by QM in case "A"; otherwise is ignored whatever is passed.

Tip: As a reference implementation, see the server that ships with QueueMetrics in the mysql-utils/xml-rpc/xmlrpc_auth_server.php file. It also contains an example of querying a LDAP server in PHP.

5.2.2. Configuration properties

A set of two new configuration properties control external auth sources in in QM:

Property Description
default.authRpcServerUrl If set, XML-RPC auth is used. Points to the URL of the auth server.
default.authSystemId The system-ID for this QM license. Can be currently any user-chosen name for the system.
Prev   Next
 Home