Differences

This shows you the differences between two versions of the page.

--- devel:documentation:uniform_password:password_filter_dll [2021/08/09 10:45]
husniko [Configuration]
+++ devel:documentation:uniform_password:password_filter_dll [2021/08/09 10:53] (current)
husniko
@@ Line 31: / Line 31: @@
 **PasswordFilter** (aka **Validate**) method
-Validate method is one of PF pillars. Any time a password change happens, it is invoked and queries IdM whether the new password for given AD account meets password policies of all related systems. The response from IdM is transformed into **PF result** which may be: **TRUE** ~ change **allowed** or **FALSE** ~ change **rejected**. Those values are immediately returned from Validate method. The third option, **TRY\_AGAIN**, is to make another query attempt. **PF result** is based on returned HTTP status code and IdM specific response if present. The table below shows possible results.
+Validate method is one of PF pillars. Any time a password change happens, it is invoked and queries IdM whether the new password for given AD account meets password policies of all related systems. The response from IdM is transformed into **PF result** which may be: **TRUE** ~ change **allowed** or **FALSE** ~ change **rejected**. Those values are immediately returned from Validate method. The third option, **TRY_AGAIN**, is to make another query attempt. **PF result** is based on returned HTTP status code and IdM specific response if present. The table below shows possible results.
 ** Transformation of an IdM response to the PF result**
 ^  HTTP status  ^has IdM result ^  PF result  ^Note ^
 |  200        | n/a                                     |  TRUE       | Password passed policy validation |
-|  400        | PASSWORD\_DOES\_NOT\_MEET\_POLICY    |  FALSE      | Password did not pass policy validation |
+|  400        | PASSWORD_DOES_NOT_MEET_POLICY    |  FALSE      | Password did not pass policy validation |
 |  :::        | n/a                                  |  FALSE      | None or unknown IdM result |
-|  404        | PASSWORD\_FILTER\_SYSTEM\_NOT\_FOUND,  PASSWORD\_FILTER\_IDENTITY\_NOT\_FOUND,  PASSWORD\_FILTER\_IDENTITY\_NOT\_FOUND      |  TRUE  | Identity is not managed by IdM or PF is not set to be used |
+|  404        | PASSWORD_FILTER_SYSTEM_NOT_FOUND,  PASSWORD_FILTER_IDENTITY_NOT_FOUND,  PASSWORD_FILTER_IDENTITY_NOT_FOUND      |  TRUE  | Identity is not managed by IdM or PF is not set to be used |
 |  :::        | n/a                                  |  FALSE      | None or unknown IdM result |
 |  423        | n/a                                     |  TRUE      | PF is disabled in IdM and must not block password change|
-|  408        | n/a                                     |  TRY\_AGAIN  | Client time out. A new attempt will be done |
+|  408        | n/a                                     |  TRY_AGAIN  | Client time out. A new attempt will be done |
-|  504        | n/a                                     |  TRY\_AGAIN  | Server/proxy time out. A new attempt will be done |
+|  504        | n/a                                     |  TRY_AGAIN  | Server/proxy time out. A new attempt will be done |
 |  others     | n/a                                     |  FALSE      | All other results |
@@ Line 53: / Line 53: @@
 ==== Configuration ====
