Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Adds example of assigning roles in Reporting #52757

Merged
merged 3 commits into from
Dec 12, 2019
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
55 changes: 47 additions & 8 deletions docs/user/security/reporting.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,56 @@ To use {reporting} with {security} enabled, you need to
<<using-kibana-with-security,set up {kib} to work with {security}>>.
If you are automatically generating reports with
{ref}/xpack-alerting.html[{watcher}], you also need to configure {watcher}
to trust the {kib} server's certificate. For more information, see
to trust the {kib} server's certificate.
////
For more information, see
<<securing-reporting>>.
////

[[reporting-app-users]]
To enable users to generate reports, assign them the built-in `reporting_user`
To enable users to generate reports, you must assign them the built-in `reporting_user`
role. Users will also need the appropriate <<kibana-privileges, {kib} privileges>> to access the objects
to report on and the {es} indices.

* If you're using the `native` realm, you can assign roles through
**Management > Users** UI in Kibana or with the `user` API. For example,
the following request creates a `reporter` user that has the
`reporting_user` role and the `kibana_user` role:

==== If you are using the `native` realm

You can assign roles through the
*Management* app in Kibana or with the `user` API.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This example shows to use *Management* to create a user who has a custom role and the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This example shows to use *Management* to create a user who has a custom role and the
This example shows how to use *Management* to create a user who has a custom role and the

`reporting_user` role.

. Go to *Management > Roles*, and click *Create role*.

. Give the new role a name, for example, `custom_reporting_user`.

. Specify the indices and privileges.
+
Access to data is an index-level privilege, so in *Create role*,
add a line for each index that contains the data for the report and give each
index `read` and `view_index_metadata` privileges.
For more information, see {ref}/security-privileges.html[Security privileges].
+
[role="screenshot"]
image::user/security/images/reporting-privileges-example.png["Reporting privileges"]

. Add space privileges.
+
Reporting users typically save searches, create
visualizations, and build dashboards. They require a space
that provides read and write privileges in
*Discover*, *Visualize*, and *Dashboard*.

. Save your new role.

. Create a user account with the proper roles.
+
Go to *Management > Users*, add a new user, and assign the user the built-in
`reporting_user` role and your new custom role, `custom_reporting_user`.

This example uses the `user` API to create a user who has the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section on creating a native realm user with the API seems like it should have a header.

Can the above link with the user API text link to this section?

Perhaps the outward-directing link that goes to security-api-put-user could be moved down to here?

`reporting_user` role and the `kibana_user` role:

[source, sh]
---------------------------------------------------------------
POST /_security/user/reporter
Expand All @@ -32,13 +69,15 @@ POST /_security/user/reporter
}
---------------------------------------------------------------

* If you are using an LDAP or Active Directory realm, you can either assign
==== If you are using an LDAP or Active Directory realm
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm guessing when this was originally written, that Kibana only supported LDAP and Active Directory outside of the built-in native realm. We have support for a few other external identity providers now, like SAML, OIDC, Kerberos, and PKI. All of these providers would require role mappings instead of the traditional user-role assignment.

What do you think about something like:

Suggested change
==== If you are using an LDAP or Active Directory realm
==== If you are using an external identity provider, such as LDAP or Active Directory


You can either assign
roles on a per user basis, or assign roles to groups of users. By default, role
mappings are configured in
{ref}/mapping-roles.html[`config/shield/role_mapping.yml`].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note to future me and future you:

#52559 is introducing a UI to manage role mappings, so when the time comes, we can link there instead of promoting the file-based role mapping mechanism.

For example, the following snippet assigns the user named Bill Murray the
`kibana_user` and `reporting_user` roles:
+

[source,yaml]
--------------------------------------------------------------------------------
kibana_user:
Expand Down