Feature Controls - Documentation

docs/api/role-management/get.asciidoc

@@ -45,9 +45,15 @@ representation of the roles.
       "cluster": [ ],
       "run_as": [ ]
     },
-    "kibana": [ {
-        "privileges": [ "all" ]
-    } ],
+    "kibana": [{
+      "base": [
+        "all"
+      ],
+      "feature": {},
+      "spaces": [
+        "*"
+      ]
+    }]
   },
   {
     "name": "my_admin_role",
@@ -82,7 +88,7 @@ the `/api/security/role/<rolename>` endpoint:
 
 [source,js]
 --------------------------------------------------
-GET /api/security/role/my_kibana_role
+GET /api/security/role/my_restricted_kibana_role
 --------------------------------------------------
 // KIBANA
 
@@ -94,7 +100,7 @@ representation of the role.
 [source,js]
 --------------------------------------------------
 {
-  "name": "my_kibana_role",
+  "name": "my_restricted_kibana_role",
   "metadata" : {
     "version" : 1
   },
@@ -106,8 +112,67 @@ representation of the role.
     "indices": [ ],
     "run_as": [ ]
   },
-  "kibana": [ {
-      "privileges": [ "all" ]
-  } ],
+   "kibana": [
+    {
+      "base": [
+        "read"
+      ],
+      "feature": {},
+      "spaces": [
+        "marketing"
+      ]
+    },
+    {
+      "base": [],
+      "feature": {
+        "discover": [
+          "all"
+        ],
+        "visualize": [
+          "all"
+        ],
+        "dashboard": [
+          "all"
+        ],
+        "dev_tools": [
+          "read"
+        ],
+        "advancedSettings": [
+          "read"
+        ],
+        "indexPatterns": [
+          "read"
+        ],
+        "timelion": [
+          "all"
+        ],
+        "graph": [
+          "all"
+        ],
+        "apm": [
+          "read"
+        ],
+        "maps": [
+          "read"
+        ],
+        "canvas": [
+          "read"
+        ],
+        "infrastructure": [
+          "all"
+        ],
+        "logs": [
+          "all"
+        ],
+        "uptime": [
+          "all"
+        ]
+      },
+      "spaces": [
+        "sales",
+        "default"
+      ]
+    }
+  ]
 }
 --------------------------------------------------

docs/api/role-management/put.asciidoc

@@ -32,9 +32,21 @@ that begin with `_` are reserved for system usage.
 `elasticsearch`:: (object) Optional {es} cluster and index privileges, valid keys are 
 `cluster`, `indices` and `run_as`. For more information, see {xpack-ref}/defining-roles.html[Defining Roles].
 
-`kibana`:: (object) An object that specifies the <<kibana-privileges>>. Valid keys are `global` and `space`. Privileges defined in the `global` key will apply to all spaces within Kibana, and will take precedent over any privileges defined in the `space` key. For example, specifying `global: ["all"]` will grant full access to all spaces within Kibana, even if the role indicates that a specific space should only have `read` privileges. 
+`kibana`:: (list) A list of objects that specifies the <<kibana-privileges>> for this role:
+`base` ::: (list) An optional base privilege. If specified, must either be `["all"]` or `["read"]`.
+The `feature` section cannot be used if a base privilege is specified here. You must use one or the other.
+"all" grants read/write access to all Kibana features for the specified spaces.
+"read" grants read-only access to all Kibana features for the specified spaces.
 
-===== Example
+`feature` ::: (object) Object containing privileges for specific features.
+The `base` section cannot be used if feature privileges are specified here. You must use one or the other.
+Use the <<features-api, Features API>> to retrieve a list of available features.
+
+`spaces` ::: (list) The spaces these privileges should be applied to.
+To grant access to all spaces, set this to `["*"]`, or omit the value.
+
+===== Example 1
+Granting access to various features in all spaces
 
 [source,js]
 --------------------------------------------------
@@ -44,32 +56,159 @@ PUT /api/security/role/my_kibana_role
     "version" : 1
   },
   "elasticsearch": {
-    "cluster" : [ "all" ],
-    "indices" : [ {
-      "names" : [ "index1", "index2" ],
-      "privileges" : [ "all" ],
-      "field_security" : {
-        "grant" : [ "title", "body" ]
-      },
-      "query" : "{\"match\": {\"title\": \"foo\"}}"
-    } ]
+    "cluster" : [ ],
+    "indices" : [ ]
   },
