Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
devel:documentation:uniform_password:password_filter_idm [2020/08/28 10:34]
kopro continue with documentation 		devel:documentation:uniform_password:password_filter_idm [2021/06/28 16:16] (current)
kopro [Find correct identity by username from system]
Line 1: Line 1:
-====== Password filter in IdM ====== +====== Password synchronization ====== 
-{{tag>password filter passwordfilter echo echos uniform password system systems change passwords}}+{{tag>synchronization password filter passwordfilter echo echos uniform password system systems change passwords CTRL+ALT+DELETE CTRL ALT DELETE}}
  
-{{ :devel:documentation:uniform_password:pf01.png?700|}}+<note tip>Password synchronization allows users **very simply** change password to **all connected system** just from theirs workstations -> **only one password trough all system**.</note>
  
 +{{ :devel:documentation:uniform_password:pf001.png?700|}}
  
-[[https://docs.microsoft.com/en-us/windows/win32/secmgmt/password-filters|Password filter]] is feature from [[https://en.wikipedia.org/wiki/Active_Directory|Active Directory]] (hereinafter as AD) that provides creating own password policy checks and password change implementation for AD (more info password filter FIXME). After user, that is logged with AD account, will process trough password change via password change form in OS (standard shortcut CTRL+ALT+DELETE) the behavior in AD will process new password via password filter. **Password filter will be called twice**, first for validation and second for password change. Both these methods (validate and change) call IdM rest endpoints for next logic described below. 
  
 +CzechIdM provides feature **synchronize passwords from system**. IdM receives request for password synchronization from external system (for example [[https://en.wikipedia.org/wiki/Active_Directory|Active Directory]], [[https://www.openldap.org/|Open Ldap]]).  After IdM successful validates request for password synchronization. Password will be distributes into connected systems via classic password change behavior. 
  
 +Setup the password synchronization is easy - administrator musts just activate the feature **password synchronization** in IdM and  setup external system for sending password change requests to IdM. Then users can simply initialized password change form on his own workstation and start changing the passwords by standard behavior. For example Windows stations has standard shortcut ''CTRL+ALT+DELETE'' for initialize password change form. External system sends request for password change into IdM and IdM will take care of the rest of the password change process.
 +
 +IdM process the password change request and **distributes password to all next connected system**. <wrap hi>The result is that user just change the password once via his local workstation and **password is same trough all connected systems**. User uses only **ONE password**.</wrap>
 +
 +Users also don't need change password via some special form or change password on every system that they use separately. Just one simple change trough own local workstation is enough.
 +
 +Workstation based on [[https://en.wikipedia.org/wiki/Active_Directory|Active Directory]] uses password synchronization via [[https://docs.microsoft.com/en-us/windows/win32/secmgmt/password-filters|password filter]] more about this component [[devel:documentation:uniform_password:password_filter_dll|can be found there]].
 +
 +Password synchronization works in two phases. First phase is password **validation** and the second is **password change** in IdM and distribution password to next system. IdM receives password trough **HTTPS** protocol and REST calling.
 +
 +<note tip>Passwords are **never saved in plain text** in IdM.</note>
 +
 +===== Phases in password synchronization =====
 +
 +
 +{{ :devel:documentation:uniform_password:300.png |}}
 +
 +
 +
 +In first phase is synchronized password validated trough defined password policies in IdM. In IdM has every connected system specific password policy including IdM application. Through these policies will be password validated and the result will be send back to user. When password doesn't meet only one password policy the password will not be changed even on users local workstation. Password must be successfully validated trough given password policies and only then can be changed. Validation can be repeated.
 +
 +{{ :devel:documentation:uniform_password:400.png |}}
 +
 +After success password validation continues password synchronization with password change. Password will be for first changed in IdM and all another connected systems. Basically the password change has same process as standard password changed that can be done in IdM by basic password change form. Before this phase must be password successfully validated, otherwise isn't possible change the password.
 +
 +Each phase has own log format and it is very easy for check and control password synchronization with own log control mechanism, or just simple via log agenda in IdM. Simple example of parsed logs:
 +
 +<code log>
 +INFO validate : Validation request pass! For identity [john.doe] and system code [AD users]. Log identifier: [1454118233]. Password filter version: [1.0.0].
 +INFO change : Change request from resource [AD users] for identity identifier [john.doe] starting. Log identifier: [3621046325]. Password filter version: [1.0.0].
 +INFO change : Password change will be processed. For identity [john.doe] and system [AD users] was found these accounts for change [john.doe,j.doe,doe,john_doe]. Log identifier: [3621046325]. Password filter version: [1.0.0].
 +
 +</code>
 +
 +===== Step by step password synchronization from Active Directory =====
 +
 +User wants change password on his own workstation and press CTRL+ALT+DELETE for initialize password change process:
 +
 +{{ :devel:documentation:uniform_password:pf1.png?600 |}}
 +
 +After user press CTRL+ALT+DELETE Windows shows context menu that allow change password by option "Change a password":
 +
 +{{ :devel:documentation:uniform_password:pf2.png |}}
 +
 +On password change form fill old password and new password and then confirm the password change by enter:
 +
 +{{ :devel:documentation:uniform_password:pf5.png |}}
 +
 +After user press enter starts whole process described in above. Validation phase and then change phase. User doesn't about anything on background and some phases:
 +
 +{{ :devel:documentation:uniform_password:pf3.png |}}
 +
 +If new password doesn't meet with policies defined in AD or inIdM Windows show to users standard info message about not valid password:
 +
 +<code>
 +Unable to update the password. The value provided for the new password does not meet the length, complexity, or history requirements of the domain
 +</code>
 +
 +{{ :devel:documentation:uniform_password:pf7.png |}}
 +
 +After successful password change Windows shows success result:
 +
 +{{ :devel:documentation:uniform_password:pf4.png |}}
 +
 +
 +====== How it works in detail? ======
 +
 +{{:devel:documentation:uniform_password:pf01.png?600 |}}
 +
 +Password synchronization can be setup **only for system that has provisioning mapping** for identities and mapped **password** (standard attribute name: ''\_\_PASSWORD\_\_'') in system atribute mapping. Configuration for password filter will be available after checkbox **Attribute with password** will be checked.
 +
 +Password synchronization has two phase as we said above. Each phase has own REST endpoint. These REST endpoints must be called with **POST** method and each endpoint has **own permission**. First endpoint provides validation and the second provides password change.
  
-System CzechIdM provides REST endpoints for AD password filter functionality. Password filter configurations will be available only if exists provisioning mapping for identities and mapped **password** (''\_\_PASSWORD\_\_'') in system atribute mapping. Configuration for password filter will be available after checkbox **Attribute with password** will be checked. 
  
  
Line 26: Line 98:
  
 Parameters ''logIdentifier'' and ''version'' is part for **every log record** written into application log. Both these parameter is not required. Parameters ''password'', ''username'' and ''resource'' is **required**. Parameters ''logIdentifier'' and ''version'' is part for **every log record** written into application log. Both these parameter is not required. Parameters ''password'', ''username'' and ''resource'' is **required**.
 +<note important>
 +Both REST endpoints has new permissions ''SYSTEM\_PASSWORDFILTERVALIDATE'' for validation and for change ''SYSTEM\_PASSWORDFILTERCHANGE''. Identity that password filter used for calling these REST endpoint must have both these permissions. For authentization can be used standard **basic** authentization or **CIDMST** token. Recommended is use **CIDMST** token with long expiration date. It's recommend create new identity with these permissions. </note>
  
-Both REST endpoints has new permissions ''SYSTEM\_PASSWORDFILTERVALIDATE'' for validation and for change ''SYSTEM\_PASSWORDFILTERCHANGE''. Identity that password filter used for calling these REST endpoint must have both these permissions. For authentization can be used standard **basic** authentization or **CIDMST** token. Recommended is use **CIDMST** token with long expiration date.+=== Permission settings for password filter ===
  
-===== Why we want check echos? =====+{{:devel:documentation:uniform_password:pf_permissions_setting.png?500|}} 
 +   
 +==== Why we want check echos? ====
 {{:devel:documentation:uniform_password:100.png |}} {{:devel:documentation:uniform_password:100.png |}}
  
Line 50: Line 126:
  
  
-===== Echo and flags =====+==== Echo and flags ====
  
 All echo records are stored in distributed cache in IdM. Echo record **can be evicted** by application configuration (Settings->Modules->Cache). In same agenda is also shown how many records are now in cache. Maximum time that will be echo stored is **12 hours**. **Longer period for echo storation cannot be set!** All echo records are stored in distributed cache in IdM. Echo record **can be evicted** by application configuration (Settings->Modules->Cache). In same agenda is also shown how many records are now in cache. Maximum time that will be echo stored is **12 hours**. **Longer period for echo storation cannot be set!**
Line 74: Line 150:
  
  
-===== Password validation request =====+==== Password validation request ====
  
 There is step by step behavior processed by endpoint **VALIDATE** (//eq: http://localhost/idm/api/v1/systems/password-filter/validate/ //): There is step by step behavior processed by endpoint **VALIDATE** (//eq: http://localhost/idm/api/v1/systems/password-filter/validate/ //):
Line 85: Line 161:
       - if attribute cannot be found or has bad configuration **exception will be throw** (404 - PASSWORD\_FILTER\_DEFINITION\_NOT\_FOUND),       - if attribute cannot be found or has bad configuration **exception will be throw** (404 - PASSWORD\_FILTER\_DEFINITION\_NOT\_FOUND),
   - **find identity** for given parameter ''username'',   - **find identity** for given parameter ''username'',
-      - if identity cannot be found **exception will be throw** (404 - PASSWORD\_FILTER\_IDENTITY\_NOT\_FOUND),+      - if identity for whom the password is being validated cannot be found in IdM **exception will be throw** (404 - PASSWORD\_FILTER\_IDENTITY\_NOT\_FOUND),
       - for more information about find specific identity see this section       - for more information about find specific identity see this section
   - **check if exists uniform password definition**   - **check if exists uniform password definition**
Line 104: Line 180:
   - **successfully** validate password trough password policies - **set/create echos** for all managed accounts with **valid check flag**.   - **successfully** validate password trough password policies - **set/create echos** for all managed accounts with **valid check flag**.
  
-===== Password change request =====+==== Password change request ====
  
 Second endpoint **CHANGE** has following behavior (//eq: http://localhost/idm/api/v1/systems/password-filter/change/ //): Second endpoint **CHANGE** has following behavior (//eq: http://localhost/idm/api/v1/systems/password-filter/change/ //):
Line 132: Line 208:
  
  
-===== PASSWORD event =====+==== PASSWORD event ====
 Endpoint change publish after all check new event **PASSWORD** for entity IdmIdentityDto. **The whole event including provisioning is synchronous now**. Classic **PASSWORD** event provides password validation, but event published by password filter has all validations skipped by property ''IdentityProcessor.SKIP\_PASSWORD\_VALIDATION''. Endpoint change publish after all check new event **PASSWORD** for entity IdmIdentityDto. **The whole event including provisioning is synchronous now**. Classic **PASSWORD** event provides password validation, but event published by password filter has all validations skipped by property ''IdentityProcessor.SKIP\_PASSWORD\_VALIDATION''.
  
Line 144: Line 220:
  
  
-===== Find correct identity by username from system =====+==== Find correct identity by username from system ==== 
 + 
 +<note tip>The script used to transform the username** must be of type** ''Transform from a system''!</note>
  
-===== Password filter attribute =====+From external system IdM receives **user identifier** - ''username'' parameter. If for the identifier exists equal account (UID) the owner of the account will be used as owner of the password change request. If doesn't exists equal account, IdM checks if exists identity (username) with the given **user identifier**.
  
 +But some external system has own system identifier. For these cases exists **transformation script** that allows to find correct owner of password change request. It is required returned identity otherwise exception will be thrown. The **script has to be** of the ''Transformation from a system'' type, **another script types will not work**!
  • by kopro