{
  "schema_version": 2,
  "id": "operate/rs/security/certificates/certificate-based-authentication",
  "title": "Certificate-based authentication",
  "url": "https://redis.io/docs/latest/operate/rs/7.8/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 Enterprise Software [REST API](https://redis.io/docs/latest/operate/rs/references/rest-api) and databases.\n\n## Set up certificate-based authentication\n\nTo set up certificate-based authentication:\n\n1. [Add the `mtls_trusted_ca` certificate.](#add-cert) \n\n1. [Configure cluster settings.](#config-cluster)\n\n1. 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.\n\n1. [Create certificate auth_method users.](#create-cert-users)\n\n### Add mtls_trusted_ca certificate {#add-cert}\n\nAdd a trusted CA certificate `mtls_trusted_ca` to the cluster using an [update cluster certificate](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/cluster/certificates#put-cluster-update_cert) request:\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### Configure cluster settings {#config-cluster}\n\n[Update cluster settings](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/cluster#put-cluster) with mutual TLS configuration.\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\": \"\u003cCommon Name\u003e\"\n  }]\n}\n```\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### Enable mutual TLS for databases {#enable-mtls-dbs}\n\nBefore 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.\n\n### Create certificate auth_method users {#create-cert-users}\n\nWhen 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\nPOST /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\nReplace the placeholder values `\u003c\u003e` with your client certificate's subject values.\n\n\u003e [!NOTE]\n\u003e The `certificate_subject_line` must:\n\u003e\n\u003e - Follow [RFC 2253](https://www.rfc-editor.org/rfc/rfc2253) format.\n\u003e\n\u003e - List the attributes in reverse order, starting with the Common Name (`CN`).\n\u003e\n\u003e - Not contain spaces after the commas that separate attributes.\n\u003e\n\u003e - Exactly match the certificate's RFC 2253 subject.\n\u003e\n\u003e - Contain only one Organizational Unit (`OU`) value.\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## 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-10-21T09:46:20-07:00"
}