# Certificate-based authentication

```json metadata
{
  "schema_version": 2,
  "title": "Certificate-based authentication",
  "description": "Certificate-based authentication allows secure, passwordless access to the REST API and databases.",
  "categories": ["docs","operate","rs"],
  "tableOfContents": {"sections":[{"children":[{"id":"add-cert","title":"Add mtls_trusted_ca certificate"},{"id":"config-cluster","title":"Configure cluster settings"},{"id":"enable-mtls-dbs","title":"Enable mutual TLS for databases"},{"id":"create-cert-users","title":"Create certificate auth_method users"}],"id":"set-up-certificate-based-authentication","title":"Set up certificate-based authentication"},{"id":"authenticate-rest-api-requests","title":"Authenticate REST API requests"},{"id":"authenticate-database-connections","title":"Authenticate database connections"},{"id":"limitations","title":"Limitations"}]}

,
  "codeExamples": []
}
```


You can set up certificate-based authentication for specific users to enable secure, passwordless access to the Redis Enterprise Software [REST API](https://redis.io/docs/latest/operate/rs/references/rest-api) and databases.

## Set up certificate-based authentication

To set up certificate-based authentication:

1. [Add the `mtls_trusted_ca` certificate.](#add-cert) 

1. [Configure cluster settings.](#config-cluster)

1. If you want to enable certificate-based authentication for databases, you must [enable mutual TLS for the relevant databases](#enable-mtls-dbs). Otherwise, you can skip this step.

1. [Create certificate auth_method users.](#create-cert-users)

### Add mtls_trusted_ca certificate {#add-cert}

To add a trusted CA certificate `mtls_trusted_ca` to the cluster, use an [update cluster certificates](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/cluster/certificates) request.

For Redis Enterprise Software versions 7.22.2 and later, use:

```sh
PUT /v1/cluster/certificates
{
  "certificates": [
    {
      "name": "mtls_trusted_ca",
      "certificate": "<content of certificate PEM file>"
    }
  ]
}
```

For Redis Enterprise Software versions 7.22.0 and earlier, use:

```sh
PUT /v1/cluster/update_cert
{
  "name": "mtls_trusted_ca",
  "certificate": "<content of certificate PEM file>"
}
```

### Configure cluster settings {#config-cluster}

[Update cluster settings](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/cluster#put-cluster) with mutual TLS configuration.

For certificate validation by Subject Alternative Name (SAN), use:

```sh
PUT /v1/cluster
{
  "mtls_certificate_authentication": true,
  "mtls_client_cert_subject_validation_type": "san_cn",
  "mtls_authorized_subjects": [{
    "CN": "<Common Name>"
  }]
}
```

For certificate validation by full Subject Name, use:

```sh
PUT /v1/cluster
{
  "mtls_certificate_authentication": true,
  "mtls_client_cert_subject_validation_type": "full_subject",
  "mtls_authorized_subjects": [{
    "CN": "<Common Name>",
    "OU": [<array of Organizational Unit strings>],
    "O": "<Organization>",
    "C": "<2-letter country code>",
    "L": "<Locality (city)>",
    "ST": "<State/Province>"
  }]
}
```

Replace the placeholder values `<>` with your client certificate's subject values.

### Enable mutual TLS for databases {#enable-mtls-dbs}

Before you can connect to a database using certificate-based authentication, you must enable mutual TLS (mTLS). See [Enable TLS](https://redis.io/docs/latest/operate/rs/security/encryption/tls/enable-tls) for detailed instructions.

### Create certificate auth_method users {#create-cert-users}

When you [create new users](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/users#post-user), include `"auth_method": "certificate"` and `certificate_subject_line` in the request body:

```sh
POST /v1/users
{
  "auth_method": "certificate",
  "certificate_subject_line": "CN=<Common Name>,OU=<Organizational Unit>,O=<Organization>,L=<Locality>,ST=<State/Province>,C=<Country>"
}
```

Replace the placeholder values `<>` with your client certificate's subject values.

> [!NOTE]
> The `certificate_subject_line` must:
>
> - Follow [RFC 2253](https://www.rfc-editor.org/rfc/rfc2253) format.
>
> - List the attributes in reverse order, starting with the Common Name (`CN`).
>
> - Not contain spaces after the commas that separate attributes.
>
> - Exactly match the certificate's RFC 2253 subject.
>
> - Contain only one Organizational Unit (`OU`) value.

## Authenticate REST API requests

To use the REST API with certificate-based authentication, you must provide a client certificate, signed by the trusted CA `mtls_trusted_ca`, and a private key.

The following example uses [cURL](https://curl.se/) to send a [REST API request](https://redis.io/docs/latest/operate/rs/references/rest-api/requests):

```sh
curl --request <METHOD> --url https://<hostname-or-IP-address>:9443/<API-version>/<API-path> --cert client.pem --key client.key
```

## Authenticate database connections

To connect to a database with certificate-based authentication, you must provide a client certificate, signed by a trusted CA, and a private key. The client certificate must either be one you previously added to the database to [enable mutual TLS](https://redis.io/docs/latest/operate/rs/security/encryption/tls/enable-tls#enable-mutual-tls) (`authentication_ssl_client_certs` in the REST API), or be signed by one of these certificates.

The following example shows how to connect to a Redis database with [`redis-cli`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/redis-cli):

```sh
redis-cli -h <hostname-or-IP-address> -p <port> --tls --cacert <redis_cert>.pem --cert redis_user.crt --key redis_user_private.key
```

## Limitations

- Certificate-based authentication is not implemented for the Cluster Manager UI.