From 21b12e1deff5fd9bade16903526756410ac65e43 Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Mon, 30 Jul 2018 17:33:34 +1000 Subject: [PATCH 01/19] [DOCS] Add docs for Application Privileges - Adds docs for new _xpack/security/privileges/ APIs - Update docs for Has Privileges API to include "application" privilege checking - Update docs for defining roles (API + guide) to include "application" privileges, and "global" privileges --- x-pack/docs/en/rest-api/security.asciidoc | 4 + .../rest-api/security/app-privileges.asciidoc | 285 ++++++++++++++++++ .../rest-api/security/create-roles.asciidoc | 18 ++ .../en/rest-api/security/get-roles.asciidoc | 6 +- ...leges.asciidoc => has-privileges.asciidoc} | 28 +- .../authorization/managing-roles.asciidoc | 65 +++- 6 files changed, 399 insertions(+), 7 deletions(-) create mode 100644 x-pack/docs/en/rest-api/security/app-privileges.asciidoc rename x-pack/docs/en/rest-api/security/{privileges.asciidoc => has-privileges.asciidoc} (73%) diff --git a/x-pack/docs/en/rest-api/security.asciidoc b/x-pack/docs/en/rest-api/security.asciidoc index f34f119ba7950..8d115681d1317 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -4,8 +4,10 @@ You can use the following APIs to perform {security} activities. +* <> * <> * <> +* <> * <> * <> @@ -49,6 +51,7 @@ native realm: * <> * <> +include::security/app-privileges.asciidoc[] include::security/authenticate.asciidoc[] include::security/change-password.asciidoc[] include::security/clear-cache.asciidoc[] @@ -66,5 +69,6 @@ include::security/get-role-mappings.asciidoc[] include::security/get-roles.asciidoc[] include::security/get-tokens.asciidoc[] include::security/get-users.asciidoc[] +include::security/has-privileges.asciidoc[] include::security/privileges.asciidoc[] include::security/ssl.asciidoc[] diff --git a/x-pack/docs/en/rest-api/security/app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/app-privileges.asciidoc new file mode 100644 index 0000000000000..24951ae9ef46c --- /dev/null +++ b/x-pack/docs/en/rest-api/security/app-privileges.asciidoc @@ -0,0 +1,285 @@ +[role="xpack"] +[[security-api-app-privileges]] +=== Application Privileges APIs + +The Application Privileges API enables you to add, remove, and retrieve +{xpack-ref}/defining-roles.html#roles-application-priv[Application Privileges]. + +==== Request + +`GET /_xpack/security/privilege` + + +`GET /_xpack/security/privilege/` + + +`GET /_xpack/security/privilege//` + + +`DELETE /_xpack/security/privilege//` + + +`POST /_xpack/security/privilege/` + + +`POST /_xpack/security/privilege//` + + +`PUT /_xpack/security/privilege//` + + +==== Description + +Application privileges allow Elasticsearch to act as an _oracle_ for security +decisions that need to take place outside of Elasticsearch. These privileges +do not have any affect on the internal security model for Elasticsearch, they +exist so that applications that run externally to Elasticsearch are able to +make use of, and build their own access controls on top of the Elasticsearch +security infrastructure (Rest API, realms) and security model (users, roles). + +The Application Privileges API enables you to create, modify, delete or retrieve +{xpack-ref}/defining-roles.html#roles-application-priv[Application Privileges] +in a cluster. + +A user's application privileges may be checked by using the +<>. + + +==== Path Parameters + +`application`:: + (string) The name of the application. Application Privileges are always + associated with exactly one application. + The validation rules for application names are described below. + If you do not specify this parameter, then the Get Application Privileges API + returns information about all privileges for all applications. + This parameter is mandatory for the Delete and Put Application Privileges APIs + +`privilege`:: + (string) The name of the privilege. + The validation rules for privilege names are described below. + If you do not specify this parameter, then the Get Application Privileges API + returns information about all privileges for the requested application. + This parameter is mandatory for the Delete and Put Application Privileges APIs + + +==== Request Body + +The GET and DELETE requests do not accept a body. + +For PUT and POST requests where the application name and privilege name are +included as path parameters, the body of the request is a JSON object that +includes the following fields: + +`application`:: (string) The name of the application to which this privilege +belongs. This field is optional, but if it exists it must match the application +name in the path parameter. + +`name`:: (string) The name of the privilege to store. This field is optional, +but if it exists it must match the privilege name in the path parameter. + +`actions`:: (array-of-string) A list of action names that are granted by this +privilege. This field must exist, and may not be an empty array. + +`metadata`:: (object) Optional meta-data. Within the `metadata` object, keys +that begin with `_` are reserved for system usage. + +For POST request that do not include the application and privilege names as +path parameters, the body of the request may define multiple privileges. +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 +follows the same structure as per the PUT request described above. +This endpoint will create or update privileges. It will not remove any +privileges that have been previously defined. + +[[security-api-app-privileges-validation]] +==== Validation + +Application Names:: + Application names are formed from a _prefix_, with an optional _suffix_ that + conform the the following rules: + * The prefix must begin with a lowercase ASCII letter + * The prefix may only contain ASCII letter or digits + * The prefix must be at least 3 characters long + * If the suffix exists, it must begin with either `-` or `_` + * The suffix may not contain any of the following characters: + `\\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, `,`, `*` + * No part of the name may contain whitespace. + +Privilege Names:: + Privilege names must begin with a lowercase ASCII letter, and may only contain + ASCII letter and digits along with the characters `_`, `-` and `.` + +Action Names:: + Action names may contain any number of printable ASCII character, 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 + +[[security-api-put-privilege]] +To add a single privilege, submit a PUT or POST request to the +`/_xpack/security/privilege//` endpoint: + +[source,js] +-------------------------------------------------- +PUT /_xpack/security/privilege/my_app/read +{ + "application": "my_app", <1> + "name": "read", <2> + "actions": [ + "action:login", <3> + "data:read/*" <4> + ], + "metadata" : { <5> + "description" : "Read access to my_add" + } +} +-------------------------------------------------- +// CONSOLE +<1> This field is optional, it is implied by the path parameter +<2> This field is optional, it is implied by the path parameter +<3> This string has significance within the "my_app" application, + Elasticsearch does not assign any meaning to it. +<4> The use of a wildcard here (`*`) means that this privilege grants + access to all actions that start with `data:read/`. Elasticsearch + does not assign any meaning to these actions, however the + <> will respect + the use of a wildcard and return `true` if the request includes an + application privilege such as `data:read/users` or `data:read/settings`. +<5> The metadata object is optional. + +A successful call returns a JSON structure that shows whether the privileg has been +created or updated. + +[source,js] +-------------------------------------------------- +{ + "my_app": { + "read": { + "created": true <1> + } + } +} +-------------------------------------------------- +// TESTRESPONSE +<1> When an existing privilege is updated, `created` is set to false. + +[[security-api-put-privileges]] +To add multiple privileges, submit a POST request to the +`/_xpack/security/privilege/` endpoint: + +[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 privileg has been +created or updated. + +[source,js] +-------------------------------------------------- +{ + "app01": { + "read" : { "created": true }, + "write": { "created": true } + }, + "app02": { + "all": { "created": true } + } +} +-------------------------------------------------- +// TESTRESPONSE + +[[security-api-get-privilege]] +To retrieve a privilege, issue a GET request to the +`/_xpack/security/privilege//` endpoint: + +[source,js] +-------------------------------------------------- +GET /_xpack/security/privilege/app01/read +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +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] +-------------------------------------------------- +{ + "app01": { + "read": { + "application": "app01", + "name": "read", + "actions": [ "action:login", "data:read/*" ], + "metadata": { } + } + } +} +-------------------------------------------------- +// TESTRESPONSE + +To retrieve all privileges for an application, omit the privilege name. + +[source,js] +-------------------------------------------------- +GET /_xpack/security/privilege/app01/ +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +To retrieve every privileges, omit both the application and privilege names. + +[source,js] +-------------------------------------------------- +GET /_xpack/security/privilege/ +-------------------------------------------------- +// CONSOLE +// TEST[continued] + + +[[security-api-delete-privielge]] +To delete a privilege, submit a DELETE request to the +`/_xpack/security/privilege//` endpoint: + +[source,js] +-------------------------------------------------- +DELETE /_xpack/security/privilege/app01/write +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +If the role is successfully deleted, the request returns `{"found": true}`. +Otherwise, `found` is set to false. + +[source,js] +-------------------------------------------------- +{ + "app01": { + "write": { + "found" : true + } + } +} +-------------------------------------------------- +// TESTRESPONSE + diff --git a/x-pack/docs/en/rest-api/security/create-roles.asciidoc b/x-pack/docs/en/rest-api/security/create-roles.asciidoc index 749676b4e8360..5e586fc6ca8cd 100644 --- a/x-pack/docs/en/rest-api/security/create-roles.asciidoc +++ b/x-pack/docs/en/rest-api/security/create-roles.asciidoc @@ -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": "my_app", + "privileges": [ "admin", "read" ], + "resources": [ "*" ] + } + ], "run_as": [ "other_user" ], // optional "metadata" : { // optional "version" : 1 diff --git a/x-pack/docs/en/rest-api/security/get-roles.asciidoc b/x-pack/docs/en/rest-api/security/get-roles.asciidoc index fa6e91b519b6f..2e8501c21e74a 100644 --- a/x-pack/docs/en/rest-api/security/get-roles.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-roles.asciidoc @@ -58,7 +58,11 @@ role. If the role is not defined in the native realm, the request returns 404. "grant" : [ "title", "body" ]} } ], - "applications" : [ ], + "applications" : [ { + "application": "my_app", + "privileges": [ "admin", "read" ], + "resources": [ "*" ] + } ], "run_as" : [ "other_user" ], "metadata" : { "version" : 1 diff --git a/x-pack/docs/en/rest-api/security/privileges.asciidoc b/x-pack/docs/en/rest-api/security/has-privileges.asciidoc similarity index 73% rename from x-pack/docs/en/rest-api/security/privileges.asciidoc rename to x-pack/docs/en/rest-api/security/has-privileges.asciidoc index adaf27e97073e..21a3482bd4dc7 100644 --- a/x-pack/docs/en/rest-api/security/privileges.asciidoc +++ b/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]] @@ -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. @@ -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"/] diff --git a/x-pack/docs/en/security/authorization/managing-roles.asciidoc b/x-pack/docs/en/security/authorization/managing-roles.asciidoc index f550c900edce0..5d53c6cc1b0af 100644 --- a/x-pack/docs/en/security/authorization/managing-roles.asciidoc +++ b/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,54 @@ 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-app-privileges.html#security-api-app-privileges-validation[Application Privileges API]. + +==== Example + +The following snippet shows an example definition of a `clicks_admin` role: [source,js] ----------- POST /_xpack/security/role/clicks_admin From 96a285ff1a62a15c99429ac5bf510a607ea0479f Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Thu, 9 Aug 2018 17:44:27 +1000 Subject: [PATCH 02/19] Fix sample application name to pass validation --- .../en/rest-api/security/app-privileges.asciidoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/app-privileges.asciidoc index 24951ae9ef46c..ea4ee18c75f3e 100644 --- a/x-pack/docs/en/rest-api/security/app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/app-privileges.asciidoc @@ -125,23 +125,23 @@ To add a single privilege, submit a PUT or POST request to the [source,js] -------------------------------------------------- -PUT /_xpack/security/privilege/my_app/read +PUT /_xpack/security/privilege/myapp/read { - "application": "my_app", <1> + "application": "myapp", <1> "name": "read", <2> "actions": [ "action:login", <3> "data:read/*" <4> ], "metadata" : { <5> - "description" : "Read access to my_add" + "description" : "Read access to myapp" } } -------------------------------------------------- // CONSOLE <1> This field is optional, it is implied by the path parameter <2> This field is optional, it is implied by the path parameter -<3> This string has significance within the "my_app" application, +<3> This string has significance within the "myapp" application, Elasticsearch does not assign any meaning to it. <4> The use of a wildcard here (`*`) means that this privilege grants access to all actions that start with `data:read/`. Elasticsearch @@ -151,13 +151,13 @@ PUT /_xpack/security/privilege/my_app/read application privilege such as `data:read/users` or `data:read/settings`. <5> The metadata object is optional. -A successful call returns a JSON structure that shows whether the privileg has been -created or updated. +A successful call returns a JSON structure that shows whether the privilege has +been created or updated. [source,js] -------------------------------------------------- { - "my_app": { + "myapp": { "read": { "created": true <1> } From 21b7366cfb146c8636bbb93e23c5e230c69b1f65 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 15 Aug 2018 16:46:23 -0700 Subject: [PATCH 03/19] [DOCS] Adds delete application privileges API --- x-pack/docs/en/rest-api/security.asciidoc | 2 + .../rest-api/security/app-privileges.asciidoc | 39 ++--------- .../security/delete-app-privileges.asciidoc | 66 +++++++++++++++++++ .../rest-api/security/has-privileges.asciidoc | 2 +- 4 files changed, 74 insertions(+), 35 deletions(-) create mode 100644 x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc diff --git a/x-pack/docs/en/rest-api/security.asciidoc b/x-pack/docs/en/rest-api/security.asciidoc index 8d115681d1317..04b50c3288219 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -7,6 +7,7 @@ You can use the following APIs to perform {security} activities. * <> * <> * <> +* <> * <> * <> * <> @@ -59,6 +60,7 @@ 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[] diff --git a/x-pack/docs/en/rest-api/security/app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/app-privileges.asciidoc index ea4ee18c75f3e..8253e0b98a120 100644 --- a/x-pack/docs/en/rest-api/security/app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/app-privileges.asciidoc @@ -2,7 +2,7 @@ [[security-api-app-privileges]] === Application Privileges APIs -The Application Privileges API enables you to add, remove, and retrieve +The Application Privileges API enables you to add and retrieve {xpack-ref}/defining-roles.html#roles-application-priv[Application Privileges]. ==== Request @@ -13,8 +13,6 @@ The Application Privileges API enables you to add, remove, and retrieve `GET /_xpack/security/privilege//` + -`DELETE /_xpack/security/privilege//` + - `POST /_xpack/security/privilege/` + `POST /_xpack/security/privilege//` + @@ -31,7 +29,7 @@ exist so that applications that run externally to Elasticsearch are able to make use of, and build their own access controls on top of the Elasticsearch security infrastructure (Rest API, realms) and security model (users, roles). -The Application Privileges API enables you to create, modify, delete or retrieve +The Application Privileges API enables you to create, modify or retrieve {xpack-ref}/defining-roles.html#roles-application-priv[Application Privileges] in a cluster. @@ -47,19 +45,19 @@ A user's application privileges may be checked by using the The validation rules for application names are described below. If you do not specify this parameter, then the Get Application Privileges API returns information about all privileges for all applications. - This parameter is mandatory for the Delete and Put Application Privileges APIs + This parameter is mandatory for the Put Application Privileges API. `privilege`:: (string) The name of the privilege. The validation rules for privilege names are described below. If you do not specify this parameter, then the Get Application Privileges API returns information about all privileges for the requested application. - This parameter is mandatory for the Delete and Put Application Privileges APIs + This parameter is mandatory for the Put Application Privileges API. ==== Request Body -The GET and DELETE requests do not accept a body. +The GET requests do not accept a body. For PUT and POST requests where the application name and privilege name are included as path parameters, the body of the request is a JSON object that @@ -256,30 +254,3 @@ GET /_xpack/security/privilege/ // CONSOLE // TEST[continued] - -[[security-api-delete-privielge]] -To delete a privilege, submit a DELETE request to the -`/_xpack/security/privilege//` endpoint: - -[source,js] --------------------------------------------------- -DELETE /_xpack/security/privilege/app01/write --------------------------------------------------- -// CONSOLE -// TEST[continued] - -If the role is successfully deleted, the request returns `{"found": true}`. -Otherwise, `found` is set to false. - -[source,js] --------------------------------------------------- -{ - "app01": { - "write": { - "found" : true - } - } -} --------------------------------------------------- -// TESTRESPONSE - diff --git a/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc new file mode 100644 index 0000000000000..c9363c0a0a26d --- /dev/null +++ b/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc @@ -0,0 +1,66 @@ +[role="xpack"] +[[security-api-delete-privilege]] +=== Delete application privileges API + +Removes application privileges. + +==== Request + +`DELETE /_xpack/security/privilege//` + +==== Description + +For more information about application privileges, see +{stack-ov}/defining-roles.html#roles-application-priv[Application Privileges]. + +To check a user's application privileges, use the +<>. + + +==== 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 `write` application privilege from the +`app01` application: + +[source,js] +-------------------------------------------------- +DELETE /_xpack/security/privilege/app01/write +-------------------------------------------------- +// CONSOLE +// TEST[skip:todo] + +If the role is successfully deleted, the request returns `{"found": true}`. +Otherwise, `found` is set to false. + +[source,js] +-------------------------------------------------- +{ + "app01": { + "write": { + "found" : true + } + } +} +-------------------------------------------------- +// TESTRESPONSE + diff --git a/x-pack/docs/en/rest-api/security/has-privileges.asciidoc b/x-pack/docs/en/rest-api/security/has-privileges.asciidoc index 21a3482bd4dc7..de84485a08678 100644 --- a/x-pack/docs/en/rest-api/security/has-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/has-privileges.asciidoc @@ -49,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] -------------------------------------------------- From c178c6b4e7e0f38e1590b73e5a058ac6f8281d66 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 15 Aug 2018 16:58:22 -0700 Subject: [PATCH 04/19] [DOCS] Adds get application privileges API --- x-pack/docs/en/rest-api/security.asciidoc | 2 + .../rest-api/security/app-privileges.asciidoc | 62 +------------ .../security/get-app-privileges.asciidoc | 93 +++++++++++++++++++ 3 files changed, 96 insertions(+), 61 deletions(-) create mode 100644 x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc diff --git a/x-pack/docs/en/rest-api/security.asciidoc b/x-pack/docs/en/rest-api/security.asciidoc index 04b50c3288219..67cc58c805057 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -8,6 +8,7 @@ You can use the following APIs to perform {security} activities. * <> * <> * <> +* <> * <> * <> * <> @@ -67,6 +68,7 @@ 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[] diff --git a/x-pack/docs/en/rest-api/security/app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/app-privileges.asciidoc index 8253e0b98a120..bf6856f0b1aa2 100644 --- a/x-pack/docs/en/rest-api/security/app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/app-privileges.asciidoc @@ -2,17 +2,11 @@ [[security-api-app-privileges]] === Application Privileges APIs -The Application Privileges API enables you to add and retrieve +The Application Privileges API enables you to add {xpack-ref}/defining-roles.html#roles-application-priv[Application Privileges]. ==== Request -`GET /_xpack/security/privilege` + - -`GET /_xpack/security/privilege/` + - -`GET /_xpack/security/privilege//` + - `POST /_xpack/security/privilege/` + `POST /_xpack/security/privilege//` + @@ -43,22 +37,16 @@ A user's application privileges may be checked by using the (string) The name of the application. Application Privileges are always associated with exactly one application. The validation rules for application names are described below. - If you do not specify this parameter, then the Get Application Privileges API - returns information about all privileges for all applications. This parameter is mandatory for the Put Application Privileges API. `privilege`:: (string) The name of the privilege. The validation rules for privilege names are described below. - If you do not specify this parameter, then the Get Application Privileges API - returns information about all privileges for the requested application. This parameter is mandatory for the Put Application Privileges API. ==== Request Body -The GET requests do not accept a body. - For PUT and POST requests where the application name and privilege name are included as path parameters, the body of the request is a JSON object that includes the following fields: @@ -206,51 +194,3 @@ created or updated. } -------------------------------------------------- // TESTRESPONSE - -[[security-api-get-privilege]] -To retrieve a privilege, issue a GET request to the -`/_xpack/security/privilege//` endpoint: - -[source,js] --------------------------------------------------- -GET /_xpack/security/privilege/app01/read --------------------------------------------------- -// CONSOLE -// TEST[continued] - -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] --------------------------------------------------- -{ - "app01": { - "read": { - "application": "app01", - "name": "read", - "actions": [ "action:login", "data:read/*" ], - "metadata": { } - } - } -} --------------------------------------------------- -// TESTRESPONSE - -To retrieve all privileges for an application, omit the privilege name. - -[source,js] --------------------------------------------------- -GET /_xpack/security/privilege/app01/ --------------------------------------------------- -// CONSOLE -// TEST[continued] - -To retrieve every privileges, omit both the application and privilege names. - -[source,js] --------------------------------------------------- -GET /_xpack/security/privilege/ --------------------------------------------------- -// CONSOLE -// TEST[continued] - diff --git a/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc new file mode 100644 index 0000000000000..00499ebb2586e --- /dev/null +++ b/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc @@ -0,0 +1,93 @@ +[role="xpack"] +[[security-api-get-privilege]] +=== Get application privileges API + +Retrieves application privileges. + +==== Request + +`GET /_xpack/security/privilege` + + +`GET /_xpack/security/privilege/` + + +`GET /_xpack/security/privilege//` + + +==== Description + +For more information about application privileges, see +{stack-ov}/defining-roles.html#roles-application-priv[Application Privileges]. + +To check a user's application privileges, use the +<>. + + +==== 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/app01/read +-------------------------------------------------- +// CONSOLE +// TEST[skip:todo] + +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] +-------------------------------------------------- +{ + "app01": { + "read": { + "application": "app01", + "name": "read", + "actions": [ "action:login", "data:read/*" ], + "metadata": { } + } + } +} +-------------------------------------------------- +// TESTRESPONSE + +To retrieve all privileges for an application, omit the privilege name: + +[source,js] +-------------------------------------------------- +GET /_xpack/security/privilege/app01/ +-------------------------------------------------- +// CONSOLE +// TEST[skip:todo] + +To retrieve every privilege, omit both the application and privilege names: + +[source,js] +-------------------------------------------------- +GET /_xpack/security/privilege/ +-------------------------------------------------- +// CONSOLE + From d52dc1b825793f8d96a16b8347e193338c078879 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 15 Aug 2018 17:32:50 -0700 Subject: [PATCH 05/19] [DOCS] Adds put application privileges API --- x-pack/docs/en/rest-api/security.asciidoc | 4 +- .../rest-api/security/app-privileges.asciidoc | 198 +----------------- .../security/get-app-privileges.asciidoc | 2 +- .../security/put-app-privileges.asciidoc | 189 +++++++++++++++++ 4 files changed, 198 insertions(+), 195 deletions(-) create mode 100644 x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc diff --git a/x-pack/docs/en/rest-api/security.asciidoc b/x-pack/docs/en/rest-api/security.asciidoc index 67cc58c805057..03ad606732c8c 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -7,8 +7,6 @@ You can use the following APIs to perform {security} activities. * <> * <> * <> -* <> -* <> * <> * <> * <> @@ -54,6 +52,8 @@ native realm: * <> include::security/app-privileges.asciidoc[] + +include::security/put-app-privileges.asciidoc[] include::security/authenticate.asciidoc[] include::security/change-password.asciidoc[] include::security/clear-cache.asciidoc[] diff --git a/x-pack/docs/en/rest-api/security/app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/app-privileges.asciidoc index bf6856f0b1aa2..185b360217fa6 100644 --- a/x-pack/docs/en/rest-api/security/app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/app-privileges.asciidoc @@ -1,196 +1,10 @@ -[role="xpack"] +[float] [[security-api-app-privileges]] -=== Application Privileges APIs +=== Application privileges -The Application Privileges API enables you to add -{xpack-ref}/defining-roles.html#roles-application-priv[Application Privileges]. +You can use the following APIs to create, update, retrieve, and delete application +privileges: -==== Request +* <>, <> +* <> -`POST /_xpack/security/privilege/` + - -`POST /_xpack/security/privilege//` + - -`PUT /_xpack/security/privilege//` - - -==== Description - -Application privileges allow Elasticsearch to act as an _oracle_ for security -decisions that need to take place outside of Elasticsearch. These privileges -do not have any affect on the internal security model for Elasticsearch, they -exist so that applications that run externally to Elasticsearch are able to -make use of, and build their own access controls on top of the Elasticsearch -security infrastructure (Rest API, realms) and security model (users, roles). - -The Application Privileges API enables you to create, modify or retrieve -{xpack-ref}/defining-roles.html#roles-application-priv[Application Privileges] -in a cluster. - -A user's application privileges may be checked by using the -<>. - - -==== Path Parameters - -`application`:: - (string) The name of the application. Application Privileges are always - associated with exactly one application. - The validation rules for application names are described below. - This parameter is mandatory for the Put Application Privileges API. - -`privilege`:: - (string) The name of the privilege. - The validation rules for privilege names are described below. - This parameter is mandatory for the Put Application Privileges API. - - -==== Request Body - -For PUT and POST requests where the application name and privilege name are -included as path parameters, the body of the request is a JSON object that -includes the following fields: - -`application`:: (string) The name of the application to which this privilege -belongs. This field is optional, but if it exists it must match the application -name in the path parameter. - -`name`:: (string) The name of the privilege to store. This field is optional, -but if it exists it must match the privilege name in the path parameter. - -`actions`:: (array-of-string) A list of action names that are granted by this -privilege. This field must exist, and may not be an empty array. - -`metadata`:: (object) Optional meta-data. Within the `metadata` object, keys -that begin with `_` are reserved for system usage. - -For POST request that do not include the application and privilege names as -path parameters, the body of the request may define multiple privileges. -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 -follows the same structure as per the PUT request described above. -This endpoint will create or update privileges. It will not remove any -privileges that have been previously defined. - -[[security-api-app-privileges-validation]] -==== Validation - -Application Names:: - Application names are formed from a _prefix_, with an optional _suffix_ that - conform the the following rules: - * The prefix must begin with a lowercase ASCII letter - * The prefix may only contain ASCII letter or digits - * The prefix must be at least 3 characters long - * If the suffix exists, it must begin with either `-` or `_` - * The suffix may not contain any of the following characters: - `\\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, `,`, `*` - * No part of the name may contain whitespace. - -Privilege Names:: - Privilege names must begin with a lowercase ASCII letter, and may only contain - ASCII letter and digits along with the characters `_`, `-` and `.` - -Action Names:: - Action names may contain any number of printable ASCII character, 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 - -[[security-api-put-privilege]] -To add a single privilege, submit a PUT or POST request to the -`/_xpack/security/privilege//` endpoint: - -[source,js] --------------------------------------------------- -PUT /_xpack/security/privilege/myapp/read -{ - "application": "myapp", <1> - "name": "read", <2> - "actions": [ - "action:login", <3> - "data:read/*" <4> - ], - "metadata" : { <5> - "description" : "Read access to myapp" - } -} --------------------------------------------------- -// CONSOLE -<1> This field is optional, it is implied by the path parameter -<2> This field is optional, it is implied by the path parameter -<3> This string has significance within the "myapp" application, - Elasticsearch does not assign any meaning to it. -<4> The use of a wildcard here (`*`) means that this privilege grants - access to all actions that start with `data:read/`. Elasticsearch - does not assign any meaning to these actions, however the - <> will respect - the use of a wildcard and return `true` if the request includes an - application privilege such as `data:read/users` or `data:read/settings`. -<5> 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. - -[[security-api-put-privileges]] -To add multiple privileges, submit a POST request to the -`/_xpack/security/privilege/` endpoint: - -[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 privileg has been -created or updated. - -[source,js] --------------------------------------------------- -{ - "app01": { - "read" : { "created": true }, - "write": { "created": true } - }, - "app02": { - "all": { "created": true } - } -} --------------------------------------------------- -// TESTRESPONSE diff --git a/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc index 00499ebb2586e..c0e438f33b6dd 100644 --- a/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc @@ -1,5 +1,5 @@ [role="xpack"] -[[security-api-get-privilege]] +[[security-api-get-privileges]] === Get application privileges API Retrieves application privileges. diff --git a/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc new file mode 100644 index 0000000000000..daa7c6cd54ec5 --- /dev/null +++ b/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc @@ -0,0 +1,189 @@ +[role="xpack"] +[[security-api-put-privileges]] +=== Add application privileges API + +Creates or updates application privileges. + +==== Request + +`POST /_xpack/security/privilege/` + + +`POST /_xpack/security/privilege//` + + +`PUT /_xpack/security/privilege//` + + +==== Description + +Application privileges enable security decisions to take place outside of {es}. +These privileges do not have any affect on the internal security model for {es}. +They exist so that applications that run externally to {es} are able to +make use of and build their own access controls on top of the {es} security +infrastructure (Rest API, realms) and security model (users, roles). + +This API creates or updates privileges. To remove privileges, use the +<>. + +For more information, see +{stack-ov}/defining-roles.html#roles-application-priv[Application privileges]. + +To check a user's application privileges, use the +<>. + +==== Path Parameters + +`application` (required):: + (string) The name of the application. Application privileges are always + associated with exactly one application. + The validation rules for application names are described below. + +`privilege` (required):: + (string) The name of the privilege. + The validation rules for privilege names are described below. + +==== Request Body + +For PUT and POST requests where the application name and privilege name are +included as path parameters, the body of the request is a JSON object that +includes the following fields: + +`application`:: (string) The name of the application to which this privilege +belongs. This field is optional, but if it exists it must match the application +name in the path parameter. + +`name`:: (string) The name of the privilege to store. This field is optional, +but if it exists it must match the privilege name in the path parameter. + +`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. + +For POST requests that do not include the application and privilege names as +path parameters, the body of the request can define multiple privileges. +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 +follows the same structure as per the PUT request described above. + + +[[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//` endpoint. For example: + +[source,js] +-------------------------------------------------- +PUT /_xpack/security/privilege/myapp/read +{ + "application": "myapp", <1> + "name": "read", <2> + "actions": [ + "action:login", <3> + "data:read/*" <4> + ], + "metadata" : { <5> + "description" : "Read access to myapp" + } +} +-------------------------------------------------- +// CONSOLE +<1> This field is optional; it is implied by the path parameter +<2> This field is optional; it is implied by the path parameter +<3> This string has significance within the "myapp" application, {es} does not + assign any meaning to it. +<4> 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 + <> respects the use of a + wildcard and returns `true`. +<5> 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] +-------------------------------------------------- +{ + "app01": { + "read" : { "created": true }, + "write": { "created": true } + }, + "app02": { + "all": { "created": true } + } +} +-------------------------------------------------- +// TESTRESPONSE From 7e7ac894bcdb37401ed60563e7ed7a020c1064c1 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 15 Aug 2018 17:43:16 -0700 Subject: [PATCH 06/19] [DOCS] Adds code snippet testing for application privilege APIs --- x-pack/docs/build.gradle | 19 +++++++++++++++++++ .../security/delete-app-privileges.asciidoc | 2 +- .../security/get-app-privileges.asciidoc | 6 +++--- 3 files changed, 23 insertions(+), 4 deletions(-) diff --git a/x-pack/docs/build.gradle b/x-pack/docs/build.gradle index 7ef17715e06a0..11779499fa657 100644 --- a/x-pack/docs/build.gradle +++ b/x-pack/docs/build.gradle @@ -750,3 +750,22 @@ setups['jacknich_user'] = ''' "metadata" : { "intelligence" : 7 } } ''' +setups['app0102_privileges'] = ''' + - do: + xpack.security.post_privileges: + body: > + { "app01": { + "read": { + "actions": [ "action:login", "data:read/*" ] + }, + "write": { + "actions": [ "action:login", "data:write/*" ] + } + }, + "app02": { + "all": { + "actions": [ "*" ] + } + } + } +''' diff --git a/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc index c9363c0a0a26d..45ee08925dff4 100644 --- a/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc @@ -47,7 +47,7 @@ The following example deletes the `write` application privilege from the DELETE /_xpack/security/privilege/app01/write -------------------------------------------------- // CONSOLE -// TEST[skip:todo] +// TEST[setup:app0102_privileges] If the role is successfully deleted, the request returns `{"found": true}`. Otherwise, `found` is set to false. diff --git a/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc index c0e438f33b6dd..fd595039a82c3 100644 --- a/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc @@ -54,7 +54,7 @@ The following example retrieves information about the `read` privilege for the GET /_xpack/security/privilege/app01/read -------------------------------------------------- // CONSOLE -// TEST[skip:todo] +// 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. @@ -81,7 +81,7 @@ To retrieve all privileges for an application, omit the privilege name: GET /_xpack/security/privilege/app01/ -------------------------------------------------- // CONSOLE -// TEST[skip:todo] +// TEST[continued] To retrieve every privilege, omit both the application and privilege names: @@ -90,4 +90,4 @@ To retrieve every privilege, omit both the application and privilege names: GET /_xpack/security/privilege/ -------------------------------------------------- // CONSOLE - +// TEST[continued] From 59ffd709a9405877b3c52c4ee7266528f80a31f3 Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 16 Aug 2018 15:57:01 -0700 Subject: [PATCH 07/19] [DOCS] Updates link to application privilege API --- x-pack/docs/en/security/authorization/managing-roles.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/security/authorization/managing-roles.asciidoc b/x-pack/docs/en/security/authorization/managing-roles.asciidoc index 5d53c6cc1b0af..5861ddb05edbf 100644 --- a/x-pack/docs/en/security/authorization/managing-roles.asciidoc +++ b/x-pack/docs/en/security/authorization/managing-roles.asciidoc @@ -133,7 +133,7 @@ The following describes the structure of an application privileges entry: have any special meaning to {security}. For details about the validation rules for these fields, see the -{ref}/security-api-app-privileges.html#security-api-app-privileges-validation[Application Privileges API]. +{ref}/security-api-put-privileges.html[add application privileges API]. ==== Example From dd8b5d94d64c980364636c5aca8479096382e504 Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 16 Aug 2018 16:09:09 -0700 Subject: [PATCH 08/19] [DOCS] Updates link to Stack Overview --- .../security/delete-app-privileges.asciidoc | 13 +++---------- .../rest-api/security/get-app-privileges.asciidoc | 6 ++---- .../en/rest-api/security/has-privileges.asciidoc | 2 +- .../rest-api/security/put-app-privileges.asciidoc | 9 ++------- 4 files changed, 8 insertions(+), 22 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc index 45ee08925dff4..4d45962aa4448 100644 --- a/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc @@ -2,20 +2,14 @@ [[security-api-delete-privilege]] === Delete application privileges API -Removes application privileges. +Removes +{stack-ov}/security-privileges.html#application-privileges[application privileges]. ==== Request `DELETE /_xpack/security/privilege//` -==== Description - -For more information about application privileges, see -{stack-ov}/defining-roles.html#roles-application-priv[Application Privileges]. - -To check a user's application privileges, use the -<>. - +//==== Description ==== Path Parameters @@ -26,7 +20,6 @@ To check a user's application privileges, use the `privilege` (required):: (string) The name of the privilege. - // ==== Request Body ==== Authorization diff --git a/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc index fd595039a82c3..22d5ec3a28acc 100644 --- a/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc @@ -2,7 +2,8 @@ [[security-api-get-privileges]] === Get application privileges API -Retrieves application privileges. +Retrieves +{stack-ov}/security-privileges.html#application-privileges[application privileges]. ==== Request @@ -15,9 +16,6 @@ Retrieves application privileges. ==== Description -For more information about application privileges, see -{stack-ov}/defining-roles.html#roles-application-priv[Application Privileges]. - To check a user's application privileges, use the <>. diff --git a/x-pack/docs/en/rest-api/security/has-privileges.asciidoc b/x-pack/docs/en/rest-api/security/has-privileges.asciidoc index de84485a08678..cae1bc4d303fe 100644 --- a/x-pack/docs/en/rest-api/security/has-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/has-privileges.asciidoc @@ -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. diff --git a/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc index daa7c6cd54ec5..e1720d892d6ce 100644 --- a/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc @@ -2,7 +2,8 @@ [[security-api-put-privileges]] === Add application privileges API -Creates or updates application privileges. +Creates or updates +{stack-ov}/security-privileges.html#application-privileges[application privileges]. ==== Request @@ -15,12 +16,6 @@ Creates or updates application privileges. ==== Description -Application privileges enable security decisions to take place outside of {es}. -These privileges do not have any affect on the internal security model for {es}. -They exist so that applications that run externally to {es} are able to -make use of and build their own access controls on top of the {es} security -infrastructure (Rest API, realms) and security model (users, roles). - This API creates or updates privileges. To remove privileges, use the <>. From 129d4e9ff81b1ca6263b63364d42e3de44c897e6 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 17 Aug 2018 18:09:40 -0700 Subject: [PATCH 09/19] [DOCS] Rebased documentation changes --- docs/reference/redirects.asciidoc | 7 ++++++- x-pack/docs/en/rest-api/security.asciidoc | 5 ++--- .../rest-api-spec/api/xpack.security.has_privileges.json | 2 +- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc index 6498637873a53..b88c7bf4547b4 100644 --- a/docs/reference/redirects.asciidoc +++ b/docs/reference/redirects.asciidoc @@ -538,4 +538,9 @@ native realm: You can use the following APIs to add, remove, and retrieve role mappings: * <>, <> -* <> \ No newline at end of file +* <> + +[role="exclude",id="security-api-privileges"] +=== Privilege APIs + +See <>. diff --git a/x-pack/docs/en/rest-api/security.asciidoc b/x-pack/docs/en/rest-api/security.asciidoc index 03ad606732c8c..beff732c477f4 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -4,13 +4,13 @@ You can use the following APIs to perform {security} activities. -* <> * <> * <> * <> -* <> * <> +include::security/app-privileges.asciidoc[] + [float] [[security-role-apis]] === Roles @@ -51,7 +51,6 @@ native realm: * <> * <> -include::security/app-privileges.asciidoc[] include::security/put-app-privileges.asciidoc[] include::security/authenticate.asciidoc[] diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.has_privileges.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.has_privileges.json index 64b15ae9c0222..9c75b40e4d1a7 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.has_privileges.json +++ b/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", From dd7a179b81c6a11ad0afe90c31a6b34de76085b4 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 17 Aug 2018 20:02:16 -0700 Subject: [PATCH 10/19] [DOCS] Fixes gradle errors --- x-pack/docs/build.gradle | 8 +++- .../rest-api/security/create-roles.asciidoc | 2 +- .../security/delete-app-privileges.asciidoc | 4 +- .../security/get-app-privileges.asciidoc | 10 ++--- .../en/rest-api/security/get-roles.asciidoc | 6 +-- .../security/put-app-privileges.asciidoc | 45 +++++++++---------- 6 files changed, 37 insertions(+), 38 deletions(-) diff --git a/x-pack/docs/build.gradle b/x-pack/docs/build.gradle index 11779499fa657..9965ed6926fa4 100644 --- a/x-pack/docs/build.gradle +++ b/x-pack/docs/build.gradle @@ -752,18 +752,24 @@ setups['jacknich_user'] = ''' ''' setups['app0102_privileges'] = ''' - do: - xpack.security.post_privileges: + xpack.security.put_privileges: body: > { "app01": { "read": { + "application": "app01", + "name": "read", "actions": [ "action:login", "data:read/*" ] }, "write": { + "application": "app01", + "name": "write", "actions": [ "action:login", "data:write/*" ] } }, "app02": { "all": { + "application": "app02", + "name": "all", "actions": [ "*" ] } } diff --git a/x-pack/docs/en/rest-api/security/create-roles.asciidoc b/x-pack/docs/en/rest-api/security/create-roles.asciidoc index 5e586fc6ca8cd..6ae130fdd16c4 100644 --- a/x-pack/docs/en/rest-api/security/create-roles.asciidoc +++ b/x-pack/docs/en/rest-api/security/create-roles.asciidoc @@ -92,7 +92,7 @@ POST /_xpack/security/role/my_admin_role ], "applications": [ { - "application": "my_app", + "application": "myapp", "privileges": [ "admin", "read" ], "resources": [ "*" ] } diff --git a/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc index 4d45962aa4448..0f10e1b551287 100644 --- a/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc @@ -40,7 +40,7 @@ The following example deletes the `write` application privilege from the DELETE /_xpack/security/privilege/app01/write -------------------------------------------------- // CONSOLE -// TEST[setup:app0102_privileges] +// TEST[skip:to-do] If the role is successfully deleted, the request returns `{"found": true}`. Otherwise, `found` is set to false. @@ -55,5 +55,5 @@ Otherwise, `found` is set to false. } } -------------------------------------------------- -// TESTRESPONSE +// NOTCONSOLE diff --git a/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc index 22d5ec3a28acc..9cf7311d344ae 100644 --- a/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc @@ -52,7 +52,7 @@ The following example retrieves information about the `read` privilege for the GET /_xpack/security/privilege/app01/read -------------------------------------------------- // CONSOLE -// TEST[setup:app0102_privileges] +// TEST[skip:to-do] 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. @@ -70,7 +70,7 @@ name. If the privilege is not defined, the request responds with a 404 status. } } -------------------------------------------------- -// TESTRESPONSE +// NOTCONSOLE To retrieve all privileges for an application, omit the privilege name: @@ -78,8 +78,7 @@ To retrieve all privileges for an application, omit the privilege name: -------------------------------------------------- GET /_xpack/security/privilege/app01/ -------------------------------------------------- -// CONSOLE -// TEST[continued] +// NOTCONSOLE To retrieve every privilege, omit both the application and privilege names: @@ -87,5 +86,4 @@ To retrieve every privilege, omit both the application and privilege names: -------------------------------------------------- GET /_xpack/security/privilege/ -------------------------------------------------- -// CONSOLE -// TEST[continued] +// NOTCONSOLE diff --git a/x-pack/docs/en/rest-api/security/get-roles.asciidoc b/x-pack/docs/en/rest-api/security/get-roles.asciidoc index 2e8501c21e74a..fa6e91b519b6f 100644 --- a/x-pack/docs/en/rest-api/security/get-roles.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-roles.asciidoc @@ -58,11 +58,7 @@ role. If the role is not defined in the native realm, the request returns 404. "grant" : [ "title", "body" ]} } ], - "applications" : [ { - "application": "my_app", - "privileges": [ "admin", "read" ], - "resources": [ "*" ] - } ], + "applications" : [ ], "run_as" : [ "other_user" ], "metadata" : { "version" : 1 diff --git a/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc index e1720d892d6ce..57c141a0d69cd 100644 --- a/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc @@ -7,11 +7,9 @@ Creates or updates ==== Request -`POST /_xpack/security/privilege/` + +`POST /_xpack/security/privileges//` + -`POST /_xpack/security/privilege//` + - -`PUT /_xpack/security/privilege//` +`PUT /_xpack/security/privileges//` ==== Description @@ -100,25 +98,26 @@ To add a single privilege, submit a PUT or POST request to the [source,js] -------------------------------------------------- -PUT /_xpack/security/privilege/myapp/read +PUT /_xpack/security/privilege { - "application": "myapp", <1> - "name": "read", <2> - "actions": [ - "action:login", <3> - "data:read/*" <4> - ], - "metadata" : { <5> - "description" : "Read access to myapp" - } + "myapp": { + "read": { + "application": "myapp", + "name": "read", + "actions": [ <1> + "data:read/*" , <2> + "action:login" ], + "metadata": { + "description": "Read access to myapp" + } + } + } } -------------------------------------------------- // CONSOLE -<1> This field is optional; it is implied by the path parameter -<2> This field is optional; it is implied by the path parameter -<3> This string has significance within the "myapp" application, {es} does not - assign any meaning to it. -<4> The use of a wildcard here (`*`) means that this privilege grants access to +<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 @@ -139,7 +138,7 @@ been created or updated. } } -------------------------------------------------- -// TESTRESPONSE +// NOTCONSOLE <1> When an existing privilege is updated, `created` is set to false. To add multiple privileges, submit a POST request to the @@ -147,7 +146,7 @@ To add multiple privileges, submit a POST request to the [source,js] -------------------------------------------------- -PUT /_xpack/security/privilege/ +PUT /_xpack/security/privileges/ { "app01": { "read": { @@ -164,7 +163,7 @@ PUT /_xpack/security/privilege/ } } -------------------------------------------------- -// CONSOLE +// NOTCONSOLE A successful call returns a JSON structure that shows whether the privileges have been created or updated. @@ -181,4 +180,4 @@ have been created or updated. } } -------------------------------------------------- -// TESTRESPONSE +// NOTCONSOLE From e7738e226abc2cbbd015c77d1d8b961df2eccbbf Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 17 Aug 2018 20:16:47 -0700 Subject: [PATCH 11/19] [DOCS] Fixes examples in put application privilege API --- .../security/put-app-privileges.asciidoc | 31 ++++++++++++------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc index 57c141a0d69cd..127ad622a2195 100644 --- a/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc @@ -7,9 +7,9 @@ Creates or updates ==== Request -`POST /_xpack/security/privileges//` + +`POST /_xpack/security/privilege` + -`PUT /_xpack/security/privileges//` +`PUT /_xpack/security/privilege` ==== Description @@ -23,6 +23,7 @@ For more information, see To check a user's application privileges, use the <>. +//// ==== Path Parameters `application` (required):: @@ -33,6 +34,7 @@ To check a user's application privileges, use the `privilege` (required):: (string) The name of the privilege. The validation rules for privilege names are described below. +//// ==== Request Body @@ -55,6 +57,7 @@ that begin with `_` are reserved for system usage. For POST requests that do not include the application and privilege names as path parameters, the body of the request can define multiple privileges. +//TBD: Is the above still valid? 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 @@ -138,7 +141,7 @@ been created or updated. } } -------------------------------------------------- -// NOTCONSOLE +// TESTRESPONSE <1> When an existing privilege is updated, `created` is set to false. To add multiple privileges, submit a POST request to the @@ -146,7 +149,7 @@ To add multiple privileges, submit a POST request to the [source,js] -------------------------------------------------- -PUT /_xpack/security/privileges/ +PUT /_xpack/security/privilege { "app01": { "read": { @@ -163,7 +166,7 @@ PUT /_xpack/security/privileges/ } } -------------------------------------------------- -// NOTCONSOLE +// CONSOLE A successful call returns a JSON structure that shows whether the privileges have been created or updated. @@ -171,13 +174,19 @@ have been created or updated. [source,js] -------------------------------------------------- { - "app01": { - "read" : { "created": true }, - "write": { "created": true } - }, "app02": { - "all": { "created": true } + "all": { + "created": true + } + }, + "app01": { + "read": { + "created": true + }, + "write": { + "created": true + } } } -------------------------------------------------- -// NOTCONSOLE +// TESTRESPONSE From 8858eecaa9bf22e37c8097ec4b0d45d11eaeec92 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 17 Aug 2018 20:36:40 -0700 Subject: [PATCH 12/19] [DOCS] Fixes example for deleting app privileges --- x-pack/docs/build.gradle | 32 ++++++++----------- .../security/delete-app-privileges.asciidoc | 10 +++--- 2 files changed, 18 insertions(+), 24 deletions(-) diff --git a/x-pack/docs/build.gradle b/x-pack/docs/build.gradle index 9965ed6926fa4..6cca05c4a0ef3 100644 --- a/x-pack/docs/build.gradle +++ b/x-pack/docs/build.gradle @@ -754,24 +754,18 @@ setups['app0102_privileges'] = ''' - do: xpack.security.put_privileges: body: > - { "app01": { - "read": { - "application": "app01", - "name": "read", - "actions": [ "action:login", "data:read/*" ] - }, - "write": { - "application": "app01", - "name": "write", - "actions": [ "action:login", "data:write/*" ] - } - }, - "app02": { - "all": { - "application": "app02", - "name": "all", - "actions": [ "*" ] - } + { + "myapp": { + "read": { + "application": "myapp", + "name": "read", + "actions": [ + "data:read/*", + "action:login" ], + "metadata": { + "description": "Read access to myapp" + } + } + } } - } ''' diff --git a/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc index 0f10e1b551287..59d659ede2713 100644 --- a/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc @@ -37,10 +37,10 @@ The following example deletes the `write` application privilege from the [source,js] -------------------------------------------------- -DELETE /_xpack/security/privilege/app01/write +DELETE /_xpack/security/privilege/myapp/read -------------------------------------------------- // CONSOLE -// TEST[skip:to-do] +// TEST[setup:app0102_privileges] If the role is successfully deleted, the request returns `{"found": true}`. Otherwise, `found` is set to false. @@ -48,12 +48,12 @@ Otherwise, `found` is set to false. [source,js] -------------------------------------------------- { - "app01": { - "write": { + "myapp": { + "read": { "found" : true } } } -------------------------------------------------- -// NOTCONSOLE +// TESTRESPONSE From ff55b1f912db9b792741d9c2b40ee566a0c7e9cc Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 17 Aug 2018 20:46:42 -0700 Subject: [PATCH 13/19] [DOCS] Fixes eamples in get application privilege API --- .../security/get-app-privileges.asciidoc | 25 +++++++++++-------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc index 9cf7311d344ae..5412a4bdceb83 100644 --- a/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc @@ -49,10 +49,10 @@ The following example retrieves information about the `read` privilege for the [source,js] -------------------------------------------------- -GET /_xpack/security/privilege/app01/read +GET /_xpack/security/privilege/myapp/read -------------------------------------------------- // CONSOLE -// TEST[skip:to-do] +// 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. @@ -60,25 +60,30 @@ name. If the privilege is not defined, the request responds with a 404 status. [source,js] -------------------------------------------------- { - "app01": { + "myapp": { "read": { - "application": "app01", + "application": "myapp", "name": "read", - "actions": [ "action:login", "data:read/*" ], - "metadata": { } + "actions": [ + "data:read/*", + "action:login" + ], + "metadata": { + "description": "Read access to myapp" + } } } } -------------------------------------------------- -// NOTCONSOLE +// TESTRESPONSE To retrieve all privileges for an application, omit the privilege name: [source,js] -------------------------------------------------- -GET /_xpack/security/privilege/app01/ +GET /_xpack/security/privilege/myapp/ -------------------------------------------------- -// NOTCONSOLE +// CONSOLE To retrieve every privilege, omit both the application and privilege names: @@ -86,4 +91,4 @@ To retrieve every privilege, omit both the application and privilege names: -------------------------------------------------- GET /_xpack/security/privilege/ -------------------------------------------------- -// NOTCONSOLE +// CONSOLE From ee511cb868ff92eca472c4249fd4cca567e58fa2 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 17 Aug 2018 21:01:40 -0700 Subject: [PATCH 14/19] [DOCS] Fixes callouts in example --- .../docs/en/rest-api/security/put-app-privileges.asciidoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc index 127ad622a2195..e8e3b380b04ed 100644 --- a/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc @@ -57,7 +57,9 @@ that begin with `_` are reserved for system usage. For POST requests that do not include the application and privilege names as path parameters, the body of the request can define multiple privileges. + //TBD: Is the above still valid? + 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 @@ -110,7 +112,7 @@ PUT /_xpack/security/privilege "actions": [ <1> "data:read/*" , <2> "action:login" ], - "metadata": { + "metadata": { <3> "description": "Read access to myapp" } } @@ -126,7 +128,7 @@ PUT /_xpack/security/privilege such as `data:read/users` or `data:read/settings`, the <> respects the use of a wildcard and returns `true`. -<5> The metadata object is optional. +<3> The metadata object is optional. A successful call returns a JSON structure that shows whether the privilege has been created or updated. From 711c7561226831cc04a2253230ded98fa8bca539 Mon Sep 17 00:00:00 2001 From: lcawl Date: Sat, 18 Aug 2018 01:06:40 -0700 Subject: [PATCH 15/19] [DOCS] Removes privileges.asciidoc --- x-pack/docs/en/rest-api/security.asciidoc | 1 - 1 file changed, 1 deletion(-) diff --git a/x-pack/docs/en/rest-api/security.asciidoc b/x-pack/docs/en/rest-api/security.asciidoc index beff732c477f4..0921f530cf6e0 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -73,5 +73,4 @@ include::security/get-roles.asciidoc[] include::security/get-tokens.asciidoc[] include::security/get-users.asciidoc[] include::security/has-privileges.asciidoc[] -include::security/privileges.asciidoc[] include::security/ssl.asciidoc[] From 45c58fd19f965e81cde46c11ab7d70e0c3267776 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 20 Aug 2018 16:00:44 -0700 Subject: [PATCH 16/19] [DOCS] Addresses feedback --- .../security/delete-app-privileges.asciidoc | 4 +- .../security/put-app-privileges.asciidoc | 55 ++++--------------- 2 files changed, 14 insertions(+), 45 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc index 59d659ede2713..d7f001721b1fd 100644 --- a/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc @@ -32,8 +32,8 @@ To use this API, you must have either: ==== Examples -The following example deletes the `write` application privilege from the -`app01` application: +The following example deletes the `read` application privilege from the +`myapp` application: [source,js] -------------------------------------------------- diff --git a/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc index e8e3b380b04ed..cfd04d08d2658 100644 --- a/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc @@ -23,48 +23,19 @@ For more information, see To check a user's application privileges, use the <>. -//// -==== Path Parameters - -`application` (required):: - (string) The name of the application. Application privileges are always - associated with exactly one application. - The validation rules for application names are described below. - -`privilege` (required):: - (string) The name of the privilege. - The validation rules for privilege names are described below. -//// - ==== Request Body -For PUT and POST requests where the application name and privilege name are -included as path parameters, the body of the request is a JSON object that +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: -`application`:: (string) The name of the application to which this privilege -belongs. This field is optional, but if it exists it must match the application -name in the path parameter. - -`name`:: (string) The name of the privilege to store. This field is optional, -but if it exists it must match the privilege name in the path parameter. - `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. -For POST requests that do not include the application and privilege names as -path parameters, the body of the request can define multiple privileges. - -//TBD: Is the above still valid? - -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 -follows the same structure as per the PUT request described above. - [[security-api-app-privileges-validation]] ==== Validation @@ -106,17 +77,15 @@ To add a single privilege, submit a PUT or POST request to the PUT /_xpack/security/privilege { "myapp": { - "read": { - "application": "myapp", - "name": "read", - "actions": [ <1> - "data:read/*" , <2> - "action:login" ], - "metadata": { <3> - "description": "Read access to myapp" - } - } - } + "read": { + "actions": [ <1> + "data:read/*" , <2> + "action:login" ], + "metadata": { <3> + "description": "Read access to myapp" + } + } + } } -------------------------------------------------- // CONSOLE From 02daafabac24427716835f1db113d7ace4ad1b3f Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Tue, 21 Aug 2018 18:23:38 +1000 Subject: [PATCH 17/19] Feedback - referential integrity --- .../docs/en/security/authorization/managing-roles.asciidoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/x-pack/docs/en/security/authorization/managing-roles.asciidoc b/x-pack/docs/en/security/authorization/managing-roles.asciidoc index 5861ddb05edbf..43854d492466f 100644 --- a/x-pack/docs/en/security/authorization/managing-roles.asciidoc +++ b/x-pack/docs/en/security/authorization/managing-roles.asciidoc @@ -135,6 +135,12 @@ The following describes the structure of an application privileges entry: 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 +not 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: From e7e5d62743216e6d4ddd2de2c673937fc81bc10e Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Tue, 21 Aug 2018 21:18:58 +1000 Subject: [PATCH 18/19] Fix typo --- x-pack/docs/en/security/authorization/managing-roles.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/security/authorization/managing-roles.asciidoc b/x-pack/docs/en/security/authorization/managing-roles.asciidoc index 43854d492466f..7b30284f58365 100644 --- a/x-pack/docs/en/security/authorization/managing-roles.asciidoc +++ b/x-pack/docs/en/security/authorization/managing-roles.asciidoc @@ -138,7 +138,7 @@ For details about the validation rules for these fields, see the 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 -not effect, and will not grant any actions in the +no effect, and will not grant any actions in the {ref}/security-api-has-privileges.html[has privileges API]. ==== Example From 8a71e1e51723e00e1631017edce17736eef9fa3f Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 23 Aug 2018 11:14:50 -0700 Subject: [PATCH 19/19] [DOCS] Deletes unnecessary files and synchs terminology --- x-pack/docs/en/rest-api/security.asciidoc | 42 ++++++++++++------- .../rest-api/security/app-privileges.asciidoc | 10 ----- .../security/create-role-mappings.asciidoc | 4 +- .../rest-api/security/create-roles.asciidoc | 4 +- .../rest-api/security/create-users.asciidoc | 4 +- .../security/put-app-privileges.asciidoc | 4 +- .../docs/en/rest-api/security/users.asciidoc | 0 7 files changed, 36 insertions(+), 32 deletions(-) delete mode 100644 x-pack/docs/en/rest-api/security/app-privileges.asciidoc delete mode 100644 x-pack/docs/en/rest-api/security/users.asciidoc diff --git a/x-pack/docs/en/rest-api/security.asciidoc b/x-pack/docs/en/rest-api/security.asciidoc index 0921f530cf6e0..3ba582d5d7856 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -9,27 +9,38 @@ You can use the following APIs to perform {security} activities. * <> * <> -include::security/app-privileges.asciidoc[] - [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: -* <>, <> -* <> -* <> +* <> +* <> +* <> [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: -* <>, <> +* <> +* <> * <> +[float] +[[security-role-apis]] +=== Roles + +You can use the following APIs to add, remove, update, and retrieve roles in the native realm: + +* <> +* <> +* <> +* <> + [float] [[security-token-apis]] === Tokens @@ -37,18 +48,21 @@ 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: -* <>, <> +* <> +* <> [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: -* <>, <> -* <>, <> +* <> * <> +* <> +* <> +* <> * <> diff --git a/x-pack/docs/en/rest-api/security/app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/app-privileges.asciidoc deleted file mode 100644 index 185b360217fa6..0000000000000 --- a/x-pack/docs/en/rest-api/security/app-privileges.asciidoc +++ /dev/null @@ -1,10 +0,0 @@ -[float] -[[security-api-app-privileges]] -=== Application privileges - -You can use the following APIs to create, update, retrieve, and delete application -privileges: - -* <>, <> -* <> - diff --git a/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc b/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc index b16ac6ee4dc40..87dedbba4f7cf 100644 --- a/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc +++ b/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 diff --git a/x-pack/docs/en/rest-api/security/create-roles.asciidoc b/x-pack/docs/en/rest-api/security/create-roles.asciidoc index 6ae130fdd16c4..fc3c613557ef0 100644 --- a/x-pack/docs/en/rest-api/security/create-roles.asciidoc +++ b/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 diff --git a/x-pack/docs/en/rest-api/security/create-users.asciidoc b/x-pack/docs/en/rest-api/security/create-users.asciidoc index 5015d0401c223..91171b0e57eb4 100644 --- a/x-pack/docs/en/rest-api/security/create-users.asciidoc +++ b/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_. diff --git a/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc b/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc index cfd04d08d2658..f715a80014bea 100644 --- a/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc +++ b/x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc @@ -1,8 +1,8 @@ [role="xpack"] [[security-api-put-privileges]] -=== Add application privileges API +=== Create or update application privileges API -Creates or updates +Adds or updates {stack-ov}/security-privileges.html#application-privileges[application privileges]. ==== Request diff --git a/x-pack/docs/en/rest-api/security/users.asciidoc b/x-pack/docs/en/rest-api/security/users.asciidoc deleted file mode 100644 index e69de29bb2d1d..0000000000000