-  "kibana": {
-    "global": ["all"]
-  }
+  "kibana": [
+    {
+      "base": [],
+      "feature": {
+       "discover": [
+          "all"
+        ],
+        "visualize": [
+          "all"
+        ],
+        "dashboard": [
+          "all"
+        ],
+        "dev_tools": [
+          "read"
+        ],
+        "advancedSettings": [
+          "read"
+        ],
+        "indexPatterns": [
+          "read"
+        ],
+        "timelion": [
+          "all"
+        ],
+        "graph": [
+          "all"
+        ],
+        "apm": [
+          "read"
+        ],
+        "maps": [
+          "read"
+        ],
+        "canvas": [
+          "read"
+        ],
+        "infrastructure": [
+          "all"
+        ],
+        "logs": [
+          "all"
+        ],
+        "uptime": [
+          "all"
+        ]
+      },
+      "spaces": [
+        "*"
+      ]
+    }
+  ]
 }
 --------------------------------------------------
 // KIBANA
 
-==== Response
+===== Example 2
+Granting "dashboard only" access to only the Marketing space.
 
-A successful call returns a response code of `204` and no response body.
+[source,js]
+--------------------------------------------------
+PUT /api/security/role/my_kibana_role
+{
+  "metadata" : {
+    "version" : 1
+  },
+  "elasticsearch": {
+    "cluster" : [ ],
+    "indices" : [ ]
+  },
+  "kibana": [
+    {
+      "base": [],
+      "feature": {
+        "dashboard": ["read"]
+      },
+      "spaces": [
+        "marketing"
+      ]
+    }
+  ]
+}
+--------------------------------------------------
+
+===== Example 3
+Granting full access to all features in the Default space.
+
+[source,js]
+--------------------------------------------------
+PUT /api/security/role/my_kibana_role
+{
+  "metadata" : {
+    "version" : 1
+  },
+  "elasticsearch": {
+    "cluster" : [ ],
+    "indices" : [ ]
+  },
+  "kibana": [
+    {
+      "base": ["all"],
+      "feature": {
+      },
+      "spaces": [
+        "default"
+      ]
+    }
+  ]
+}
+--------------------------------------------------
 
+===== Example 4
+Granting different access to different spaces.
+
+[source,js]
+--------------------------------------------------
+PUT /api/security/role/my_kibana_role
+{
+  "metadata" : {
+    "version" : 1
+  },
+  "elasticsearch": {
+    "cluster" : [ ],
+    "indices" : [ ]
+  },
+  "kibana": [
+    {
+      "base": [],
+      "feature": {
+        "discover": ["all"],
+        "dashboard": ["all"]
+      },
+      "spaces": [
+        "default"
+      ]
+    },
+    {
+      "base": ["read"],
+      "spaces": [
+        "marketing",
+        "sales"
+      ]
+    }
+  ]
+}
+--------------------------------------------------
 
-==== Granting access to specific spaces
-To grant access to individual spaces within {kib}, specify the space identifier within the `kibana` object.
 
-Note: granting access 
+===== Example 5
+Granting access to both Kibana and Elasticsearch.
 
 [source,js]
 --------------------------------------------------
@@ -89,12 +228,19 @@ PUT /api/security/role/my_kibana_role
       "query" : "{\"match\": {\"title\": \"foo\"}}"
     } ]
   },
-  "kibana": {
-    "global": [],
-    "space": {
-      "marketing": ["all"],
-      "engineering": ["read"] 
+  "kibana": [
+    {
+      "base": ["all"],
+      "feature": {
+      },
+      "spaces": [
+        "default"
+      ]
     }
-  }
+  ]
 }
 --------------------------------------------------
+
+==== Response
+
+A successful call returns a response code of `204` and no response body.

docs/development/plugin-development.asciidoc

@@ -8,13 +8,16 @@ The Kibana plugin interfaces are in a state of constant development.  We cannot
 
 * <<development-plugin-resources>>
 * <<development-uiexports>>
+* <<development-plugin-feature-registration>>
 * <<development-plugin-functional-tests>>
 * <<development-plugin-localization>>
 
 include::plugin/development-plugin-resources.asciidoc[]
 
 include::plugin/development-uiexports.asciidoc[]
 
+include::plugin/development-plugin-feature-registration.asciidoc[]
+
 include::plugin/development-plugin-functional-tests.asciidoc[]
 
 include::plugin/development-plugin-localization.asciidoc[]