Menu ▾ ▴

User authentication and identification

Authentication Identification Configuration (1)
Sebastian Reitenbach

Authentication and identification

The default configuration for OpenGroupware authentication and identification is to use the account database provided in the database backend. However OpenGroupware can be configured to use LDAP for authentication and initial identification.

Session logs

Each time a user logs into or out of the OpenGroupware web interface that event in recorded in the “session_log” table. This behavior can be disabled by setting the “LSDisableSessionLog” default to a value of “YES”; deleting this default will cause the logging of session events to resume.

If session logs are enabled, which is the default, the contents of the “session_log” table should be reduced on some regular interval; this can be achieved via a scheduled task in the system's schedular, which is CRON on most UNIX and UNIX-like systems.

DELETE FROM session_log 
WHERE log_date < (now() - INTERVAL '120 days');

Accounts in the database

Accounts in the OpenGroupware database backend are records in the person table where the field “is_account” has a value of “1”. Each account has a unique numeric id in the “company_id” field much like a UNIX system account has a unique uidNumber in its password file entry or LDAP object. The “company_id” field is the primary key of the person table. The login and password values for an account are stored in the login and password fields respectively. Due to the hierarchical nature of OpenGroupware's database schema all entries in the person table are present in the company table as well. It is important to note that the password for the user is also stored in these tables, so direct access to the person and company tables should be heavily restricted. If LDAP authentication is used the user's password is never copied into the database.

Template accounts

Locked accounts

An account may be placed into a locked state. An active account has a value of “0” or an absence of value in the “is_locked” field of the “person” table, a value of “1” in this field disables the account. When disabled the account exists and can own objects, etc... but is simply unable to login. It is possible to set an account as locked from the user management section of the Administration application provided by the OpenGroupware web interface. All template accounts are locked by default.

Locking Accounts For Failed Login Attempts

The OpenGroupware Administrator

OpenGroupware uses a special account, by default called “root”, to facilitate administration. This administrative user has access to all content on the server as well as the additional “Administration” application. When OpenGroupware is first initialized this account has no password, and authentication of other users is inoperable until a password is set for this account. (See “Setting The Administrative Password”).

The administrative account exists in the person table along with all the other user accounts, like the root account on UNIX systems it is not the name “root” that is significant but the underlying id. On UNIX systems the administrative account is the account with a uidNumber of zero, in OpenGroupware the administrative account is the account with a company_id of 10,000. As the company_id field of the person table is the primary key there can be only one administrative account.

Renaming The Administrative Account

A benefit of this company_id oriented schema is that the administrative account can be renamed, this is especially useful when using LDAP authentication as there may already be an account called “root”. Simply update the person table's login and name fields to reflect the desired username for the record with a company_id of 10,0001. Be very cautious when modifying the database directly, and it is always safest to make such changes with the OpenGroupware services offline.

Do not rename the administrative account to a login intended to be used as a user account; the company_id of 10,000 is filtered out of various views and treated differently by applications than are other accounts. The administrative account should always be a separate account used only for the administration of the OpenGroupware instance.

Permitting Space In Logins

If your site's usernames contain spaces you will need to set the “AllowSpacesInLogin” default to “YES”. Otherwise spaces are removed from the username during authentication and subsequent operations.

Using HTTP Basic Authentication For The Web Interface

Rather than using the form authentication for the web interface you can enable the use of HTTP basic authentication by setting the default LSUseBasicAuthentication to “YES”. The LSUseBasicAuthentication default does not need to be set in the global domain, it can be set in the application domain of the web interface. With basic authentication enabled if a user attempts to access OpenGroupware they should be prompted for a username and password with a browser authentication popup. The default realm for the authentication is “OpenGroupware”; this can be overridden by setting the AuthName directive in the Apache configuration if Apache is configured to perform the initial authentication.

