Sorry, search feature is not supported in Internet Explorer 11

Self-Service Client installation guide

Adaxes Self-Service Client provides secure access to the self-password reset system and enables users to reset their own Active Directory passwords from the Windows/macOS login and unlock screens without any intervention of administrative staff. If certain users haven't enrolled for password self-service, the Self-Service Client can periodically remind them to do so in the system notification area.

This guide provides the information you need to install, configure, and troubleshoot Adaxes Self-Service Client, and is intended for system administrators, integrators, and other IT professionals that are using the product.

Security

Adaxes Self-Service Client enables users to reset their passwords without logging in to the system by clicking on a special link on the login screen. When a user clicks the link, they get anonymous access to the Adaxes password self-service site opened in Microsoft Internet Explorer or Safari. The web browser session used to access the service is restricted, preventing insecure actions. The most noticeable restrictions applied to this session include:

  • Inability to follow links to other sites from the self-password reset site
  • Limited context menus on Windows
  • Disabled context menus on macOS
  • Disabled shortcuts
  • Disabled the Open in New Window option

Offline/offsite password self-service

Self-service password reset can be performed on a computer that is not connected to an Active Directory domain controller or has no network access at all.

Note

Currently, offline and offsite password self-service is available on Windows only.

When the Out of Office password reset and/or Offline password reset options are enabled, Adaxes Self-Service Client updates the local credentials cache on the user’s computer so the user can login immediately after resetting their password. Since updating the cache is a security-sensitive operation, it can only be performed after making sure that the password has been updated in Active Directory via Adaxes. This is done by using a request-response authentication model.

When Adaxes Self-Service Client initiates a password reset, it generates a Request Key that is passed to the Adaxes service. After the user resets their password using self-service password reset, the Adaxes service creates a Response Key that contains the hash of the password. That key can be decrypted only on the computer where the corresponding Request Key was created. The Self-Service Client decrypts the Response Key and compares the password hash contained there with the hash of the password provided to the client, thus making sure that the password is the same. If both hashes are identical, the client updates the domain credentials cache on the user’s computer.

To ensure that the process is secure, the Adaxes service generates a key pair (2048-bit RSA) and publishes the public key in Active Directory. The Self-Service Client generates a 1024-bit secret key, encrypts it using the Adaxes public key, and publishes the encrypted key in Active Directory. The key can be decrypted back only with the help of the Adaxes private key, which is known exclusively to the Adaxes service.

The Response Key generated on the server side is encrypted using the computer's secret key (HMAC SHA-512). Since the secret key is known to the Adaxes service and Self-Service Client only, the Response Key can be decrypted back only on the user's computer, and only if it was encrypted by the Adaxes service. Thus, by checking the password hash contained in the key, the client verifies that the password has already been updated in Active Directory via the Adaxes service.

Traffic encryption

During password reset, users enter security-sensitive information, such as answers to security questions and the new password. Adaxes encrypts all the security-sensitive data passed between the user's web browser and the Web interface even if you don't use SSL. On the client side (web browser), the data is encrypted using a public key that is known to everyone. The encrypted data can be decrypted back only with the help of the private key that is never passed across the network and known exclusively to the Web interface.

It means that even if you don’t enable SSL, security-sensitive information entered by users will be encrypted anyway. Nevertheless, SSL will only enhance the protection. To learn how to enable SSL, refer to the Microsoft documentation.

Installation

You can download Adaxes Self-Service Client here.

System requirements

Platform Software requirements Hardware requirements
Windows Windows Vista and higher
  • Minimum 5 MB disk space
  • Minimum 512 KB free RAM
Mac macOS 10.12 Sierra and higher
  • Minimum 5 MB disk space
  • Minimum 512 KB free RAM

Manual installation

For evaluation and testing purposes you can install Adaxes Self-Service Client on one or several computers manually. Simply launch the installation package and follow the instructions in the wizard.

Alternatively, you can install the Self-Service Client from the command line:

 Windows
msiexec /quiet /i "<path>AdaxesSelfServiceClient.msi"

where <path> is the path to the Adaxes Self-Service Client installation file (AdaxesSelfServiceClient.msi).

 macOS
sudo installer -pkg "<path>AdaxesSelfServiceClient.pkg" -target /

