Password filter in IdM

Password filter is feature from Active Directory (hereinafter as AD) that provides creating own password policy checks and password change implementation for AD (more info password filter TODO). 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.

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.

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.

Both IdM REST endpoints receive following parameters from password filter:

• password - new password changed on system,
• username - for the username is new password changed,
• resource - unique identifier system where is password changed,
• logIdentifier - identifier that is printed into all logs - identifier helps connect request from password filter with IdM process,
• version - version of password filter.

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.

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.

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 trought 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't check echo the password will be sent againt to AD from which was password change executed for first time - red line. The AD doesn't know about password initializor and will process password again against via password filter to IdM and whole password change can cycles to infinity.

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 even create user with password. For all these cases IdM create echo record and it is not possible for a cycle to occur.

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't know about who sended the request and password filter send request again to IdM. IdM will check echo for the given system - echo for AD exists and IdM will not process password again against trough AD - red line.

If IdM does not check the echo. The process marked as red line will be processed and the cycle occurs.

All echo records are stored in distributed cache in IdM.

There is step by step behavior processed by endpoint VALIDATE (eq: http://localhost/idm/api/v1/systems/password-filter/validate/ ):

1. find correct system (SysSystemDto) by parameter resource,
   1. if system cannot be found exception will be throw (404 - PASSWORD\_FILTER\_SYSTEM\_NOT\_FOUND),
2. find mapped attribute that contains configuration for password filter,
   1. if attribute cannot be found or has bad configuration exception will be throw (404 - PASSWORD\_FILTER\_DEFINITION\_NOT\_FOUND),
3. find identity for given parameter username,
   1. if identity cannot be found exception will be throw (404 - PASSWORD\_FILTER\_IDENTITY\_NOT\_FOUND),
   2. for more information about find specific identity see this section
4. check if exists uniform password definition
   1. uniform password definition unite all another password policies by systems,
   2. on the systems will be also changed password
   3. for system with password filter will be also set echo record,
5. check echo record for the system from which the password validation request came. Checking echo for validation has following steps:
   1. echo doesn't exists ✅ - password will be processed
   2. echo record exists - password in echo record isn't same ✅ - password validation will be processed
   3. echo record exists - password in echo record is same ❌ - password validation will not be processed - to password filter will be returned password is valid
   4. echo record is already expired ✅ - password will be processed
   5. echo record was already changed and validated ❌ - skip all another process - to password filter will be returned password is valid,
   6. echo record was already only checked and someone call second validation ✅ - password will be processed
6. check if exists uniform password with IdM system (change in IdM),
7. create final password policy set that may include default password policy,
8. process validation,
9. when only one password policy failed - set/create echos for all managed accounts with failed check flag,
10. successfully validate password trough password policies - set/create echos for all managed accounts with valid check flag.

Second endpoint CHANGE has following behavior (eq: http://localhost/idm/api/v1/systems/password-filter/change/ ):

- find correct system (SysSystemDto) by parameter resource,

1. if system cannot be found exception will be throw (404 - PASSWORD\_FILTER\_SYSTEM\_NOT\_FOUND),

- find mapped attribute that contains configuration for password filter,

1. 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,

1. if identity cannot be found exception will be throw (404 - PASSWORD\_FILTER\_IDENTITY\_NOT\_FOUND),
2. for more information about find specific identity see this section

- check if exists uniform password definition

1. uniform password definition unite all another password policies by systems,
2. on the systems will be also changed password
3. 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:

1. echo doesn't exists ❌ - exception will be throw (403 - PASSWORD\_FILTER\_NOT\_VALID\_CHANGE\_REQUEST),
2. echo record exists - password in echo record isn't same ❌ - exception will be throw (403 - PASSWORD\_FILTER\_NOT\_VALID\_CHANGE\_REQUEST),
3. echo record exists - password in echo record is same ✅ - password change request continues,
4. 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).

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.

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 PasswordFilterManager.EXCLUDED\_SYSTEM that skip password change on some specific system.

If you use password reset module and setup the configuration correctly - add the event types PASSWORD\_RESET and PASSWORD\_GENERATE the echo system and uniform password will works even for password reset module.

When provisioning with password ended with another operation state than executed from echo record will be removed flag for change.