Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Add docs for Application Privileges #32635

Merged
merged 19 commits into from
Aug 24, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion docs/reference/redirects.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -538,4 +538,9 @@ native realm:
You can use the following APIs to add, remove, and retrieve role mappings:

* <<security-api-put-role-mapping,Add role mappings>>, <<security-api-delete-role-mapping,Delete role mappings>>
* <<security-api-get-role-mapping,Get role mappings>>
* <<security-api-get-role-mapping,Get role mappings>>

[role="exclude",id="security-api-privileges"]
=== Privilege APIs

See <<security-api-has-privileges>>.
19 changes: 19 additions & 0 deletions x-pack/docs/build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}
}
}
'''
48 changes: 34 additions & 14 deletions x-pack/docs/en/rest-api/security.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -6,65 +6,85 @@ You can use the following APIs to perform {security} activities.

* <<security-api-authenticate>>
* <<security-api-clear-cache>>
* <<security-api-privileges>>
* <<security-api-has-privileges>>
* <<security-api-ssl>>

[float]
[[security-role-apis]]
=== Roles
[[security-api-app-privileges]]
=== Application privileges

You can use the following APIs to add, remove, and retrieve roles in the native realm:
You can use the following APIs to add, update, retrieve, and remove application
privileges:

* <<security-api-put-role,Create role>>, <<security-api-delete-role,Delete role>>
* <<security-api-clear-role-cache,Clear roles cache>>
* <<security-api-get-role,Get roles>>
* <<security-api-put-privileges,Create or update privileges>>
* <<security-api-delete-privilege,Delete privileges>>
* <<security-api-get-privileges,Get privileges>>

[float]
[[security-role-mapping-apis]]
=== Role mappings

You can use the following APIs to add, remove, and retrieve role mappings:
You can use the following APIs to add, remove, update, and retrieve role mappings:

* <<security-api-put-role-mapping,Add role mappings>>, <<security-api-delete-role-mapping,Delete role mappings>>
* <<security-api-put-role-mapping,Create or update role mappings>>
* <<security-api-delete-role-mapping,Delete role mappings>>
* <<security-api-get-role-mapping,Get role mappings>>

[float]
[[security-role-apis]]
=== Roles

You can use the following APIs to add, remove, update, and retrieve roles in the native realm:

* <<security-api-put-role,Create or update roles>>
* <<security-api-clear-role-cache,Clear roles cache>>
* <<security-api-delete-role,Delete roles>>
* <<security-api-get-role,Get roles>>

[float]
[[security-token-apis]]
=== Tokens

You can use the following APIs to create and invalidate bearer tokens for access
without requiring basic authentication:

* <<security-api-get-token,Get token>>, <<security-api-invalidate-token,Invalidate token>>
* <<security-api-get-token,Get token>>
* <<security-api-invalidate-token,Invalidate token>>

[float]
[[security-user-apis]]
=== Users

You can use the following APIs to create, read, update, and delete users from the
You can use the following APIs to add, remove, update, or retrieve users in the
native realm:

* <<security-api-put-user,Create users>>, <<security-api-delete-user,Delete users>>
* <<security-api-enable-user,Enable users>>, <<security-api-disable-user,Disable users>>
* <<security-api-put-user,Create or update users>>
* <<security-api-change-password,Change passwords>>
* <<security-api-delete-user,Delete users>>
* <<security-api-disable-user,Disable users>>
* <<security-api-enable-user,Enable users>>
* <<security-api-get-user,Get users>>


include::security/put-app-privileges.asciidoc[]
include::security/authenticate.asciidoc[]
include::security/change-password.asciidoc[]
include::security/clear-cache.asciidoc[]
include::security/create-role-mappings.asciidoc[]
include::security/clear-roles-cache.asciidoc[]
include::security/create-roles.asciidoc[]
include::security/create-users.asciidoc[]
include::security/delete-app-privileges.asciidoc[]
include::security/delete-role-mappings.asciidoc[]
include::security/delete-roles.asciidoc[]
include::security/delete-tokens.asciidoc[]
include::security/delete-users.asciidoc[]
include::security/disable-users.asciidoc[]
include::security/enable-users.asciidoc[]
include::security/get-app-privileges.asciidoc[]
include::security/get-role-mappings.asciidoc[]
include::security/get-roles.asciidoc[]
include::security/get-tokens.asciidoc[]
include::security/get-users.asciidoc[]
include::security/privileges.asciidoc[]
include::security/has-privileges.asciidoc[]
include::security/ssl.asciidoc[]
Original file line number Diff line number Diff line change
@@ -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

Expand Down
22 changes: 20 additions & 2 deletions x-pack/docs/en/rest-api/security/create-roles.asciidoc
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions x-pack/docs/en/rest-api/security/create-users.asciidoc
Original file line number Diff line number Diff line change
@@ -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_.


Expand Down
59 changes: 59 additions & 0 deletions x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc
Original file line number Diff line number Diff line change
@@ -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

94 changes: 94 additions & 0 deletions x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc
Original file line number Diff line number Diff line change
@@ -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
Loading