[[anonymous-access]]
=== Enabling Anonymous Access added[1.1.0]

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:

[source,yaml]
----------------------------------------
shield.authc:
  anonymous:
    username: anonymous_user <1>
    roles: role1, role2 <2>
    authz_exception: true <3>
----------------------------------------
<1> The username/principal of the anonymous user. This setting is optional and will be set to `_es_anonymous_user` by default
	when not configured.
<2> The roles that will be associated with the anonymous user. This setting is mandatory - without it, anonymous access
	will be disabled (i.e. anonymous requests will be rejected and return an authentication error)
<3> When `true`, a HTTP 403 response will be returned when the anonymous user does not have the appropriate permissions
    for the requested action. The web browser will not be prompt the user to provide credentials to access the requested
    resource. When set to `false`, a HTTP 401 will be returned allowing for credentials to be provided for a user with
    the appropriate permissions. If you are using anonymous access in combination with HTTP, setting this to `false` may
    be necessary if your client does not support preemptive basic authentication. This setting is optional and will be
    set to `true` by default.