Using basic authentication removes the ability of the user to logout of the web interface since as soon as they return to the login page the browser will supply the cached credentials and log the user in again1. But this brief logout will be sufficient for making any changes made to preferences that require a logout to become effective.

OpenGroupware's basic authentication support is provided primarily for an environment where Apache is performing the initial authentication using one of its many authentication modules. Apache will then pass the provided, and verified, username and password on to the OpenGroupware web interface.

If you wish to use basic authentication in a production environment you should configure Apache to handle the authentication and not merely set LSUseBasicAuthentication. Otherwise once a user fails basic authentication by incorrectly entering their username and password they will fall back to the OpenGroupware login form page, resulting in an inconsistent user experience. However, to use basic authentication in this manner requires that your external authentication source and the OpenGroupware user database be in sync, or the use of a common external authentication source such as LDAP.

Basic Authentication & JavaScript

JavaScript support in the client browser is detected when the login form is processed. A result of this is that the use of basic authentication disables JavaScript since the login form is never used. To work around this deficiency the “OGoAlwaysEnableJavaScript” default should be set to “YES”; with this default set JavaScript is enabled regardless of client detection.

LDAP Authentication

OpenGroupware can be configured to use an LDAP DSA (Directory Service Agent) to authenticate users. When a new user authenticates via the LDAP server OpenGroupware will automatically create an account entry in the database backend, copying several attributes from the user's LDAP object into their account specification. From that point forward LDAP is relevant only for authentication, the attributes of the OpenGroupware account object are not updated to reflect changes to the user's LDAP object.
In order to authenticate via LDAP you must set at least the LSAuthLDAPServer, LSAuthLDAPServerRoot, and LSAuthLDAPServerPort defaults. If these three defaults are set OpenGroupware will attempt a protocol level two anonymous bind to the DSA in order to locate the user's DN and perform a bind attempt as that DN with the password the user provided. If the subsequent bind is successful then the user is authenticated, otherwise user authentication fails.

The LDAP attributes copied into the new account object are as follows: “sn” into “name” (which appears in the web interface as “last name”), “title” into “degree”, “givenName” into “firstname”, “initials” into “description” (which appears in the web interface as “nickname”), “mail” into “email1”, and “labeledURI” up until the first space into “url”1. Once these attributes have been mapped into the user account and contact objects they can subsequently be edited. Setting the default LSCreateAccountsReadonly makes account objects created by LDAP authentication read-only.

It is important to understand that first OpenGroupware must locate the user's object and then attempts to bind using the user provided password. If OpenGroupware is unable to perform the initial anonymous bind to the DSA all user authentication will fail. There are two common reasons for the initial bind attempt to fail: (1) the DSA does not permit anonymous binds, (2) the DSA does not permit or support protocol level two. The first case is most commonly true of Microsoft Active Directory although many DSAs decline anonymous binds for security reasons. The second case is common with recent versions of OpenLDAP which disable protocol level 2 by default.

If either of these conditions prevents LDAP authentication from functioning you can either change the configuration of the DSA to support protocol level 2 and/or anonymous binds, or use OpenGroupware's LDAPInitialBindSpecific default. Configuration of the DSA depends entirely on the DSA in question and is not covered here; use of LDAPInitialBindSpecific is a superior solution to lowering the bind requirements on your DSA or supporting down level protocol versions if OpenGroupware is the only service that requires those changes.

Setting LDAPInitialBindSpecific enables LDAP protocol level 3 which is the current LDAP protocol level. When setting LDAPInitialBindSpecific you must also provide a bind DN and password for OpenGroupware to use when performing the initial bind and search to determine the user's DN. These credentials are provided by setting the LDAPInitialBindDN and LDAPInitialBindPW defaults respectively. LDAPInitialBindDN is the DN OpenGrouware will bind as for the initial search, using the password provided via LDAPInitialBindPW.

