{
  "schema_version": 2,
  "id": "operate/rs/security/access-control/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-09-24T09:16:28+01:00",
  "page_type": "content",
  "content_hash": "945f5f53b43dd17c646019e315dd4ba42091a8b35bfcceef37af6770f581364e",
  "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> [!NOTE]\n> This setting applies only to the cluster management REST API. It does not change how clients authenticate to databases."
    },
    {
      "id": "before-you-begin",
      "title": "Before you begin",
      "role": "content",
      "text": "> [!WARNING]\n> 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\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 support **certificate credentials** when Basic and Digest authentication are disabled or unavailable. These flows don't use JWT or LDAP:\n\n- **Joining a node to the cluster** and **Active-Active database 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 for cluster management](https://redis.io/docs/latest/operate/rs/security/certificates/certificate-based-authentication#certificate-based-authentication-for-cluster-management)."
    },
    {
      "id": "follow-this-order",
      "title": "Follow this order",
      "role": "content",
      "text": "Set up and verify certificate-based authentication *before* you disable basic authentication. If you disable it first, you can lock yourself out of the cluster and out of Active-Active database management.\n\n1. Enable certificate-based authentication on the cluster (`mtls_certificate_authentication`) and add the client certificate's signing CA to the cluster's `mtls_trusted_ca`. See [Set up certificate-based authentication for the REST API](https://redis.io/docs/latest/operate/rs/security/certificates/certificate-based-authentication#set-up-certificate-based-authentication-for-the-rest-api).\n\n1. Verify that certificate authentication works *while basic authentication is still enabled*. Enabling certificate-based authentication is additive—it doesn't disable password-based access:\n\n    [code example]\n\n1. Verify that your client trusts the cluster's API certificate chain:\n\n    [code example]\n\n1. Configure certificate credentials for each participating cluster whose basic authentication you're disabling. Use either a username and password or certificate credentials per cluster—not both—so participating clusters can migrate one at a time. See [Manage an Active-Active database](https://redis.io/docs/latest/operate/rs/security/certificates/certificate-based-authentication#manage-an-active-active-database).\n\n1. Disable basic authentication.\n\nIf you lose access, see [Re-enable basic authentication](#re-enable-basic-authentication)—`rladmin` runs locally on a cluster node and doesn't require REST API access."
    },
    {
      "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": "> [!NOTE]\n> 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\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": "follow-this-order-ex0",
      "language": "sh",
      "code": "curl --cert client.pem --key client.key https://<host>:9443/v1/cluster\n    # HTTP 200",
      "section_id": "follow-this-order"
    },
    {
      "id": "follow-this-order-ex1",
      "language": "sh",
      "code": "curl --cacert <ca-bundle> --cert client.pem --key client.key https://<host>:9443/v1/cluster",
      "section_id": "follow-this-order"
    },
    {
      "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"
    }
  ]
}