.. _configureuseridresolver: Configuring UserIdResolvers --------------------------- .. index:: UserIdResolver The idea of UserIdResolvers and Realms is described in section :ref:`manageclientuseridresolvers`. 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:///manage**, open **LinOTP Config** and select **UserIdResolvers**: | .. figure:: images/webui_useridresolver_menu1.png :width: 100% | Choose **New** in the next popup: | .. figure:: images/webui_useridresolver_popup_manage.png :width: 50% | 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: | .. figure:: images/useridresolver_new_choose_type.png :width: 50% | ``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: | .. figure:: images/webui_useridresolver_popup_type.png :width: 50% | This is an example of a complete configurated LDAPS UserIdResolver: | .. image:: images/webui_useridresolver_ldaps_popup_configuration.png :width: 70% | **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. | .. image:: images/useridresolver_ldap_enforce_tls_small.png :width: 70% | ``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. If the server only sends its own certificate the full chain can be deployed here: .. figure:: images/ldaps_certificate.png :width: 70% | Alternatively certificates can be stored directly in the 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 :ref:`troubleldap`. ``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 [#dn]_. You can only assign tokens to those users found by the search filter. Examples: Filter users belonging to a group "administration": .. code:: (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): .. code:: (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: | .. figure:: images/webui_useridresolver_popup_type.png :width: 50% | This is the configuration popup for SQL UserIdResolvers: | .. figure:: images/sql_resolver.png :width: 70% | **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: .. code:: 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) [#pwidpassword]_ 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 [#pwwiki]_ 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:* .. code:: bash 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: .. code:: chown linotp /etc/linotp2/passwd.linotp chmod 400 /etc/linotp2/passwd.linotp .. [#dn] Distinguished Name .. [#fqdn] Fully qualified domain name .. [#pwidpassword] 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. .. [#pwwiki] http://en.wikipedia.org/wiki/Passwd