Native User Authentication

The easiest way to manage and authenticate users is with the internal native realm. You use the REST APIs 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.

You can, however, configure options for an native realm in the shield.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 the cache options.

To configure a native realm:

Add a realm configuration of type native to elasticsearch.yml in the shield.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 an native realm.

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

Native Realm Settings

edit

Setting	Required	Description
`type`	yes	Indicates the realm type. Must be set to `native`.
`order`	no	Indicates the priority of this realm within the realm chain. Realms with a lower order are consulted first. Although not required, we recommend explicitly setting this value when you configure multiple realms. Defaults to `Integer.MAX_VALUE`.
`enabled`	no	Indicates whether this realm is enabled or disabled. Enables you to disable a realm without removing its configuration. Defaults to `true`.
`cache.ttl`	no	Specifies the time-to-live for cached user entries. A user’s credentials are cached for this period of time. Specify the time period using the standard Elasticsearch time units. Defaults to `20m`.
`cache.max_users`	no	Specifies the maximum number of user entries that can be stored in the cache at one time. Defaults to 100,000.
`cache.hash_algo`	no	Specifies the hashing algorithm that is used for the cached user credentials. See Cache hash algorithms for the possible values. (Expert Setting)

Managing Native Users

edit

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

Migrating from file-based realm to the native realm

edit

There is a migrate tool to assist in migration of file-based users and roles to the native realm.

Adding Native Users

edit

To add or update a user, submit a PUT or POST request to the /_shield/user/<username> endpoint. A username must be at least 1 character and no longer than 30 characters. The first character must be a letter (a-z or A-Z) or an underscore (_). Subsequent characters can be letters, underscores (_), digits (0-9), or any of the following symbols @, -, . or $

POST /_shield/user/ironman
{
  "password" : "j@rV1s", 
  "roles" : [ "admin", "other_role1" ], 
  "full_name" : "Tony Stark", 
  "email" : "tony@starkcorp.co", 
  "metadata" : { 
    "intelligence" : 7
  }
}

	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 privileges.
	The user’s full name. Optional.
	The user’s email address. Optional.
	Arbirtary metadata you want to associate with the user. Optional.

If you are updating a user, you can omit the password field unless you want to change the user’s password. You must specify the user’s roles. Omitting the optional full_name, email, or metadata fields sets those values to null.

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

{
  "user": {
    "created" : true 
  }
}

When an existing user is updated, created is set to false.

Retrieving Native Users

edit

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

GET /_shield/user

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

GET /_shield/user/ironman,hulk

An array of users is returned that contains the JSON representation of each user. Note that user passwords are not included.

{
  "found" : true, 
  "users" : [
    {
      "username" : "ironman",
      "roles" : [ "admin", "other_role1" ],
      "full_name" : "Tony Stark",
      "email" : "tony@starkcorp.co",
        "metadata" : {
          "intelligence" : 7
        }
      }
    }
  ]
}

If the user is not defined in the native realm, found is set to false.

Deleting Native Users

edit

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

DELETE /_shield/user/ironman

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

{
  "found" : true
}

« Enabling Anonymous Access [1.1.0] Added in 1.1.0. LDAP User Authentication »