Refactors Security section into three sections

docs/alerting/index.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Alerting
-nav_order: 6
+nav_order: 8
 has_children: true
 ---
 

docs/elasticsearch/configuration.md

@@ -63,7 +63,7 @@ PUT /_cluster/settings
 
 ## Configuration file
 
-You can find `elasticsearch.yml` in `/usr/share/elasticsearch/config/elasticsearch.yml` (Docker) or `/etc/elasticsearch/elasticsearch.yml` (RPM) on each node. Out of the box, it contains a number of default settings for the Security plugin that you should modify before using Open Distro for Elasticsearch for a production workload. To learn more, see [Security](../../security/).
+You can find `elasticsearch.yml` in `/usr/share/elasticsearch/config/elasticsearch.yml` (Docker) or `/etc/elasticsearch/elasticsearch.yml` (RPM) on each node. Out of the box, it contains a number of default settings for the Security plugin that you should modify before using Open Distro for Elasticsearch for a production workload. To learn more, see [Security](../../security-configuration/).
 
 
 ### Sample configuration file

docs/install/deb.md

@@ -59,7 +59,7 @@ These steps assume you're using Ubuntu 18.04.
    curl -XGET https://localhost:9200/_cat/plugins?v -u admin:admin --insecure
    ```
 
-1. For instructions on installing and running Kibana, see [Kibana](../../kibana).
+1. For instructions on installing and running Kibana, see [Kibana](../../kibana/).
 
 1. To check the status of the service:
 

docs/install/docker-security.md

@@ -88,7 +88,7 @@ networks:
   odfe-net:
 ```
 
-Then make your changes to `elasticsearch.yml`. For a full list of settings, see [Security](../../security). This example adds (extremely) verbose audit logging:
+Then make your changes to `elasticsearch.yml`. For a full list of settings, see [Security](../../security-configuration/). This example adds (extremely) verbose audit logging:
 
 ```yml
 opendistro_security.ssl.transport.pemcert_filepath: esnode.pem
@@ -121,7 +121,7 @@ If you encounter any `File /usr/share/elasticsearch/config/elasticsearch.yml has
 
 ## Change passwords for read-only users
 
-After the cluster starts, change the passwords for the [read-only user accounts](../../security/api/#read-only-and-hidden-resources): `admin` and `kibanaserver`.
+After the cluster starts, change the passwords for the [read-only user accounts](../../security-configuration/api/#read-only-and-hidden-resources): `admin` and `kibanaserver`.
 
 - The `admin` user has full privileges on the cluster.
 - `kibanaserver` user has certain permissions to the `.kibana` index that let it perform management tasks like setting index patterns and retrieving visualizations. This user, or one just like it, is required for Kibana to work properly with the Security plugin. We recommend just using `kibanaserver`.
@@ -207,4 +207,4 @@ curl -XGET https://localhost:9200 -u admin:newpassword -k
 
 Then you can open Kibana at [http://localhost:5601](http://localhost:5601), sign in, and perform additional user management in the **Security** panel.
 
-You can use this same override process to specify new [authentication settings](../../security/configuration) in `/usr/share/elasticsearch/plugins/opendistro_security/securityconfig/config.yml`.
+You can use this same override process to specify new [authentication settings](../../security-configuration/configuration/) in `/usr/share/elasticsearch/plugins/opendistro_security/securityconfig/config.yml`.

docs/install/docker.md

@@ -171,7 +171,7 @@ services:
       - ./custom-kibana.yml:/usr/share/kibana/config/kibana.yml
 ```
 
-You can use this same method to [pass your own certificates](../docker-security/) for use with the [Security](../../security/) plugin.
+You can use this same method to [pass your own certificates](../docker-security/) for use with the [Security](../../security-configuration/) plugin.
 
 
 ## Bash access to containers
@@ -218,7 +218,7 @@ docker build --tag=odfe-custom-plugin .
 docker run -p 9200:9200 -p 9600:9600 -v /usr/share/elasticsearch/data odfe-custom-plugin
 ```
 
-You can also use a `Dockerfile` to pass your own certificates for use with the [Security](../../security/) plugin, similar to the `-v` argument in [Configure Elasticsearch](#configure-elasticsearch):
+You can also use a `Dockerfile` to pass your own certificates for use with the [Security](../../security-configuration/) plugin, similar to the `-v` argument in [Configure Elasticsearch](#configure-elasticsearch):
 
 ```
 FROM amazon/opendistro-for-elasticsearch:0.9.0

docs/kibana/index.md

@@ -8,7 +8,7 @@ has_toc: false
 
 # Kibana
 
-Kibana is the default visualization tool for data in Elasticsearch. It also serves as a user interface for the Open Distro for Elasticsearch [Security plugin](../security/).
+Kibana is the default visualization tool for data in Elasticsearch. It also serves as a user interface for the Open Distro for Elasticsearch [Security plugin](../security-configuration/).
 
 
 ## Run Kibana using Docker

docs/pa/index.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Performance Analyzer
-nav_order: 8
+nav_order: 10
 has_children: true
 ---
 

docs/security/cross-cluster-search.md → docs/security-access-control/cross-cluster-search.md

@@ -1,8 +1,8 @@
 ---
 layout: default
 title: Cross-Cluster Search
-parent: Security
-nav_order: 30
+parent: Security - Access Control
+nav_order: 60
 ---
 
 # Cross-cluster search

docs/security/default-action-groups.md → docs/security-access-control/default-action-groups.md

@@ -1,8 +1,8 @@
 ---
 layout: default
 title: Default Action Groups
-parent: Security
-nav_order: 20
+parent: Security - Access Control
+nav_order: 71
 ---
 
 # Default action groups

docs/security/document-level-security.md → docs/security-access-control/document-level-security.md

@@ -1,8 +1,8 @@
 ---
 layout: default
 title: Document-Level Security
-parent: Security
-nav_order: 23
+parent: Security - Access Control
+nav_order: 2
 ---
 
 # Document-level security

docs/security/field-level-security.md → docs/security-access-control/field-level-security.md

@@ -1,8 +1,8 @@
 ---
 layout: default
 title: Field-Level Security
-parent: Security
-nav_order: 24
+parent: Security - Access Control
+nav_order: 3
 ---
 
 # Field-level security
@@ -95,7 +95,7 @@ someonerole:
 
 ### REST API
 
-See [Create role](../api/#create-role).
+See [Create role](../../security-configuration/api/#create-role).
 
 
 ## Interaction with multiple roles

docs/security/field-masking.md → docs/security-access-control/field-masking.md

@@ -1,8 +1,8 @@
 ---
 layout: default
 title: Field Masking
-parent: Security
-nav_order: 25
+parent: Security - Access Control
+nav_order: 4
 ---
 
 # Field masking
@@ -69,7 +69,7 @@ someonerole:
 
 ### REST API
 
-See [Create role](../api/#create-role).
+See [Create role](../../security-configuration/api/#create-role).
 
 
 ## (Advanced) Use an alternative hash algorithm

docs/security/impersonation.md → docs/security-access-control/impersonation.md

@@ -1,8 +1,8 @@
 ---
 layout: default
 title: User Impersonation
-parent: Security
-nav_order: 22
+parent: Security - Access Control
+nav_order: 5
 ---
 
 # User impersonation

docs/security-access-control/index.md

@@ -0,0 +1,27 @@
+---
+layout: default
+title: Security - Access Control
+nav_order: 6
+has_children: true
+has_toc: false
+---
+
+# Access control
+
+After you [configure the Security plugin](../security-configuration/) to use your own certificates and preferred authentication backend, you can start adding users, creating roles, and mapping roles to users.
+
+This section of the documentation covers what a user is allowed to see and do after successfully authenticating.
+
+
+## Concepts
+
+Term | Description
+:--- | :---
+Permission | An individual action, such as creating an index (e.g. `indices:admin/create`). For a complete list, see [Permissions](permissions/).
+Action group | A set of permissions. For example, the predefined `SEARCH` action group authorizes roles to use the `_search` and `_msearch` APIs.
+Role | Security roles define the scope of a permission or action group: cluster, index, document, or field. For example, a role named `delivery_analyst` might have no cluster permissions, the `READ` action group for all indices that match the `delivery-data-*` pattern, access to all document types within those indices, and access to all fields except `delivery_driver_name`.
+Backend role | (Optional) Additional, external roles that come from an authorization backend (e.g. LDAP/Active Directory).
+User | Users make requests to Elasticsearch clusters. A user has credentials (e.g. a username and password), zero or more backend roles, and zero or more custom attributes.
+Role mapping | Users assume roles after they successfully authenticate. Role mappings, well, map roles to users (or backend roles). For example, a mapping of `kibana_user` (role) to `jdoe` (user) means that John Doe gains all the permissions of `kibana_user` after authenticating. Likewise, a mapping of `all_access` (role) to `admin` (backend role) means that any user with the backend role of `admin` (from an LDAP/Active Directory server) gains all the permissions of `all_access` after authenticating. You can map each role to many users and/or backend roles.
+
+The Security plugin comes with a number of [predefined action groups](default-action-groups/), roles, mappings, and users. These entities serve as sensible defaults and are good examples of how to use the plugin.

docs/security/multi-tenancy.md → docs/security-access-control/multi-tenancy.md

@@ -1,8 +1,8 @@
 ---
 layout: default
 title: Kibana Multi-Tenancy
-parent: Security
-nav_order: 25
+parent: Security - Access Control
+nav_order: 10
 ---
 
 # Kibana multi-tenancy

docs/security/permissions.md → docs/security-access-control/permissions.md

@@ -1,13 +1,13 @@
 ---
 layout: default
 title: Permissions
-parent: Security
-nav_order: 21
+parent: Security - Access Control
+nav_order: 70
 ---
 
 # Permissions
 
-This page is a complete list of available permissions in the Security plugin. Each permission controls access to a data type or API. For more information about permissions, see [Configuration](../configuration).
+This page is a complete list of available permissions in the Security plugin. Each permission controls access to a data type or API. For more information about permissions, see [Configuration](../../security-configuration/configuration).
 
 Rather than creating new action groups from individual permissions, you can often achieve your desired security posture using some combination of the default action groups. To learn more, see [Default Action Groups](../default-action-groups).
 {: .tip }

docs/security-access-control/users-roles.md

@@ -0,0 +1,123 @@
+---
+layout: default
+title: Users and Roles
+parent: Security - Access Control
+nav_order: 1
+---
+
+# Users and roles
+
+The Security plugin includes an internal user database. Use this database in place of or in addition to an external authentication system such as LDAP or Active Directory.
+
+Roles are the core way of controlling access to your cluster. Roles contain any combination of cluster-wide permissions, index-specific permissions, document- and field-level security, and tenants. Then you map users to these roles so that users gain those permissions.
+
+Unless you need to create new [read-only or hidden users](../../security-configuration/api/#read-only-and-hidden-resources), we **highly** recommend using Kibana or the REST API to create new users, roles, and role mappings. The `.yml` files are for initial setup, not ongoing use.
+{: .warning }
+
+---
+
+#### Table of contents
+1. TOC
+{:toc}
+
+
+---
+
+## Create users
+
+You can create users using Kibana, `internal_users.yml`, or the REST API.
+
+### Kibana
+
+1. Choose **Security**, **Internal User Database**, and **Add a new internal user**.
+1. Provide a username and password. The Security plugin automatically hashes the password and stores it in the `.opendistro_security` index.
+1. If desired, specify backend roles and attributes.
+
+   Backend roles differ from security roles. Backend roles are external roles that come from an external authentication system (e.g. LDAP/Active Directory). If you aren't using an external system, you can ignore backend roles.
+
+   Attributes are optional user properties that you can use for variable substitution in index permissions or document-level security.
+
+1. Choose **Submit**.
+
+
+### internal_users.yml
+
+```yml
+logstash:
+  hash: $2a$12$u1ShR4l4uBS3Uv59Pa2y5.1uQuZBrZtmNfqB3iM/.jL0XoV9sghS2
+  roles:
+    - logstash
+```
+
+
+### REST API
+
+See [Create user](../../security-configuration/api/#create-user).
+
+
+## Create roles
+
+Just like users, you can create roles using Kibana, `roles.yml`, or the REST API.
+
+
+### Kibana
+
+1. Choose **Security**, **Roles**, and **Add a new role**.
+1. Provide a name for the role.
+1. Then add
+
+   For example, you might give a role no cluster permissions, `READ` permissions to two indices, `UNLIMITED` permissions to a third index, and read permissions to the `analysts` tenant.
+
+1. Choose **Submit**.
+
+
+### roles.yml
+
+```yml
+someonerole:
+  cluster: []
+  indices:
+    movies:
+      '*':
+      - "READ"
+      _fls_:
+      - "~actors"
+      - "~title"
+      - "~year"
+```
+
+
+### REST API
+
+See [Create role](../../security-configuration/api/#create-role).
+
+
+## Map users to roles
+
+After creating roles, you map users (or backend roles) to them. Intuitively, people often think of this process as giving a user one or more roles, but in the Security plugin, the process is reversed; you select a role and then map one or more users to it.
+
+Just like users and roles, you create role mappings using Kibana, `roles_mapping.yml`, or the REST API.
+
+
+### Kibana
+
+1. Choose **Security**, **Role Mappings**, and **Add a new role mapping**.
+1. Select the role. If a role is greyed-out, a mapping for it already exists. Return to the **Role Mappings** screen and edit the existing mapping.
+1. Specify users, backend roles (roles from from LDAP or Active Directory), and hosts (e.g. `*.devops.my-organization.org`) as desired.
+1. Choose **Submit**.
+
+
+### roles_mapping.yml
+
+```yml
+kibana_user:
+  users:
+    - my-kibana-user
+  backendroles:
+    - kibanauser
+```
+
+
+### REST API
+
+See [Create role mapping](../../security-configuration/api/#create-role-mapping).

docs/security/audit-logs-field-reference.md → docs/security-audit-logs/field-reference.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Audit Log Field Reference
-parent: Security
+parent: Security - Audit Logs
 nav_order: 97
 ---
 

docs/security/audit-logs.md → docs/security-audit-logs/index.md

@@ -1,11 +1,12 @@
 ---
 layout: default
-title: Audit Logs
-parent: Security
-nav_order: 95
+title: Security - Audit Logs
+nav_order: 7
+has_children: true
+has_toc: false
 ---
 
-# Enable audit logs
+# Audit logs
 
 Audit logs let you track access to your Elasticsearch cluster and are useful for compliance purposes or in the aftermath of a security breach. You can configure the categories to be logged, the detail level of the logged messages, and where to store the logs.
 
@@ -17,7 +18,7 @@ To enable audit logging:
    opendistro_security.audit.type: internal_elasticsearch
    ```
 
-   This setting stores audit logs on the current cluster. For other storage options, see [Audit Log Storage Types](../storage-types).
+   This setting stores audit logs on the current cluster. For other storage options, see [Audit Log Storage Types](storage-types/).
 
 2. Restart each node.
 

docs/security/audit-log-storage-types.md → docs/security-audit-logs/storage-types.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Audit Log Storage Types
-parent: Security
+parent: Security - Audit Logs
 nav_order: 96
 ---