The password provided via LDAPInitialBindPW is stored in clear text in the OpenGroupware defaults, this bind DN and password should have only the access required to search for user DNs and copy the requisite attributes into the account database. The LDAPInitialBindDN does not need any write access to the DSA and should never be set to your DSA's administrative DN. The object at the DN specified in LDAPInitialBindDN does not need to be an actual system account; an account object with an auxiliary objectclass of simpleSecurityObject is sufficient.

Another possible problem when attempting to initially configure LDAP authentication is that your directory information tree does not conform to the RFC2307 schema that OpenGroupware assumes by default. With RFC2307 the user's account name (login name) corresponds to the attribute “uid”. However some directory configuration store the account name in a different attribute, for instance Microsoft Active Directory uses the “cn” attribute to store the account name. The LDAPLoginAttributeName default can be used to specify the name of the attribute to be used when searching for the user's DN.

Regardless of the DSA or the DSA's configuration one other important default to consider is LSUseLowercaseLogin. When searching an attribute like “uid” in an LDAP Dit, the search is performed in a case insensitive manner. So a search for user “adam” and user “ADAM” will both select the same DN in order to test the user's credentials, and if the credentials are correct that bind attempt will succeed. However the database backend is not so lax and will see “adam” and “ADAM” as two distinct users. One possible way to circumvent this dilemma, provided your site does not use mixed case usernames, it to set LSUseLowercaseLogin to “Yes”. When LSUseLowercaseLogin has a value of “Yes” OpenGroupware will always change whatever username is provided to lowercase before authentication is attempted. In other words, if the user enters a username of “ADAM” or “Adam” and LSUseLowercaseLogin is set to “Yes” then authentication will be actually be attempted for user “adam”.

If you are having problems configuring LDAP authentication the “LDAPDebugEnabled” default to “YES” will increase the level of LDAP relating information recorded in the system's log. For more information see this document's section on debugging.

Disabling Password Changes

When using an external authentication mechanism it is useful to remove the “edit password” link from the preferences application of the web interface. This is because OpenGroupware cannot necessarily update passwords within the external mechanism. The presence of this link can be controlled by setting the DisablePasswordModification default in the NSGlobalDomain to “YES”. If this default is not set, or is set to “NO”, then the edit password link appears. Unfortunately setting of this default does not remove the “Change Password” section from the setting page provided by ZideStore.

Authenticating Third Party Services via PAM

If an external service or application supports PAM authentication it is possible to authenticate that service against OpenGroupware's account database. This is accomplished via the PAM module provided by the pam-pgsql SourceForge project1. This module connects to a PostgreSQL database and attempts to perform authentication requests against the configured table and field names.

Configuration of this module is through a configuration file. usually “/etc/pam_pgsql.conf”. This file must contains the following configuration directives:

database = OGo
host = localhost
user = OGo
password = ***********
table = ogo_users
user_column = login
pwd_column = password
pw_type = crypt
  • “database” - The name of the database to which the module should attempt to connect.
  • “host” - The hostname of the PostgreSQL server.
  • “user” & “password” - The username and password the module should use when attempting to authenticate to the PostgreSQL server.
  • “table” - The name of the table containing user account information.
  • “user_column” - The field name in the specified table that contains the login of the user.
  • “pwd_column” -The field name in the specified table that contains the password of the user”.
  • “pw_type” - Describes how, or if, the value in the “pwd_column” is encrypted. OpenGroupware used the traditional crypt() method to encrypt user passwords which corresponds to the configuration value of “crypt”.

In order to provide only the accounts from the person table to the PAM module it is advisable to create a view on the “person” table specifically for authenticating users. This view should filter for at least where the “is_account” field has a value of 1 and the “password” field is not null. You may also want to filter out users where the “is_locked” field has a value of 1 or the “is_template_user” value is not null.

CREATE VIEW ogo_users (password, login) AS
SELECT password, login 
FROM person 
WHERE is_account = 1 
  AND password IS NOT NULL;