Configuring the Security backend
One of the first steps when setting up the Security plugin is deciding which authentication backend to use. The role played by the backend in authentication is covered in steps 2 and 3 of the authentication flow. The plugin has an internal user database, but many people prefer to use an existing authentication backend, such as an LDAP server, or some combination of the two.
The primary file used to configure an authentication and authorization backend is config/opensearch-security/config.yml
. This file defines how the Security plugin retrieves user credentials, how it verifies the credentials, and how it fetches additional roles when the backend selected for authentication and authorization supports this feature. This topic provides a basic overview of the configuration file and its requirements for setting up security. For information about configuring a specific backend, see Authentication backends.
The config.yml
file includes three main parts:
config:
dynamic:
http:
...
authc:
...
authz:
...
The sections that follow describe the main elements in each part of the config.yml
file and provide basic examples of their configuration. For a more detailed example, see the sample file on GitHub.
HTTP
The http
section includes the following format:
http:
anonymous_auth_enabled: <true|false>
xff: # optional section
enabled: <true|false>
internalProxies: <string> # Regex pattern
remoteIpHeader: <string> # Name of the header in which to look. Typically: x-forwarded-for
proxiesHeader: <string>
trustedProxies: <string> # Regex pattern
The settings used in this configuration are described in the following table.
Setting | Description |
---|---|
anonymous_auth_enabled | Either enables or disables anonymous authentication. When true , HTTP authenticators try to find user credentials in the HTTP request. If credentials are found, the user is authenticated. If none are found, the user is authenticated as an anonymous user. This user then has the username anonymous and one role named anonymous_backendrole . When you enable anonymous authentication, all defined HTTP authenticators are non-challenging. For more information, see The challenge setting. |
xff | Used to configure proxy-based authentication. For more information about this backend, see Proxy-based authentication. |
For instructions on how to configure anonymous authentication, see Anonymous authentication.
Authentication
The authc
section has the following format:
authc:
<domain_name>:
http_enabled: <true|false>
transport_enabled: <true|false>
order: <integer>
http_authenticator:
...
authentication_backend:
...
An entry in the authc
section is called an authentication domain. It specifies where to get the user credentials and against which backend they should be authenticated.
You can use more than one authentication domain. Each authentication domain has a name (for example, basic_auth_internal
), settings for enabling the domain on the REST and transport layers, and an order
. The order makes it possible to chain authentication domains together. The Security plugin uses them in the order that you provide. If the user successfully authenticates with one domain, the Security plugin skips the remaining domains.
Settings that are typically found in this part of the configuration are included in the following table.
Setting | Description |
---|---|
http_enabled | Enables or disables authentication on the REST layer. Default is true (enabled). |
transport_enabled | Enables or disables authentication on the transport layer. Default is true (enabled). |
order | Determines the order in which an authentication domain is queried with an authentication request when multiple backends are configured in combination. Once authentication succeeds, any remaining domains do not need to be queried. Its value is an integer. |
The http_authenticator
definition specifies the authentication method for the HTTP layer. The following example shows the syntax used for defining an HTTP authenticator:
http_authenticator:
type: <type>
challenge: <true|false>
config:
...
The type
setting for http_authenticator
accepts the following values. For more information about each of the authentication options, see the links to authentication backends in Next steps.
Value | Description |
---|---|
basic | HTTP basic authentication. For more information about using basic authentication, see the HTTP basic authentication documentation. |
jwt | JSON Web Token (JWT) authentication. See the JSON Web Token documentation for additional configuration information. |
openid | OpenID Connect authentication. See the OpenID Connect documentation for additional configuration information. |
saml | SAML authentication. See the SAML documentation for additional configuration information. |
proxy , extended-proxy | Proxy-based authentication. The extended-proxy type authenticator allows you to pass additional user attributes for use with document-level security. See the Proxy-based authentication documentation for additional configuration information. |
clientcert | Authentication through a client TLS certificate. This certificate must be trusted by one of the root certificate authorities (CAs) in the truststore of your nodes. See the Client certificate authentication documentation for additional configuration information. |
After setting an HTTP authenticator, you must specify against which backend system you want to authenticate the user:
authentication_backend:
type: <type>
config:
...
The following table shows the possible values for the type
setting under authentication_backend
.
Value | Description |
---|---|
noop | No further authentication against any backend system is performed. Use noop if the HTTP authenticator has already authenticated the user completely, as in the case of JWT or client certificate authentication. |
internal | Use the users and roles defined in internal_users.yml for authentication. |
ldap | Authenticate users against an LDAP server. This setting requires additional LDAP-specific configuration settings. |
Authorization
The authz
configuration is used to extract backend roles from an LDAP implementation. After the user has been authenticated, the Security plugin can optionally collect additional roles from the backend system. The authorization configuration has the following format:
authz:
<name>:
http_enabled: <true|false>
transport_enabled: <true|false>
authorization_backend:
type: <type>
config:
...
You can define multiple entries in this section, as with authentication entries. In this case, however, the execution order is not relevant and the order
setting is not used.
The following table shows the possible values for the type
setting under authorization_backend
.
Value | Description |
---|---|
noop | Skips the authorization configuration step altogether. |
ldap | Fetches additional roles from an LDAP server. This setting requires additional LDAP-specific configuration settings. |
Backend configuration examples
The default config/opensearch-security/config.yml
file included in your OpenSearch distribution contains many configuration examples. Use these examples as a starting point and customize them to your needs.
Next steps
To learn about configuring the authentication backends, see the Authentication backends documentation. Alternatively, you can view documentation for a specific backend by using the links in the following list of topics:
- HTTP basic authentication
- JSON Web Token
- OpenID Connect
- SAML
- Active Directory and LDAP
- Proxy-based authentication
- Client certificate authentication