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 password self-reset site

  • Limited context menus on Windows

  • Disabled context menus on macOS

  • Disabled shortcuts

  • Disabled the Open in New Window option

Offline / out of office password self-service

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

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 log in 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.

FileVault on macOS

If FileVault full-disk encryption is enabled on a Mac, the self-service client will not be launched until FileVault unlocks the disk. This means the Reset password button will not be displayed right after such a Mac is powered on or rebooted. To unlock the disk, the user should log in with another account whose credentials they know (e.g. local administrator account). After the disk is unlocked, the user can sign out from that account and reset their password from the login screen as normal.

After resetting the account password, the FileVault password will remain as it was. This means if the Mac is rebooted again, the user will not be able to unlock the disk with their new password. Adaxes self-service client will offer the user to synchronize the new password to FileVault and complete the password reset. The user will need to enter the credentials of a SecureToken administrator (e.g. local administrator account), as only such accounts have the permissions to update FileVault data. The notification that prompts the user to complete the password reset can be customized.

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).

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 any MDM solution of your choice on macOS.

 Windows (GPO) {id=deploy-win}

  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.

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 are usually required before the self-service client is installed.

You can run the following command to force the GPO refresh and restart the computer only once: 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, make sure 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 {id=deploy-mac}

  1. Download the installation package for macOS (AdaxesSelfServiceClient.pkg).

  2. Use your MDM solution to deploy the self-service client. For detailed instructions, refer to the documentation of that MDM solution.

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 (GPO)

  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

Use your MDM solution to uninstall the self-service client. Refer to the documentation of your MDM solution for detailed instructions.

Configuration

You can configure global and local settings for the self-service client. Global settings are set in the Administration console and 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. Any Web interface configuration can be used for this purpose. The only requirement is that the Web interface must have the Password self-service component enabled. By default, the component is enabled in the Self-Service Web interface only.

 How to enable the password self-service component

  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.

Out of office and offline password reset

For users to be able to reset passwords from out of office, the specified Web interface must be available from the outside of your network. For details on how to expose Web interface to the Internet, 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, only the password self-service feature will be available in that Web interface.

 How to deny access to a Web interface for all users

  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 {id=local-settings-win}

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.

  2. 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.

  3. 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 Templates 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 Templates folder).
  6. Configure the settings.
 macOS {id=local-settings-macOS}

Local settings of the self-service client on macOS are configured using configuration profiles. You can use any MDM solution of your choice to push the settings to your Macs.

Download the configuration profile (com.softerra.adaxes.selfservice.plist) for Adaxes self-service client. The plist file contains all the possible self-service client settings and their default values.

It is not recommended to push the entire configuration profile as is, because it will override ALL global settings. Instead, use the appropriate payload for your configuration needs and remove the settings you don't want to change from the plist file.

The settings can be divided into two categories – texts and configuration settings:

Texts

Settings from this category let you change the default texts of the application menus, buttons, and labels e.g. if you need to translate the self-service client to another language. For instance:

<key>ResetPasswordButton.OptionalText</key>
<string>Haben Sie Ihr Kennwort vergessen?</string>

Configuration

Settings from this category let you configure the self-service client features. For instance:

<key>OfflinePasswordReset.Enabled</key>
<true/>
 Settings
Key Description
AllowLoginScreenPasswordReset Set to true to allow users to reset their passwords from the Mac login screen or set to false to deny it.
WebInterfaceURL Specify the URL of Adaxes Web interface that the self-service client will use for resetting passwords e.g. http://host.example.com/Adaxes/SelfService
ResetPasswordButton.Position Specify the position to display the Reset Password button on the login screen. Possible values: top-left, top-right, bottom-left, bottom-right.
UpdateCredentialsCache.Enabled Set to true to allow users to reset their passwords when out of office (not connected to company network) or set to false to deny it.
OfflinePasswordReset.Enabled Set to true to allow users to reset their passwords when the Mac is not connected to the Internet or set to false to deny it.
EnrollReminder.Enable Set to true to display an alert in the Notification Center that reminds users to enroll for password self-service.
EnrollReminder.IntervalMins Set the interval that indicates how often (in minutes) the reminder to enroll for password self-service will appear. Use 0 to display once when the system starts.
EnrollReminder.Url Specify the URL of the Web interface Adaxes will use to obtain the enrollment status e.g. http://host.example.com/Adaxes/SelfService.
EnrollReminder.Proxy Specify the proxy server for obtaining the enrollment status from the Web interface or leave blank.
FileVaultSyncPrompt.Enabled Set to true to display an alert in the Notification Center that prompts users to sync their new password to FileVault.
FileVaultSyncPrompt.RemindLaterIntervalMins Set the interval that indicates how often (in minutes) the reminder to sync the password to FileVault will appear. Use 0 to display once when the system starts.

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

These cmdlets are included in the Adaxes PowerShell module. 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 modify 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 enrollment notification balloon doesn't show up {id=no-notification}

  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. For details, see global settings in the Configuration section.

  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 bulk installation of the self-service client {id=bulk-install-issues}

