Merge pull request #454 from lvydra/WFCORE-5740

[WFCORE-5740] Add the ability to ignore unavailable realms for a distributed-realm

elytron/WFCORE-5740-ability-to-ignore-unavailable-realms-for-a-distributed-realm.adoc

@@ -0,0 +1,75 @@
+= [WFCORE-5740] Add the ability to ignore unavailable realms for a distributed-realm
+:author:            Lukas Vydra
+:email:             [email protected]
+:toc:               left
+:icons:             font
+:idprefix:
+:idseparator:       -
+
+== Overview
+A distributed-realm is made up of a list of realms. Each realm in the list is attempted until we either find the user or run out of realms. 
+If a realm happens to be unavailable, we currently stop searching altogether. This is undesirable if the user could have been found in a subsequent realm.
+
+This enhancmend will add an ignore-unavailable-realms boolean attribute to a distributed-realm to allow users to specify that the search should continue on to the next realm if a realm happens to be unavailable.
+
+** Example configuration:
+
+```
+   /subsystem=elytron/distributed-realm=distributedRealm:add(realms=[realm1, realm2], ignore-unavailable-realms=true)
+```
+
+== Issue Metadata
+
+=== Issue
+* https://issues.redhat.com/browse/WFCORE-5740[WFCORE-5740]
+
+
+=== Related Issues
+
+* https://issues.redhat.com/browse/ELY-2305[ELY-2305]
+* https://issues.redhat.com/browse/EAP7-1862[EAP7-1862]
+
+=== Dev Contacts
+
+* mailto:{email}[{author}]
+
+=== QE Contacts
+* mailto:{email}[{author}]
+
+=== Testing By
+[x] Engineering
+
+[ ] QE
+
+=== Affected Projects or Components
+* WildFly, Security, WildFly-Core, Elytron
+
+=== Other Interested Projects
+
+== Requirements 
+
+=== Hard Requirements
+
+* It should be possible to configure an ```distributed-realm``` with the optional attribute ```ignore-unavailable-realms``` which
+allow users to specify that the search should continue on to the next realm if a realm happens to be unavailable.
+Default value for the ```ignore-unavailable-realms``` attribute will be `false`.
+
+When ```ignore-unavailable-realms``` is set to true and realm happens to be unavailable, SecurityRealmUnavailableEvent will be emitted to the corresponding SecurityDomain.
+This can be turned off by adding `emit-events` attribute and setting it to `false`.
+`emit-events` is a new optional attribute with a default value set to `true`.
+
+
+=== Nice-to-Have Requirements
+
+=== Non-Requirements
+
+== Test Plan
+WildFly integration tests will be added. Tests also will be added to the Elytron testsuite.
+
+== Community Documentation
+
+Documentation should be added under elytron/components in the WildFly documentation, describing there added ```ignore-unavailable-realms``` attribute.
+
+== Release Note Content
+
+* New Distributed Realm attribute ```ignore-unavailable-realms``` enables user to switch to ignore unavailable realms during search and continue searching in subsequent realms.