{
  "id": "certificate-based-authentication",
  "title": "Certificate-based authentication",
  "url": "https://redis.io/docs/latest/operate/rs/8.0/security/certificates/certificate-based-authentication/",
  "summary": "Certificate-based authentication allows secure, passwordless access to the REST API and databases.",
  "content": "\nYou 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.\n\n## Certificate-based authentication for the REST API\n\n### Set up certificate-based authentication for the REST API\n\nTo set up certificate-based authentication:\n\n1. 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:\n\n    **Redis Software v7.22.2 and later:**\n\nFor Redis Software versions 7.22.2 and later, use:\n\n```sh\nPUT /v1/cluster/certificates\n{\n  \"certificates\": [\n    {\n      \"name\": \"mtls_trusted_ca\",\n      \"certificate\": \"\u003ccontent of certificate PEM file\u003e\"\n    }\n  ]\n}\n```\n\n**Redis Software v7.22.0 and earlier:**\n\nFor Redis Software versions 7.22.0 and earlier, use:\n\n```sh\nPUT /v1/cluster/update_cert\n{\n  \"name\": \"mtls_trusted_ca\",\n  \"certificate\": \"\u003ccontent of certificate PEM file\u003e\"\n}\n```\n\n\n\n1. [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:\n\n    **Without subject validation:**\n\nAdditional certificate validation is optional. To enable mutual TLS without subject validation, use:\n\n```sh\nPUT /v1/cluster\n{\n  \"mtls_certificate_authentication\": true,\n  \"mtls_client_cert_subject_validation_type\": \"disabled\"\n}\n```\n\n**With SAN validation:**\n\nFor certificate validation by Subject Alternative Name (SAN), use:\n\n```sh\nPUT /v1/cluster\n{\n  \"mtls_certificate_authentication\": true,\n  \"mtls_client_cert_subject_validation_type\": \"san_cn\",\n  \"mtls_authorized_subjects\": [{\n    \"CN\": \"\u003cSubject Common Name or SAN DNS entry\u003e\"\n  }]\n}\n```\n\nReplace the placeholder value `\u003c\u003e` with your client certificate's Subject Common Name or SAN DNS entry.\n\n**Example certificate and mTLS settings**\n\nIf a client certificate has:\n\n- Subject: `CN=client.example.com`\n\n- SAN: `DNS:app1.example.com, DNS:client.example.com, DNS:app1-prod.example.com`\n\nYou can use any of these values for the CN in `mtls_authorized_subjects`:\n\n```sh\nPUT /v1/cluster\n{\n  \"mtls_certificate_authentication\": true,\n  \"mtls_client_cert_subject_validation_type\": \"san_cn\",\n  \"mtls_authorized_subjects\": [\n    {\"CN\": \"client.example.com\"},   // Subject CN\n    {\"CN\": \"app1.example.com\"},     // SAN DNS entry\n    {\"CN\": \"app1-prod.example.com\"} // Another SAN DNS entry\n  ]\n}\n```\n\n**With Full Subject Name validation:**\n\nFor certificate validation by full Subject Name, use:\n\n```sh\nPUT /v1/cluster\n{\n  \"mtls_certificate_authentication\": true,\n  \"mtls_client_cert_subject_validation_type\": \"full_subject\",\n  \"mtls_authorized_subjects\": [{\n    \"CN\": \"\u003cCommon Name\u003e\",\n    \"OU\": [\u003carray of Organizational Unit strings\u003e],\n    \"O\": \"\u003cOrganization\u003e\",\n    \"C\": \"\u003c2-letter country code\u003e\",\n    \"L\": \"\u003cLocality (city)\u003e\",\n    \"ST\": \"\u003cState/Province\u003e\"\n  }]\n}\n```\n\nReplace the placeholder values `\u003c\u003e` with your client certificate's subject values.\n\n**Example certificate and mTLS settings**\n\nIf a client certificate has:\n\n- Subject: `CN=client.example.com`\n\n- SAN: `DNS:app1.example.com, DNS:client.example.com, DNS:app1-prod.example.com`\n\nYou can use any of these values for the CN in `mtls_authorized_subjects`:\n\n```sh\nPUT /v1/cluster\n{\n  \"mtls_certificate_authentication\": true,\n  \"mtls_client_cert_subject_validation_type\": \"san_cn\",\n  \"mtls_authorized_subjects\": [\n    {\"CN\": \"client.example.com\"},   // Subject CN\n    {\"CN\": \"app1.example.com\"},     // SAN DNS entry\n    {\"CN\": \"app1-prod.example.com\"} // Another SAN DNS entry\n  ]\n}\n```\n\n\n\n1. 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:\n\n    ```sh\n    POST /v1/users\n    {\n      \"auth_method\": \"certificate\",\n      \"certificate_subject_line\": \"CN=\u003cCommon Name\u003e,OU=\u003cOrganizational Unit\u003e,O=\u003cOrganization\u003e,L=\u003cLocality\u003e,ST=\u003cState/Province\u003e,C=\u003cCountry\u003e\"\n    }\n    ```\n\n    Replace the placeholder values `\u003c\u003e` with your client certificate's subject values.\n\n    \nThe `certificate_subject_line` must:\n\n- Follow [RFC 2253](https://www.rfc-editor.org/rfc/rfc2253) format.\n\n- List the attributes in reverse order, starting with the Common Name (`CN`).\n\n- Not contain spaces after the commas that separate attributes.\n\n- Exactly match the certificate's RFC 2253 subject.\n\n- Contain only one Organizational Unit (`OU`) value.\n    \n\n### Authenticate REST API requests\n\nTo 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.\n\nThe following example uses [cURL](https://curl.se/) to send a [REST API request](https://redis.io/docs/latest/operate/rs/references/rest-api/requests):\n\n```sh\ncurl --request \u003cMETHOD\u003e --url https://\u003chostname-or-IP-address\u003e:9443/\u003cAPI-version\u003e/\u003cAPI-path\u003e --cert client.pem --key client.key\n```\n\n## Certificate-based authentication for databases\n\n### Set up certificate-based authentication for databases\n\nTo set up certificate-based authentication for databases:\n\n1. 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.\n\n1. 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:\n\n    ```sh\n    POST /v1/users\n    {\n      \"auth_method\": \"certificate\",\n      \"certificate_subject_line\": \"CN=\u003cCommon Name\u003e,OU=\u003cOrganizational Unit\u003e,O=\u003cOrganization\u003e,L=\u003cLocality\u003e,ST=\u003cState/Province\u003e,C=\u003cCountry\u003e\"\n    }\n    ```\n\n    Replace the placeholder values `\u003c\u003e` with your client certificate's subject values.\n\n    \nThe `certificate_subject_line` must:\n\n- Follow [RFC 2253](https://www.rfc-editor.org/rfc/rfc2253) format.\n\n- List the attributes in reverse order, starting with the Common Name (`CN`).\n\n- Not contain spaces after the commas that separate attributes.\n\n- Exactly match the certificate's RFC 2253 subject.\n\n- Contain only one Organizational Unit (`OU`) value.\n    \n\n### Authenticate database connections\n\nTo 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.\n\nThe 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):\n\n```sh\nredis-cli -h \u003chostname-or-IP-address\u003e -p \u003cport\u003e --tls --cacert \u003credis_cert\u003e.pem --cert redis_user.crt --key redis_user_private.key\n```\n\n## Limitations\n\n- Certificate-based authentication is not implemented for the Cluster Manager UI.\n",
  "tags": ["docs","operate","rs"],
  "last_updated": "2026-07-23T12:00:25-05:00"
}