Differences
This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
devel:documentation:uniform_password:password_filter_idm [2020/08/03 07:17] kopro created |
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 | + | ====== Password |
- | [[https:// | + | {{tag> |
- | System CzechIdM provides REST endpoints for AD password filter functionality. | + | <note tip>Password |
- | {{ : | + | {{ : |
- | CzechIdM has two REST endpoints that will be called by password filter implementation. The first endpoint that **must be called** is validate. Call directly change isn't allowed and **error will be thrown**. | ||
- | ===== Validate | + | CzechIdM provides feature **synchronize passwords from system**. IdM receives request for password synchronization from external system (for example [[https:// |
+ | |||
+ | 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 '' | ||
+ | |||
+ | 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**.</ | ||
+ | |||
+ | 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:// | ||
+ | |||
+ | 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> | ||
+ | |||
+ | ===== Phases in password synchronization | ||
+ | |||
+ | |||
+ | {{ : | ||
+ | |||
+ | |||
+ | |||
+ | 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' | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | 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, | ||
+ | |||
+ | </ | ||
+ | |||
+ | ===== 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: | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | After user press CTRL+ALT+DELETE Windows shows context menu that allow change password by option " | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | On password change form fill old password and new password and then confirm the password change by enter: | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | After user press enter starts whole process described in above. Validation phase and then change phase. User doesn' | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | If new password doesn' | ||
+ | |||
+ | < | ||
+ | Unable to update the password. The value provided for the new password does not meet the length, complexity, or history requirements of the domain | ||
+ | </ | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | After successful password change Windows shows success result: | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | |||
+ | ====== How it works in detail? ====== | ||
+ | |||
+ | {{: | ||
+ | |||
+ | Password synchronization can be setup **only for system that has provisioning mapping** for identities and mapped **password** (standard attribute name: '' | ||
+ | |||
+ | 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. | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | CzechIdM has two REST endpoints that is called by password filter implementation. The first endpoint **validate** **must be called** before the second endpoint **change**. Call directly **change** REST endpoint isn't allowed and **error will be thrown**. | ||
+ | |||
+ | |||
+ | <note tip>The **change** REST endpoint doesn' | ||
+ | |||
+ | Both IdM REST endpoints receive following parameters from password filter: | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | Parameters '' | ||
+ | <note important> | ||
+ | Both REST endpoints has new permissions '' | ||
+ | |||
+ | === Permission settings for password filter === | ||
+ | |||
+ | {{: | ||
+ | |||
+ | ==== Why we want check echos? ==== | ||
+ | {{: | ||
+ | |||
+ | Without checking echos is very likely that password filter call IdM, IdM will process password and provisioning to all another system, **but including** the system from which was password change executed. The password filter on the system again catch this second password change and whole password change process is executed repeatably. | ||
+ | |||
+ | As you see on picture at left side. The **user initialize** password change on his **own computer**. The computer process the password **change trough AD**. AD **send password to IdM** via password filter and IdM check echo's and then process password into next systems //(eq LDAP, Card system, AD's, …)//. If IdM doesn' | ||
+ | |||
+ | <wrap hi>When IdM check echo the process marked as red line will never happen.</ | ||
+ | |||
+ | ---- | ||
+ | |||
+ | |||
+ | {{ : | ||
+ | |||
+ | The second image (right image) present password change **executed by user from IdM**. Password change can be executed by **public change form**, **classic form** change on user detail, **password reset**, **password generation**, | ||
+ | |||
+ | After user executed password change. IdM will **create** and process **provisioning operation** with password to all systems that has mapped password. For systems with password filter will be also **create echo** records and then will be processed classic provisioning with password. AD and other system with password //(eq: LDAP, card system, ...)// **receives request** with password change and process. AD **process the password** change request via **password filer**. AD's password filter doesn' | ||
+ | |||
+ | <wrap hi>If IdM does not check the echo. The process marked as red line will be processed and the cycle occurs.</ | ||
+ | |||
+ | |||
+ | ==== Echo and flags ==== | ||
+ | |||
+ | All echo records are stored in distributed cache in IdM. Echo record **can be evicted** by application configuration (Settings-> | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | <note tip>Echo record are persisted in cache - with application restart may be all echos deleted - it depend on cache configuration.</ | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | **Global agenda for all echo doesn' | ||
+ | |||
+ | Echo column will be shown only when logged user has permission for '' | ||
+ | |||
+ | In modal windows with echo detail are show 4 rows with these information: | ||
+ | * **Password changed** (boolean) - flag/check if password was **successfully** changed, | ||
+ | * **Changed date** (date) - date when was password **successfully** changed, | ||
+ | * **Performed successful password validation** (boolean) - flag if password validation was success or not, | ||
+ | * **Validation date** (date) - validation date. | ||
+ | |||
+ | <wrap hi>Echo record will be created after password filter call first validation REST endpoint</ | ||
+ | |||
+ | |||
+ | |||
+ | ==== Password validation request | ||
There is step by step behavior processed by endpoint **VALIDATE** (//eq: http:// | There is step by step behavior processed by endpoint **VALIDATE** (//eq: http:// | ||
- | <note tip> | + | <note tip> |
- | - **find correct system** (SysSystemDto) | + | - **find correct system** (SysSystemDto) by parameter |
- | - **find mapped attribute** that contains configuration for password filter. If attribute cannot be found or has bad configuration **exception will be throw** (404 - PASSWORD\_FILTER\_DEFINITION\_NOT\_FOUND), | + | - if system cannot be found **exception will be throw** (404 - PASSWORD\_FILTER\_SYSTEM\_NOT\_FOUND), |
- | - **find identity** for given parameter | + | - **find mapped attribute** that contains configuration for password filter, |
- | - **check if exists uniform password definition** - uniform password definition unite all another systems. On the systems will be also changed password | + | - if attribute cannot be found or has bad configuration **exception will be throw** (404 - PASSWORD\_FILTER\_DEFINITION\_NOT\_FOUND), |
- | - **check echo record** | + | - **find identity** for given parameter |
- | - **echo doesn' | + | - if identity |
- | - **password in echo record isn't same** | + | - for more information about find specific identity see this section |
- | - **echo record is already expired** | + | - **check if exists uniform password definition** |
- | - **echo record | + | |
- | - **echo record was already only checked and someone call second validation** | + | - on the systems will be also changed password |
- | - **check if exists uniform password** | + | - for system with password filter will be also set echo record, |
+ | - **check echo record** | ||
+ | - **echo doesn' | ||
+ | - **echo record exists** - password in echo record | ||
+ | - **echo record exists** - password in echo record **is same** ❌ - password validation **will not be** processed - to password filter will be returned password is valid | ||
+ | - **echo record is already expired** | ||
+ | - **echo record | ||
+ | - **echo record was already only checked and someone call second validation** | ||
+ | - **check if exists uniform password | ||
- create **final password policy set** that may include default password policy, | - create **final password policy set** that may include default password policy, | ||
- **process validation**, | - **process validation**, | ||
- | - when only one item **failed** - **set/ | + | - when only one password policy |
- **successfully** validate password trough password policies - **set/ | - **successfully** validate password trough password policies - **set/ | ||
- | ===== Change ===== | + | ==== Password change request |
- | There is step by step behavior processed by endpoint **VALIDATE** (//eq: http:// | + | Second |
+ | |||
+ | |||
+ | <note tip> | ||
+ | |||
+ | - **find correct system** (SysSystemDto) by parameter '' | ||
+ | - if system cannot be found **exception will be throw** (404 - PASSWORD\_FILTER\_SYSTEM\_NOT\_FOUND), | ||
+ | - **find mapped attribute** that contains configuration for password filter, | ||
+ | - if attribute cannot be found or has bad configuration **exception will be throw** (404 - PASSWORD\_FILTER\_DEFINITION\_NOT\_FOUND), | ||
+ | - **find identity** for given parameter '' | ||
+ | - if identity cannot be found **exception will be throw** (404 - PASSWORD\_FILTER\_IDENTITY\_NOT\_FOUND), | ||
+ | - for more information about find specific identity see this section | ||
+ | - **check if exists uniform password definition** | ||
+ | - uniform password definition unite all another password policies by systems, | ||
+ | - on the systems will be also changed password | ||
+ | - for system with password filter will be also set echo record, | ||
+ | - **check echo record** for the system from which the password change request came. Checking echo for change request has following steps: | ||
+ | - **echo doesn' | ||
+ | - **echo record exists** - password in echo record **isn' | ||
+ | - **echo record exists** - password in echo record **is same** ✅ - password change request continues, | ||
+ | - **password wan't successfully validate** ❌ - exception will be throw (403 - PASSWORD\_FILTER\_NOT\_VALID\_CHANGE\_REQUEST), | ||
+ | - prepare final account set for password change request, | ||
+ | - set echos for all managed accounts (accounts for systems where is active password filter), | ||
+ | - process password change event trough IdM (for more information see section bellow). | ||
+ | |||
+ | |||
+ | ==== 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 '' | ||
+ | |||
+ | One part of **PASSWORD** event also provides unite by uniform password system. The uniform password behavior is not wanted because cycles can arise. The whole event **PASSWORD** contains second parameter '' | ||
+ | |||
+ | If you use [[tutorial: | ||
+ | |||
+ | <note tip> | ||
+ | |||
+ | When provisioning with password ended with another operation state than **executed** from echo record will be removed flag for change. | ||
- | Second endpoint **CHANGE** | ||
- | ===== Find correct identity by username from system | + | ==== Find correct identity by username from system ==== |
- | ===== Echo flags ===== | + | <note tip>The script used to transform the username** must be of type** '' |
- | ===== Password filter attribute ===== | + | From external system IdM receives **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 '' |