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

docs/reference/redirects.asciidoc

@@ -539,3 +539,8 @@ 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>>
+
+[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,28 +6,41 @@ 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
@@ -35,20 +48,25 @@ You can use the following APIs to add, remove, and retrieve role mappings:
 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[]
@@ -56,15 +74,17 @@ 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

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

@@ -1,6 +1,6 @@
 [role="xpack"]
-[[security-api-privileges]]
-=== Privilege APIs
+[[security-api-has-privileges]]
+=== Has Privileges API
 
 [[security-api-has-privilege]]
 
@@ -15,7 +15,7 @@ a specified list of privileges.
 ==== Description
 
 For a list of the privileges that you can specify in this API,
-see {xpack-ref}/security-privileges.html[Security Privileges].
+see {stack-ov}/security-privileges.html[Security privileges].
 
 A successful call returns a JSON structure that shows whether each specified
 privilege is assigned to the user.
@@ -30,6 +30,14 @@ privilege is assigned to the user.
 `privileges`::: (list) A list of the privileges that you want to check for the
 specified indices.
 
+`application`::
+`application`::: (string) The name of the application.
+`privileges`::: (list) A list of the privileges that you want to check for the
+specified resources. May be either application privilege names, or the names of
+actions that are granted by those privileges
+`resources`::: (list) A list of resource names against which the privileges
+should be checked
+
 ==== Authorization
 
 All users can use this API, but only to determine their own privileges.
@@ -41,7 +49,7 @@ more information, see
 ==== Examples
 
 The following example checks whether the current user has a specific set of
-cluster and indices privileges:
+cluster, index, and application privileges:
 
 [source,js]
 --------------------------------------------------
@@ -57,6 +65,13 @@ GET _xpack/security/user/_has_privileges
       "names": [ "inventory" ],
       "privileges" : [ "read", "write" ]
     }
+  ],
+  "application": [
+    {
+      "application": "inventory_manager",
+      "privileges" : [ "read", "data:write/inventory" ],
+      "resources" : [ "product/1852563" ]
+    }
   ]
 }
 --------------------------------------------------
@@ -85,7 +100,14 @@ The following example output indicates which privileges the "rdeniro" user has:
       "write" : false
     }
   },
-  "application" : {}
+  "application" : {
+    "inventory_manager" : {
+      "product/1852563" : {
+        "read": false,
+        "data:write/inventory": false
+      }
+    }
+  }
 }
 --------------------------------------------------
 // TESTRESPONSE[s/"rdeniro"/"$body.username"/]

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

