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] Update snippets in security APIs #46191

Merged
merged 4 commits into from
Sep 5, 2019
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
5 changes: 2 additions & 3 deletions x-pack/docs/en/rest-api/security/authenticate.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -31,15 +31,14 @@ If the user cannot be authenticated, this API returns a 401 status code.
To authenticate a user, submit a GET request to the
`/_security/_authenticate` endpoint:

[source,js]
[source,console]
--------------------------------------------------
GET /_security/_authenticate
--------------------------------------------------
// CONSOLE

The following example output provides information about the "rdeniro" user:

[source,js]
[source,console-result]
--------------------------------------------------
{
"username": "rdeniro",
Expand Down
6 changes: 2 additions & 4 deletions x-pack/docs/en/rest-api/security/change-password.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -51,20 +51,18 @@ For more information about the native realm, see

The following example updates the password for the `jacknich` user:

[source,js]
[source,console]
--------------------------------------------------
POST /_security/user/jacknich/_password
{
"password" : "s3cr3t"
}
--------------------------------------------------
// CONSOLE
// TEST[setup:jacknich_user]

A successful call returns an empty JSON structure.

[source,js]
[source,console-result]
--------------------------------------------------
{}
--------------------------------------------------
// TESTRESPONSE
9 changes: 3 additions & 6 deletions x-pack/docs/en/rest-api/security/clear-cache.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -44,25 +44,22 @@ To evict roles from the role cache, see the

For example, to evict all users cached by the `file` realm:

[source,js]
[source,console]
--------------------------------------------------
POST /_security/realm/default_file/_clear_cache
--------------------------------------------------
// CONSOLE

To evict selected users, specify the `usernames` parameter:

[source,js]
[source,console]
--------------------------------------------------
POST /_security/realm/default_file/_clear_cache?usernames=rdeniro,alpacino
--------------------------------------------------
// CONSOLE

To clear the caches for multiple realms, specify the realms as a comma-delimited
list:

[source, js]
[source,console]
------------------------------------------------------------
POST /_security/realm/default_file,ldap1/_clear_cache
------------------------------------------------------------
// CONSOLE
3 changes: 1 addition & 2 deletions x-pack/docs/en/rest-api/security/clear-roles-cache.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,7 @@ For more information about the native realm, see
The clear roles cache API evicts roles from the native role cache. For example,
to clear the cache for `my_admin_role`:

[source,js]
[source,console]
--------------------------------------------------
POST /_security/role/my_admin_role/_clear_cache
--------------------------------------------------
// CONSOLE
5 changes: 2 additions & 3 deletions x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ expire.

The following example creates an API key:

[source, js]
[source,console]
------------------------------------------------------------
POST /_security/api_key
{
Expand Down Expand Up @@ -93,7 +93,6 @@ POST /_security/api_key
}
}
------------------------------------------------------------
// CONSOLE
<1> optional expiration for the API key being generated. If expiration is not
provided then the API keys do not expire.
<2> optional role descriptors for this API key, if not provided then permissions
Expand All @@ -102,7 +101,7 @@ POST /_security/api_key
A successful call returns a JSON structure that provides
API key information.

[source,js]
[source,console-result]
--------------------------------------------------
{
"id":"VuaCfGcBCdbkQm-e5aOx", <1>
Expand Down
30 changes: 10 additions & 20 deletions x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ The Examples section below demonstrates the use of templated role names.

The following example assigns the "user" role to all users:

[source, js]
[source,console]
------------------------------------------------------------
POST /_security/role_mapping/mapping1
{
Expand All @@ -119,28 +119,26 @@ POST /_security/role_mapping/mapping1
}
}
------------------------------------------------------------
// CONSOLE
<1> Mappings that have `enabled` set to `false` are ignored when role mapping
is performed.
<2> Metadata is optional.

A successful call returns a JSON structure that shows whether the mapping has
been created or updated.

[source,js]
[source,console-result]
--------------------------------------------------
{
"role_mapping" : {
"created" : true <1>
}
}
--------------------------------------------------
// TESTRESPONSE
<1> When an existing mapping is updated, `created` is set to false.

The following example assigns the "user" and "admin" roles to specific users:

[source,js]
[source,console]
--------------------------------------------------
POST /_security/role_mapping/mapping2
{
Expand All @@ -151,10 +149,9 @@ POST /_security/role_mapping/mapping2
}
}
--------------------------------------------------
// CONSOLE

