[DOCS] Add docs for Application Privileges (#32635)

Author: tvernum

docs/reference/redirects.asciidoc

@@ -533,4 +533,9 @@ native realm:
 You can use the following APIs to add, remove, and retrieve role mappings:
 
 * <<security-api-put-role-mapping,Add role mappings>>, <<security-api-delete-role-mapping,Delete role mappings>>
-* <<security-api-get-role-mapping,Get role mappings>>
+* <<security-api-get-role-mapping,Get role mappings>>
+
+[role="exclude",id="security-api-privileges"]
+=== Privilege APIs
+
+See <<security-api-has-privileges>>.

x-pack/docs/build.gradle

@@ -750,3 +750,22 @@ setups['jacknich_user'] = '''
             "metadata" : { "intelligence" : 7 }
           }
 '''
+setups['app0102_privileges'] = '''
+  - do:
+        xpack.security.put_privileges:
+          body: >
+            {
+              "myapp": {
+                "read": {
+                  "application": "myapp",
+                  "name": "read",
+                  "actions": [
+                    "data:read/*",
+                    "action:login" ], 
+                  "metadata": {
+                    "description": "Read access to myapp"
+                  }
+                }
+              } 
+            }
+'''

x-pack/docs/en/rest-api/security.asciidoc

@@ -6,65 +6,85 @@ You can use the following APIs to perform {security} activities.
 
 * <<security-api-authenticate>>
 * <<security-api-clear-cache>>
-* <<security-api-privileges>>
+* <<security-api-has-privileges>>
 * <<security-api-ssl>>
 
 [float]
-[[security-role-apis]]
-=== Roles
+[[security-api-app-privileges]]
+=== Application privileges
 
-You can use the following APIs to add, remove, and retrieve roles in the native realm:
+You can use the following APIs to add, update, retrieve, and remove application 
+privileges:
 
-* <<security-api-put-role,Create role>>, <<security-api-delete-role,Delete role>>
-* <<security-api-clear-role-cache,Clear roles cache>>
-* <<security-api-get-role,Get roles>>
+* <<security-api-put-privileges,Create or update privileges>> 
+* <<security-api-delete-privilege,Delete privileges>>
+* <<security-api-get-privileges,Get privileges>>
 
 [float]
 [[security-role-mapping-apis]]
 === Role mappings
 
-You can use the following APIs to add, remove, and retrieve role mappings:
+You can use the following APIs to add, remove, update, and retrieve role mappings:
 
-* <<security-api-put-role-mapping,Add role mappings>>, <<security-api-delete-role-mapping,Delete role mappings>>
+* <<security-api-put-role-mapping,Create or update role mappings>> 
+* <<security-api-delete-role-mapping,Delete role mappings>>
 * <<security-api-get-role-mapping,Get role mappings>>
 
+[float]
+[[security-role-apis]]
+=== Roles
+
+You can use the following APIs to add, remove, update, and retrieve roles in the native realm:
+
+* <<security-api-put-role,Create or update roles>>
+* <<security-api-clear-role-cache,Clear roles cache>>
+* <<security-api-delete-role,Delete roles>>
+* <<security-api-get-role,Get roles>>
+
 [float]
 [[security-token-apis]]
 === Tokens
 
 You can use the following APIs to create and invalidate bearer tokens for access
 without requiring basic authentication:
 
-* <<security-api-get-token,Get token>>, <<security-api-invalidate-token,Invalidate token>>
+* <<security-api-get-token,Get token>>
+* <<security-api-invalidate-token,Invalidate token>>
 
 [float]
 [[security-user-apis]]
 === Users
 
-You can use the following APIs to create, read, update, and delete users from the
+You can use the following APIs to add, remove, update, or retrieve users in the
 native realm:
 
-* <<security-api-put-user,Create users>>, <<security-api-delete-user,Delete users>>
-* <<security-api-enable-user,Enable users>>, <<security-api-disable-user,Disable users>>
+* <<security-api-put-user,Create or update users>>
 * <<security-api-change-password,Change passwords>>
+* <<security-api-delete-user,Delete users>>
+* <<security-api-disable-user,Disable users>>
+* <<security-api-enable-user,Enable users>>
 * <<security-api-get-user,Get users>>
 
+
+include::security/put-app-privileges.asciidoc[]
 include::security/authenticate.asciidoc[]
 include::security/change-password.asciidoc[]
 include::security/clear-cache.asciidoc[]
 include::security/create-role-mappings.asciidoc[]
 include::security/clear-roles-cache.asciidoc[]
 include::security/create-roles.asciidoc[]
 include::security/create-users.asciidoc[]
+include::security/delete-app-privileges.asciidoc[]
 include::security/delete-role-mappings.asciidoc[]
 include::security/delete-roles.asciidoc[]
 include::security/delete-tokens.asciidoc[]
 include::security/delete-users.asciidoc[]
 include::security/disable-users.asciidoc[]
 include::security/enable-users.asciidoc[]
+include::security/get-app-privileges.asciidoc[]
 include::security/get-role-mappings.asciidoc[]
 include::security/get-roles.asciidoc[]
 include::security/get-tokens.asciidoc[]
 include::security/get-users.asciidoc[]
-include::security/privileges.asciidoc[]
+include::security/has-privileges.asciidoc[]
 include::security/ssl.asciidoc[]

x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc

@@ -1,8 +1,8 @@
 [role="xpack"]
 [[security-api-put-role-mapping]]
-=== Add role mappings API
+=== Create or update role mappings API
 
-Adds and updates role mappings.
+Creates and updates role mappings.
 
 ==== Request
 

x-pack/docs/en/rest-api/security/create-roles.asciidoc

@@ -1,8 +1,8 @@
 [role="xpack"]
 [[security-api-put-role]]
-=== Create roles API
+=== Create or update roles API
 
-Adds roles in the native realm.
+Adds and updates roles in the native realm.
 
 ==== Request
 
@@ -29,9 +29,20 @@ file-based role management. For more information about the native realm, see
 The following parameters can be specified in the body of a PUT or POST request
 and pertain to adding a role:
 
+`applications`:: (list) A list of application privilege entries.
+`application` (required)::: (string) The name of the application to which this entry applies
+`privileges`::: (list) A list of strings, where each element is the name of an application
+privilege or action.
+`resources`::: (list) A list resources to which the privileges are applied. 
+
 `cluster`:: (list) A list of cluster privileges. These privileges define the
 cluster level actions that users with this role are able to execute.
 
+`global`:: (object) An object defining global privileges. A global privilege is
+a form of cluster privilege that is request-aware. Support for global privileges
+is currently limited to the management of application privileges.
+This field is optional.
+
 `indices`:: (list) A list of indices permissions entries.
 `field_security`::: (list) The document fields that the owners of the role have
 read access to. For more information, see
@@ -79,6 +90,13 @@ POST /_xpack/security/role/my_admin_role
       "query": "{\"match\": {\"title\": \"foo\"}}" // optional
     }
   ],
