From 08fdac5a93afe705c338f2a352360ebfadf81909 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 28 Jun 2017 11:02:40 -0700 Subject: [PATCH] [DOCS] Move security APIs to Elasticsearch Ref (elastic/x-pack-elasticsearch#1877) * [DOCS] Move security APIs to Elasticsearch Ref * [DOCS] Update links to security APIs * [DOCS] Fix link to security APIs Original commit: elastic/x-pack-elasticsearch@d7a9d3f1ab4294f2fcdee63d4ca9e1ae9dae0790 --- docs/en/rest-api/index.asciidoc | 6 +++--- docs/en/rest-api/security.asciidoc | 1 + .../en/rest-api/security/authenticate.asciidoc | 1 + .../rest-api/security/change-password.asciidoc | 1 + docs/en/rest-api/security/clear-cache.asciidoc | 4 +++- docs/en/rest-api/security/privileges.asciidoc | 10 ++++++---- .../en/rest-api/security/role-mapping.asciidoc | 3 ++- docs/en/rest-api/security/roles.asciidoc | 4 +++- docs/en/rest-api/security/tokens.asciidoc | 1 + docs/en/rest-api/security/users.asciidoc | 7 ++++--- docs/en/rest-api/xindex.asciidoc | 18 ------------------ docs/en/security/authentication.asciidoc | 5 +++-- .../active-directory-realm.asciidoc | 10 +++++----- .../authentication/ldap-realm.asciidoc | 12 ++++++------ .../authentication/native-realm.asciidoc | 15 ++++++++------- .../security/authentication/pki-realm.asciidoc | 8 ++++---- .../authentication/user-cache.asciidoc | 3 ++- .../authorization/mapping-roles.asciidoc | 2 +- docs/en/security/how-security-works.asciidoc | 9 +++++---- docs/en/security/reference.asciidoc | 2 +- docs/en/security/release-notes.asciidoc | 5 +++-- 21 files changed, 63 insertions(+), 64 deletions(-) delete mode 100644 docs/en/rest-api/xindex.asciidoc diff --git a/docs/en/rest-api/index.asciidoc b/docs/en/rest-api/index.asciidoc index 6d5e4d48fd6..006d22c21db 100644 --- a/docs/en/rest-api/index.asciidoc +++ b/docs/en/rest-api/index.asciidoc @@ -10,7 +10,7 @@ directly to configure and access {xpack} features. * <> * Graph <> * <> -* {xpack-ref}/security-api.html[Security APIs] +* <> * <> -- @@ -18,6 +18,6 @@ directly to configure and access {xpack} features. include::info.asciidoc[] include::graph/explore.asciidoc[] include::ml-api.asciidoc[] -// include::security.asciidoc[] +include::security.asciidoc[] include::watcher.asciidoc[] -include::defs.asciidoc[] \ No newline at end of file +include::defs.asciidoc[] diff --git a/docs/en/rest-api/security.asciidoc b/docs/en/rest-api/security.asciidoc index 3b42154c96b..d80c7c78528 100644 --- a/docs/en/rest-api/security.asciidoc +++ b/docs/en/rest-api/security.asciidoc @@ -1,3 +1,4 @@ +[role="xpack"] [[security-api]] == Security APIs diff --git a/docs/en/rest-api/security/authenticate.asciidoc b/docs/en/rest-api/security/authenticate.asciidoc index ce876dd7677..2f0c24a979b 100644 --- a/docs/en/rest-api/security/authenticate.asciidoc +++ b/docs/en/rest-api/security/authenticate.asciidoc @@ -1,3 +1,4 @@ +[role="xpack"] [[security-api-authenticate]] === Authenticate API diff --git a/docs/en/rest-api/security/change-password.asciidoc b/docs/en/rest-api/security/change-password.asciidoc index b10322eed8e..fb65ba355df 100644 --- a/docs/en/rest-api/security/change-password.asciidoc +++ b/docs/en/rest-api/security/change-password.asciidoc @@ -1,3 +1,4 @@ +[role="xpack"] [[security-api-change-password]] === Change Password API diff --git a/docs/en/rest-api/security/clear-cache.asciidoc b/docs/en/rest-api/security/clear-cache.asciidoc index 10794363f72..c4e06eeff23 100644 --- a/docs/en/rest-api/security/clear-cache.asciidoc +++ b/docs/en/rest-api/security/clear-cache.asciidoc @@ -1,3 +1,4 @@ +[role="xpack"] [[security-api-clear-cache]] === Clear Cache API @@ -29,4 +30,5 @@ POST _xpack/security/realm/default_file,ldap1/_clear_cache ------------------------------------------------------------ // CONSOLE -For more information, see <>. +For more information, see +{xpack-ref}/controlling-user-cache.html[Controlling the User Cache]. diff --git a/docs/en/rest-api/security/privileges.asciidoc b/docs/en/rest-api/security/privileges.asciidoc index 727fc1a053c..e1b42bc9536 100644 --- a/docs/en/rest-api/security/privileges.asciidoc +++ b/docs/en/rest-api/security/privileges.asciidoc @@ -1,3 +1,4 @@ +[role="xpack"] [[security-api-privileges]] === Privilege APIs @@ -6,9 +7,10 @@ The `has_privileges` API allows you to determine whether the logged in user has a specified list of privileges. -All users can use this API, but only to determine their own privileges. -To check the privileges of other users, you must use the -<> feature. +All users can use this API, but only to determine their own privileges. +To check the privileges of other users, you must use the run as feature. For +more information, see +{xpack-ref}/run-as-privilege.html[Submitting Requests on Behalf of Other Users]. To check you privileges, submit a GET request to the `_xpack/security/user/_has_privileges` endpoint: @@ -22,7 +24,7 @@ GET _xpack/security/user/_has_privileges { "names": [ "suppliers", "products" ], "privileges": [ "read" ] - }, + }, { "names": [ "inventory" ], "privileges" : [ "read", "write" ] diff --git a/docs/en/rest-api/security/role-mapping.asciidoc b/docs/en/rest-api/security/role-mapping.asciidoc index c5b4a753417..81ac7e4f1e4 100644 --- a/docs/en/rest-api/security/role-mapping.asciidoc +++ b/docs/en/rest-api/security/role-mapping.asciidoc @@ -1,3 +1,4 @@ +[role="xpack"] [[security-api-role-mapping]] === Role Mapping APIs @@ -6,7 +7,7 @@ To use this API, you must have at least the `manage_security` cluster privilege. NOTE: The API requires that each role-mapping have a distinct name. The name is used solely as an identifier to facilitate interaction via the API, and does - not affect the behaviour of the mapping in any way. + not affect the behavior of the mapping in any way. [[security-api-put-role-mapping]] To add a role-mapping, submit a PUT or POST request to the `/_xpack/security/role_mapping/` diff --git a/docs/en/rest-api/security/roles.asciidoc b/docs/en/rest-api/security/roles.asciidoc index f9e2f764aef..219b111d54a 100644 --- a/docs/en/rest-api/security/roles.asciidoc +++ b/docs/en/rest-api/security/roles.asciidoc @@ -1,3 +1,4 @@ +[role="xpack"] [[security-api-roles]] === Role Management APIs @@ -40,7 +41,8 @@ Within the `metadata` object, keys beginning with `_` are reserved for system usage. The `field_security` and `query` fields are both optional. They are used to -implement <>. +implement field and document level security. For more information, see +{xpack-ref}/field-and-document-access-control.html[Setting Up Field and Document Level Security]. A successful call returns a JSON structure that shows whether the role has been created or updated. diff --git a/docs/en/rest-api/security/tokens.asciidoc b/docs/en/rest-api/security/tokens.asciidoc index 3441bab7781..c1cbf58ed77 100644 --- a/docs/en/rest-api/security/tokens.asciidoc +++ b/docs/en/rest-api/security/tokens.asciidoc @@ -1,3 +1,4 @@ +[role="xpack"] [[security-api-tokens]] === Token Management APIs diff --git a/docs/en/rest-api/security/users.asciidoc b/docs/en/rest-api/security/users.asciidoc index f27483aa5c0..80d08fbe9df 100644 --- a/docs/en/rest-api/security/users.asciidoc +++ b/docs/en/rest-api/security/users.asciidoc @@ -1,3 +1,4 @@ +[role="xpack"] [[security-api-users]] === User Management APIs @@ -10,9 +11,9 @@ To add a user, submit a PUT or POST request to the `/_xpack/security/user/> -* {ref}/watcher-api.html[Watcher APIs] - --- - -include::security.asciidoc[] \ No newline at end of file diff --git a/docs/en/security/authentication.asciidoc b/docs/en/security/authentication.asciidoc index 0d53b60930c..7fab042b6e2 100644 --- a/docs/en/security/authentication.asciidoc +++ b/docs/en/security/authentication.asciidoc @@ -40,7 +40,8 @@ any changes you have applied will be lost. Although they share the same API, the built-in users are separate and distinct from users managed by the <>. Disabling the native realm will not have any effect on the built-in users. The built-in users can -be disabled individually, using the <>. +be disabled individually, using the +{ref}/security-api-users.html[user management API]. [float] [[reset-built-in-user-passwords]] @@ -50,7 +51,7 @@ be disabled individually, using the <>. You must reset the default passwords for all built-in users, and then <>. You can update passwords from the *Management > Users* UI in Kibana or with the -<>: +{ref}/security-api-reset-user-password.html[Reset Password API]: [source,js] --------------------------------------------------------------------- diff --git a/docs/en/security/authentication/active-directory-realm.asciidoc b/docs/en/security/authentication/active-directory-realm.asciidoc index 27055d48bfb..8751c34c91f 100644 --- a/docs/en/security/authentication/active-directory-realm.asciidoc +++ b/docs/en/security/authentication/active-directory-realm.asciidoc @@ -71,9 +71,9 @@ xpack: <3> When this option is enabled, Active Directory groups are automatically mapped to roles of the same name. + -IMPORTANT: When you configure realms in `elasticsearch.yml`, only the -realms you specify are used for authentication. If you also want to use the -`native` or `file` realms, you must include them in the realm chain. +IMPORTANT: When you configure realms in `elasticsearch.yml`, only the +realms you specify are used for authentication. If you also want to use the +`native` or `file` realms, you must include them in the realm chain. . Restart Elasticsearch. @@ -288,7 +288,7 @@ represent user roles for different systems in the organization. The `active_directory` realm enables you to map Active Directory users to roles via their Active Directory groups, or other metadata. This role mapping can be -configured via the <>, or by using +configured via the {ref}/security-api-role-mapping.html[role-mapping API], or by using a file stored on each node. When a user authenticates against an Active Directory realm, the privileges for that user are the union of all privileges defined by the roles to which the user is mapped. @@ -355,7 +355,7 @@ For more information, see <>. ==== User Metadata in Active Directory Realms When a user is authenticated via an Active Directory realm, the following properties are populated in the user's _metadata_. This metadata is returned in the -<>, and can be used with +{ref}/security-api-authenticate.html[authenticate API], and can be used with <> in roles. |======================= diff --git a/docs/en/security/authentication/ldap-realm.asciidoc b/docs/en/security/authentication/ldap-realm.asciidoc index 6e5405debed..cee955a78fd 100644 --- a/docs/en/security/authentication/ldap-realm.asciidoc +++ b/docs/en/security/authentication/ldap-realm.asciidoc @@ -72,9 +72,9 @@ xpack: unmapped_groups_as_roles: false ------------------------------------------------------------ + -IMPORTANT: When you configure realms in `elasticsearch.yml`, only the -realms you specify are used for authentication. If you also want to use the -`native` or `file` realms, you must include them in the realm chain. +IMPORTANT: When you configure realms in `elasticsearch.yml`, only the +realms you specify are used for authentication. If you also want to use the +`native` or `file` realms, you must include them in the realm chain. . Restart Elasticsearch @@ -278,7 +278,7 @@ failover and load balancing modes of operation. impact, `bind_dn` is not exposed via the {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API]. | `bind_password` | no | The password for the user that is used to bind to the - LDAP. Due to its potential security impact, + LDAP. Due to its potential security impact, `bind_password` is not exposed via the {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API]. | `user_search.base_dn` | yes | Specifies a container DN to search for users. @@ -337,7 +337,7 @@ systems in the organization. The `ldap` realm enables you to map LDAP users to to roles via their LDAP groups, or other metadata. This role mapping can be configured via the -<>, or by using a file stored +{ref}/security-api-role-mapping.html[role-mapping API], or by using a file stored on each node. When a user authenticates with LDAP, the privileges for that user are the union of all privileges defined by the roles to which the user is mapped. @@ -395,7 +395,7 @@ For more information, see <>. ==== User Metadata in LDAP Realms When a user is authenticated via an LDAP realm, the following properties are populated in user's _metadata_. This metadata is returned in the -<>, and can be used with +{ref}/security-api-authenticate.html[authenticate API], and can be used with <> in roles. |======================= diff --git a/docs/en/security/authentication/native-realm.asciidoc b/docs/en/security/authentication/native-realm.asciidoc index f70ac511243..1bd05a49f05 100644 --- a/docs/en/security/authentication/native-realm.asciidoc +++ b/docs/en/security/authentication/native-realm.asciidoc @@ -13,9 +13,9 @@ The native realm is added to the realm chain by default. You don't need to explicitly configure a native realm to manage users through the REST APIs. -IMPORTANT: When you configure realms in `elasticsearch.yml`, only the -realms you specify are used for authentication. To use the -`native` realm as a fallback, you must include it in the realm chain. +IMPORTANT: When you configure realms in `elasticsearch.yml`, only the +realms you specify are used for authentication. To use the +`native` realm as a fallback, you must include it in the realm chain. You can, however, configure options for the `native` realm in the `xpack.security.authc.realms` namespace in `elasticsearch.yml`. Explicitly @@ -87,7 +87,8 @@ xpack: [[managing-native-users]] ==== Managing Native Users -You manage users in the `native` realm through the <>. +You manage users in the `native` realm through the +{ref}/security-api-users.html[user API]. [[migrating-from-file]] NOTE: To migrate file-based users to the `native` realm, use the @@ -100,9 +101,9 @@ NOTE: To migrate file-based users to the `native` realm, use the To add a user, submit a PUT or POST request to the `/_xpack/security/user/` endpoint. -Usernames must be at least 1 and no more than 1024 characters. They can -contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, punctuation, and -printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block]. +Usernames must be at least 1 and no more than 1024 characters. They can +contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, 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. [source,js] diff --git a/docs/en/security/authentication/pki-realm.asciidoc b/docs/en/security/authentication/pki-realm.asciidoc index 4eada47ec6f..1757ad30dcc 100644 --- a/docs/en/security/authentication/pki-realm.asciidoc +++ b/docs/en/security/authentication/pki-realm.asciidoc @@ -46,9 +46,9 @@ With this configuration, any certificate trusted by the SSL/TLS layer is accepte for authentication. The username is the common name (CN) extracted from the DN of the certificate. + -IMPORTANT: When you configure realms in `elasticsearch.yml`, only the -realms you specify are used for authentication. If you also want to use the -`native` or `file` realms, you must include them in the realm chain. +IMPORTANT: When you configure realms in `elasticsearch.yml`, only the +realms you specify are used for authentication. If you also want to use the +`native` or `file` realms, you must include them in the realm chain. + If you want to use something other than the CN of the DN as the username, you can specify a regex to extract the desired username. For example, the regex in @@ -118,7 +118,7 @@ xpack: ==== Mapping Roles for PKI Users You map roles for PKI users through the -<>, or by using a file stored on +{ref}/security-api-role-mapping.html[role-mapping API], or by using a file stored on each node. When a user authenticates against a PKI realm, the privileges for that user are the union of all privileges defined by the roles to which the user is mapped. diff --git a/docs/en/security/authentication/user-cache.asciidoc b/docs/en/security/authentication/user-cache.asciidoc index 8e7b43fec21..586aa471a6f 100644 --- a/docs/en/security/authentication/user-cache.asciidoc +++ b/docs/en/security/authentication/user-cache.asciidoc @@ -35,7 +35,8 @@ setting the `cache_hash_algo` setting to any of the following: [[cache-eviction-api]] ==== Evicting Users from the Cache -{security} exposes a <> you can use +{security} exposes a +{ref}/security-api-clear-cache.html[Clear Cache API] you can use to force the eviction of cached users. For example, the following request evicts all users from the `ad1` realm: diff --git a/docs/en/security/authorization/mapping-roles.asciidoc b/docs/en/security/authorization/mapping-roles.asciidoc index 192fe226e5b..3106c16fb72 100644 --- a/docs/en/security/authorization/mapping-roles.asciidoc +++ b/docs/en/security/authorization/mapping-roles.asciidoc @@ -27,7 +27,7 @@ you are able to map users to both API-managed roles and file-managed roles ==== Using the Role Mapping API You can define role-mappings through the -<>. +{ref}/security-api-role-mapping.html[role mapping API]. Each role-mapping has a distinct name which is used to interact with it via the API. The name does not affect the behaviour of the mapping in any way, but it diff --git a/docs/en/security/how-security-works.asciidoc b/docs/en/security/how-security-works.asciidoc index 4576212973f..2e315a048ae 100644 --- a/docs/en/security/how-security-works.asciidoc +++ b/docs/en/security/how-security-works.asciidoc @@ -27,7 +27,8 @@ _realms_. {security} provides the following built-in realms: | `native` | | | An internal realm where users are stored in a dedicated Elasticsearch index. With this realm, users are authenticated by usernames and passwords. The users - are managed via the <>. + are managed via the + {ref}/security-api-users.html[User Management API]. | `ldap` | | | A realm that uses an external LDAP server to authenticate the users. With this realm, users are authenticated by @@ -124,9 +125,9 @@ to, from and within the cluster. This support accounts for: For more information, see <>. {security} also enables you to <> which can -be seen as a light mechanism for node/client authentication. With IP Filtering -you can restrict the nodes and clients that can connect to the cluster based -on their IP addresses. The IP filters configuration provides whitelisting +be seen as a light mechanism for node/client authentication. With IP Filtering +you can restrict the nodes and clients that can connect to the cluster based +on their IP addresses. The IP filters configuration provides whitelisting and blacklisting of IPs, subnets and DNS domains. diff --git a/docs/en/security/reference.asciidoc b/docs/en/security/reference.asciidoc index ba91513eeb5..0e4a3139788 100644 --- a/docs/en/security/reference.asciidoc +++ b/docs/en/security/reference.asciidoc @@ -3,7 +3,7 @@ * <> * {ref}/security-settings.html[Security Settings] * <> -* <> +* {ref}/security-api.html[Security API] include::reference/privileges.asciidoc[] diff --git a/docs/en/security/release-notes.asciidoc b/docs/en/security/release-notes.asciidoc index 604299f5653..5e037a1f2d0 100644 --- a/docs/en/security/release-notes.asciidoc +++ b/docs/en/security/release-notes.asciidoc @@ -82,7 +82,8 @@ April 4, 2016 March 30, 2016 .New Features -* <> with support for <>. +* <> with support for +{ref}/security-api-users.html[user management APIs]. * <> have been added. .Bug Fixes @@ -199,7 +200,7 @@ August 10, 2015 .Bug Fixes * When using the <> mechanism, connection errors during startup no longer cause the node to stop. -* The <> no longer generates invalid JSON. +* The {ref}/security-api-clear-cache.html[Clear Cache API] no longer generates invalid JSON. * The <> starts properly when forwarding the audit events to a remote cluster and uses the correct user to index the audit events.