Merge pull request #530 from Skyllarr/WFLY-18185

[WFLY-18185] Provide a possibility for a caching realm to authenticate users with underlying realm when credential verification with cached credential fails

elytron/ELY-2538-caching-realm-update-cached-credential.adoc

@@ -0,0 +1,96 @@
+---
+categories:
+  - elytron
+  - security
+---
+= ELY-2538 Provide a possibility for a caching realm to authenticate users with underlying realm when credential verification with cached credential fails
+:author:            Diana Krepinska
+:email:             [email protected]
+:toc:               left
+:icons:             font
+:idprefix:
+:idseparator:       -
+
+== Overview
+
+For LDAP servers that do not support persistent search, we do not receive notifications if the cached identities have had their passwords changed in LDAP server externally.
+
+This issue is to provide a possibility for the caching realm to authenticate a user with the underlying realm directly when the authentication fails with the cached credential. If the credential verification is successful with the underlying realm, remove the old credential from cache and put the updated credential to the cache.
+
+== Issue Metadata
+
+=== Issue
+
+* https://issues.redhat.com/browse/ELY-2538[ELY-2538]
+
+=== Related Issues
+
+* https://issues.redhat.com/browse/EAP7-2069[EAP7-2069] - EAP issue tracker
+* https://issues.redhat.com/browse/ELY-2538[ELY-2538] - Elytron project issue tracker
+* https://issues.redhat.com/browse/WFLY-18185[WFLY-18185] - Wildfly community documentation issue tracker
+
+=== Stability Level
+// Choose the planned stability level for the proposed functionality
+* [ ] Experimental
+
+* [ ] Preview
+
+* [ ] Community
+
+* [x] default
+
+
+
+=== Dev Contacts
+
+* mailto:[email protected][Diana Krepinska]
+
+=== QE Contacts
+
+* mailto:[email protected][Ondrej Kotek]
+
+=== Testing By
+// Put an x in the relevant field to indicate if testing will be done by Engineering or QE.
+// Discuss with QE during the Kickoff state to decide this
+[x] Engineering
+
+[ ] QE
+
+=== Affected Projects or Components
+
+* https://github.com/wildfly-security/wildfly-elytron[WildFly Elytron project]
+* Wildfly Security component will be consequently affected by the improvements introduced by this new feature
+
+== Requirements
+
+=== Hard Requirements
+
+* It must be possible for the caching realm to authenticate a user and update the cached credential if it has been changed externally and a user attempts to authenticate with the new credential.
+
+=== Nice-to-Have Requirements
+
+N/A
+
+=== Non-Requirements
+
+N/A
+
+== Implementation Plan
+
+This functionality should either be added as a default, as this was the behaviour of the legacy security subsystem. Or we can add this behaviour under a new attribute of the caching realm. If we add it as configurable with a property, then it can be backported with a system property.
+
+I have decided to make this functionality a default  behaviour that is not optional. The reason for this is that this functionality was present in the legacy security, and users can consider the absence of this functionality to be a bug.
+
+Specification of the functionality that will be added: if a user currently cached by the caching realm has had their credentials updated externally, then if this user provides an updated password when authenticating to the WildFly server, the caching realm will be able to successfully authenticate a user. This is because if the caching realm receives a credential that is different from the credential that the identity has cached, it will attempt to authenticate directly with the underlying realm. If the authentication succeeds, the credential in the cache will be updated. Outdated credential will therefore not be possible to be used anymore.
+
+== Test Plan
+
+* WildFly Elytron test suite: Functional tests
+
+== Community Documentation
+
+WildFly - community documentation will be delivered in form of a PR to a main branch
+
+== Release Note Content
+
+Authentication using credentials updated outside of WildFly will now succeed, and credentials and attributes in the cache will be automatically updated upon such authentication.