Client certificate based authentication
Search Guard can use a client TLS certificate in the HTTP request to authenticate users and assign roles and permissions.
Search Guard setup
In order for Search Guard to pick up client certificate on the REST layer, you need to set the
elasticsearch.yml to either
The configuration for the client certificate authenticator is very minimal:
auth_domains: - type: clientcert
In this configuration, users logged in by client cert show up in Search Guard with the full distinguished name (“dn”) of the certificate subject.
If you want to use just a RDN of the certificate subject, you can access it in
user_mapping using the attribute
auth_domains: - type: clientcert user_mapping.user_name.from: clientcert.subject.cn
In this configuration, the cn (“common name”) component of the certificate subject is used as the user name in Search Guard.
Certificates carry no role information. In order to define authorization information for users authenticated by client certificates, you have several options:
- Assign roles to concrete users in
- Use a user information backend to retrieve roles.
- If the client is capable and trustworthy to define the roles by itself, you can use the same mechanism as described for proxy authentication.
To map a certificate based user to a role, just use the username as specified by
sg_roles_mapping.yml, for example:
You issued a certificate for the user
kirk for which the subject of the certificate is (
openssl x509 -in kirk.crt.pem -text -noout):
Subject: C=DE, L=Test, O=client, OU=client, CN=kirk
You would then map the role like so:
sg_role_starfleet: users: - kirk backend_roles: - ... hosts: - ...
Activate the setup
After having applied the changes to
sgctl to upload the file to Search Guard:
$ ./sgctl.sh update-config sg_authc.yml
That’s it. Use your favorite REST client capable of client certificate authentication to test logging in. If you are using curl, you can use a command similar to the following:
$ curl --cert client.crt.pem --key client.key.pem "https://cluster.example.com:9200/_searchguard/authinfo"