Setting Up User Authentication

edit

Setting Up User Authentication

edit

Authentication identifies an individual. To gain access to restricted resources, a user must prove their identity, via passwords, credentials, or some other means (typically referred to as authentication tokens).

In Shield, an authenticated user can submit requests on behalf of other another user if they have the appropriate run_as permission. For more information, see Submitting Requests on Behalf of Other Users.

A realm is an authentication mechanism, which Shield uses to resolve and authenticate users and their roles. Shield currently provides four realm types:

esusers

A native authentication system built into Shield and available by default. See Using esusers to Authenticate Users.

LDAP

Authentication via an external Lightweight Directory Protocol. See Using LDAP to Authenticate Users.

Active Directory

Authentication via an external Active Directory service. See Using Active Directory to Authenticate Users.

PKI

Authentication through the use of trusted X.509 certificates. See Using PKI to Authenticate Users [1.3.0] Added in 1.3.0. .

The esusers, LDAP, and Active Directory realms authenticate using the username and password authentication tokens.

Shield also supports custom realms. If you need to integrate with another authentication system, you can build a custom realm plugin. For more information, see Integrating with Other Authentication Systems.

Realms live within a realm chain. It is essentially a prioritized list of configured realms (typically of various types). The order of the list determines the order in which the realms will be consulted. During the authentication process, Shield will consult and try to authenticate the request one realm at a time. Once one of the realms successfully authenticates the request, the authentication is considered to be successful and the authenticated user will be associated with the request (which will then proceed to the authorization phase). If a realm cannot authenticate the request, the next in line realm in the chain will be consulted. If all realms in the chain could not authenticate the request, the authentication is then considered to be unsuccessful and an authentication error will be returned (as HTTP status code 401).

Shield attempts to authenticate to each configured realm sequentially. Some systems (e.g. Active Directory) have a temporary lock-out period after several successive failed login attempts. If the same username exists in multiple realms, unintentional account lockouts are possible. For more information, please see here.

For example, if UserA exists in both Active Directory and esusers, and the Active Directory realm is checked first and esusers is checked second, an attempt to authenticate as UserA in the esusers realm would first attempt to authenticate against Active Directory and fail, before successfully authenticating against the esusers realm. Because authentication is verified on each request, the Active Directory realm would be checked - and fail - on each request for UserA in the esusers realm. In this case, while the Shield request completed successfully, the account on Active Directory would have received several failed login attempts, and that account may become temporarily locked out. Plan the order of your realms accordingly.

The realm chain can be configured in the elasticsearch.yml file. When not explicitly configured, a default chain will be created that only holds the esusers realm in it. When explicitly configured, the created chain will be the exact reflection of the configuration (e.g. the only realms in the chain will be those configured realms that are enabled)

The following snippet shows an example of realms configuration:

shield.authc:
    realms:
        esusers:
            type: esusers
            order: 0

        ldap1:
            type: ldap
            order: 1
            enabled: false
            url: 'url_to_ldap1'
            ...

        ldap2:
            type: ldap
            order: 2
            url: 'url_to_ldap2'
            ...

        ad1:
            type: active_directory
            order: 3
            url: 'url_to_ad'

As can be seen above, each realm has a unique name that identifies it. There are three settings that are common to all realms:

  • type (required) - Identifies the type of the ream (currently can be esusers, ldap or active_directory). The realm type determines what other settings the realms should be configured with.
  • order (optional) - Defines the priority/index of the realm within the realm chain. This will determine when the realm will be consulted during authentication, with lower order being consulted first.
  • enabled (optional) - When set to false the realm will be disabled and will not be added to the realm chain. This is useful for debugging purposes, where one can remove a realm from the chain without deleting and losing its configuration.

The realm types can roughly be categorized to two categories:

  • internal - Internal realm types are realms that are internal to Elasticsearch and don’t require any communication with external parties - they are fully managed by shield. There can only be a maximum of one configured realm per internal realm type. (Currently, only one internal realm type exists - esusers).
  • external - External realm types are realms that require interaction with parties/components external to Elasticsearch, typically, with enterprise level identity management systems. Unlike the internal realms, there can be as many external realms as one would like - each with a unique name and different settings. (Currently the only external realm types that exist are ldap, active_directory, and pki).