Tigase Custom Auth connector

The Tigase Custom Auth connector with shortcut name: tigase-custom is implemented in the class: tigase.db.jdbc.TigaseCustomAuth. It allows you to connect to any external database to perform user authentication and use a custom queries for all actions..

You can find more details how to setup a custom connector in Custom Authentication Connectors guide.

The basic configuration is very simple:

--auth-db = tigase-custom
--auth-db-uri = jdbc:mysql://localhost/drupal?user=user&password=passwd

 That's it.

The connector loads correctly and starts working using predefined, default list of queries. In most cases you also want to define your own queries in the configuration file. The shortest possible description is the following example of the content from init.properties file:

basic-conf/auth-repo-params/conn-valid-query=select 1
basic-conf/auth-repo-params/init-db-query=update tig_users set online_status = 0
basic-conf/auth-repo-params/add-user-query={ call TigAddUserPlainPw(?, ?) }
basic-conf/auth-repo-params/del-user-query={ call TigRemoveUser(?) }
basic-conf/auth-repo-params/get-password-query=select user_pw from tig_users where user_id = ?
basic-conf/auth-repo-params/update-password-query=update tig_users set user_pw = ? where user_id = ?
basic-conf/auth-repo-params/user-logout-query=update tig_users, set online_status = online_status - 1 where user_id = ?
basic-conf/auth-repo-params/non-sasl-mechs=password,digest
basic-conf/auth-repo-params/sasl-mechs=PLAIN,DIGEST-MD5

Queries are defined in the configuration file and they can be either plain SQL queries or stored procedures. If the query starts with characters: '{ call' then the server assumes this is a stored procedure call, otherwise it is executed as a plain SQL query. Each configuration value is stripped from white characters on both ends before processing.

Please don't use semicolon ';' at the end of the query as many JDBC drivers get confused and the query may not work for unknown reason.

Some queries take arguments. Arguments are marked by question marks '?' in the query. Refer to the configuration parameters description for more details about what parameters are expected in each query.

The first example shows how to put a stored procedure as a query with 2 required parameters.

add-user-query={ call TigAddUserPlainPw(?, ?) }

The same query with plain SQL parameters instead:

add-user-query=insert into users (user_id, password) values (?, ?)

The order of the query arguments is important and must be exactly as described in specification for each parameter.

• 'conn-valid-query' - Query executing periodically to ensure active connection with the database.
  
  Takes no arguments.
  Example query: 'select 1'
• 'init-db-query' - Database initialization query which is run after the server is started.
  
  Takes no arguments.
  Example query: 'update tig_users set online_status = 0'
• 'add-user-query' - Query adding a new user to the database.
  
  Takes 2 arguments: (user_id (JID), password)
  Example query: 'insert into tig_users (user_id, user_pw) values (?, ?)'
• 'del-user-query' - Removes a user from the database.
  
  Takes 1 argument: (user_id (JID))
  Example query: 'delete from tig_users where user_id = ?'
• 'get-password-query' - Rertieves user password from the database for given user_id (JID).
  
  Takes 1 argument: (user_id (JID))
  Example query: 'select user_pw from tig_users where user_id = ?'
• 'update-password-query' - Updates (changes) password for a given user_id (JID).
  
  Takes 2 arguments: (password, user_id (JID))
  Example query: 'update tig_users set user_pw = ? where user_id = ?'
• 'user-login-query' - Performs user login. Normally used when there is a special SP used for this purpose. This is an alternative way to a method requiring retrieving user password. Therefore at least one of those queries must be defined: user-login-query or get-password-query.
  
  If both queries are defined then user-login-query is used. Normally this method should be only used with plain text password authentication or sasl-plain.
  
  The Tigase server expects a result set with user_id to be returned from the query if login is successful and empty results set if the login is unsuccessful.
  
  Takes 2 arguments: (user_id (JID), password)
  Example query: 'select user_id from tig_users where (user_id = ?) AND (user_pw = ?)'
• 'user-logout-query' - This query is called when user logs out or disconnects. It can record that event in the database.
  
  Takes 1 argument: (user_id (JID))
  Example query: 'update tig_users, set online_status = online_status - 1 where user_id = ?'
• 'non-sasl-mechs' - Comma separated list of NON-SASL authentication mechanisms. Possible mechanisms are: password and digest. digest mechanism can work only with get-password-query active and only when password are stored in plain text format in the database.
• 'sasl-mechs' - Comma separated list of SASL authentication mechanisms. Possible mechanisms are all mechanisms supported by Java implementation. The most common are: PLAIN, DIGEST-MD5, CRAM-MD5.
  "Non-PLAIN" mechanisms will work only with the get-password-query active and only when passwords are stored in plain text formay in the database.