1.3.2. Configuring UserIdResolvers

The idea of UserIdResolvers and Realms is described in section UserIdResolvers and Realms - The Concepts. You should read this to get an idea of how to setup LinOTP in the right way.

Go to the token management web gui https://<LINOTP>/manage, open LinOTP Config and select UserIdResolvers:

Choose New in the next popup:

Here all the UserIdResolvers that hold the user data can be defined. LinOTP only needs read access to those user stores. You can define as many UserIdResolvers as you like to. There are three possible types at the moment:

LDAP

Which can be used to read users from LDAP servers like OpenLDAP, Active Directory and Novell eDirectory.

SQL

Which can be used to read users from a vast number of different SQL servers.

Flatfile

Which can be used to read the users from any flat file located on the LinOTP server. This would usually be a copy of /etc/passwd or any other file in compatible format.

Configuring LDAP UserIdResolver

The LDAPIdResolver can be used to resolve user login names via OpenLDAP, Active Directory or Novell eDirectory.

Choose LDAP in the dialog:

This is an example of a complete configurated LDAPS UserIdResolver:

The configuration details are:

Resolver name

contains the name of the UserIdResolver, it may contain characters, numbers and ‘_-‘.

Server-URI

addresses of the LDAP or LDAPS servers.

To get redundancy, you can configure more than one LDAP server. To do this, you may enter more than one server in the LDAP Server configuration URI. Lets say, you have got two domain controllers named ad1.example.net and ad2.example.net. Then you need to enter the line:

ldap://ad1.example.net, ldap://ad2.example.net

Note

Starting with 2.9.1 LinOTP will try to establish a secure connection to the LDAP server via StartTLS. This will work even if LinOTP can not validate the servers certificate unless the “Enforce STARTTLS” option is activated as described below.

or for LDAPS:

ldaps://ad1.example.net, ldaps://ad2.example.net

If LinOTP fails to contact the first LDAP server, it will try to contact the second one. If the second one can be contacted, it will be set first then.

Enforce STARTTLS

