github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-23 17:28:26 -04:00
Code Issues Projects Releases Packages Wiki Activity

Feature Controls - Documentation (#35656)

Browse source 
* update spaces images

* add Spaces FC section

* Updates for kibana authorization section

* update plugin development guide

* start adding docs

* remove unused description field from Feature Registry interface

* Update role management API documentation

* Apply suggestions from code review

Thanks, Gail!

Co-Authored-By: legrego <lgregorydev@gmail.com>

* Update docs/api/role-management/put.asciidoc

* update kibana privileges section intro

* relocate link to Role Management API

* update PUT role docs to align with ES

* indicate that base and feature privileges cannot be used at the same time

* restructure kibana privileges section

* add UI and API examples to Kibana Privileges section

* Apply suggestions from code review

Co-Authored-By: legrego <lgregorydev@gmail.com>

* address PR feedback

* Apply suggestions from code review

Co-Authored-By: legrego <lgregorydev@gmail.com>

* Apply suggestions from code review

Co-Authored-By: legrego <lgregorydev@gmail.com>

* address pr feedback

* Update docs/api/role-management/put.asciidoc

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

* Update docs/security/index.asciidoc

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

* address PR feedback

* fix merge from master

* Update docs/spaces/managing-spaces.asciidoc

Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com>
This commit is contained in:
Larry Gregory 2019-05-22 14:01:15 -04:00 • committed by GitHub
parent d8c2757cb9
commit be765767ee
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
29 changed files with 770 additions and 133 deletions
Download patch file Download diff file Expand all files Collapse all files

81
docs/api/role-management/get.asciidoc
View file

@ -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"
]
}
]
}
--------------------------------------------------

194
docs/api/role-management/put.asciidoc
View file

@ -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,30 +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.
===== Example 5
Granting access to both Kibana and Elasticsearch.
[source,js]
--------------------------------------------------
@ -87,12 +228,27 @@ PUT /api/security/role/my_kibana_role
"query" : "{\"match\": {\"title\": \"foo\"}}"
} ]
},
<<<<<<< HEAD
"kibana": [
{
"base": ["all"],
"feature": {
},
"spaces": [
"default"
]
=======
"kibana": {
"global": [],
"space": {
"marketing": ["all"],
"engineering": ["read"]
>>>>>>> 83b7ea76b0fd7afcbeff26cd95241ef4b075d12e
}
}
]
}
--------------------------------------------------
==== Response
A successful call returns a response code of `204` and no response body.

3
docs/development/plugin-development.asciidoc
View file

@ -8,6 +8,7 @@ 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>>
@ -15,6 +16,8 @@ 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[]

192
docs/development/plugin/development-plugin-feature-registration.asciidoc Normal file
View file

