Security

Active contributors: Ioana Tagirta, Albert Zaharovits, Tim Vernum

Purpose

X-Pack security adds authentication, authorization, audit, and TLS/encryption to Elasticsearch. The server has to call out to security at hot paths (every transport action, every REST request, every shard read), so security is integrated as a set of Plugin hooks rather than as a separate process.

Source layout

x-pack/plugin/security/
├── src/main/java/org/elasticsearch/xpack/security/
│   ├── Security.java                     Plugin entry point
│   ├── authc/                            Realms (native, file, LDAP, AD, PKI, OIDC, SAML, JWT, API key, Kerberos)
│   ├── authz/                            RoleResolver, IndicesPermission, PrivilegeResolver
│   │   ├── store/                        Native + reserved + file-based role stores
│   │   ├── permission/                   IndicesPermission, ClusterPermission, ApplicationPermission
│   │   └── interceptor/                  ActionFilter / ShardSearchRequest interceptors
│   ├── audit/                            Audit trail
│   ├── operator/                         Operator-only privileges
│   ├── transport/                        Transport security (TLS, header parsing)
│   ├── support/                          API keys, service accounts
│   └── action/                           REST + transport actions for security APIs
└── ...

x-pack/plugin/identity-provider/         Built-in OIDC IdP for serverless
x-pack/plugin/security/cli/              Setup / autoconfigure CLI tooling

Authentication realms

Authentication is a chain of Realm instances queried in order until one succeeds. Built-in realms:

Realm	Source	Purpose
native	authc/esnative	Users in the .security system index
file	authc/file	Users from users / users_roles files
reserved	authc/support/UserRoleMapper	Built-in superusers (elastic, kibana_system, ...)
ldap	authc/ldap	LDAP / AD with bind-and-search
active_directory	authc/ldap	AD-tuned LDAP
pki	authc/pki	TLS client certificates
kerberos	authc/kerberos	SPNEGO
oidc	authc/oidc	OpenID Connect
saml	authc/saml	SAML 2.0
jwt	authc/jwt	Bearer JWT
_es_api_key	authc/ApiKeyService.java	Stateless API keys
_service_account	support/serviceaccounts	Service tokens for stack components

Each realm produces an Authentication (user + token + realm) that is attached to the thread context.

Authorization

AuthorizationService (x-pack/plugin/security/.../authz/AuthorizationService.java) is invoked from a server ActionFilter. For every action it:

1. Resolves the user's roles (from native, file, or external mapping).
2. Computes effective privileges (ClusterPermission, IndicesPermission, ApplicationPermission).
3. Checks the action against those privileges. Indices privileges are matched by action pattern (indices:data/read/*) and index name pattern.
4. Records the decision in the audit trail.

Roles are documents in the .security system index (or hard-coded reserved roles). The privilege catalog is maintained in x-pack/plugin/core/.../security/authz/privilege/.

API keys and service accounts

API keys are first-class authentication tokens stored in the .security index, with their own privilege envelope (so a key can be more restricted than its owner). Service accounts (e.g. elastic/kibana) are server-managed identities with predefined privileges that other Elastic stack components use to talk to Elasticsearch.

Document and field-level security (DLS / FLS)

DLS attaches a query filter to every search/read on behalf of a user. FLS strips fields from _source and disables aggregations on hidden fields. Both are wired in via SecurityIndicesPermissions and a search-time interceptor.

Audit

AuditTrail records authentication / authorization events in either a local log file or an audit index. Configurable per-event-type and per-user.

Operator privileges

x-pack/plugin/security/.../operator/ adds an "operator" tier — a small set of cluster-management actions reserved for explicitly-named users, regardless of their normal role. Used for serverless-style separation of cloud operators from end users.

TLS

libs/ssl-config plus x-pack/plugin/security/.../transport/ set up TLS for HTTP and transport. Two layers:

• HTTP TLS — certificates configured under xpack.security.http.ssl.*.
• Transport TLS — xpack.security.transport.ssl.*. Required when security is enabled.

Auto-configuration on first start uses the certutil pipeline in x-pack/plugin/security/cli/ to generate self-signed certs and enrollment tokens.

FIPS mode

The build's elasticsearch.fips Gradle plugin produces a FIPS-compliant distribution that uses the Bouncy Castle FIPS provider and disables non-approved algorithms.

Where to extend

• New realm: implement Realm and a Realm.Factory, register via Security.Plugin#getAuthenticationFailureHandler plus realm registration.
• New cluster privilege: add to ClusterPrivilege.Builtin.
• New audited event: add to AuditTrail.Event.
• Custom role provider: implement BiConsumer<Set<String>, ActionListener<RoleRetrievalResult>> and contribute via getRolesProviders.