If a server is contacted via LDAP-URI (ldap://ad1.example.net) LinOTP tries to establish a secure connection via StartTLS and falls back to unencrypted communication if StartTLS does not work (e.g. if StartTLS is not supported by the LDAP server). If Enforce STARTTLS is activated LinOTP will:

• require a valid certificate (chain) for the LDAP server

• terminate the connection if a proper StartTLS connection can not be established

Thus LinOTP will ensure a secure connection to a trusted LDAP server.

CA Certificate

LDAPS and enforced StartTLS require a valid certificate. The CA root certificate should be sufficient if the LDAP server provides the full certificate chain. Store the certificates in the default operating system certificate store, e.g. /etc/ssl/certs, and read the manual about certificate handling of your operating system.

BaseDN

the tree which contains the required data.

BindDN

the distinguished name used to connect to the LDAP server. This should be an extra account created for LinOTP without any further permissions.

Bind Password

password of the query account.

Timeout

contains one or two values (in seconds) of the format 5.0;7.5 The first value is the timeout to connect and log in to the LDAP server. The second value (optional, available in LinOTP >=2.8.1.2) is the time to wait for an answer from the LDAP server after the session is established before terminating the connection.

Sizelimit

how many user entries are requested from the LDAP.

No anonymous referral chasing

when configuring a LDAPIdResolver for connecting to Active Directory and your BaseDN is set to your top level domain components like dc=mydomain,dc=com you should also select this option.

Note

Before saving your configuration, you should push the button “Test LDAP connection” to see, if your settings enable the LinOTP server to connect to the LDAP successfully and if any users can be found. If you have got problems setting up your LDAP connection, you may monitor your LinOTP log file /var/log/linotp/linotp.log on your LinOTP server. This may give you some clues about problems with the LDAP connection. Also see section LDAP/Active Directory Connection.

Loginname attribute

is the attribute that holds the name the users will use to login.

Search filter

is used to filter the user objects found within the configured base DN [1]. You can only assign tokens to those users found by the search filter.

Examples:

Filter users belonging to a group “administration”:

(objectClass=user)(memberOf=cn=administration,dc=example,dc=net)

Filter all users of a stacked AD group “all_otpusers” (and by this include all members of related groups recursively):

(objectClass=user)(memberOf:1.2.840.113556.1.4.1941:=cn=all_otpusers,dc=example,dc=net)

User Filter

in turn will be used to resolve the users the other way round. E.g. if the user logs in, he will provide the loginname. The login name will be replaced with the “%s” in the user filter, to resolve the login name to the distinguished name of the user object in the LDAP.

Attribute mapping

will fetch more user information from your LDAP server and map them to correct internal identifiers of LinOTP. So for example the LinOTP attribute phone can be used for SMS token and here you tell which LDAP attribute should be mapped for this purpose.

username, phone, groups, mobile, email, surname, given name

Note

The required attribute is username. All other attributes are optional.

UID Type

this identifies the user entry unambiguously. So for example if the user name is changed the user can login with the new name and his previously assigned tokens. This attribute should be objectGUID for Active Directories and entryUUID for OpenLDAP.

By default “Preset Active Directory” is selected to configure the default LDAP attribute definitions do fit the needs in an Active Directory environment. In this case you will not need to change the attribute definition manually. Select “Preset LDAP” for a setup with OpenLDAP. After having entered and checked all necessary values, you need to push “Save” to store the changes.

Configuring SQL UserIdResolver

The SQL UserIdResolver can be used to resolve login names via SQL databases. You need to enter a valid database driver like SQLite, MySQL, PostgreSQL, Oracle, Firebird, Microsoft SQL Server, Firebird as described in the SQLAlchemy documentation:

http://docs.sqlalchemy.org/en/rel_1_0/dialects/

Choose SQL in the dialog:

This is the configuration popup for SQL UserIdResolvers:

The configuration details are:

Resolver name

contains the name of the UserIdResolver, it may contain characters, numbers and ‘_-‘.

Driver

contains the name of the driver as used in sqlalchemy. mysql is configured and supported by default for other SQL engines (like Oracle) dependencies have to be installed and configured in the operating system.

Server

addresses of the servers. IPs or FQDNs can be used. More than one server can be configured for redundancy:

mysqlserver1.example.net, mysqlserver2.example.net

Port

the port to connect to for accessing the database.

Database

name of the database.

User

the account used to connect to the SQL server. This should be an extra account created for LinOTP without any further permissions.

Password

password of the query account.

Database table

the name of the table where the users are stored in.

Limit

how many user entries are fetch with one request from the SQL server.

Database encoding

the encoding of the database. This should be “utf-8” but could also be something like “latin1”.

Additional connection parameters

these parameters are added to the connection string. The parameters very much depend on the used driver. If you are only using ASCII characters you will not have to bother with this setting. E.g. for a mysql database containing utf-8 tables and storing usernames with non-ASCII characters, you should add the parameters “use_unicode=1&charset=utf8”.

Note

Before saving your configuration, you should push the button “Test SQL connection” to see, if your settings enable the LinOTP server to connect to the SQL server successfully and if any users can be found.

Attribute mapping will fetch more user information from the SQL server

and map them to correct internal identifiers of LinOTP. So for example the LinOTP attribute phone can be used for SMS token and here you tell which SQL attribute should be mapped for this purpose.

username, phone, groups, mobile, email, surname, given name, password, salt

Note

The attributes username and userid are required. All other attributes are optional.

The password column in the attribute mapping holds a encrypted password, where the first two bytes are the salt that was used to crypt the password. The tool create-sqlidresolver-user.py can be used to create encrypted passwords.

E.g. if your user table has a column “loginname” and a primary key “id”, you might at least enter:

{ "username":"loginname", "userid":"id"  }

Where statement

can be used to filter the users used for LinOTP. If you e.g. only want to use with an ID bigger than 5 you could enter a where statement like “id>5”.

If your usernames or other fields contain non-ASCII characters you probably use another encoding. In this case you can enter the information, what encoding your database table uses. Usually it might be latin1 or utf-8.

After having entered all necessary values, you need to push the button “Save” to store the changes.

Configuring Passwd (Flatfile) UserIdResolver

The simplest user store are flat files on the LinOTP server. These flat files can be used by configuring the Flatfile UserIdResolver. You only need to enter the filename of the file on the LinOTP server. The default filename is “/etc/passwd”.

Using /etc/passwd

Please be aware: If you wish to use system user password hashes (as OTP PIN or logging in to the selfservice potal), the file must contain the actual password hashes. You can use pwunconv to transfer the hashes from “/etc/shadow” to “/etc/passwd”. “/etc/passwd” can then be used as the target for the UserIdResolver. Or alternatively, a new independent file can be created as a copy and used as target as described below. After this the procedure can be reverted with pwconv.

We recommend the use of a separate file. If you decide to operate on the passwd file of your system please take note: when hashes are moved from “/etc/shadow” to “/etc/passwd”, your system will no longer apply any configuration regarding password aging. Also, you should consider changing the permissions of “/etc/passwd” in order to prevent access by locally logged in users.

The following commands should set sensible permissions on most distributions:

chmod o-rw /etc/passwd
setfacl -m u:linotp:r /etc/passwd #this requires ACLs to be activated

Please check the configuration carefully because the security of your systems depends on it.

Using a separate file

If you decide to use a new file, it needs to follow the syntax of the passwd file. Each line represents a user entry in each line. All fields are separated by a colon (:)

The fields represent the following

1. column: loginname (used as login name by LinOTP)

2. column: password (used for otppin=1 policies and login to selfservice) [3]

3. column: numerical id (used as unique ID by LinOTP)

4. column: (not used – usually this would contain the groupid)

5. column: description. Containing information about given name, surname, email and phone numbers. According to [4] this field is a comma separated list of 5 items.

   1. item: Name. The name is split by a blank into given name and surname.

   2. item: (not used – usually this would contain the room number)

   3. item: Used as mobile number.

   4. item: Used as phone number.

   5. item: Used as email address.

6. column: (not used – usually this would contain the home directory)

7. column: (not used – usually this would contain the login shell)

LinOTP does provide a tool for creating syntactical correct entries: linotp-create-pwidresolver-user. In the Appliance you have to enter unsupported mode first in order to be able to execute the programm.

Show help for linotp-create-pwidresolver-user:

linotp-create-pwidresolver-user --help

Please make sure, LinOTP is able to read the file containing the user information. If a separate file (e.g. “/etc/linotp2/passwd.linotp”) is used (either a copy of the original “/etc/passwd” or one generated from scratch) the owner and permissions should be changed accordingly:

chown linotp /etc/linotp2/passwd.linotp
chmod 400 /etc/linotp2/passwd.linotp

[1]

Distinguished Name

[2]

Fully qualified domain name

[3]

The file /etc/passwd does not contain the password. Using the tool linotp-create-pwidresolver-user you can create valid lines, that also contain the password.

[4]

http://en.wikipedia.org/wiki/Passwd