@ -0,0 +1,192 @@
[[development-plugin-feature-registration]]
=== Plugin feature registration
If your plugin will be used with {kib}’s default distribution, then you have the ability to register the features that your plugin provides. Features are typically apps in {kib}; once registered, you can toggle them via Spaces, and secure them via Roles when security is enabled.
==== UI Capabilities
Registering features also gives your plugin access to “UI Capabilities”. These capabilities are boolean flags that you can use to conditionally render your interface, based on the current user’s permissions. For example, you can hide or disable a Save button if the current user is not authorized.
==== Registering a feature
Feature registration is controlled via the built-in `xpack_main` plugin. To register a feature, call `xpack_main`'s `registerFeature` function from your plugin’s `init` function, and provide the appropriate details:
["source","javascript"]
-----------
init(server) {
const xpackMainPlugin = server.plugins.xpack_main;
xpackMainPlugin.registerFeature({
// feature details here.
});
}
-----------
===== Feature details
Registering a feature consists of the following fields. For more information, consult the {repo}blob/{branch}/x-pack/plugins/xpack_main/server/lib/feature_registry/feature_registry.ts[feature registry interface].
[cols="1a, 1a, 1a, 1a"]
|===
|Field name |Data type |Example |Description
|`id` (required)
|`string`
|`"sample_feature"`
|A unique identifier for your feature. Usually, the ID of your plugin is sufficient.
|`name` (required)
|`string`
|`"Sample Feature"`
|A human readable name for your feature.
|`app` (required)
|`string[]`
|`["sample_app", "kibana"]`
|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/xpack_main/server/lib/feature_registry/feature_registry.ts[`FeatureWithAllOrReadPrivileges`].
|see examples below
|The set of privileges this feature requires to function.
|`icon`
|`string`
|"discoverApp"
|An https://elastic.github.io/eui/#/display/icons[EUI Icon] to use for this feature.
|`navLinkId`
|`string`
|"sample_app"
|The ID of the navigation link associated with your feature.
|===
===== Privilege definition
The `privileges` section of feature registration allows plugins to implement read/write and read-only modes for their applications.
For a full explanation of fields and options, consult the {repo}blob/{branch}/x-pack/plugins/xpack_main/server/lib/feature_registry/feature_registry.ts[feature registry interface].
==== Using UI Capabilities
UI Capabilities are available to your public (client) plugin code. These capabilities are read-only, and are used to inform the UI. This object is namespaced by feature id. For example, if your feature id is “foo”, then your UI Capabilities are stored at `uiCapabilities.foo`.
To access capabilities, import them from `ui/capabilities`:
["source","javascript"]
-----------
import { uiCapabilities } from ‘ui/capabilities’;
const canUserSave = uiCapabilities.foo.save;
if (canUserSave) {
// show save button
}
-----------
==== Example 1: Canvas Application
["source","javascript"]
-----------
init(server) {
const xpackMainPlugin = server.plugins.xpack_main;
xpackMainPlugin.registerFeature({
id: 'canvas',
name: 'Canvas',
icon: 'canvasApp',
navLinkId: 'canvas',
app: ['canvas', 'kibana'],
catalogue: ['canvas'],
privileges: {
all: {
savedObject: {
all: ['canvas-workpad'],
read: ['index-pattern'],
},
ui: ['save'],
},
read: {
savedObject: {
all: [],
read: ['index-pattern', 'canvas-workpad'],
},
ui: [],
},
},
});
}
-----------
This shows how the Canvas application might register itself as a Kibana feature.
Note that it specifies different `savedObject` access levels for each privilege:
- Users with read/write access (`all` privilege) need to be able to read/write `canvas-workpad` saved objects, and they need read-only access to `index-pattern` saved objects.
- Users with read-only access (`read` privilege) do not need to have read/write access to any saved objects, but instead get read-only access to `index-pattern` and `canvas-workpad` saved objects.
Additionally, Canvas registers the `canvas` UI app and `canvas` catalogue entry. This tells Kibana that these entities are available for users with either the `read` or `all` privilege.
The `all` privilege defines a single “save” UI Capability. To access this in the UI, Canvas could:
["source","javascript"]
-----------
import { uiCapabilities } from ‘ui/capabilities’;
const canUserSave = uiCapabilities.canvas.save;
if (canUserSave) {
// show save button
}
-----------
Because the `read` privilege does not define the `save` capability, users with read-only access will have their `uiCapabilities.canvas.save` flag set to `false`.
==== Example 2: Dev Tools
["source","javascript"]
-----------
init(server) {
const xpackMainPlugin = server.plugins.xpack_main;
xpackMainPlugin.registerFeature({
id: 'dev_tools',
name: i18n.translate('xpack.main.featureRegistry.devToolsFeatureName', {
defaultMessage: 'Dev Tools',
}),
icon: 'devToolsApp',
navLinkId: 'kibana:dev_tools',
app: ['kibana'],
catalogue: ['console', 'searchprofiler', 'grokdebugger'],
privileges: {
all: {
api: ['console'],
savedObject: {
all: [],
read: [],
},
ui: ['show'],
},
read: {
api: ['console'],
savedObject: {
all: [],
read: [],
},
ui: ['show'],
},
},
privilegesTooltip: i18n.translate('xpack.main.featureRegistry.devToolsPrivilegesTooltip', {
defaultMessage:
'User should also be granted the appropriate Elasticsearch cluster and index privileges',
}),
});
}
-----------
Unlike the Canvas example above, Dev Tools does not require access to any saved objects to function. Dev Tools does specify an API endpoint, however. When this is configured, the Security plugin will automatically authorize access to any server API route that is tagged with `access:console`, similar to the following:
["source","javascript"]
-----------
server.route({
path: '/api/console/proxy',
method: 'POST',
config: {
tags: ['access:console'],
handler: async (req, h) => {
// ...
}
}
});
-----------

