WARNING: Version 5.6 of the Elastic Stack has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« Enabling Anonymous Access LDAP User Authentication »

› › ›

Native User Authentication

edit

Native User Authentication

edit

The easiest way to manage and authenticate users is with the internal native realm. You can use the REST APIs or Kibana to add and remove users, assign user roles, and manage user passwords.

Configuring a Native Realm

edit

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.

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 configuring a native realm enables you to set the order in which it appears in the realm chain, temporary disable the realm, and control its cache options.

To configure a native realm:

Add a realm configuration of type native to elasticsearch.yml under the xpack.security.authc.realms namespace. At a minimum, you must set the realm type to native. If you are configuring multiple realms, you should also explicitly set the order attribute. See Native Realm Settings for all of the options you can set for the native realm.

For example, the following snippet shows a native realm configuration that sets the order to zero so the realm is checked first:
```
xpack:
  security:
    authc:
      realms:
        native1:
          type: native
          order: 0
```
Restart Elasticsearch.

Native Realm Settings

edit

See Native realm settings.

Managing Native Users

edit

You manage users in the native realm through the user API.

To migrate file-based users to the native realm, use the migrate tool.

Adding Users

edit

To add a user, submit a PUT or POST request to the /_xpack/security/user/<username> 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 Basic Latin (ASCII) block. Leading or trailing whitespace is not allowed.

POST /_xpack/security/user/jacknich
{
  "password" : "j@rV1s", 
  "roles" : [ "admin", "other_role1" ], 
  "full_name" : "Jack Nicholson", 
  "email" : "jacknich@example.com", 
  "metadata" : { 
    "intelligence" : 7
  },
  "enabled": true 
}

	You must specify a password when adding a user. Passwords must be at least 6 characters long.
	You must assign at least one role to the user. The roles determine the user’s access permissions.
	The user’s full name. Optional.
	The user’s email address. Optional.
	Arbitrary metadata you want to associate with the user. Optional.
	Specifies whether the user should be enabled. Optional with a default of true.

Retrieving Users

edit

To retrieve all users, submit a GET request to the /_xpack/security/user endpoint:

GET /_xpack/security/user

To retrieve particular users, specify the users as a comma-separated list:

GET /_xpack/security/user/jacknich,rdeniro

An object is returned holding the found users, each keyed by the relevant username. Note that user passwords are not included.

{
  "jacknich" : {
    "username": "jacknich",
    "roles" : [ "admin", "other_role1" ],
    "full_name" : "Jack Nicholson",
    "email" : "jacknich@example.com",
    "enabled" : true,
    "metadata" : {
      "intelligence" : 7
    }
  }
}

Deleting Users

edit

To delete a user, submit a DELETE request to the /_xpack/security/user/<username> endpoint:

DELETE /_xpack/security/user/jacknich

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

{
  "found" : true
}

« Enabling Anonymous Access LDAP User Authentication »