{
  "id": "disable-basic-authentication",
  "title": "Disable basic authentication for the REST API",
  "url": "https://redis.io/docs/latest/operate/rs/security/access-control/disable-basic-authentication/",
  "summary": "Disable Basic and Digest authentication for the cluster management REST API and require certificate or JWT authentication instead.",
  "tags": [
    "docs",
    "operate",
    "rs"
  ],
  "last_updated": "2026-07-24T10:52:10-07:00",
  "page_type": "content",
  "content_hash": "5fb92b598c6597b35b5e6ce1ee698f4725bff7ed401185b84507da87c44bd7b2",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "By default, the Redis Software cluster management REST API accepts HTTP Basic authentication using a cluster username and password. Starting with Redis Software 8.2.0, you can disable Basic and Digest authentication cluster-wide with the `control_plane_basic_authentication` setting.\n\nWhen you disable basic authentication, the cluster rejects Basic and Digest authentication on all inbound REST API requests, and clients must authenticate with a client certificate (mTLS) or a JSON Web Token (JWT) instead. This reduces the cluster's attack surface by removing password-based access to the management API.\n\n\nThis setting applies only to the cluster management REST API. It does not change how clients authenticate to databases.\n\n\n<!-- TODO(confirm — RED-201786 / Iren Friedland + Aharon): does the Cluster Manager UI still work when basic authentication is disabled, or does it also require certificate/JWT auth? Source (cluster schema @ v8.2.0-26) only states inbound REST API requests reject Basic/Digest. Confirm UI impact before GA. -->"
    },
    {
      "id": "before-you-begin",
      "title": "Before you begin",
      "role": "content",
      "text": "Before you disable basic authentication, make sure every client and tool that calls the REST API can still authenticate another way. If you disable basic authentication without another working method in place, you lose REST API access to the cluster.\n\n\nWhen basic authentication is disabled, other configured authentication methods—such as certificate-based (mTLS), JWT, and LDAP—continue to work. Set up at least one before you disable basic authentication:\n\n- **Certificate-based (mTLS) authentication** (recommended) — see [Certificate-based authentication](https://redis.io/docs/latest/operate/rs/security/certificates/certificate-based-authentication).\n\n- **JWT authentication** — obtain a token with an [authorize user](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/users/authorize) request, then send it as a bearer token on subsequent requests.\n\nSome cluster-management flows require **certificate-based authentication** specifically when basic authentication is disabled—they don't use JWT or LDAP:\n\n- **Joining a node to the cluster** and **Active-Active (CRDB) management.** Configure these flows to use certificate credentials (client certificate, client key, and trusted CA) instead of a username and password. The client certificate's signing CA must be present in the cluster's `mtls_trusted_ca`. See [Certificate-based authentication](https://redis.io/docs/latest/operate/rs/security/certificates/certificate-based-authentication)."
    },
    {
      "id": "disable-basic-authentication",
      "title": "Disable basic authentication",
      "role": "content",
      "text": "Basic authentication is enabled by default (`control_plane_basic_authentication` is `true`). To disable it, use one of the following methods:\n\n**REST API:**\n\nTo disable basic authentication using the REST API, use an [update cluster settings](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/cluster#put-cluster) request:\n\n[code example]\n\n**rladmin:**\n\nTo disable basic authentication using [`rladmin tune cluster`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/tune):\n\n[code example]"
    },
    {
      "id": "verify",
      "title": "Verify",
      "role": "content",
      "text": "After you disable basic authentication, a request that uses Basic authentication returns `401 Unauthorized`:\n\n[code example]\n\nA request that uses a client certificate or a JWT succeeds. For example, using a client certificate:\n\n[code example]"
    },
    {
      "id": "re-enable-basic-authentication",
      "title": "Re-enable basic authentication",
      "role": "content",
      "text": "If disabling basic authentication left you without cluster access, use the `rladmin` method below. It runs locally on a cluster node and doesn't require REST API access.\n\n\nTo re-enable basic authentication, use one of the following methods:\n\n**REST API:**\n\n[code example]\n\n**rladmin:**\n\n[code example]"
    }
  ],
  "examples": [
    {
      "id": "disable-basic-authentication-ex0",
      "language": "sh",
      "code": "PUT https://<host>:<port>/v1/cluster\n{\n    \"control_plane_basic_authentication\": false\n}",
      "section_id": "disable-basic-authentication"
    },
    {
      "id": "disable-basic-authentication-ex1",
      "language": "sh",
      "code": "rladmin tune cluster control_plane_basic_authentication disabled",
      "section_id": "disable-basic-authentication"
    },
    {
      "id": "verify-ex0",
      "language": "sh",
      "code": "curl -k -u \"<username>:<password>\" https://<host>:<port>/v1/cluster\n# HTTP 401 Unauthorized",
      "section_id": "verify"
    },
    {
      "id": "verify-ex1",
      "language": "sh",
      "code": "curl -k --cert <client-cert> --key <client-key> https://<host>:<port>/v1/cluster",
      "section_id": "verify"
    },
    {
      "id": "re-enable-basic-authentication-ex0",
      "language": "sh",
      "code": "PUT https://<host>:<port>/v1/cluster\n{\n    \"control_plane_basic_authentication\": true\n}",
      "section_id": "re-enable-basic-authentication"
    },
    {
      "id": "re-enable-basic-authentication-ex1",
      "language": "sh",
      "code": "rladmin tune cluster control_plane_basic_authentication enabled",
      "section_id": "re-enable-basic-authentication"
    }
  ]
}