The following example matches users who authenticated against a specific realm:
[source, js]
[source,console]
------------------------------------------------------------
POST /_security/role_mapping/mapping3
{
Expand All @@ -165,12 +162,11 @@ POST /_security/role_mapping/mapping3
}
}
------------------------------------------------------------
// CONSOLE

The following example matches any user where either the username is `esadmin`
or the user is in the `cn=admin,dc=example,dc=com` group:

[source, js]
[source,console]
------------------------------------------------------------
POST /_security/role_mapping/mapping4
{
Expand All @@ -192,7 +188,6 @@ POST /_security/role_mapping/mapping4
}
}
------------------------------------------------------------
// CONSOLE

The example above is useful when the group names in your identity management
system (such as Active Directory, or a SAML Identity Provider) do not have a
Expand All @@ -213,7 +208,7 @@ roles is inefficient and can have a negative effect on system performance.
If you only need to map a subset of the groups, then you should do this
using explicit mappings.

[source, js]
[source,console]
------------------------------------------------------------
POST /_security/role_mapping/mapping5
{
Expand All @@ -229,15 +224,14 @@ POST /_security/role_mapping/mapping5
"enabled": true
}
------------------------------------------------------------
// CONSOLE
<1> The `tojson` mustache function is used to convert the list of
group names into a valid JSON array.
<2> Because the template produces a JSON array, the format must be
set to `json`.

The following example matches users within a specific LDAP sub-tree:

[source, js]
[source,console]
------------------------------------------------------------
POST /_security/role_mapping/mapping6
{
Expand All @@ -248,12 +242,11 @@ POST /_security/role_mapping/mapping6
}
}
------------------------------------------------------------
// CONSOLE

The following example matches users within a particular LDAP sub-tree in a
specific realm:

[source, js]
[source,console]
------------------------------------------------------------
POST /_security/role_mapping/mapping7
{
Expand All @@ -267,7 +260,6 @@ POST /_security/role_mapping/mapping7
}
}
------------------------------------------------------------
// CONSOLE

The rules can be more complex and include wildcard matching. For example, the
following mapping matches any user where *all* of these conditions are met:
Expand All @@ -278,7 +270,7 @@ following mapping matches any user where *all* of these conditions are met:
- the user does not have a `terminated_date`


[source, js]
[source,console]
------------------------------------------------------------
POST /_security/role_mapping/mapping8
{
Expand Down Expand Up @@ -316,7 +308,6 @@ POST /_security/role_mapping/mapping8
}
}
------------------------------------------------------------
// CONSOLE

A templated role can be used to automatically map every user to their own
custom role. The role itself can be defined through the
Expand All @@ -329,7 +320,7 @@ role that is their username prefixed with `_user_`.
As an example, the user `nwong` would be assigned the `saml_user` and
`_user_nwong` roles.

[source, js]
[source,console]
------------------------------------------------------------
POST /_security/role_mapping/mapping9
{
Expand All @@ -341,7 +332,6 @@ POST /_security/role_mapping/mapping9
"enabled": true
}
------------------------------------------------------------
// CONSOLE
<1> Because it is not possible to specify both `roles` and `role_templates` in
the same role mapping, we can apply a "fixed name" role by using a template
that has no substitutions.
Expand Down
6 changes: 2 additions & 4 deletions x-pack/docs/en/rest-api/security/create-roles.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ For more information, see {stack-ov}/defining-roles.html[Defining roles].

The following example adds a role called `my_admin_role`:

[source,js]
[source,console]
--------------------------------------------------
POST /_security/role/my_admin_role
{
Expand Down Expand Up @@ -110,18 +110,16 @@ POST /_security/role/my_admin_role
}
}
--------------------------------------------------
// CONSOLE

A successful call returns a JSON structure that shows whether the role has been
created or updated.

[source,js]
[source,console-result]
--------------------------------------------------
{
"role": {
"created": true <1>
}
}
--------------------------------------------------
// TESTRESPONSE
<1> When an existing role is updated, `created` is set to false.
6 changes: 2 additions & 4 deletions x-pack/docs/en/rest-api/security/create-users.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ access permissions. To create a user without any roles, specify an empty list:

The following example creates a user `jacknich`:

[source,js]
[source,console]
--------------------------------------------------
POST /_security/user/jacknich
{
Expand All @@ -117,18 +117,16 @@ POST /_security/user/jacknich
}
}
--------------------------------------------------
// CONSOLE

A successful call returns a JSON structure that shows whether the user has been
created or updated.

