General information

Password filter is an external standalone module for OpenIAM that runs on Active Directory and captures the event of the password update of the AD users. It captures the user’s identity who changed the password and the new password value. So, Password filter can do following:

1. Check updated password against password policies that are configured in OpenIAM. Depending on evaluation, password change could be either allowed or blocked. If password is not allowed - Windows would display standard message that password does not fit password policy.
2. Notify OpenIAM about the new user password. This password could be used for other linked systems as well. For example, when you change password in AD, if your Linux box and Oracle database are also linked to OpenIAM - password of your user inside that systems could also be changed.

Availability

As we mentioned above, Password Filter could be used for validating new passwords and sending notifications about updated password to OpenIAM:

• First operation - validating password should be performed in real-time. Therefore, there is a setting inside Password Filter that defines what should be done if OpenIAM is not available or some communication error occurred - either allow or reject user password.

• Second operation - updated password notification is less critical. And in case of OpenIAM is not available at the moment, Password Filter contains backup mechanism that will be periodically checking for OpenIAM availability. And as soon as OpenIAM appears available - performs sync. However, for your convenience, there is still a setting that allows you either to use this backup service or drop password sync.

Communication with OpenIAM

• Password Filters that have versions lower than 3.5 run SOAP sync
• Password Filters between versions 3.5 and 4.2 can use both SOAP and REST
• Password Filters that have versions 4.3 and upper use only REST sync

OpenIAM recommends using REST sync in all cases, where it is available, as well as it relies on enhanced features of OpenIAM while SOAP is deprecated.

Installing Password Filter

To run, the Password Filter need to fit requirements:

• Windows Server 2008R2 and above versions
• Installation on all domain controllers inside your environment (or at least DC with PDC emulator role)

Password Filter relies on native Windows components and does not require any external dependencies. Below is the main installation window of the Password Filter:

As you see, configuration is very straightforward - you just need to insert correct OpenIAM hostname, set username and password.

Default installation of OpenIAM uses 'sysadmin' and 'passwd00' passwords. For obvious reasons, in production those username and passwords should be changed. Those settings could be changed in Password Filter configuration as well.

If you set 'Debug messages' checked - you will be able to see very verbose log records inside your Windows Event viewer. If not - you will be able to see only brief important messages.

Finalizing the installation

Password filter works close to Windows OS and it registers itself inside the OS during the boot time. So after the installation is completed – the DC with the fresh installation needs to be restarted. OpenIAM installer will suggest to restart as soon as the installation is complete.

Uninstalling Password Filter

Password filter can be uninstalled as usual Windows application using the control panel. Additionally, you will be able to see what exact version of the PasswordFilter is installed on your Domain Controller.

After the uninstallation process you will be asked to reboot the DC as well. It needs to be done as well as the Password filter registration needs to be removed from the operating system.

Uninstalling version 3.4 and below

If you have Password Filter with version is 3.4 and below (issued before 2015) and you would like to upgrade it to newer version, there are number of steps that you need to do manually:

1. Uninstall Password filter (but do not restart the server)
2. Delete OpenIAMPassFilt.dll and OpenIAMPassFiltService.exe if they exist in system32 folder
3. Go to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SharedDLLs and delete records: 'C:\Windows\system32\OpenIAMPassFilt.dll' and 'C:\Windows\system32\OpenIAMPassFilt.dll'
4. Restart OS

Upgrading Password Filter

For updating the password filter you need to:

1. Uninstall the previous version of the Password filter
2. Install the new version of the password filter

Installation and uninstalling operations are described above. After the uninstallation process system needs to be rebooted for unregistering and will need to be rebooted after the installation as well – for registering the new password filter.

Configuring Password Filter

It is possible to change parameters of the password filter on-the-fly, without the need of the reinstallation or restarting.

To change parameters, you need to go to the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\OpenIAM\Password Filter

There you will see the values that can be applied to the password filter:

• Cache - should not be changed manually
• Debug - if set to 1, Password Filter would generate very verbose log messages in system EventViewer
• IsActive - use this flag to turn Password filter off without uninstalling.
• ManagedSystemID - identifier of the managed system inside OpenIAM that should update changed user password. In most use cases it is 0
• OnUnknownResponse - applies only for notification mode. Values are 'Keep' or 'Drop'. If 'Keep' is set and Password filter received unknown response, backup service will be started to update OpenIAM later.
• OnUnknownValidationResponse - applies only for password validation mode, when Password filter sends updated user password for OpenIAM approval. This parameter defines what to do if some unknown response or communication issue occurs. Default value is 'Allow', which allows password change, however, if set to 'Drop' - Password Filter will disable password change operation and user password would remain unchanged.
• OpenIAM login - service account login. This account should have sufficient privileges inside OpenIAM to be able to change password of the user.
• OpenIAM password - service account password
• RestrictionPathFile - this file could be used to restrict password update events only from certain AD location. Could not be used without Active Directory environment
• ServiceBaseUrl - Url of OpenIAM endpoint that is responsible for changing passwords. Usually, this parameter is never changed
• SkipHttpsCertValidation - used for scenarios when OpenIAM runs https using self-signed certificates (for example during POC)
• Timer - defines interval in seconds of password sync re-try, that us used by backup service
• UseRestrictionFile - activates 'Restriction file' feature
• ValidateOIAMPasswdPolicy - if set to 1, Password filter will ask OpenIAM to validate new password against policy. In this case the new password would be allowed only in case if it complies OpenIAM policy. If set to 0 - policy validation would be skipped and password would be approved at once.