2
docs/development/security/rbac.asciidoc
View file

@ -70,7 +70,7 @@ The application is created by concatenating the prefix of `kibana-` with the val
}
----------------------------------
Roles that grant <<kibana-privileges>> should be managed using the <<role-management-api>> or the *Management* / *Security* / *Roles* page, not directly using the {es} {ref}/security-api.html#security-role-apis[role management API]. This role can then be assigned to users using the {es}
Roles that grant <<kibana-privileges>> should be managed using the <<role-management-api>> or the *Management -> Security -> Roles* page, not directly using the {es} {ref}/security-api.html#security-role-apis[role management API]. This role can then be assigned to users using the {es}
{ref}/security-api.html#security-user-apis[user management APIs].
[[development-rbac-authorization]]

BIN
docs/images/security_base_all.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 365 KiB

BIN
docs/images/spaces_secure_all_privileges.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 136 KiB

BIN
docs/images/spaces_secure_specific_spaces.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 100 KiB

97
docs/security/authorization/index.asciidoc
View file

@ -1,21 +1,92 @@
[role="xpack"]
[[xpack-security-authorization]]
=== Authorization
Authorizing users to use {kib} in simple configurations is as easy as assigning the user
either the `kibana_user` or `kibana_dashboard_only_user` reserved role. If you're running
a single tenant of {kib} against your {es} cluster, and you're not controlling access to individual spaces, then this is sufficient and no other action is required.
=== Granting access to {kib}
The Elastic Stack comes with the `kibana_user` {stack-ov}/built-in-roles.html[built-in role], which you can use to grant access to all Kibana features in all spaces. To grant users access to a subset of spaces or features, you can create a custom role that grants the desired Kibana privileges.
==== Spaces
When you assign a user multiple roles, the user receives a union of the roles’ privileges. Therefore, assigning the `kibana_user` role in addition to a custom role that grants Kibana privileges is ineffective because `kibana_user` has access to all the features in all spaces.
If you want to control individual spaces in {kib}, do **not** use the `kibana_user` or `kibana_dashboard_only_user` roles. Users with these roles are able to access all spaces in Kibana. Instead, create your own roles that grant access to specific spaces.
NOTE: When running multiple tenants of Kibana by changing the `kibana.index` in your `kibana.yml`, you cannot use `kibana_user` to grant access. You must create custom roles that authorize the user for that specific tenant. Although multi-tenant installations are supported, the recommended approach to securing access to Kibana segments is to grant users access to specific spaces.
==== Multi-tenant {kib}
[role="xpack"]
=== {kib} role management
When running multiple tenants of {kib}, and changing the `kibana.index` in your `kibana.yml`, you
must create custom roles that authorize the user for that specific tenant. You can use
either the *Management / Security / Roles* page in {kib} or the <<role-management-api>>
to assign a specific <<kibana-privileges, Kibana privilege>> at that tenant. After creating the
custom role, you should assign this role to the user(s) that you wish to have access.
To create a role that grants {kib} privileges, go to **Management -> Security -> Roles** and click **Create role**.
==== Adding {kib} privileges
To assign {kib} privileges to the role, click **Add space privilege** in the Kibana section.
[role="screenshot"]
image::security/images/add-space-privileges.png[Add space privileges]
Open the **Spaces** dropdown menu to specify whether to grant the role access to all spaces *** Global (all spaces)** or one or more individual spaces. If you select *** Global (all spaces)**, you can’t select individual spaces until you clear your selection.
Use the **Privilege** menu to grant access to features. The default is **Custom**, which you can use to grant access to individual features. Otherwise, you can grant read and write access to all current and future features by selecting **All**, or grant read access to all current and future features by selecting **Read**.
[IMPORTANT]
If a feature is hidden using the Spaces disabled features, it will remain hidden even if the user has the necessary privileges.
When using the **Customize by feature** option, you can choose either **All**, **Read** or **None** for access to each feature. As new features are added to Kibana, roles that use the custom option do not automatically get access to the new features. You must manually update the roles.
NOTE: Machine Learning and Stack Monitoring rely on built-in roles to grant access. When a user is assigned the appropriate roles, the Machine Learning and Stack Monitoring application are available; otherwise, these applications are not visible.
To apply your changes, click **Create space privilege**. The space privilege shows up under the Kibana privileges section of the role.
[role="screenshot"]
image::security/images/create-space-privilege.png[Create space privilege]
==== Assigning different privileges to different spaces
Using the same role, it’s possible to assign different privileges to different spaces. After you’ve added space privileges, click **Add space privilege**. If you’ve already added privileges for either *** Global (all spaces)** or an individual space, you will not be able to select these in the **Spaces** control.
Additionally, if you’ve already assigned privileges at *** Global (all spaces)**, you are only able to assign additional privileges to individual spaces. Similar to the behavior of multiple roles granting the union of all privileges, space privileges are also a union. If you’ve already granted the user the **All** privilege at *** Global (all spaces)**, you’re not able to restrict the role to only the **Read** privilege at an individual space.
==== Privilege summary
To view a summary of the privileges granted, click **View privilege summary**.
[role="screenshot"]
image::security/images/view-privilege-summary.png[View privilege summary]
==== Example 1: Grant all access to Dashboard at an individual space
. Click **Add space privilege**.
. For **Spaces**, select an individual space.
. For **Privilege**, leave the default selection of **Custom**.
. For the Dashboard feature, select **All**
. Click **Create space privilege**.
[role="screenshot"]
image::security/images/privilege-example-1.png[Privilege example 1]
==== Example 2: Grant all access to one space and read access to another
. Click **Add space privilege**.
. For **Spaces**, select the first space.
. For **Privilege**, select **All**.
. Click **Create space privilege**.
. Click **Add space privilege**.
. For **Spaces**, select the second space.
. For **Privilege**, select **Read**.
. Click **Create space privilege**.
[role="screenshot"]
image::security/images/privilege-example-2.png[Privilege example 2]
==== Example 3: Grant read access to all spaces and write access to an individual space
. Click **Add space privilege**.
. For **Spaces**, select *** Global (all spaces)**.
. For **Privilege**, select **Read**.
. Click **Create space privilege**.
. Click **Add space privilege**.
. For **Spaces**, select the individual space.
. For **Privilege**, select **All**.
. Click **Create space privilege**.
[role="screenshot"]
image::security/images/privilege-example-3.png[Privilege example 3]
While multi-tenant installations are supported, the recommended approach to securing access to segments of {kib} is to grant users access to specific spaces.

