Merge pull request #449 from keithhc2/od-security-roles-mapping

Updated to include instructions on how to map opendistro_security_roles

Author: keithhc2

docs/security/access-control/api.md

@@ -402,12 +402,15 @@ DELETE _opendistro/_security/api/internalusers/<username>
 
 Creates or replaces the specified user. You must specify either `password` (plain text) or `hash` (the hashed user password). If you specify `password`, the security plugin automatically hashes the password before storing it.
 
+Note that any role you supply in the `opendistro_security_roles` array must already exist for the security plugin to map the user to that role. To see predefined roles, refer to [the list of predefined roles](../users-roles/#predefined-roles). For instructions on how to create a role, refer to [creating a role](./#create-role).
+
 #### Request
 
 ```json
 PUT _opendistro/_security/api/internalusers/<username>
 {
   "password": "kirkpass",
+  "opendistro_security_roles": ["maintenance_staff", "weapons"],
   "backend_roles": ["captains", "starfleet"],
   "attributes": {
     "attribute1": "value1",
@@ -428,7 +431,7 @@ PUT _opendistro/_security/api/internalusers/<username>
 
 ### Patch user
 
-Updates individual attributes of an internal user.
+Updates individual attributes of an internal user. 
 
 #### Request
 
@@ -438,6 +441,9 @@ PATCH _opendistro/_security/api/internalusers/<username>
   {
     "op": "replace", "path": "/backend_roles", "value": ["klingons"]
   },
+  {
+    "op": "replace", "path": "/opendistro_security_roles", "value": ["ship_manager"]
+  },
   {
     "op": "replace", "path": "/attributes", "value": { "newattribute": "newvalue" }
   }

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

@@ -26,7 +26,7 @@ Unless you need to create new [read-only or hidden users](../api/#read-only-and-
 
 ## Create users
 
-You can create users using Kibana, `internal_users.yml`, or the REST API.
+You can create users using Kibana, `internal_users.yml`, or the REST API. When creating a user, you can map users to roles using `internal_users.yml` or the REST API, but that feature is not currently available in Kibana.
 
 ### Kibana
 
@@ -38,7 +38,6 @@ You can create users using Kibana, `internal_users.yml`, or the REST API.
 
 1. Choose **Submit**.
 
-
 ### internal_users.yml
 
 See [YAML files](../../configuration/yaml/#internal_usersyml).
@@ -77,11 +76,10 @@ See [Create role](../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.
+If you didn't specify roles when you created your user, you can map roles to it afterwards.
 
 Just like users and roles, you create role mappings using Kibana, `roles_mapping.yml`, or the REST API.
 
-
 ### Kibana
 
 1. Choose **Security**, **Roles**, and a role.

docs/security/configuration/yaml.md

@@ -34,9 +34,9 @@ new-user:
   reserved: false
   hidden: false
   opendistro_security_roles:
-  - "some-security-role"
+  - "specify-some-security-role-here"
   backend_roles:
-  - "some-backend-role"
+  - "specify-some-backend-role-here"
   attributes:
     attribute1: "value1"
   static: false