9.5 KiB
Executable File
layout | title | parent | nav_order | redirect_from | |
---|---|---|---|---|---|
default | Configuring the Security backend | Configuration | 5 |
|
Configuring the Security backend
One of the first steps to using the Security plugin is to decide on an authentication backend, which handles steps 2-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 main configuration file for authentication and authorization backends is config/opensearch-security/config.yml
. It defines how the Security plugin retrieves the user credentials, how it verifies these credentials, and how to fetch additional roles from backend systems (optional).
config.yml
has three main parts:
opensearch_security:
dynamic:
http:
...
authc:
...
authz:
...
For a more complete example, see the sample file on GitHub.
HTTP
The http
section has the following format:
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
If you disable anonymous authentication, the Security plugin won't initialize if you have not provided at least one authc
.
Authentication
The authc
section has the following format:
<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
), enabled
flags, 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.
http_authenticator
specifies which authentication method that you want to use on the HTTP layer.
This is the syntax for defining an authenticator on the HTTP layer:
http_authenticator:
type: <type>
challenge: <true|false>
config:
...
These are the allowed values for type
:
basic
: HTTP basic authentication. No additional configuration is needed.jwt
: JSON Web Token (JWT) authentication. Additional configuration is needed. See Configuring JWTs for more information.clientcert
: Authentication through a client TLS certificate. This certificate must be trusted by one of the root CAs in the truststore of your nodes.
After setting an HTTP authenticator, you must specify against which backend system you want to authenticate the user:
authentication_backend:
type: <type>
config:
...
These are the possible values for type
:
noop
: No further authentication against any backend system is performed. Usenoop
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 ininternal_users.yml
for authentication.ldap
: Authenticate users against an LDAP server. This setting requires additional, LDAP-specific configuration settings.
Authorization
After the user has been authenticated, the Security plugin can optionally collect additional roles from backend systems. 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 the same way as you can for authentication entries. In this case, execution order is not relevant, so there is no order
field.
These are the possible values for type
:
noop
: Skip this step altogether.ldap
: Fetch additional roles from an LDAP server. This setting requires additional, LDAP-specific configuration settings.
HTTP basic authentication
To set up HTTP basic authentication, you must enable it in the http_authenticator
section of the configuration:
http_authenticator:
type: basic
challenge: true
In most cases, you set the challenge
flag to true
. The flag defines the behavior of the Security plugin if the Authorization
field in the HTTP header is not set.
If challenge
is set to true
, the Security plugin sends a response with status UNAUTHORIZED
(401) back to the client. If the client is accessing the cluster with a browser, this triggers the authentication dialog box, and the user is prompted to enter a user name and password.
If challenge
is set to false
and no Authorization
header field is set, the Security plugin does not send a WWW-Authenticate
response back to the client, and authentication fails. You might want to use this setting if you have another challenge http_authenticator
in your configured authentication domains. One such scenario is when you plan to use basic authentication and OpenID Connect together.
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 supported authentication backends, see the relevant topic for each type in the Authentication backends documentation.