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.

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.

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.

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.

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.

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