-Password filter (PF) is controlled by configuration file. By default the configuration file is searched at the location ''c:\CzechIdM\PasswordFilter\etc\PasswordFilterConfig.cfg''. The file location can be specified by setting of the environmental variable ''BCV\_PWF\_CONFIG\_FILE\_PATH'' with the full path to the file. When the configuration file is read it is first searched at the location specified by ''BCV\_PWF\_CONFIG\_FILE\_PATH''. If variable not set or the path to the file does not exist then the default location is used. Configuration file uses JSON structure and has to be in UTF-8 character encoding format without BOM. It is a mandatory part of password filter library and if not found or an error occurs during its parsing, the password filter is not able to work properly and switches to the **inactive state**. It means that it acts as no password filter was installed i.e. it allows all password changes without policy validation and performs no IdM notification. All configuration properties are mandatory and incomplete configuration file is invalid. Configuration file is read during PF initialization phase and then checked every 3 seconds whether it has changed. If so, it is reloaded. If the configuration file is missing or has wrong name etc., the monitoring system stops working. The only current solution is to provide config file and restart AD. Configuration file has to contain following items:
+Password filter (PF) is controlled by configuration file. By default the configuration file is searched at the location ''c:\CzechIdM\PasswordFilter\etc\PasswordFilterConfig.cfg''. The file location can be specified by setting of the environmental variable ''BCV_PWF_CONFIG_FILE_PATH'' with the full path to the file. When the configuration file is read it is first searched at the location specified by ''BCV_PWF_CONFIG_FILE_PATH''. If variable not set or the path to the file does not exist then the default location is used. Configuration file uses JSON structure and has to be in UTF-8 character encoding format without BOM. It is a mandatory part of password filter library and if not found or an error occurs during its parsing, the password filter is not able to work properly and switches to the **inactive state**. It means that it acts as no password filter was installed i.e. it allows all password changes without policy validation and performs no IdM notification. All configuration properties are mandatory and incomplete configuration file is invalid. Configuration file is read during PF initialization phase and then checked every 3 seconds whether it has changed. If so, it is reloaded. If the configuration file is missing or has wrong name etc., the monitoring system stops working. The only current solution is to provide config file and restart AD. Configuration file has to contain following items:
    * ''restBaseUrl''  - is an array of base addresses with common parts of REST API; if connection is not successful next address is tried
@@ Line 90: / Line 90: @@
 ==== Logging ====
-Password filter (PF) is currently able to write logs into a logging file only. The default logging file is located at ''c:\CzechIdM\PasswordFilter\log\PasswordFilterLog.log''. The log folder can be user specified by environmental variable ''BCV\_PWF\_LOG\_FILE\_FOLDER''. The name of the file remains the same ''PasswordFilterLog.log''. PF logging file is rotated by its size at the moment it reaches 10MB. Logging library which takes care of logging maintains always one file where PF currently logs to and one previous file with the name ''PasswordFilterLog.log.1''.
+Password filter (PF) is currently able to write logs into a logging file only. The default logging file is located at ''c:\CzechIdM\PasswordFilter\log\PasswordFilterLog.log''. The log folder can be user specified by environmental variable ''BCV_PWF_LOG_FILE_FOLDER''. The name of the file remains the same ''PasswordFilterLog.log''. PF logging file is rotated by its size at the moment it reaches 10MB. Logging library which takes care of logging maintains always one file where PF currently logs to and one previous file with the name ''PasswordFilterLog.log.1''.
 Logging verbosity level can be set via ''logLevel'' in the configuration file. Setting of this item is case insensitive and accepts following values:
@@ Line 138: / Line 138: @@
 ---