72
docs/security/authorization/kibana-privileges.asciidoc
View file

@ -2,14 +2,70 @@
[[kibana-privileges]]
=== Kibana privileges
This section lists the Kibana privileges that you can assign to a role.
{kib} privileges grant users access to features within {kib}. Roles have privileges to determine whether users have write or read access.
[horizontal]
==== Base privileges
Assigning a base privilege grants access to all available features in Kibana (Discover, Visualize, Dashboard, and so on).
[[kibana-privileges-all]]
`all`::
All Kibana privileges, can read, write and delete saved searches, dashboards, visualizations,
short URLs, Timelion sheets, graph workspaces, index patterns and advanced settings.
`all`:: Grants full read-write access.
`read`:: Grants read-only access.
`read`::
Can read saved searches, dashboards, visualizations, short URLs, Timelion sheets, graph workspaces,
index patterns, and advanced settings.
===== Assigning base privileges
From the role management screen:
[role="screenshot"]
image::security/images/assign_base_privilege.png[Assign base privilege]
From the <<role-management-api-put, role management API>>:
[source,js]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
{
"elasticsearch": {
"cluster" : [ ],
"indices" : [ ]
},
"kibana": [
{
"base": ["all"],
"feature": {},
"spaces": ["marketing"]
}
]
}
--------------------------------------------------
==== Feature privileges
Assigning a feature privilege grants access to a specific feature.
`all`:: Grants full read-write access.
`read`:: Grants read-only access.
===== Assigning feature privileges
From the role management screen:
[role="screenshot"]
image::security/images/assign_feature_privilege.png[Assign feature privilege]
From the <<role-management-api-put, role management API>>:
[source,js]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
{
"elasticsearch": {
"cluster" : [ ],
"indices" : [ ]
},
"kibana": [
{
"base": [],
"feature": {
"dashboard": ["all"]
},
"spaces": ["marketing"]
}
]
}
--------------------------------------------------

