From 8043828e84f74f458796ef322871630ad30d3465 Mon Sep 17 00:00:00 2001
From: Sascha Dirbach <sascha.dirbach@endless-webservices.de>
Date: Wed, 16 Oct 2019 17:33:19 +0200
Subject: [PATCH] ARTEMIS-2521 add documentation for role-mapping

---
 docs/user-manual/en/configuration-index.md |  3 +++
 docs/user-manual/en/security.md            | 14 ++++++++++++++
 2 files changed, 17 insertions(+)

diff --git a/docs/user-manual/en/configuration-index.md b/docs/user-manual/en/configuration-index.md
index 0deb10473d..9239123ee7 100644
--- a/docs/user-manual/en/configuration-index.md
+++ b/docs/user-manual/en/configuration-index.md
@@ -374,6 +374,9 @@ Name | Description
 [permission](security.md) |
 [permission.type](security.md) | the type of permission
 [permission.roles](security.md) | a comma-separated list of roles to apply the permission to
+[role-mapping](security.md) | A simple role mapping that can be used to map roles from external authentication providers (i.e. LDAP) to internal roles
+[role-mapping.from](security.md) | The external role which should be mapped
+[role-mapping.to](security.md) | The internal role which should be assigned to the authenticated user
 
 
 ## broker-plugin type
diff --git a/docs/user-manual/en/security.md b/docs/user-manual/en/security.md
index 6a45271f01..063fc28913 100644
--- a/docs/user-manual/en/security.md
+++ b/docs/user-manual/en/security.md
@@ -1022,6 +1022,20 @@ superseded by SASL GSSAPI. However, for clients that don't support SASL (core
 client), using TLS can provide Kerberos authentication over an *unsecure*
 channel.
 
+## Mapping external roles
+Roles from external authentication providers (i.e. LDAP) can be mapped to internally used roles. The is done through role-mapping entries in the security-settings block:
+
+```xml
+<security-settings>
+   [...]
+   <role-mapping from="cn=admins,ou=Group,ou=ActiveMQ,ou=system" to="my-admin-role"/>
+   <role-mapping from="cn=users,ou=Group,ou=ActiveMQ,ou=system" to="my-user-role"/>
+</security-settings>
+```
+
+Note: Role mapping is additive. That means the user will keep the original role(s) as well as the newly assigned role(s).
+
+Note: This role mapping only affects the roles which are used to authorize queue access through the configured acceptors. It can not be used to map the role required to access the web console.
 
 ## SASL
 [AMQP](using-AMQP.md) supports SASL. The following mechanisms are supported; PLAIN, EXTERNAL, ANONYMOUS, GSSAPI.