Document sub-feature privileges (#62335)

* documenting sub-feature privileges

* Apply suggestions from code review

Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com>

* address PR feedback

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

docs/developer/plugin/development-plugin-feature-registration.asciidoc

@@ -45,10 +45,15 @@ Registering a feature consists of the following fields. For more information, co
 |An array of applications this feature enables. Typically, all of your plugin's apps (from `uiExports`) will be included here.
 
 |`privileges` (required)
-|{repo}blob/{branch}/x-pack/plugins/features/server/feature.ts[`FeatureWithAllOrReadPrivileges`].
+|{repo}blob/{branch}/x-pack/plugins/features/common/feature.ts[`FeatureConfig`].
 |See <<example-1-canvas,Example 1>> and <<example-2-dev-tools,Example 2>>
 |The set of privileges this feature requires to function.
 
+|`subFeatures` (optional)
+|{repo}blob/{branch}/x-pack/plugins/features/common/feature.ts[`FeatureConfig`].
+|See <<example-3-discover,Example 3>>
+|The set of subfeatures that enables finer access control than the `all` and `read` feature privileges. These options are only available in the Gold subscription level and higher.
+
 |`icon`
 |`string`
 |"discoverApp"
@@ -192,3 +197,78 @@ server.route({
  }
 });
 -----------
+
+[[example-3-discover]]
+==== Example 3: Discover
+
+Discover takes advantage of subfeature privileges to allow fine-grained access control. In this example,
+a single "Create Short URLs" subfeature privilege is defined, which allows users to grant access to this feature without having to grant the `all` privilege to Discover. In other words, you can grant `read` access to Discover, and also grant the ability to create short URLs.
+
+["source","javascript"]
+-----------
+init(server) {
+  const xpackMainPlugin = server.plugins.xpack_main;
+  xpackMainPlugin.registerFeature({
+    {
+      id: 'discover',
+      name: i18n.translate('xpack.features.discoverFeatureName', {
+        defaultMessage: 'Discover',
+      }),
+      order: 100,
+      icon: 'discoverApp',
+      navLinkId: 'kibana:discover',
+      app: ['kibana'],
+      catalogue: ['discover'],
+      privileges: {
+        all: {
+          app: ['kibana'],
+          catalogue: ['discover'],
+          savedObject: {
+            all: ['search', 'query'],
+            read: ['index-pattern'],
+          },
+          ui: ['show', 'save', 'saveQuery'],
+        },
+        read: {
+          app: ['kibana'],
+          catalogue: ['discover'],
+          savedObject: {
+            all: [],
+            read: ['index-pattern', 'search', 'query'],
+          },
+          ui: ['show'],
+        },
+      },
+      subFeatures: [
+        {
+          name: i18n.translate('xpack.features.ossFeatures.discoverShortUrlSubFeatureName', {
+            defaultMessage: 'Short URLs',
+          }),
+          privilegeGroups: [
+            {
+              groupType: 'independent',
+              privileges: [
+                {
+                  id: 'url_create',
+                  name: i18n.translate(
+                    'xpack.features.ossFeatures.discoverCreateShortUrlPrivilegeName',
+                    {
+                      defaultMessage: 'Create Short URLs',
+                    }
+                  ),
+                  includeIn: 'all',
+                  savedObject: {
+                    all: ['url'],
+                    read: [],
+                  },
+                  ui: ['createShortUrl'],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    }
+  });
+}
+-----------

docs/user/security/authorization/kibana-privileges.asciidoc

@@ -43,6 +43,10 @@ Assigning a feature privilege grants access to a specific feature.
 `all`:: Grants full read-write access.
 `read`:: Grants read-only access.
 
+===== Sub-feature privileges
+Some features allow for finer access control than the `all` and `read` privileges.
+This additional level of control is available in the Gold subscription level and higher.
+
 ===== Assigning feature privileges
 From the role management screen:
 
@@ -62,7 +66,8 @@ PUT /api/security/role/my_kibana_role
     {
       "base": [],
       "feature": {
-        "dashboard": ["all"]
+        "visualize": ["all"],
+        "dashboard": ["read", "url_create"]
       },
       "spaces": ["marketing"]
     }