BIN
docs/security/images/add-space-privileges.png Executable file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 221 KiB

BIN
docs/security/images/assign_base_privilege.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 365 KiB

BIN
docs/security/images/assign_feature_privilege.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 496 KiB

BIN
docs/security/images/create-space-privilege.png Executable file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 67 KiB

BIN
docs/security/images/privilege-example-1.png Executable file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 216 KiB

BIN
docs/security/images/privilege-example-2.png Executable file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 48 KiB

BIN
docs/security/images/privilege-example-3.png Executable file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 53 KiB

BIN
docs/security/images/view-privilege-summary.png Executable file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 151 KiB

7
docs/security/index.asciidoc
View file

@ -13,7 +13,7 @@ auditing. For more information, see
[float]
=== Users
You can create and manage users on the *Management* / *Security* / *Users* page.
You can create and manage users on the *Management -> Security -> Users* page.
You can also change their passwords and roles. For more information about
authentication and built-in users, see
{stack-ov}/setting-up-authentication.html[Setting up user authentication].
@ -21,9 +21,8 @@ authentication and built-in users, see
[float]
=== Roles
You can manage roles on the *Management* / *Security* / *Roles* page, or use
{kib}'s <<role-management-api>>. For more information on configuring roles for
{kib} see <<xpack-security-authorization, {kib} Authorization>>.
You can manage roles on the *Management -> Security -> Roles* page, or use
the <<role-management-api>>. For more information on configuring roles for {kib}, see <<xpack-security-authorization, Granting access to {kib}>>.
For a more holistic overview of configuring roles for the entire stack,
see {stack-ov}/authorization.html[Configuring role-based access control].

BIN
docs/spaces/images/delete-space.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 280 KiB

After

Width:  |  Height:  |  Size: 400 KiB

Before After
Before After

BIN
docs/spaces/images/edit-space-feature-visibility.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 311 KiB

BIN
docs/spaces/images/edit-space.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 168 KiB

After

Width:  |  Height:  |  Size: 403 KiB

Before After
Before After

BIN
docs/spaces/images/space-management.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 214 KiB

After

Width:  |  Height:  |  Size: 366 KiB

Before After
Before After

BIN
docs/spaces/images/space-selector.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 626 KiB

3
docs/spaces/index.asciidoc
View file

@ -11,7 +11,7 @@ You can change your current space at any time, by clicking on the space avatar i
[role="screenshot"]
image::spaces/images/change-space.png["Change current space"]
With security enabled, you can <<spaces-securing, control which users have access to individual spaces>>.
With security enabled, you can <<xpack-security-authorization, control which users have access to individual spaces>>.
[float]
@ -26,5 +26,4 @@ version of {kib}, then the default space will contain all of your existing saved
Although you can't delete the default space, you can customize it to your liking.
include::managing-spaces.asciidoc[]
include::securing-spaces.asciidoc[]
include::moving-saved-objects.asciidoc[]

11
docs/spaces/managing-spaces.asciidoc
View file

