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

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:

  1. 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
  2. Restart Elasticsearch.
Native Realm Settings

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

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

Migrating from file-based realm to the native realm

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

Adding Native Users

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.

Note

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

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

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
}