+  "applications": [
+    {
+      "application": "myapp",
+      "privileges": [ "admin", "read" ],
+      "resources": [ "*" ]
+    }
+  ],
   "run_as": [ "other_user" ], // optional
   "metadata" : { // optional
     "version" : 1

x-pack/docs/en/rest-api/security/create-users.asciidoc

@@ -1,8 +1,8 @@
 [role="xpack"]
 [[security-api-put-user]]
-=== Create users API
+=== Create or update users API
 
-Creates and updates users in the native realm. These users are commonly referred 
+Adds and updates users in the native realm. These users are commonly referred 
 to as _native users_.
 
 

x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc

@@ -0,0 +1,59 @@
+[role="xpack"]
+[[security-api-delete-privilege]]
+=== Delete application privileges API
+
+Removes 
+{stack-ov}/security-privileges.html#application-privileges[application privileges].
+
+==== Request
+
+`DELETE /_xpack/security/privilege/<application>/<privilege>` 
+
+//==== Description
+
+==== Path Parameters
+
+`application` (required)::
+  (string) The name of the application. Application privileges are always
+  associated with exactly one application.
+
+`privilege` (required)::
+  (string) The name of the privilege.
+
+// ==== Request Body
+
+==== Authorization
+
+To use this API, you must have either:
+
+- the `manage_security` cluster privilege (or a greater privilege such as `all`); _or_
+- the _"Manage Application Privileges"_ global privilege for the application being referenced
+  in the request
+
+==== Examples
+
+The following example deletes the `read` application privilege from the 
+`myapp` application:
+
+[source,js]
+--------------------------------------------------
+DELETE /_xpack/security/privilege/myapp/read
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:app0102_privileges] 
+
+If the role is successfully deleted, the request returns `{"found": true}`.
+Otherwise, `found` is set to false.
+
+[source,js]
+--------------------------------------------------
+{
+  "myapp": {
+    "read": {
+      "found" : true
+    }
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE
+

x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc

@@ -0,0 +1,94 @@
+[role="xpack"]
+[[security-api-get-privileges]]
+=== Get application privileges API
+
+Retrieves 
+{stack-ov}/security-privileges.html#application-privileges[application privileges].
+
+==== Request
+
+`GET /_xpack/security/privilege` +
+
+`GET /_xpack/security/privilege/<application>` +
+
+`GET /_xpack/security/privilege/<application>/<privilege>` 
+
+
+==== Description
+
+To check a user's application privileges, use the
+<<security-api-has-privileges,has privileges API>>.
+
+
+==== Path Parameters
+
+`application`::
+  (string) The name of the application. Application privileges are always
+  associated with exactly one application.
+  If you do not specify this parameter, the API returns information about all 
+  privileges for all applications.
+
+`privilege`::
+  (string) The name of the privilege. If you do not specify this parameter, the 
+  API returns information about all privileges for the requested application.
+
+//==== Request Body
+
+==== Authorization
+
+To use this API, you must have either:
+
+- the `manage_security` cluster privilege (or a greater privilege such as `all`); _or_
+- the _"Manage Application Privileges"_ global privilege for the application being referenced
+  in the request
+
+==== Examples
+
+The following example retrieves information about the `read` privilege for the 
+`app01` application:
+
+[source,js]
+--------------------------------------------------
+GET /_xpack/security/privilege/myapp/read
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:app0102_privileges]
+
+A successful call returns an object keyed by application name and privilege
+name. If the privilege is not defined, the request responds with a 404 status.
+
+[source,js]
+--------------------------------------------------
+{
+  "myapp": {
+    "read": {
+      "application": "myapp",
+      "name": "read",
+      "actions": [
+        "data:read/*",
+        "action:login"
+      ],
+      "metadata": {
+        "description": "Read access to myapp"
+      }
+    }
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE
+
+To retrieve all privileges for an application, omit the privilege name:
+
+[source,js]
+--------------------------------------------------
+GET /_xpack/security/privilege/myapp/
+--------------------------------------------------
+// CONSOLE
+
+To retrieve every privilege, omit both the application and privilege names:
+
+[source,js]
+--------------------------------------------------
+GET /_xpack/security/privilege/
+--------------------------------------------------
+// CONSOLE