[source,js]
[source,console-result]
--------------------------------------------------
{
"created": true <1>
}
--------------------------------------------------
// TESTRESPONSE
<1> When an existing user is updated, `created` is set to false.

After you add a user, requests from that user can be authenticated. For example:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -73,19 +73,18 @@ client's certificate.

The following is an example request:

[source, js]
[source,console]
------------------------------------------------------------
POST /_security/delegate_pki
{
"x509_certificate_chain": ["MIIDbTCCAlWgAwIBAgIJAIxTS7Qdho9jMA0GCSqGSIb3DQEBCwUAMFMxKzApBgNVBAMTIkVsYXN0aWNzZWFyY2ggVGVzdCBJbnRlcm1lZGlhdGUgQ0ExFjAUBgNVBAsTDUVsYXN0aWNzZWFyY2gxDDAKBgNVBAoTA29yZzAeFw0xOTA3MTkxMzMzNDFaFw0yMzA3MTgxMzMzNDFaMEoxIjAgBgNVBAMTGUVsYXN0aWNzZWFyY2ggVGVzdCBDbGllbnQxFjAUBgNVBAsTDUVsYXN0aWNzZWFyY2gxDDAKBgNVBAoTA29yZzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANHgMX2aX8t0nj4sGLNuKISmmXIYCj9RwRqS7L03l9Nng7kOKnhHu/nXDt7zMRJyHj+q6FAt5khlavYSVCQyrDybRuA5z31gOdqXerrjs2OXS5HSHNvoDAnHFsaYX/5geMewVTtc/vqpd7Ph/QtaKfmG2FK0JNQo0k24tcgCIcyMtBh6BA70yGBM0OT8GdOgd/d/mA7mRhaxIUMNYQzRYRsp4hMnnWoOTkR5Q8KSO3MKw9dPSpPe8EnwtJE10S3s5aXmgytru/xQqrFycPBNj4KbKVmqMP0G60CzXik5pr2LNvOFz3Qb6sYJtqeZF+JKgGWdaTC89m63+TEnUHqk0lcCAwEAAaNNMEswCQYDVR0TBAIwADAdBgNVHQ4EFgQU/+aAD6Q4mFq1vpHorC25/OY5zjcwHwYDVR0jBBgwFoAU8siFCiMiYZZm/95qFC75AG/LRE0wDQYJKoZIhvcNAQELBQADggEBAIRpCgDLpvXcgDHUk10uhxev21mlIbU+VP46ANnCuj0UELhTrdTuWvO1PAI4z+WbDUxryQfOOXO9R6D0dE5yR56L/J7d+KayW34zU7yRDZM7+rXpocdQ1Ex8mjP9HJ/Bf56YZTBQJpXeDrKow4FvtkI3bcIMkqmbG16LHQXeG3RS4ds4S4wCnE2nA6vIn9y+4R999q6y1VSBORrYULcDWxS54plHLEdiMr1vVallg82AGobS9GMcTL2U4Nx5IYZG7sbTk3LrDxVpVg/S2wLofEdOEwqCeHug/iOihNLJBabEW6z4TDLJAVW5KCY1DfhkYlBfHn7vxKkfKoCUK/yLWWI="] <1>
}
------------------------------------------------------------
// CONSOLE
<1> A one element certificate chain.

Which returns the following response:

[source,js]
[source,console-result]
--------------------------------------------------
{
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -38,17 +38,16 @@ To use this API, you must have either:
The following example deletes the `read` application privilege from the
`myapp` application:

[source,js]
[source,console]
--------------------------------------------------
DELETE /_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]
[source,console-result]
--------------------------------------------------
{
"myapp": {
Expand All @@ -58,5 +57,3 @@ Otherwise, `found` is set to false.
}
}
--------------------------------------------------
// TESTRESPONSE

Original file line number Diff line number Diff line change
Expand Up @@ -37,20 +37,18 @@ see {stack-ov}/mapping-roles.html[Mapping users and groups to roles].

The following example delete a role mapping:

[source,js]
[source,console]
--------------------------------------------------
DELETE /_security/role_mapping/mapping1
--------------------------------------------------
// CONSOLE
// TEST[setup:role_mapping]

If the mapping is successfully deleted, the request returns `{"found": true}`.
Otherwise, `found` is set to false.

[source,js]
[source,console-result]
--------------------------------------------------
{
"found" : true
}
--------------------------------------------------
// TESTRESPONSE
Loading