@ -18,8 +18,17 @@ You cannot change the space identifier once the space is created.
[role="screenshot"]
image::spaces/images/edit-space.png["Updating a space"]
==== Controlling feature visibility
You can control which {kib} features are visible in each space. For example, you can hide “Dev Tools” in your “Executive” space, if users of that space don’t need this feature.
[role="screenshot"]
image::spaces/images/edit-space-feature-visibility.png["Controlling features visiblity"]
NOTE: This is not considered a security feature. If you wish to secure access to specific features on a per-user basis, then you need to configure <<xpack-security-authorization, Kibana Security>>.
==== Deleting spaces
Deleting a space is a destructive operation, which cannot be undone. When you delete a space, all of the saved objects that belong to that space are also deleted.
[role="screenshot"]
image::spaces/images/delete-space.png["Deleting a space"]
image::spaces/images/delete-space.png["Deleting a space"]

74
docs/spaces/securing-spaces.asciidoc
View file

@ -1,74 +0,0 @@
[role="xpack"]
[[spaces-securing]]
=== Securing spaces
With a Gold or Platinum license, you can control which roles have access to
each space. To get started, navigate to **Management > Roles**.
[role="screenshot"]
image::images/spaces_secure_all_privileges.png[]
==== Setting privileges
Access for all spaces in {kib} is governed by a concept called "minimum privilege."
There are three options for minimum privilege:
[cols="2*^<"]
|===
|`all`
|Users have read/write access to all spaces in {kib}. Additionally,
users can create, edit, and delete individual spaces. This extends to spaces
that users create in the future.
|`read`
|Users have read-only access to all spaces in {kib}. This extends to spaces
that users create in the future.
|`none`
|Users do not have the all-spaces access. You must set access on
individual spaces.
|===
Once you set the minimum privilege for all spaces, you can then add read and write
access to individual spaces.
==== Examples
[cols="2*^<"]
|===
s|To provide
s|Do this
|Full access to all spaces
|Set the minimum privilege to `all`. This grants
full access to all spaces. In this case, you can't
customize access to specific spaces.
|Read-only access to all spaces, with full access to specific spaces
|Set the minimum privilege to `read`,
then grant the `all` privilege to individual spaces as needed. You can't revoke
access to an individual space.
|Read-only access to a specific space
|Set the minimum privilege to `none` to prevent all-space access,
then set the `read` privilege for an individual space,
as shown below.
|===
[role="screenshot"]
image::images/spaces_secure_specific_spaces.png[]
[float]
=== Viewing all space privileges
To see which roles have access to each space, click *View summary of spaces privileges*.

1
x-pack/plugins/xpack_main/server/lib/feature_registry/feature_registry.test.ts
View file

