A realm is used to resolve and authenticate users and their roles. Shield supports the following types of realms:

The native, file, 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).

For example, if UserA exists in both Active Directory and the file realm, and the Active Directory realm is checked first and file is checked second, an attempt to authenticate as UserA in the file realm would first attempt to authenticate against Active Directory and fail, before successfully authenticating against the file realm. Because authentication is verified on each request, the Active Directory realm would be checked - and fail - on each request for UserA in the file 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 default realm chain contains the native and file realms. To explicitly, configure a realm chain, you specify the chain in elasticsearch.yml. When you configure a realm chain, only the realms you specify are used for authentication. To use the native and file realms, you must include them in the chain.

The following snippet configures a realm chain that includes the file and native realms, as well as two LDAP realms and an Active Directory realm.

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

        file:
            type: file
            order: 1

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

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

        ad1:
            type: active_directory
            order: 4
            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:

The realm types can roughly be categorized to two categories: