Authentication

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).

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

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 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:

The realm types can roughly be categorized to two categories:

The authentication process can be split into two phases - token extraction and user authentication. During the first phase (token extraction phase), the configured realms are requested to try and extract/resolve an authentication token from the incoming request. The first realm that finds an authentication token in the request "wins", meaning, the found authentication token will be used for authentication (moving to the second phase - user authentication - where each realm that support this authentication token type will try to authenticate the user).

In the event where no authentication token was resolved by any of the active realms, the incoming request is considered to be anonymous.

By default, anonymous requests are rejected and an authentication error is returned (status code 401). It is possible to change this behaviour and instruct Shield to associate an default/anonymous user with the anonymous request. This can be done by configuring the following settings in the elasticsearch.yml file:

shield.authc:
	anonymous:
		username: anonymous_user 
		roles: role1, role2