Windows

  1. Make sure the computer in question is linked to the GPO used for Adaxes Self Service Client deployment.

  2. Make sure that the Make this 32-bit X86 application available to Win64 machines checkbox is enabled in the installation package properties.

     How

    • Edit the GPO used for Adaxes self-service client deployment.

    • Open the Computer Configuration folder under the selected GPO, expand Policies, and then expand Software Settings.

    • Click the Software installation node.

    • In the Result Pane on the right, right-click the Adaxes self-service client package, and in the context menu click Properties.

    • Activate the Deployment tab, and click Advanced.

    • In the Advanced Deployment Options dialog box, make sure the Make this 32-bit X86 application available to Win64 machines checkbox is enabled.

  3. Execute the gpupdate /force command on the computer in question and restart it to force the group policy refresh.

  4. 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.

    • If you need assistance with troubleshooting, send the error events related to the self-service client to support@adaxes.com.

macOS

  1. Make sure the computer in question is enrolled for mobile device management (MDM) in your MDM solution.

  2. Make sure that the self-service client has been pushed to the computer in question.

  3. Check errors in the Console:

    • Launch the Console app.

    • Start the logging stream.

    • Push the self-service client to the computer in question and check the errors in the Console app.

    • If you need assistance with troubleshooting, send the log records related to the self-service client to support@adaxes.com.

 If you have a problem with applying local settings (GPO/Profiles) {id=local-settings-issues}

Windows

  1. Make sure the computer in question is linked to the GPO where the self-service client local settings are configured.

  2. Execute the gpupdate /force command on the computer in question to force the group policy refresh.

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

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:

    • Enable debug logging to track all the Adaxes self-service client actions. How to enable debug logging.

    • Attempt to apply the configuration profile to log the issue.

    • Sign out from the system.

    • Sign back in.

    • Send the log file to support@adaxes.com.

 If the login screen is broken {id=login-screen-broken}

Windows

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

  • Enable debug logging to track all the Adaxes self-service client actions. How to enable debug logging.

  • Sign out or switch user to get to the login screen.

  • Take a picture of the login screen.

  • Send the log file and the picture to support@adaxes.com.

macOS

  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:

    • Enable debug logging to track all the Adaxes self-service client actions. How to enable debug logging.

    • Sign out or switch user to get to the login screen.

    • Take a picture of the login screen.

    • Send the log file and the picture to support@adaxes.com.

How do I

 Enable debug logging {id=enableDebugLogging}

To enable/disable debug logging for Adaxes self-service client on a specific computer:

 On Windows {id=debug-win}

  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.

    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-mac}

  1. Launch Terminal.

  2. To enable debug logging, execute the following command.

    sudo defaults write /Library/Preferences/com.softerra.adaxes.selfservice.plist LogLevel 2

  3. 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.

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.

 View local self-service client settings {id=view-local-settings}

To view local self-service client settings on a specific computer:

 On Windows {id=view-local-win}

  1. Launch Registry Editor.

  2. Locate the following registry key: [HKEY_LOCAL_MACHINE\Software\Softerra\Adaxes Self-Service Client]. Each setting is represented by a data entry within this key.

 On macOS {id=view-local-mac}

  1. Launch Terminal.

  2. Execute the following command.

    sudo defaults read ~/Library/Preferences/com.softerra.adaxes.selfservice.plist
 Disable self-service client on all computers {id=disable-ssc-everywhere}

In case of an emergency, you can completely disable Adaxes self-service client on all computers in all domains managed by Adaxes. To do this, you first need to disable the client in the global settings.

 Disable in 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, clear the following checkboxes:

    • 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

  5. Save the settings.

If you have configured local self-service client settings for specific computers and you are having an issue with the client on those computers, you also need to disable the client in the local settings.

 Disable in local settings on Windows

  1. Edit the GPO where local settings for Adaxes self-service client are configured.

  2. In the Group Policy Management Editor, expand Computer Configuration / Policies / Administrative Templates folder.

  3. Select the Adaxes Self-Service Client folder (under the Administrative Templates folder).

  4. In the Result Pane on the right, right click the Enable users to reset passwords from the Winlogon screen setting, and in the context menu select Edit.

  5. Toggle the radio button to Disabled, and click OK.

  6. Right click the Display a balloon in the system tray to remind users to enroll for Password Self-Service setting, and in the context menu select Edit.

  7. Toggle the radio button to Disabled, and click OK.

To apply the new settings, perform one of the following actions on all computers within the scope of the GPO:

  • Restart the computer.

  • Run the gpupdate /force command.

 Disable in local settings on Mac

Set the following keys in the configuration profile payload to false and push the changes to all devices via your MDM solution.

  • AllowLoginScreenPasswordReset
  • EnrollReminder.Enable

Here's how a sample payload would look like:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC 
    "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<!-- Allow users to reset their passwords 
        from the computer login screen -->
	<key>AllowLoginScreenPasswordReset</key>
	<false/>

	<!-- Display an alert in the Notification Center 
        to remind users to enroll for Password Self-Service -->
	<key>EnrollReminder.Enable</key>
	<false/>
</dict>
</plist>

Adaxes self-service client caches its settings on each computer where it is installed. When you change global or local settings, the self-service client can update the cached settings only if the computer is connected to a domain controller. If the computer is not connected to AD, it won't be able to receive the new settings.

Security Installation Uninstallation Configuration Automated bulk enrollement Scheduled enrollment Troubleshooting How do I
© Softerra 2022. All rights reserved.
Contact us