# Migrate to Redpanda Console v3.0.0

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [streaming-full.txt](https://docs.redpanda.com/streaming-full.txt)

---
title: Migrate to Redpanda Console v3.0.0
latest-redpanda-tag: v25.1.1
latest-console-tag: v3.7.3
latest-operator-version: v26.1.4
# EOL = End-of-Life (support lifecycle status)
page-is-nearing-eol: "false"
page-is-past-eol: "true"
page-eol-date: April 7, 2026
latest-connect-version: 4.93.0
docname: console-v3
page-component-name: streaming
page-version: "25.1"
page-component-version: "25.1"
page-component-title: Streaming
page-relative-src-path: console-v3.adoc
page-edit-url: https://github.com/redpanda-data/docs/edit/v/25.1/modules/migrate/pages/console-v3.adoc
page-git-created-date: "2025-05-07"
page-git-modified-date: "2025-10-02"
support-status: past end-of-life
---

<!-- Source: https://docs.redpanda.com/streaming/25.1/migrate/console-v3.md -->

This guide provides step-by-step instructions for migrating from Redpanda Console v2.x.x (v2) to v3.0.x (v3). The new release introduces user impersonation to unify authentication and authorization between Redpanda Console and Redpanda, along with several breaking changes. This guide explains these changes and provides examples to help you update your configuration.

For details on the new authentication and authorization system, see [Authentication in Redpanda Console](https://docs.redpanda.com/streaming/25.1/console/config/security/authentication/). For a list of breaking changes, see [What’s New in Redpanda](https://docs.redpanda.com/streaming/25.1/get-started/release-notes/redpanda/).

> 💡 **TIP: Try the Redpanda Console migration tool**
>
> Use the [migration tool](#migrator) to convert your v2 configuration to v3 format.

## [](#authentication-and-authorization-migration)Authentication and authorization migration

In v2, authentication and authorization was handled by the Redpanda Console. In v3, Redpanda Console uses the same authentication and authorization system as Redpanda. This change unifies the authentication and authorization model across Redpanda and Redpanda Console, enabling a more consistent and secure experience.

### [](#migrate-from-the-plain-login-provider)Migrate from the plain login provider

In v3, the plain login provider has been removed. Instead, you can either enable user impersonation or use static credentials for authentication. User impersonation forwards the credentials from the logged-in user to the APIs that have user impersonation enabled. With static credentials, the credentials specified in the configuration are used to authenticate with the APIs. For more information, see [Authentication in Redpanda Console](https://docs.redpanda.com/streaming/25.1/console/config/security/authentication/).

Here is an example of how to migrate from the plain login provider to user impersonation:

V2 plain login with RBAC

```yaml
login:
  enabled: true
  jwtSecret: "secret-key"
  useSecureCookies: false
  plain:
    enabled: true
    credentials:
      - username: "jane"
        password: "some-other-secret-password"
      - username: "john"
        password: "some-secret-password"
enterprise:
  rbac:
    enabled: true
    roleBindingsFilepath: /tmp/role-bindings.yml
```

V3 user impersonation

```yaml
kafka:
  sasl:
    enabled: true
    impersonateUser: true (1)
redpanda:
  adminApi:
    authentication:
      impersonateUser: true
schemaRegistry:
  enabled: true
  authentication:
    impersonateUser: true
authentication:  (2)
  jwtSigningKey: "secret-key"
  useSecureCookies: false
  basic:
    enabled: true  (3)
```

| 1 | When using user impersonation, the credentials from the logged-in user are forwarded to this API. As a result, any static role-binding settings are ignored for impersonated API calls. Ensure your users are provisioned as SASL/SCRAM users in Redpanda. See Configure Authentication. |
| --- | --- |
| 2 | The authentication stanza replaces the login stanza in v3. Use this stanza to configure authentication settings. |
| 3 | The basic block enables basic authentication for Redpanda Console. |

Role bindings in Redpanda Console are ignored with user impersonation. Instead, the credentials from the logged-in user are forwarded to the Redpanda APIs that have user impersonation enabled. Ensure that your logged-in users have the necessary ACLs in Redpanda. See [Redpanda Authorization Mechanisms](https://docs.redpanda.com/streaming/25.1/manage/security/authorization/).

If you prefer to disable user impersonation so that static credentials are used instead, modify your configuration as follows:

V3 static credentials

```yaml
kafka:
  sasl:
    enabled: true
    impersonateUser: false (1)
    username: "jane" (2)
    password: "some-other-secret-password"
    mechanism: SCRAM-SHA-256
schemaRegistry:
  enabled: true
  authentication:
    impersonateUser: false
    basic:
      username: "jane"
      password: "some-other-secret-password"
    #bearerToken: "example-bearer-token" # For OAuth2 bearer token
redpanda:
  adminApi:
    authentication:
      impersonateUser: false
      basic:
        username: "jane"
        password: "some-other-secret-password"
      #bearerToken: "example-bearer-token" # For OAuth2 bearer token
authentication:
  jwtSigningKey: "secret-key"
  useSecureCookies: false
  basic:
    enabled: true
# With static credentials, the role bindings still apply to control Console access.
authorization: (3)
  roleBindings:
    - roleName: admin
      users:
        - loginType: basic
          name: "jane"
```

| 1 | Set impersonateUser to false to disable user impersonation. |
| --- | --- |
| 2 | Specify the username, password, and mechanism for the static credentials. |
| 3 | Role bindings are applied when using static credentials. |

> ❗ **IMPORTANT**
>
> When impersonation is disabled, the static credentials specified in the `kafka.sasl` block are used to authenticate with the Kafka API when you log into Redpanda Console. Ensure that these credentials have the necessary ACLs in Redpanda. See [Redpanda Authorization Mechanisms](https://docs.redpanda.com/streaming/25.1/manage/security/authorization/).

### [](#migrate-from-oidc-providers)Migrate from OIDC providers

In v2, Redpanda Console supported separate configuration for OIDC providers such as Google, GitHub, and Keycloak. In v3, the OIDC configuration has been simplified, and the `login` stanza has been replaced by the `authentication` stanza. For more information, see [Authentication in Redpanda Console](https://docs.redpanda.com/streaming/25.1/console/config/security/authentication/).

> 📝 **NOTE**
>
> OIDC-based group authorization is no longer available in Redpanda Console. With the move to unified authentication, RBAC is now managed directly in Redpanda, which does not support OIDC groups. If you previously relied on OIDC groups to manage access, you must now transition to the RBAC model. Redpanda Data recommends mapping your existing group-based permissions to RBAC roles that reflect the same access levels. This change provides a more unified and fine-grained authorization approach.

Here is an example of how to migrate from Google OIDC in v2 to v3:

V2 Google OIDC

```yaml
login:
  enabled: true
  jwtSecret: "old-google-secret"
  google:
    enabled: true
    clientId: "google-client-id-v2"
    clientSecret: "google-client-secret-v2"
    issuerUrl: "https://accounts.google.com"
    # issuerTls, displayName, and userIdentifyingClaimKey may be present in v2 but are omitted here for brevity.
```

V3 Google OIDC

```yaml
kafka:
  sasl:
    enabled: true
    impersonateUser: true (1)
authentication: (2)
  jwtSigningKey: "old-google-secret"
  useSecureCookies: true
  oidc: (3)
    enabled: true
    issuerUrl: "https://accounts.google.com"
    clientId: "google-client-id-v2"
    clientSecret: "google-client-secret-v2"
```

| 1 | When using user impersonation, the credentials from the logged-in user are forwarded to the Kafka API. As a result, any static role-binding settings are ignored for impersonated API calls. Ensure your Redpanda cluster has SASL/OAUTHBEARER authentication enabled. See Redpanda Authorization Mechanisms. |
| --- | --- |
| 2 | The authentication stanza replaces the login stanza in v3. Use this stanza to configure authentication settings. |
| 3 | The oidc block enables OIDC authentication for Redpanda Console. See Authentication in Redpanda Console. |

Redpanda requires a JWT-encoded access token for authentication. While most identity providers issue JWTs, some (like Google) follow the OAuth spec and issue opaque tokens instead. Since Redpanda relies on JWTs to introspect the audience and subject, providers that do not support JWT access tokens cannot be used for authentication.

### [](#role-bindings)Role bindings

In Console v2, role bindings could be configured in a separate file. In v3, role bindings are configured directly in the `authorization.roleBindings` stanza of the main configuration file.

If you do **not** use impersonation, you can continue to use role bindings to control access within Redpanda Console. Each role binding maps users to roles in Redpanda Console using their login type and identity.

Here is an example of how to migrate role bindings from a separate file to the main configuration:

V2 role bindings

```yaml
enterprise:
  rbac:
    enabled: true
    roleBindingsFilepath: "/path/to/roleBindings.yaml"
# v2: Role bindings configured in a separate file.
roleBindings:
  - roleName: admin
    metadata:
      name: Developers
      creator: John Doe
    subjects:
      - kind: user
        provider: Plain
        name: alice
```

V3 role bindings

```yaml
authorization:
  roleBindings:
    - roleName: admin
      users:
        - loginType: basic
          name: alice
```

#### [](#migrate-console-roles-to-redpanda-acls)Migrate Console roles to Redpanda ACLs

If you are using **impersonation** in v3, `roleBindings` are ignored. Instead, access is controlled by Redpanda using ACLs and RBAC.

You must provision your users in Redpanda and grant them the appropriate permissions.

The following examples show how to map Console roles (`viewer`, `editor`, `admin`) to Redpanda ACLs.

| Console Role | Equivalent ACLs in Redpanda |
| --- | --- |
| Viewer | read, describe on topics and groups |
| Editor | read, write, describe on topics and describe on groups |
| Admin | All of the above, plus add the user as a superuser principal using the cluster configuration |

```bash
# Viewer role in Redpanda Console -> Redpanda ACLs
rpk security acl create \
  --allow-principal User:alice@example.com \
  --operation read,describe \
  --topic '*' \
  --group '*'

# Editor role in Redpanda Console -> Redpanda ACLs
rpk security acl create \
  --allow-principal User:alice@example.com \
  --operation read,write,describe \
  --topic '*'

rpk security acl create \
  --allow-principal User:alice@example.com \
  --operation describe \
  --group '*'

# Admin role in Redpanda Console -> Redpanda superuser
rpk cluster config set superusers "['alice@example.com']"
```

For details, see:

-   [Access Control Lists](https://docs.redpanda.com/streaming/25.1/manage/security/authorization/acl/)

-   [Authorization in Redpanda Console](https://docs.redpanda.com/streaming/25.1/console/config/security/authorization/)


## [](#schema-registry-migration)Schema Registry migration

In v2, the Schema Registry configuration was nested under the `kafka` stanza. In v3, this configuration is now a top-level stanza.

V2 Schema Registry

```yaml
kafka:
  brokers:
    - "broker-0.mycompany.com:19092"
  schemaRegistry:
    enabled: true
    urls:
      - "http://schema-registry.mycompany.com:8081"
    # Basic authentication:
    username: "example-user"
    password: "example-password"
    # Bearer token:
    bearerToken: "example-bearer-token"
    # TLS configuration:
    tls:
      enabled: false
      caFilepath: "/path/to/ca-cert.pem"
      certFilepath: "/path/to/client-cert.pem"
      keyFilepath: "/path/to/client-key.pem"
      insecureSkipTlsVerify: false
```

V3 Schema Registry

```yaml
schemaRegistry:
  enabled: true
  urls:
    - "http://schema-registry.mycompany.com:8081"
  authentication:
    impersonateUser: false
    basic:
      username: "example-user"
      password: "example-password"
    bearerToken: "example-bearer-token"
  tls:
    enabled: false
    caFilepath: "/path/to/ca-cert.pem"
    certFilepath: "/path/to/client-cert.pem"
    keyFilepath: "/path/to/client-key.pem"
    insecureSkipTlsVerify: false
```

## [](#serde-and-kafka-connect-migration)Serde and Kafka Connect migration

In v3, all serialization settings are consolidated under the `serde` stanza. The connect configuration has been renamed to `kafkaConnect`, and the `console.maxDeserializationPayloadSize` setting is now part of the `serde` configuration.

V2 serde and Kafka Connect

```yaml
kafka:
  protobuf:
    enabled: false
    mappings: []
  cbor:
    enabled: false
  messagePack:
    enabled: false
console:
  maxDeserializationPayloadSize: 20480
connect:
  enabled: false
  clusters: []
```

V3 serde and Kafka Connect

```yaml
serde:
  maxDeserializationPayloadSize: 20480
  protobuf:
    enabled: false
    mappings: []
  cbor:
    enabled: false
  messagePack:
    enabled: false
kafkaConnect:
  enabled: false
  clusters: []
```

## [](#validate-migration)Validate migration

After updating your configuration, verify that:

-   Users can log in using the new authentication settings.

-   API calls to Kafka, Schema Registry, and the Admin API are authenticated correctly.


## [](#migrator)Redpanda Console migration tool

This migration tool attempts to convert your Redpanda Console configuration from v2 to v3 format. The tool is provided as a convenience and may not cover all migration scenarios. Always review the output to ensure that your configuration is correct.

To use the tool, paste your v2 YAML configuration into the text box and click **Migrate** to generate the updated configuration. To test the tool, click **Load sample** to load a sample configuration.

If you have a separate file for role bindings, paste the contents into the text box along with the main configuration. In v3, role bindings are configured directly in the main configuration file. The tool attempts to convert your role bindings into the new format and adds them to the main configuration file in the output.

Load sample Clear Migrate

Review the output before deploying the new configuration. If you encounter any issues, refer to the examples in this guide to manually update your configuration.

Copy output

## [](#suggested-reading)Suggested reading

-   [Authentication in Redpanda Console](https://docs.redpanda.com/streaming/25.1/console/config/security/authentication/)

-   [Redpanda Console Security](https://docs.redpanda.com/streaming/25.1/console/config/security/)

-   [Configure Authentication](https://docs.redpanda.com/streaming/25.1/manage/security/authentication/)

-   [Redpanda Authorization Mechanisms](https://docs.redpanda.com/streaming/25.1/manage/security/authorization/)