solr/solr-ref-guide/src/cert-authentication-plugin.adoc

= Certificate Authentication Plugin
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

Solr can support extracting the user principal out of the client's certificate with the use of the CertAuthPlugin.

== Enable Certificate Authentication

For Certificate authentication, the `security.json` file must have an `authentication` part which defines the class being used for authentication.

An example `security.json` is shown below:

[source,json]
----
{
 "authentication": {
  "class":"solr.CertAuthPlugin"
 }
}
----

=== Certificate Validation

Parts of certificate validation, including verifying the trust chain and peer hostname/ip address will be done by the web servlet container before the request ever reaches the authentication plugin.
These checks are described in the <<enabling-ssl.adoc#,Enabling SSL>> section.

This plugin provides no additional checking beyond what has been configured via SSL properties.

=== User Principal Extraction

This plugin will configure the user principal for the request based on the X500 subject present in the client certificate.
Authorization plugins will need to accept and handle the full subject name, for example:

[source,text]
----
CN=Solr User,OU=Engineering,O=Example Inc.,C=US
----

A list of possible tags that can be present in the subject name is available in https://tools.ietf.org/html/rfc5280#section-4.1.2.4[RFC-5280, Section 4.1.2.4]. Values may have spaces, punctuation, and other characters.

It is best practice to verify the actual contents of certificates issued by your trusted certificate authority before configuring authorization based on the contents.

== Using Certificate Auth with Clients (including SolrJ)

With certificate authentication enabled, all client requests must include a valid certificate.
This is identical to the <<enabling-ssl.adoc#example-client-actions,client requirements>> when using SSL.