From 7b4be5008dfaca122d5a277b4010807a176a2992 Mon Sep 17 00:00:00 2001
From: Justin Bertram <jbertram@apache.org>
Date: Mon, 9 Jul 2018 09:36:33 -0500
Subject: [PATCH] ARTEMIS-1974 document LDAP role expansion

---
 .../spi/core/security/jaas/LDAPLoginModule.java     |  6 ++++++
 docs/user-manual/en/security.md                     | 13 +++++++++++++
 2 files changed, 19 insertions(+)

diff --git a/artemis-server/src/main/java/org/apache/activemq/artemis/spi/core/security/jaas/LDAPLoginModule.java b/artemis-server/src/main/java/org/apache/activemq/artemis/spi/core/security/jaas/LDAPLoginModule.java
index 19194fab17..7d58a0b97b 100644
--- a/artemis-server/src/main/java/org/apache/activemq/artemis/spi/core/security/jaas/LDAPLoginModule.java
+++ b/artemis-server/src/main/java/org/apache/activemq/artemis/spi/core/security/jaas/LDAPLoginModule.java
@@ -480,6 +480,12 @@ public class LDAPLoginModule implements LoginModule {
          while (!pendingNameExpansion.isEmpty()) {
             String name = pendingNameExpansion.remove();
             final String expandFilter = expandRolesMatchingFormat.format(new String[]{name});
+            if (logger.isDebugEnabled()) {
+               logger.debug("Get 'expanded' user roles.");
+               logger.debug("Looking for the 'expanded' user roles in LDAP with ");
+               logger.debug("  base DN: " + getLDAPPropertyValue(ROLE_BASE));
+               logger.debug("  filter: " + expandFilter);
+            }
             try {
                results = Subject.doAs(brokerGssapiIdentity, (PrivilegedExceptionAction< NamingEnumeration<SearchResult>>) () -> context.search(getLDAPPropertyValue(ROLE_BASE), expandFilter, constraints));
             } catch (PrivilegedActionException e) {
diff --git a/docs/user-manual/en/security.md b/docs/user-manual/en/security.md
index 47fb22897c..63e49a6c0a 100644
--- a/docs/user-manual/en/security.md
+++ b/docs/user-manual/en/security.md
@@ -690,6 +690,19 @@ system. It is implemented by
 - `referral` - specify how to handle referrals; valid values: `ignore`,
   `follow`, `throw`; default is `ignore`.
 
+- `expandRoles` - boolean indicating whether to enable the role expansion
+  functionality or not; default false. If enabled, then roles within roles will
+  be found. For example, role `A` is in role `B`. User `X` is in role `A`,
+  which means user `X` is in role `B` by virtue of being in role `A`.
+
+- `expandRolesMatching` - specifies an LDAP search filter which is applied to
+  the subtree selected by `roleBase`. Before passing to the LDAP search operation,
+  the string value you provide here is subjected to string substitution, as
+  implemented by the `java.text.MessageFormat` class. Essentially, this means that
+  the special string, `{0}`, is substituted by the role name as extracted from the
+  previous role search. This option must always be set to enable role expansion
+  because it has no default value. Example value: `(member={0})`.
+
 - `debug` - boolean flag; if `true`, enable debugging; this is used only for
   testing or debugging; normally, it should be set to `false`, or omitted;
   default is `false`