where <path> is the path to the Adaxes Self-Service Client installation file (AdaxesSelfServiceClient.pkg).

Note

If you have not configured Adaxes Self-Service Client prior to installation, the Reset Password link will not be available on the login screen because this option is disabled by default. With the option disabled, Adaxes Self-Service Client will not modify the login screen even if the software is installed in the system.

Bulk deployment

To deploy the Self-Service Client to a large number of computers, you can use Group Policies (GPO) on Windows and Profiles on macOS.

 Windows
  1. Download the installation package for Windows (AdaxesSelfServiceClient.msi).
  2. Copy the downloaded file to a network share accessible from all computers where you want to install the Self-Service Client.
  3. Create a new GPO or select an existing GPO to use for Adaxes Self-Service Client deployment. The GPO must be linked to all the computers, sites, domains, or Organizational Units where you want to install the Self-Service Client.
  4. Open the Computer Configuration folder under the selected GPO, expand Policies, and then expand Software Settings.
  5. Right-click the Software installation node, in the context menu select New, and click Package.
  6. Select the Self-Service Client installation file located in the shared folder and click Open.
  7. Select the Assigned deployment method and click OK.

Important

Computers with Fast Login Optimization enabled might not install the Self-Service Client during the first restart. Such computers perform a background refresh of Group Policies that makes the login faster, but some GPOs might not be applied immediately. Multiple restarts might be required before the Self-Service Client is installed.

Alternatively, you can run the following command to force the GPO refresh and restart the computer once when prompted: gpupdate /force.

Installation on x64 computers

Adaxes Self-Service Client is an x86 package. By default, the option that allows the installation of x86 packages on x64 computers is enabled for all new packages. To check whether this option is enabled for the Adaxes Self-Service Client package:

  1. Right-click the Adaxes Self-Service Client package, and in the context menu click Properties.
  2. Activate the Deployment tab, and click Advanced.
  3. In the Advanced Deployment Options dialog box, ensure the Make this 32-bit X86 application available to Win64 machines checkbox is enabled.

Self-Service Client language

You can change the texts in the Self-Service Client, effectively meaning it can be translated to any language. However, the language of the installation package is English. If on any computer linked to the GPO, the language of the operating system differs from the language of Adaxes Self-Service Client, you need to ignore the default language properties of the installation package. To do this:

  1. Right-click the Adaxes Self-Service Client package and choose Properties.
  2. Activate the Deployment tab, and click Advanced
  3. Enable the Ignore language when deploying this package checkbox.
 macOS
  1. Download the installation package for macOS (AdaxesSelfServiceClient.pkg).

Note

If Profile Manager hasn't been used in your organization before, you need to configure it and enroll your macOS computers for MDM (mobile device management) before proceeding to the next step.

  1. Open the Profile manager administration portal.
  2. In the left navigation menu, click Apps.
  3. Add a new enterprise app, and select the AdaxesSelfServiceClient.pkg file.
  4. Click Device groups and select the group of devices on which you want to deploy the client.
  5. Click the Settings cog at the bottom, and in the context menu select Push apps.
  6. Select the Self-Service Password Reset app and click OK.

Uninstallation

You can uninstall Adaxes Self-Service Client manually if installed on one or several computers. To uninstall Adaxes Self-Service Client from multiple computers in bulk:

 Windows
  1. Select the GPO used for the Self-Service Client deployment, and launch Group Policy Object Editor.
  2. Open the Computer Configuration folder under the selected GPO, expand Policies, and then expand Software Settings.
  3. Click the Software installation node.
  4. Right-click the Adaxes Self-Service Client package, and in the context menu select All Tasks, then click Remove.
  5. In the Remove Software dialog box, select the Immediately uninstall the software from users and computers option and click OK.
 macOS
  1. Open the Profile manager administration portal.
  2. Click Device groups and select the group of devices from which you want to remove the client.
  3. Click the Settings cog at the bottom, and in the context menu select Remove apps.
  4. Select the Self-Service Password Reset app and click OK.

Configuration

You can configure global and local settings for the Self-Service Client. Global settings affect all computers where the client is installed. Local settings are set via Group Policy Objects (GPO) on Windows or Profiles on macOS and apply only to the computers within their scope. In case of any conflicts, local settings have higher priority.

