Skip to content

Commit

Permalink
[DOCS] Update snippets in security APIs (#46191) (#46410)
Browse files Browse the repository at this point in the history
  • Loading branch information
lcawl authored Sep 5, 2019
1 parent 3fabe5f commit ab3b5e0
Show file tree
Hide file tree
Showing 30 changed files with 99 additions and 203 deletions.
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

0 comments on commit ab3b5e0

Please sign in to comment.