# Certificate-based authentication ```json metadata { "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":"set-up-certificate-based-authentication-for-the-rest-api","title":"Set up certificate-based authentication for the REST API"},{"id":"authenticate-rest-api-requests","title":"Authenticate REST API requests"}],"id":"certificate-based-authentication-for-the-rest-api","title":"Certificate-based authentication for the REST API"},{"children":[{"id":"set-up-certificate-based-authentication-for-databases","title":"Set up certificate-based authentication for databases"},{"id":"authenticate-database-connections","title":"Authenticate database connections"}],"id":"certificate-based-authentication-for-databases","title":"Certificate-based authentication for databases"},{"id":"limitations","title":"Limitations"}]} , "codeExamples": [] } ``` You can set up certificate-based authentication for specific users to enable secure, passwordless access to the Redis Software [REST API](https://redis.io/docs/latest/operate/rs/references/rest-api) and databases. ## Certificate-based authentication for the REST API ### Set up certificate-based authentication for the REST API To set up certificate-based authentication: 1. Add a trusted CA certificate `mtls_trusted_ca` to the cluster using an [update cluster certificates](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/cluster/certificates) request: **Redis Software v7.22.2 and later:** For Redis Software versions 7.22.2 and later, use: ```sh PUT /v1/cluster/certificates { "certificates": [ { "name": "mtls_trusted_ca", "certificate": "" } ] } ``` **Redis Software v7.22.0 and earlier:** For Redis Software versions 7.22.0 and earlier, use: ```sh PUT /v1/cluster/update_cert { "name": "mtls_trusted_ca", "certificate": "" } ``` 1. [Update cluster settings](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/cluster#put-cluster) with mutual TLS (mTLS) configuration using one of the following options: **Without subject validation:** Additional certificate validation is optional. To enable mutual TLS without subject validation, use: ```sh PUT /v1/cluster { "mtls_certificate_authentication": true, "mtls_client_cert_subject_validation_type": "disabled" } ``` **With SAN validation:** 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": "" }] } ``` Replace the placeholder value `<>` with your client certificate's Subject Common Name or SAN DNS entry. **Example certificate and mTLS settings** If a client certificate has: - Subject: `CN=client.example.com` - SAN: `DNS:app1.example.com, DNS:client.example.com, DNS:app1-prod.example.com` You can use any of these values for the CN in `mtls_authorized_subjects`: ```sh PUT /v1/cluster { "mtls_certificate_authentication": true, "mtls_client_cert_subject_validation_type": "san_cn", "mtls_authorized_subjects": [ {"CN": "client.example.com"}, // Subject CN {"CN": "app1.example.com"}, // SAN DNS entry {"CN": "app1-prod.example.com"} // Another SAN DNS entry ] } ``` **With Full Subject Name validation:** 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": "", "OU": [], "O": "", "C": "<2-letter country code>", "L": "", "ST": "" }] } ``` Replace the placeholder values `<>` with your client certificate's subject values. **Example certificate and mTLS settings** If a client certificate has: - Subject: `CN=client.example.com` - SAN: `DNS:app1.example.com, DNS:client.example.com, DNS:app1-prod.example.com` You can use any of these values for the CN in `mtls_authorized_subjects`: ```sh PUT /v1/cluster { "mtls_certificate_authentication": true, "mtls_client_cert_subject_validation_type": "san_cn", "mtls_authorized_subjects": [ {"CN": "client.example.com"}, // Subject CN {"CN": "app1.example.com"}, // SAN DNS entry {"CN": "app1-prod.example.com"} // Another SAN DNS entry ] } ``` 1. 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=,OU=,O=,L=,ST=,C=" } ``` Replace the placeholder values `<>` with your client certificate's subject values. 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 --url https://:9443// --cert client.pem --key client.key ``` ## Certificate-based authentication for databases ### Set up certificate-based authentication for databases To set up certificate-based authentication for databases: 1. Enable mutual TLS for the relevant databases. See [Enable TLS](https://redis.io/docs/latest/operate/rs/security/encryption/tls/enable-tls) for detailed instructions. 1. 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=,OU=,O=,L=,ST=,C=" } ``` Replace the placeholder values `<>` with your client certificate's subject values. 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 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 -p --tls --cacert .pem --cert redis_user.crt --key redis_user_private.key ``` ## Limitations - Certificate-based authentication is not implemented for the Cluster Manager UI.