Global settings

To configure the global settings:

  1. Launch the Adaxes Administration console.
  2. In the Console Tree, expand the Adaxes service node (the icon represents service nodes).
  3. Expand Configuration / Password Self-Service and select OS Integration.
  4. In the Result Pane on the right, configure the settings.

Web interface for password self-service

To reset passwords, the Self-Service Client uses Adaxes Web interface. The Web interface which is used depends on the specified Web interface URL. You can specify an existing Web interface or create a new Web interface exclusively for self-service password reset. Note, that the Web interface must have the Password self-service component enabled.

 How to enable the password self-service component {.black}
  1. Open the Web interface configurator.
  2. In the top left corner, select the Web Interface you want to customize.
  3. In the left navigation menu, click Components.
  4. Enable the Password Self-Service checkbox.
  5. Save the changes.

Note

By default, the Password self-service component is enabled in the Self-Service Web interface only.

Out of office and offline password reset

For users to be able to reset passwords from out of office, the specified Web interface URL must be available from the Internet. For details, see the Exposing Web interface to the Internet section of Adaxes installation guide.

It is recommended to create a separate Web interface for this purpose and deny all users to sign in to it. This way, it will only be possible to self-reset passwords through that Web interface.

 How to deny access to a Web interface for all users {.black}
  1. Open the Web interface configurator.
  2. In the top left corner, select the Web Interface you want to customize.
  3. In the left navigation menu, click Access Control.
  4. In the User Access section, select the Deny access for all users option.
  5. Save the changes.

Multiple Adaxes configurations

If a domain is managed by multiple Adaxes services from different configuration sets, they can have different settings for Adaxes Self-Service Client. To avoid ambiguity, you need to specify which Adaxes service has higher priority. To do so, click Advanced and enter the priority of the current settings.

Local settings

By default, Adaxes Self-Service Client uses the global settings that are configured in the Administration console and applied to all computers managed by Adaxes. You can override these settings for specific computers using Group Policies on Windows and Profiles on macOS.

 Windows

Local settings of the Self-Service Client on Windows are configured using administrative templates.

  1. Download and extract the administrative template (AdaxesSelfServiceClientAdminTemplate.zip) for Adaxes Self-Service Client.

ADM or ADMX

The downloaded ZIP archive will contain two templates: ADM and ADMX. If your Active Directory is based on Windows Server 2008 or later, it is recommended to use the ADMX template. The ADM template can still be used, but the ADMX format offers several advantages over legacy ADM files, such as a central storage point where you can manage all your administrative templates.

  1. Create a new GPO or select an existing GPO that is linked to the computers, sites, domains, or Organizational Units where you want to override the default settings of Adaxes Self-Service Client.
  2. Install the administrative template and configure the settings.

ADMX template

  1. If you have a central store for GPO templates configured in your environment, copy the full content of the ADMX folder from the downloaded archive (including the language directories, such as en-US and de-DE) to the \\SYSVOL\\Policies\PolicyDefinitions folder. If you don't have a central store for GPOs, copy the extracted files to %systemroot%\PolicyDefinitions folder on the local computer.
  2. In the Group Policy Management Editor, expand Computer Configuration / Policies / Administrative Templates folder under the selected GPO.
  3. Select the Adaxes Self-Service Client folder (under the Administrative Template folder).
  4. Configure the settings.

ADM template

  1. In the Group Policy Management Editor, expand the Computer Configuration / Policies folder under the selected GPO.
  2. Right-click the Administrative Templates node, and in the context menu select Add/Remove Templates.
  3. In the dialog that opens, click Add.
  4. Select the downloaded AdaxesSelfServiceClient.adm file, click Open, and then click Close.
  5. Select the added Adaxes Self-Service Client folder (under the Administrative Template folder).
  6. Configure the settings.
 macOS

Local settings of the Self-Service Client on macOS are configured using configuration profiles.

  1. Download the configuration profile (com.softerra.adaxes.selfservice.plist) for Adaxes Self-Service Client.
  2. Open the Profile manager administration portal.
  3. Click Device groups and select the device group to apply the settings to.
  4. Click Settings.
  5. Under Settings for <groupName>, click Edit.
  6. In the left navigation menu, click Custom Settings.
  7. Click Configure.
  8. Click Upload file and select the com.softerra.adaxes.selfservice.plist file.
  9. Configure the values for the following keys:
Key Description
AllowLoginScreenPasswordReset Set to true to allow users to reset their passwords from the computer login screen.
WebInterfaceURL The URL of Adaxes Web interface that the Self-Service Client will use for resetting passwords.
ResetPasswordButton.OptionalText The additional text for the Reset Password button on the login screen.
ResetPasswordButton.Text The text for the Reset Password button on the login screen.
ResetPasswordButton.Position The position to display the Reset Password button on the login screen.
ResetPasswordDialog.Title The title of the Reset password dialog.
ResetPasswordDialog.LoadingText The text user will see when the Reset password dialog is loading.
EnrollReminder.Enable Set to true to display a balloon in the system notification area to remind users to enroll for password self-service.
EnrollReminder.Title The title of the enrollment reminder balloon.
EnrollReminder.Text The text of the enrollment reminder balloon.
EnrollReminder.Url The URL of the Web interface Adaxes will use to obtain the enrollment status.
EnrollReminder.Proxy The proxy server for obtaining the enrollment status from the Web interface.
EnrollReminder.IntervalMins The interval that indicates how often (in minutes) the reminder to enroll for password self-service will appear.
EnrollReminder.MenuEnrollText The text of the Enroll item in the notification context menu.
EnrollReminder.MenuExitText The text of the Exit item in the notification context menu.
  1. Click OK.
  2. Click Save.

Automated bulk enrollment

If the Security Questions and Answers option is enabled in your password self-service policy, users need to enroll for password self-service and specify answers for security questions.

Adaxes enables you to enroll users automatically with predefined answers. If your organization has an HR or some other database with user-specific data, such as social security numbers, ID numbers, etc. you can preload the existing data as answers for security questions in bulk. For this purpose, you need to use the following PowerShell cmdlets:

Examples

Enroll user:

$question = "What are the last 4 digits of your credit card?"
$answer = "1234"
New-AdmPasswordSelfServiceEnrollment j.smith -QuestionsAndAnswers @{$question = $answer} `
    -AdaxesService localhost

Disenroll user:

Remove-AdmPasswordSelfServiceEnrollment j.smith -AdaxesService localhost

Note

These cmdlets are included in the Adaxes PowerShell module that comes with the Adaxes service. How to install Adaxes PowerShell module.

Scheduled enrollment

The information in the data source used for automated enrollment can be changed or updated. To keep answers for security questions updated as well, you can automate the synchronization with the data source by enabling the built-in Scheduled Task named Self-Password Reset Enroller. This task periodically runs a PowerShell script for automated enrollment on a predefined schedule.

To activate the Self-Password Reset Enroller Scheduled Task, you need to enable it in Adaxes Administration Console and customize the script for working with your data source.

For more details on how to automate the enrollment process, see Autoenroll Users for Self-Password Reset.

Troubleshooting

 If the Reset password link is not displayed on the login screen
  1. Make sure Adaxes Self-Service Client is installed on the computer in question.
  2. Make sure that the Allow users to reset their passwords from the computer login screen option is enabled in Adaxes Administration Console. For details, see the Configuration section.
  3. Make sure that the Allow users to reset their passwords from the computer login screen option is not disabled for the computer in question via local settings (GPO/Profiles).
  4. Send debug information to the Adaxes support team to help them troubleshoot the issue:

FileVault

After powering on or restarting a Mac with FileVault installed, the Reset password button will not be displayed on the login screen, as no apps can be launched before FileVault unlocks the disk. Once the disk is unlocked, the Self-Service Client will work normally.

In this case, the user can do the following:

  1. Log in to their Mac as a different user whose password they know.
  2. Log out or switch user.
  3. Use the Reset password button that will appear on the login screen.
 If the enrollment notification balloon doesn't show up
  1. Make sure Adaxes Self-Service Client is installed on the computer in question.
  2. Make sure the Display a balloon in the system notification area to remind users to enroll for password self-service option is enabled in Adaxes Administration Console.
  3. Make sure that the enrollment notification is not disabled for the computer in question via local settings (GPO/Profiles).
  4. Make sure that notifications from the Self-Service Client are not disabled in the operating system settings.
  5. Make sure a password self-service policy is assigned to the currently logged in user.
  6. Make sure the currently logged in user is not already enrolled for password self-service.
  7. Send debug information to the Adaxes support team to help them troubleshoot the issue:
 If you have a problem with the GPO-based installation on Windows
  1. Make sure the computer in question is linked to the GPO used for Adaxes Self Service Client deployment.
  2. Execute the gpupdate /force command on the computer in question and restart it to force the group policy refresh.
  3. Check errors in the System Event Log:
    • Launch Event Viewer.
    • In the console tree of the Event Viewer open the Windows Logs folder and select Application.
    • Check error events in the right pane.
  4. Send debug information to the Adaxes support team to help them troubleshoot the issue:
 If you have a problem with the Profile-based installation on macOS
  1. Make sure the computer in question is enrolled for mobile device management (MDM) in Profile Manager or other MDM solution you are using.
  2. Make sure that the profile with the Self-Service Client settings has been pushed to the computer in question.
  3. Check errors in the Console:
    • Launch the Console app.
    • Push the Self-Service Client to the computer in question and check the events in the right pane.
  4. Send debug information to the Adaxes support team to help them troubleshoot the issue:
 If you have a problem with applying configuration profiles on macOS
  1. Make sure that you are applying the configuration profile to a device or a device group, not a user or a user group.
  2. Make sure you are applying the settings to a computer different from the one where macOS Server is running.
  3. Send debug information to the Adaxes support team to help them troubleshoot the issue:
 If the login screen is broken

Windows

Send debug information to the Adaxes support team to help them troubleshoot the issue:

Mac

  1. If the Reset password button is displayed over another UI element, change the button position:
    • Launch the Adaxes Administration console.
    • In the Console Tree, expand the Adaxes service node (the icon represents service nodes).
    • Expand Configuration / Password Self-Service and select OS Integration.
    • In the Result Pane on the right, click More options.
    • Change the position of the button.
    • Alternatively, change the button position via local settings. Change the value of the ResetPasswordButton.Position key to move the button.
  2. Send debug information to the Adaxes support team to help them troubleshoot the issue:
 If you have a problem with the Self-Service Client on multiple computers

In case of an emergency situation, you can disable Adaxes Self-Service Client on all computers in all domains managed Adaxes. To disable the client, deselect the following options in Adaxes Administration Console:

  • Allow users to reset their passwords from the computer login screen
  • Display a balloon in the system notification area to remind users to enroll for password self-service

For details, see Global settings.


If the problem occurred on Windows computers where the Self-Service Client is configured via GPO, you need to select the Disabled radio button in the following policy settings:

  • Enable users to reset passwords from the Winlogon screen.
  • Display a balloon in the system tray to remind users to enroll for password self-service

If the problem occured on Mac computers where the Self-Service Client is configured via Profiles, you need to change the following settings to false in the applied configuration profile:

  • AllowLoginScreenPasswordReset
  • EnrollReminder.Enable

For details, see Local settings.

How to enable debug logging

To enable/disable debug logging for Adaxes Self-Service Client on a specific computer:

 On Windows {id=debug-windows}
  1. Launch Registry Editor.

  2. Locate the following registry key: [HKEY_LOCAL_MACHINE\Software\Softerra\Adaxes Self-Service Client].

  3. Right-click the LogLevel entry and select Modify.

    Note

    Create the LogLevel entry if it doesn't exist.

  4. In the Value data box, type 2 to enable debug logging or 0 to disable it, and click OK.

All events will be logged to the adaxeswinlogonextlog.txt file, located in the System32 subfolder of the Windows folder.

 On macOS {id=debug-macOS}
  1. Launch Terminal.
  2. To enable debug logging, execute the following command.
sudo defaults write /Library/Preferences/com.softerra.adaxes.selfservice.plist LogLevel 2
  1. To disable debug logging, execute the following command.
sudo defaults write /Library/Preferences/com.softerra.adaxes.selfservice.plist LogLevel 0

The errors generated by the Adaxes Self-Service Client will be logged to the /tmp/adaxesselfservice.log file.

Tip

Since debug logging is quite intensive, the log file can grow very quickly. Permanent logging of debug information consumes resources and affects performance. Therefore, it is recommended to disable logging when it is no longer needed.

See also