@ -29,7 +29,6 @@ describe('FeatureRegistry', () => {
const feature: Feature = {
id: 'test-feature',
name: 'Test Feature',
description: 'this is a rather boring feature description !@#$%^&*()_+-=\\[]{}|;\':"/.,<>?',
icon: 'addDataApp',
navLinkId: 'someNavLink',
app: ['app1', 'app2'],

166
x-pack/plugins/xpack_main/server/lib/feature_registry/feature_registry.ts
View file

@ -7,18 +7,107 @@
import Joi from 'joi';
import { cloneDeep, difference, uniq } from 'lodash';
import { UICapabilities } from 'ui/capabilities';
/**
* Feature privilege definition
*/
export interface FeatureKibanaPrivileges {
/**
* If this feature includes management sections, you can specify them here to control visibility of those
* pages based on user privileges.
*
* Example:
* // Enables access to the "Advanced Settings" management page within the Kibana section
* management: {
* kibana: ['settings']
* }
*/
management?: {
[sectionId: string]: string[];
};
/**
* If this feature includes a catalogue entry, you can specify them here to control visibility based on user permissions.
*/
catalogue?: string[];
/**
* If your feature includes server-side APIs, you can tag those routes to secure access based on user permissions.
*
* Example:
* // Configure your routes with a tag starting with the 'access:' prefix
* server.route({
* path: '/api/my-route',
* method: 'GET',
* handler: () => { ...},
* options: {
* tags: ['access:my_feature-admin']
* }
* });
*
* Then, specify the tags here (without the 'access:' prefix) which should be secured:
*
* {
* api: ['my_feature-admin']
* }
*
* NOTE: It is important to name your tags in a way that will not collide with other plugins/features.
* A generic tag name like "access:read" could be used elsewhere, and access to that API endpoint would also
* extend to any routes you have also tagged with that name.
*/
api?: string[];
/**
* If your feature exposes a client-side application (most of them do!), then you can control access to them here.
*
* Example:
* {
* app: ['my-app', 'kibana']
* }
*
*/
app?: string[];
/**
* If your feature requires access to specific saved objects, then specify your access needs here.
*/
savedObject: {
/**
* List of saved object types which users should have full read/write access to when granted this privilege.
* Example:
* {
* all: ['my-saved-object-type']
* }
*/
all: string[];
/**
* List of saved object types which users should have read-only access to when granted this privilege.
* Example:
* {
* read: ['config']
* }
*/
read: string[];
};
/**
* A list of UI Capabilities that should be granted to users with this privilege.
* These capabilities will automatically be namespaces within your feature id.
*
* Example:
* {
* ui: ['show', 'save']
* }
*
* This translates in the UI to the following (assuming a feature id of "foo"):
* import { uiCapabilities } from 'ui/capabilities';
*
* const canShowApp = uiCapabilities.foo.show;
* const canSave = uiCapabilities.foo.save;
*
* Note: Since these are automatically namespaced, you are free to use generic names like "show" and "save".
*
* @see UICapabilities
*/
ui: string[];
}
@ -29,20 +118,93 @@ export type FeatureWithAllOrReadPrivileges = Feature<{
read?: FeatureKibanaPrivileges;
}>;
/**
* Interface for registering a feature.
* Feature registration allows plugins to hide their applications with spaces,
* and secure access when configured for security.
*/
export interface Feature<TPrivileges extends Partial<PrivilegesSet> = PrivilegesSet> {
/**
* Unique identifier for this feature.
* This identifier is also used when generating UI Capabilities.
*
* @see UICapabilities
*/
id: string;
/**
* Display name for this feature.
* This will be displayed to end-users, so a translatable string is advised for i18n.
*/
name: string;
/**
* Optional array of supported licenses.
* If omitted, all licenses are allowed.
* This does not restrict access to your feature based on license.
* Its only purpose is to inform the space and roles UIs on which features to display.
*/
validLicenses?: Array<'basic' | 'standard' | 'gold' | 'platinum'>;
/**
* An optional EUI Icon to be used when displaying your feature.
*/
icon?: string;
description?: string;
/**
* The optional Nav Link ID for feature.
* If specified, your link will be automatically hidden if needed based on the current space and user permissions.
*/
navLinkId?: string;
/**
* An array of app ids that are enabled when this feature is enabled.
* Apps specified here will automatically cascade to the privileges defined below, unless specified differently there.
*/
app: string[];
/**
* If this feature includes management sections, you can specify them here to control visibility of those
* pages based on the current space.
*
* Items specified here will automatically cascade to the privileges defined below, unless specified differently there.
*
* Example:
* // Enables access to the "Advanced Settings" management page within the Kibana section
* management: {
* kibana: ['settings']
* }
*/
management?: {
[sectionId: string]: string[];
};
/**
* If this feature includes a catalogue entry, you can specify them here to control visibility based on the current space.
*
* Items specified here will automatically cascade to the privileges defined below, unless specified differently there.
*/
catalogue?: string[];
/**
* Feature privilege definition.
*
* Example:
* {
* all: {...},
* read: {...}
* }
* @see FeatureKibanaPrivileges
*/
privileges: TPrivileges;
/**
* Optional message to display on the Role Management screen when configuring permissions for this feature.
*/
privilegesTooltip?: string;
/**
* @private
*/
reserved?: {
privilege: FeatureKibanaPrivileges;
description: string;