You're viewing version 2.13 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
Client certificate authentication
After obtaining your own certificates either from a certificate authority (CA) or by generating your own certificates using OpenSSL, you can start configuring OpenSearch to authenticate a user using a client certificate.
Client certificate authentication offers more security advantages than just using basic authentication (username and password). Because client certificate authentication requires both a client certificate and its private key, which are often in the user’s possession, it is less vulnerable to brute force attacks in which malicious individuals try to guess a user’s password.
Another benefit of client certificate authentication is you can use it along with basic authentication, providing two layers of security.
Enabling client certificate authentication
To enable client certificate authentication, you must first set clientauth_mode
in opensearch.yml
to either OPTIONAL
or REQUIRE
:
plugins.security.ssl.http.clientauth_mode: OPTIONAL
Next, enable client certificate authentication in the client_auth_domain
section of config.yml
.
clientcert_auth_domain:
description: "Authenticate via SSL client certificates"
http_enabled: true
transport_enabled: true
order: 1
http_authenticator:
type: clientcert
config:
username_attribute: cn #optional, if omitted DN becomes username
challenge: false
authentication_backend:
type: noop
Assigning roles to a certificate’s common name
You can now assign your certificate’s common name (CN) to a role. This step requires you to identify the certificate’s CN and the role you want to assign it to. To view a list of all predefined OpenSearch roles, see Predefined roles. To get started, first define a role and then map your certificate’s CN to that role.
After determining which role to map to your certificate’s CN, you can use OpenSearch Dashboards, roles_mapping.yml
, or the REST API to map the role. The following example uses the REST API
to map the CN CLIENT1
to the role readall
.
Example request
PUT _plugins/_security/api/rolesmapping/readall
{
"backend_roles" : ["sample_role" ],
"hosts" : [ "example.host.com" ],
"users" : [ "CLIENT1" ]
}
Example response
{
"status": "OK",
"message": "'readall' updated."
}
After mapping a role to your client certificate’s CN, you’re ready to connect to your cluster using those credentials.
The code example below uses the Python requests
library to connect to a local OpenSearch cluster and sends a GET request to the movies
index.
import requests
import json
base_url = 'https://localhost:9200/'
headers = {
'Content-Type': 'application/json'
}
cert_file_path = "/full/path/to/client-cert.pem"
key_file_path = "/full/path/to/client-cert-key.pem"
root_ca_path = "/full/path/to/root-ca.pem"
# Send the request.
path = 'movies/_doc/3'
url = base_url + path
response = requests.get(url, cert = (cert_file_path, key_file_path), verify=root_ca_path)
print(response.text)
Using certificates with Docker
While we recommend using the tarball installation of ODFE to test client certificate authentication configurations, you can also use any of the other install types. For instructions on using Docker security, see Configuring basic security settings.