@@ -0,0 +1,163 @@
+[role="xpack"]
+[[security-api-put-privileges]]
+=== Create or update application privileges API
+
+Adds or updates 
+{stack-ov}/security-privileges.html#application-privileges[application privileges].
+
+==== Request
+
+`POST /_xpack/security/privilege` +
+
+`PUT /_xpack/security/privilege`
+
+
+==== Description
+
+This API creates or updates privileges. To remove privileges, use the 
+<<security-api-delete-privilege,delete application privilege API>>. 
+
+For more information, see 
+{stack-ov}/defining-roles.html#roles-application-priv[Application privileges].
+
+To check a user's application privileges, use the
+<<security-api-has-privileges,has privileges API>>.
+
+==== Request Body
+
+The body is a JSON object where the names of the fields are the application
+names and the value of each field is an object. The fields in this inner
+object are the names of the privileges and each value is a JSON object that 
+includes the following fields:
+
+`actions`:: (array-of-string) A list of action names that are granted by this
+privilege. This field must exist and cannot be an empty array.
+
+`metadata`:: (object) Optional meta-data. Within the `metadata` object, keys
+that begin with `_` are reserved for system usage.
+
+
+[[security-api-app-privileges-validation]]
+==== Validation
+
+Application Names::
+    Application names are formed from a _prefix_, with an optional _suffix_ that
+    conform to the following rules:
+    * The prefix must begin with a lowercase ASCII letter
+    * The prefix must contain only ASCII letters or digits
+    * The prefix must be at least 3 characters long
+    * If the suffix exists, it must begin with either `-` or `_`
+    * The suffix cannot contain any of the following characters:
+      `\\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, `,`, `*`
+    * No part of the name can contain whitespace.
+
+Privilege Names::
+    Privilege names must begin with a lowercase ASCII letter and must contain
+    only ASCII letters and digits along with the characters `_`, `-` and `.`
+
+Action Names::
+    Action names can contain any number of printable ASCII characters and must 
+    contain at least one of the following characters: `/` `*`, `:`
+
+==== 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
+
+To add a single privilege, submit a PUT or POST request to the
+`/_xpack/security/privilege/<application>/<privilege>` endpoint. For example:
+
+[source,js]
+--------------------------------------------------
+PUT /_xpack/security/privilege
+{
+  "myapp": {
+    "read": {
+      "actions": [ <1>
+        "data:read/*" , <2> 
+        "action:login" ], 
+        "metadata": { <3>
+          "description": "Read access to myapp"
+        }
+      }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+<1> These strings have significance within the "myapp" application. {es} does not 
+    assign any meaning to them.
+<2> The use of a wildcard here (`*`) means that this privilege grants access to 
+    all actions that start with `data:read/`. {es} does not assign any meaning 
+    to these actions. However, if the request includes an application privilege 
+    such as `data:read/users` or `data:read/settings`, the 
+    <<security-api-has-privileges,has privileges API>> respects the use of a 
+    wildcard and returns `true`.
+<3> The metadata object is optional.
+
+A successful call returns a JSON structure that shows whether the privilege has
+been created or updated.
+
+[source,js]
+--------------------------------------------------
+{
+  "myapp": {
+    "read": {
+      "created": true <1>
+    }
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE
+<1> When an existing privilege is updated, `created` is set to false.
+
+To add multiple privileges, submit a POST request to the 
+`/_xpack/security/privilege/` endpoint. For example:
+
+[source,js]
+--------------------------------------------------
+PUT /_xpack/security/privilege
+{
+  "app01": {
+    "read": {
+      "actions": [ "action:login", "data:read/*" ]
+    },
+    "write": {
+      "actions": [ "action:login", "data:write/*" ]
+    }
+  },
+  "app02": {
+    "all": {
+      "actions": [ "*" ]
+    }
+  }
+}
+--------------------------------------------------
+// CONSOLE
+
+A successful call returns a JSON structure that shows whether the privileges 
+have been created or updated.
+
+[source,js]
+--------------------------------------------------
+{
+  "app02": {
+    "all": {
+      "created": true
+    }
+  },
+  "app01": {
+    "read": {
+      "created": true
+    },
+    "write": {
+      "created": true
+    }
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE

x-pack/docs/en/security/authorization/managing-roles.asciidoc

@@ -9,7 +9,10 @@ A role is defined by the following JSON structure:
 {
   "run_as": [ ... ], <1>
   "cluster": [ ... ], <2>
-  "indices": [ ... ] <3>
+  "global": { ... }, <3>
+  "indices": [ ... ], <4>
+  "applications": [ ... ] <5>
+
 }
 -----
 // NOTCONSOLE
@@ -19,8 +22,15 @@ A role is defined by the following JSON structure:
     cluster level actions users with this role are able to execute. This field
     is optional (missing `cluster` privileges effectively mean no cluster level
     permissions).
-<3> A list of indices permissions entries. This field is optional (missing `indices`
+<3> An object defining global privileges. A global privilege is a form of
+    cluster privilege that is request sensitive. A standard cluster privilege
+    makes authorization decisions based solely on the action being executed.
+    A global privilege also considers the parameters included in the request.
+    Support for global privileges is currently limited to the management of
+    application privileges.  This field is optional.
+<4> A list of indices permissions entries. This field is optional (missing `indices`
     privileges effectively mean no index level permissions).
+<5> A list of application privilege entries. This field is optional.
 
 [[valid-role-name]]
 NOTE: Role names must be at least 1 and no more than 1024 characters. They can
@@ -28,6 +38,9 @@ NOTE: Role names must be at least 1 and no more than 1024 characters. They can
       punctuation, and printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block].
       Leading or trailing whitespace is not allowed.
 
+[[roles-indices-priv]]
+==== Indices Privileges
+
 The following describes the structure of an indices permissions entry:
 
 [source,js]
@@ -77,8 +90,60 @@ names or regular expressions that refer to multiple indices.
 ------------------------------------------------------------------------------
 ==============================================================================
 
-The following snippet shows an example definition of a `clicks_admin` role:
+[[roles-global-priv]]
+==== Global Privileges
+The following describes the structure of a global privileges entry:
 
+[source,js]
+-------
+{
+  "application": {
+    "manage": {    <1>
+        "applications": [ ... ] <2>
+    }
+  }
+}
+-------
+// NOTCONSOLE
+
+<1> The only supported global privilege is the ability to manage application
+    privileges
+<2> The list of application names that may be managed. This list supports
+    wildcards (e.g. `"myapp-*"`) and regular expressions (e.g.
+    `"/app[0-9]*/"`)
+
+[[roles-application-priv]]
+==== Application Privileges
+The following describes the structure of an application privileges entry:
+
+[source,js]
+-------
+{
+  "application": "my_app", <1>
+  "privileges": [ ... ],   <2>
+  "resources": [ ... ]     <3>
+}
+-------
+// NOTCONSOLE
+
+<1> The name of the application.
+<2> The list of the names of the application privileges to grant to this role.
+<3> The resources to which those privileges apply. These are handled in the same
+    way as index name pattern in `indices` permissions. These resources do not
+    have any special meaning to {security}.
+
+For details about the validation rules for these fields, see the
+{ref}/security-api-put-privileges.html[add application privileges API].
+
+A role may refer to application privileges that do not exist - that is, they
+have not yet been defined through the add application privileges API (or they
+were defined, but have since been deleted). In this case, the privilege has
+no effect, and will not grant any actions in the
+{ref}/security-api-has-privileges.html[has privileges API].
+
+==== Example
+
+The following snippet shows an example definition of a `clicks_admin` role:
 [source,js]
 -----------
 POST /_xpack/security/role/clicks_admin

x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.has_privileges.json

@@ -1,6 +1,6 @@
 {
   "xpack.security.has_privileges": {
-    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-privileges.html",
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-has-privileges.html",
     "methods": [ "GET", "POST" ],
     "url": {
       "path": "/_xpack/security/user/_has_privileges",