This is an older version of Search Guard. Switch to Latest version
Custom authentication modules
Content
If none of the Enterprise modules fits your needs, you can also write your own implementation. This is a feature of the Enterprise Edition, you can implement your own HTTP authenticator and also your own authentication and authorization backends.
The HTTP authenticator is responsible for extracting user credentials from a HTTP call, while the authentication backend is responsible for validating these credentials. An authorization backend fetches a user’s backend roles.
Setting up your project
In order to write your own implementations, you need to implement interfaces provided in the Search Guard plugin. The easiest way is to add the required dependencies in the pom.xml of your Maven project:
<dependency>
<groupId>com.floragunn</groupId>
<artifactId>search-guard-7</artifactId>
<version>${searchguard.version}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.elasticsearch</groupId>
<artifactId>elasticsearch</artifactId>
<version>${elasticsearch.version}</version>
<scope>provided</scope>
</dependency>
Where the ${searchguard.version}
and ${elasticsearch.version}
are the Search Guard / Elasticsearch versions you want to compile against, e.g. 7.6.0.
Implementing a custom HTTPAuthenticator
A custom HTTPAuthenticator must extend the interface com.floragunn.searchguard.auth.HTTPAuthenticator
.
The methods to implement are fully documented in JavaDoc.
Implementing a custom AuthenticationBackend
A custom AuthenticationBackend must extend the interface com.floragunn.searchguard.auth.AuthenticationBackend
.
The methods to implement are fully documented in JavaDoc.
Implementing a custom AuthorisationBackend
A custom AuthorisationBackend must extend the interface com.floragunn.searchguard.auth.AuthorizationBackend
.
The methods to implement are fully documented in JavaDoc.
Configuring custom implementations
Custom implementations can be configured in sg_config.yml
by simply providing their fully qualified class name as type in the authc and/or authz section:
authz:
custom_authc_domain:
http_enabled: true
order: 0
http_authenticator:
type: com.floragunn.custom.CustomHttpAuthenticator
challenge: false
config:
key: value
authentication_backend:
type: com.floragunn.custom.CustomAuthenticationBackend
config:
key: value
...
authz:
custom_authz_domain:
http_enabled: true
authorization_backend:
type: com.floragunn.custom.CustomAuthorizationBackend
config:
key: value
...
Accessing configuration settings
All custom implementations need to provide a public constructor, which takes a org.elasticsearch.common.settings.Settings
object as argument.
This object will contain the settings from the config
sections of your custom modules in sg_config.yml
. In the above example, all three custom modules would receieve a org.elasticsearch.common.settings.Settings
object where key
contains value
.
Adding additional user attributes
You can add additional properties to the user by either:
- Calling
AuthCredentials#addAttribute
in the HTTPAuthenticator - Calling
User#getCustomAttributesMap
and modify the returned map directly
Attributes can be used to further describe the user, and, more importantly, they can be used as variables in the Document Level Security query. This makes it possible to write dynamic DLS queries based on a user’s attributes.