-==== Password filter deployment ====
+===== Password filter deployment =====
-#### Password filter distribution and installation ####
+==== Password filter distribution and installation ====
 <note important>**Before starting installation make sure there is a dedicated user in IdM system with [[devel:documentation:uniform_password:password_filter_idm#how_it_works_in_detail|sufficient permissions]] for password filter to use!**
@@ Line 152: / Line 152: @@
   - Unpack the supplied archive
-  - Install MS MSVC Redistributable package by running ''VC\_redist.exe'' in ''bin'' directory
+  - Install MS MSVC Redistributable package by running ''VC_redist.exe'' in ''bin'' directory
   - Create a directory structure ''c:\CzechIdM\PasswordFilter\etc'' in the local filesystem for PF configuration file
   - Copy a configuration file to the location created during the step 3). An example is situated in ''share\CzechIdM\PasswordFilter\etc\PasswordFilterConfig.cfg''. The file needs to have UTF-8 encoding. When editing in ''notepad.exe'' the encoding is usually changed. Set all necessary parts, especially:
@@ Line 159: / Line 159: @@
     - systemId - The name of the connected system in IdM, the password filter is used on.
   - Copy all ''\*.dll'' files located in ''lib\'' directory and from all its sub-directories directly into ''c:\Windows\System32\'' (do not follow original directory structure)
-  - Add (in ''regedit'' or ''regedit.exe'') the password filter name (by default **PasswordFilterDll**) to the register key ''HKEY\_LOCAL\_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Notification Packages'' (see the picture below)
+  - Add (in ''regedit'' or ''regedit.exe'') the password filter name (by default **PasswordFilterDll**) to the register key ''HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Notification Packages'' (see the picture below)
   - Restart server
@@ Line 205: / Line 205: @@
 In case of troubles with deploying the password filter AD does not provide much information. The error log can be found in Windows event manager (see the picture below). This error log is common and may occur when some of following cases happens:
   * ''PasswordFilterDll'' *.dll file is not present in expected directory i.e. ''c:\Windows\System32\''.
-  * The record in the register ''HKEY\_LOCAL\_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Notification Packages'' does not correspond to real password filter dll's name (by default PasswordFilterDll).
+  * The record in the register ''HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Notification Packages'' does not correspond to real password filter dll's name (by default PasswordFilterDll).
   * Password filter dll is not able to find all its dependencies. Check the installation process manual for details.
@@ Line 212: / Line 212: @@
 ------
 -
-=== Building password filter dll ===
+==== Building password filter dll ====
 To build PF dll it is necessary to install development tools and libraries PF depends on. [[https://visualstudio.microsoft.com/vs/|MS Visual Studio]] (VS) was used for PF dll development. Along with VS installation there are installed common runtime libraries. Beside them we need to install cpprestsdk and log4cpp libraries. Both are available on Gitlab, but we will utilize package system called [[https://github.com/microsoft/vcpkg|VCPKG]] provided by Microsoft. It will save us from manual download and installation of libraries. Please follow [[https://github.com/microsoft/vcpkg#quick-start-windows|the installation and configuration]] steps on the original vcpkg site including integration of installed libraries to Visual Studio. It will ease your further development. The process of integration may have to be repeated after installation of libraries listed in the following paragraph.
@@ Line 230: / Line 230: @@
 Project build in Visual Studio is quite straightforward. [[https://github.com/bcvsolutions/password-filter|Download]] PF project from Github and open its Solution in VS.
 There is no need of project adjusting if you performed the integration of vcpkg libraries as mentioned in the previous paragraph. The only thing which needs to be done is the selection of destination platform and compilation profile. Choose *Debug* for development and *Release* for deployment. Run *Rebuild* command applied on *PasswordFilterDll*
-project in the Solution. Compiled libraries can be found in ''<SOLUTION\_DIR>/<PLATFORM\_DIR>/<BUILD\_PROFILE>''. We will need PasswordFilterDll.dll, orocos-log4cpp.dll and cpprest\_X\_XX.dll (where X is a version number). Create or reuse the structure of installation [[https://nexus.bcvsolutions.eu/repository/maven-releases/eu/bcvsolutions/idm/password-filter-dll/1.0.0/password-filter-dll-1.0.0-x64.zip|package]] and place there these libraries. Overwrite the existing ones.
+project in the Solution. Compiled libraries can be found in ''<SOLUTION_DIR>/<PLATFORM_DIR>/<BUILD_PROFILE>''. We will need PasswordFilterDll.dll, orocos-log4cpp.dll and cpprest_X_XX.dll (where X is a version number). Create or reuse the structure of installation [[https://nexus.bcvsolutions.eu/repository/maven-releases/eu/bcvsolutions/idm/password-filter-dll/1.0.0/password-filter-dll-1.0.0-x64.zip|package]] and place there these libraries. Overwrite the existing ones.
 {{ :devel:documentation:uniform_password:vsdllbuildguide.png?400 |}}