Added documents for wildcard matching in authorization (#543)

conf/broker.conf

@@ -140,8 +140,9 @@ authenticationProviders=
 # Enforce authorization
 authorizationEnabled=false
 
-# Actions that can be authorized by using permitted role name which contains wildcard
-# e.g. pulsar.service.*
+# Allow wildcard matching in authorization
+# (wildcard matching only applicable if wildcard-char:
+# * presents at first or last position eg: *.pulsar.service, pulsar.service.*)
 authorizationAllowWildcardsMatching=false
 
 # Role names that are treated as "super-user", meaning they will be able to do all admin

conf/standalone.conf

@@ -106,8 +106,9 @@ authenticationProviders=false
 # Enforce authorization
 authorizationEnabled=false
 
-# Actions that can be authorized by using permitted role name which contains wildcard
-# e.g. pulsar.service.*
+# Allow wildcard matching in authorization
+# (wildcard matching only applicable if wildcard-char:
+# * presents at first or last position eg: *.pulsar.service, pulsar.service.*)
 authorizationAllowWildcardsMatching=false
 
 # Role names that are treated as "super-user", meaning they will be able to do all admin

conf/websocket.conf

@@ -59,8 +59,9 @@ authenticationProviders=
 # Enforce authorization
 authorizationEnabled=false
 
-# Actions that can be authorized by using permitted role name which contains wildcard
-# e.g. pulsar.service.*
+# Allow wildcard matching in authorization
+# (wildcard matching only applicable if wildcard-char:
+# * presents at first or last position eg: *.pulsar.service, pulsar.service.*)
 authorizationAllowWildcardsMatching=false
 
 # Role names that are treated as "super-user", meaning they will be able to do all admin

pulsar-broker-common/src/main/java/org/apache/pulsar/broker/ServiceConfiguration.java

@@ -137,7 +137,9 @@ public class ServiceConfiguration implements PulsarConfiguration {
     // do all admin operations and publish/consume from all topics
     private Set<String> superUserRoles = Sets.newTreeSet();
 
-    // Actions that can be authorized by using permitted role name which contains wildcard
+    // Allow wildcard matching in authorization
+    // (wildcard matching only applicable if wildcard-char:
+    // * presents at first or last position eg: *.pulsar.service, pulsar.service.*)
     private boolean authorizationAllowWildcardsMatching = false;
 
     // Authentication settings of the broker itself. Used when the broker connects

pulsar-websocket/src/main/java/org/apache/pulsar/websocket/service/WebSocketProxyConfiguration.java

@@ -67,7 +67,9 @@ public class WebSocketProxyConfiguration implements PulsarConfiguration {
     // do all admin operations and publish/consume from all topics
     private Set<String> superUserRoles = Sets.newTreeSet();
 
-    // Actions that can be authorized by using permitted role name which contains wildcard
+    // Allow wildcard matching in authorization
+    // (wildcard matching only applicable if wildcard-char:
+    // * presents at first or last position eg: *.pulsar.service, pulsar.service.*)
     private boolean authorizationAllowWildcardsMatching = false;
 
     // Authentication settings of the proxy itself. Used to connect to brokers

site/_includes/explanations/permissions.md

@@ -14,6 +14,37 @@ $ pulsar-admin namespaces grant-permission test-property/cl1/ns1 \
   --role admin10
 ```
 
+Wildcard authorization can be performed when `authorizationAllowWildcardsMatching` is set to `true` in `broker.conf`.
+
+e.g.
+```shell
+$ pulsar-admin namespaces grant-permission test-property/cl1/ns1 \
+                        --actions produce,consume \
+                        --role 'my.role.*'
+```
+
+Then, roles `my.role.1`, `my.role.2`, `my.role.foo`, `my.role.bar`, etc. can produce and consume.  
+
+```shell
+$ pulsar-admin namespaces grant-permission test-property/cl1/ns1 \
+                        --actions produce,consume \
+                        --role '*.role.my'
+```
+
+Then, roles `1.role.my`, `2.role.my`, `foo.role.my`, `bar.role.my`, etc. can produce and consume.
+
+**Note**: A wildcard matching works at **the beginning or end of the role name only**.
+
+e.g.
+```shell
+$ pulsar-admin namespaces grant-permission test-property/cl1/ns1 \
+                        --actions produce,consume \
+                        --role 'my.*.role'
+```
+
+In this case, only the role `my.*.role` has permissions.  
+Roles `my.1.role`, `my.2.role`, `my.foo.role`, `my.bar.role`, etc. **cannot** produce and consume.
+
 #### REST API
 
 {% endpoint POST /admin/namespaces/:property/:cluster/:namespace/permissions/:role %}