With Version 4.1 of Univention Corporate Server Univention is integrating a service into Univention Corporate Server which makes life easier for users and administrators alike: the Univention Self Service modules. These allow users to change their saved passwords autonomously (without administrator involvement).

There are currently two modules available: “Change Password” and “Password Reset. “Change Password” involves a website where users can change their (expired) password if they still remember it. “Password Reset” involves a website which allows users who have forgotten their password to send a token to a previously saved address. Both modules can be accessed easily from the UCS server overview page.

The Univention Self Service modules can be installed on servers with the roles “domain controller master” and “domain controller backup” from the App Center. Following installation, the modules can be enabled and disabled individually. For example, the “Password Reset” module is disabled by entering the following in the command line:
univention-self-service-modules disable passwordreset

As usual, the “--help” option offers information about further options.

App developers can offer self service for their applications

One aspect that is particularly interesting for app developers is that when a user logs in to an app with an expired password, the app can display a link to change the password. The link is stored in Univention Configuration Registry (UCR) variables.
ucs/web/overview/entries/service/passwordchange/link or
ucs/web/overview/entries/service/passwordchange/link/de
if you want to preset the language to German.

Saving contact details

Administrators who want to utilize the “Password Reset” module, should inform users of the need to save their contact details on the website as they are required for resetting valid passwords. Users without saved contact details will not be able to use this service if they subsequently forget their password. The administrator can view the data on the “Password Reset” tab in the user module of the Univention Management Console.

Configuration for resetting passwords

Although no settings need to be made for the simple password change (“Change Password” module), the module for resetting passwords (“Password Reset” module) has been designed in such a way that it can be adjusted to suit as many different environments as possible. This makes it possible to specify privileges, the length of the tokens, and the means of sending. In the default settings for UCS, the tokens can only be sent by e-mail.

To view all the relevant UCR variables, search for “self-service”:
ucr search --brief self service

The --brief option gives a more concise overview as the descriptions of the variables are not printed.

Assigning Privileges

The UCR variables “umc/self-service/passwordreset/blacklist/*” and “umc/self-service/passwordreset/whitelist/*” can be used to permit users and groups access to the service. In the default setting, all users who are members of the “Domain Users” group but not the “Administrators” or “Domain Admins” group are allowed to use the service.
ucr search umc/self-service/passwordreset/.*list

Setting Token length

The length of the token to be sent can be set individually for each type of sending. An SMS not only has capacity for fewer characters than an e-mail, but it can also be assumed that the token then has to be typed in somewhere else manually. Users can copy a longer token directly out of an e-mail or click on an embedded link. Tokens are always valid for one hour before expiring automatically. The user cannot request any further tokens within this hour. The standard lengths of the tokens can be found in the descriptions of the UCR variables:
ucr search umc/self-service/passwordreset/.*/token_length

Three means to send tokens

The tokens can be sent in a number of ways. In the default setting, only “e-mail” is enabled.
ucr search umc/self-service/passwordreset/.*/enabled

I will explain the configuration required for sending via e-mail, SMS, or any other method below:

Sending token by e-mail

Sending via e-mail requires a mail server to be configured. Its name or IP address is saved in the UCR variable umc/self-service/passwordreset/email/server. The mail server must be able to accept and forward e-mails without a password. This is usually only possible on “localhost”. The mail system must deliver outgoing e-mails directly or via a mail relay. More detailed information on the configuration of a mail relay can be found in the UCS handbook.

The message to be sent is generated from a text file. The UCR variable umc/self-service/passwordreset/email/text_file can be used to specify which is used. If you wish to modify the text, the file with the standard text should be copied elsewhere from /usr/share/pyshared/univention/management/console/modules/passwordreset/sending/email_body.txt
and then edited. The path to the new file is then entered in the UCR variable.

The following string is entered into the text before sending:
* {username}: The user wishing to reset his/her password.
* {token}: The token to be sent.
* {link}: Link to the “Password Reset” website.
* {tokenlink}: Link to the “Password Reset” website with the user name and token already entered.

UCS - Password Reset Request EN

Sending the token via SMS

Unfortunately there is no standard for SMS gateways on the Internet. The Self Service module has therefore been designed in such a way as to allow easy mounting of external programs. The following UCR variable can be configured for this purpose:
ucr search umc/self-service/passwordreset/sms

* umc/self-service/passwordreset/sms/command: The program used by the Self Service module to send an SMS, e.g.: /usr/local/sbin/send_sms. All the required data is transferred to the environment variables.
* umc/self-service/passwordreset/sms/country_code: Country code that may need to be inserted before a cellphone number, e.g.: “+49” for Germany. Please enter a number here even if your SMS software does not require this.
* umc/self-service/passwordreset/sms/password_file: A text file with the name and password for the SMS service you are using, e.g.: /etc/sip-password.txt. The file should contain exactly one line: Username:Password. Please create this file even if your SMS software does not require this.

Data is provided to the opened program in the following environment variables:
* selfservice_username: The user wishing to reset his/her password.
* selfservice_address: User’s cellphone number.
* selfservice_token: The token to be sent.
* sms_country_code: Contents of umc/self-service/passwordreset/sms/country_code.
* sms_username: The information before the colon in umc/self-service/passwordreset/sms/password_file.
* sms_password: The information after the colon in umc/self-service/passwordreset/sms/password_file.

If the specified program starts additional programs, it must be ensured that the environment variables with passwords and tokens are deleted, as environment variables are inherited by child processes.

If you experience any problems or have any tips regarding the implementation, it would be great if you could leave them as comments here in the blog or discuss them with us at Univention and other UCS users in our forum.

Self-defined sending process

In addition to e-mail and SMS, other sending methods are also supported. Just as for sending via SMS, a program is also started for the sending. The following UCS variables are available for configuration:
ucr search umc/self-service/passwordreset/external

* umc/self-service/passwordreset/external/command: The program opened for the sending, as for SMS, e.g.: “/usr/local/sbin/send_with_jabber”.
* umc/self-service/passwordreset/external/method: Identifier used internally to differentiate between modules, e.g.: “xmpp”. This cannot be “e-mail” or “mobile”.
* umc/self-service/passwordreset/external/method_label: The identifier for the methods as shown on the website, e.g.: “Jabber”.
* umc/self-service/passwordreset/external/udm_property: Name of the attribute of the user module from which the contact details should be taken, e.g.: “description”.

The e-mail module used PasswordRecoveryEmail, the SMS module PasswordRecoveryMobile. The following program can be used to display a list of all known attributes:
udm users/user

As for the SMS module, data is provided to the opened program in the following environment variables:
* selfservice_username: The user wishing to reset his/her password.
* selfservice_address: User’s cellphone number.
* selfservice_token: The token to be sent.

The security warning about the inheritance of environment variables also applies here.

Feedback wanted!

I hope that this article has been able to offer you useful information on the use of the new Self Service modules. We UCS developers are convinced that we can continue to make the use and administration of UCS domains easier with the Self Service modules. We would love to find out more about your experiences with the modules, the ways you employ the services, and of course its user acceptance.

Daniel Tröder is Open Source Software Engineer. Currently, he is intensively taking care of the further development of the UCS mail stack.