Working with encrypted values

As you see on above screenshot, Password Filter stores some configuration values in encrypted format. Encryption is based on DPAPI, a native Windows technology that guarantees that the value, encrypted on this machine could be decrypted only on the same machine.

Password filter protects username and password parameters and expects that those parameters can go encrypted (however will handle them properly as unencrypted as well). If you would like to replace username or password with new, but encrypted value, you should run from command-line:

OIAMCryptHelper.exe

Above executable starts being available after Password Filter installation. Having run above, you would get a window that would allow you to input cleartext string and get encrypted value that could be copied to registry.

Windows Event Viewer and EventID descriptions

PasswordFilter writes event logs to Windows Event Viewer. Working in normal (not debug) mode will give minimal log output and will write notifications only about the most important events. Setting PasswordFilter to debug mode will give plenty of informative messages about each step, that PasswordFilter is doing.

Blow you can find EventID’s that point to certain event types.

Restriction file

This section could be applied only to Active Directory environment. Does not work for standalone Windows servers.

It is possible to exclude some locations from sync, or include just some of them. To allow this feature you should set 'UseRestrictionFile' parameter to 1 and edit restriction file (could be set by 'RestrictionPathFile' parameter) using syntax below. This works for particular and all sub-locations (like OU etc.) in Active Directory.

If you want to exclude some locations from the sync – you need to put predicate #! For example, you need to disable syncs from security OU and all child locations – you need to put in the restriction file line, starting with #!

#!OU=security,DC=test,DC=local

If you need to allow sync only from this OU you need to specify it without #! - like:

OU=security,DC=test,DC=local

All restriction rules are being processed at first. If location (or sub-location) matches one of restrictions – sync will be disabled. Next PasswordFilter looks for allowed locations. If no directly allowed locations are specified – sync is getting permitted from any location. If there is at least one location – sync will be permitted only in case user is located inside one of those locations or sub-locations.

If restriction file does not exist – all syncs will be allowed.

Supporting multiple OpenIAM instances notifications

PasswordFilter can send updates to many OpenIAM instances at once. Configurations for updates of different instances are fully independent.

To add additional configuration for update you need to create a sub-key at

HKEY_LOCAL_MACHINE\SOFTWARE\OpenIAM\Password Filter

The sub-key should have the same sets of values. And in this case HKEY_LOCAL_MACHINE\SOFTWARE\OpenIAM\Password Filter will contain the main configuration and all subkeys will contain additional ones.

Troubleshooting the Password filter

If Password filter seems not to sync the passwords, please do the following steps:

1. Go to registry and set 'Debug' parameter to 1 (was described in aboce sections)
2. Go to Windows Event log -> Windows Log -> Application
3. Try to change some test user password
4. Update the list of log records. You should be able to find one or more records generated by ‘OpenIAM Password Filter’ or ‘OpenIAMPassFiltService’. In 'Debug' mode those messages are very verbose, so it is very probable that you would be able to read issue inside logs

If no events were found – that should mean that OpenIAM is not working. However, there are some steps that could help to troubleshoot this.

1. Verify that Password filter is registered under: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\LSA , the value is ‘Notification Packages’
2. From the command line run ‘msinfo32’ and in the window that appeared validate the values inside 'System' -> 'Software environment' -> 'Loaded modules'. If OpenIAMPassFilt doesn`t exist on the right panel, it means that it is not registered in system correctly.

Common http errors

Sometimes the cause of issues could be in network communication. By enabling debug mode and examining event log you may find winhttp errors. Most common errors are:

• WinHttpSendRequest (12007) - The server name cannot be resolved. Please check if you specified OpenIAM hostname correctly
• WinHttpSendRequest (12002) - request timeout. Please see if port and endpoint are active on OpenIAM side. Full list of winhttp error messages could be found here: https://docs.microsoft.com/en-us/windows/win32/winhttp/error-messages
• WinHttpSendRequest (12175) - this appears to be issue connected to establishing connection using TLS. Probably, your system is quite old and has latest updates missing. You can either update your OS or use this article by Microsoft https://support.microsoft.com/en-us/topic/update-to-enable-tls-1-1-and-tls-1-2-as-default-secure-protocols-in-winhttp-in-windows-c4bd73d2-31d7-761e-0178-11268bb10392#easy and download quick fix tool. Method above would allow you to fix issue with Password Filter side. For Backup service you should make sure that you run PasswordFilter version not less than 4.4.0