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/lucenia-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.

warning

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/lucenia-security/config.yml file included in your Lucenia 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