<a id="cloud-cluster-link-security"></a>

# Manage Security for Cluster Linking on Confluent Cloud

Cluster Linking security uses RBAC roles or Apache Kafka® ACLs to control access at
each lifecycle phase. This page describes security considerations,
configurations, and options for Cluster Linking on Confluent Cloud.

## RBAC roles and Kafka ACLs summary

A user needs [role-based access control (RBAC)](../../security/access-control/rbac/overview.md#cloud-rbac) or Apache Kafka®
[ACLs](../../security/access-control/acls/overview.md#acl-manage) on the destination cluster in order to create and
manage cluster links and mirror topics.

The cluster link itself needs specific RBAC roles or Kafka ACLs on the source
cluster to read data and metadata.

RBAC roles and Kafka ACLs are not mutually exclusive. A [principal](../../_glossary.md#term-principal)
may have a mix of RBAC roles and Kafka ACLs, if that would better suit your
security model. In the following table, authentication options are API key or
[OAuth](../../security/authenticate/workload-identities/identity-providers/oauth/overview.md#oauth-overview) for all roles and operations.

| Principal                        | Operation                                                  | Cluster                                    | Kafka RBAC Roles                                                                                                                                                                                                                                                                                                                                 | or   | Kafka ACLs                                                                                                                                    |
|----------------------------------|------------------------------------------------------------|--------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| User, or your tooling            | Create or modify a cluster link                            | Destination cluster                        | - CloudClusterAdmin, or<br/>- EnvironmentAdmin, or<br/>- OrganizationAdmin                                                                                                                                                                                                                                                                       | or   | ALTER: Cluster                                                                                                                                |
| User, or your tooling            | Create or modify a cluster link                            | Source cluster for a source-initiated link | - CloudClusterAdmin, or<br/>- EnvironmentAdmin, or<br/>- OrganizationAdmin                                                                                                                                                                                                                                                                       | or   | ALTER: Cluster                                                                                                                                |
| User, or your tooling            | Create or modify a mirror topic                            | Destination cluster                        | - CloudClusterAdmin, or<br/>- EnvironmentAdmin, or<br/>- OrganizationAdmin                                                                                                                                                                                                                                                                       | or   | - ALTER: Cluster, and<br/>- ALTER_CONFIGS: Cluster, and<br/>- CREATE: Topic                                                                   |
| User, or your tooling            | Create or modify a mirror topic                            | Source cluster for a source-initiated link | - CloudClusterAdmin, or<br/>- EnvironmentAdmin, or<br/>- OrganizationAdmin                                                                                                                                                                                                                                                                       | or   | - ALTER: Cluster, and<br/>- ALTER_CONFIGS: Cluster, and<br/>- CREATE: Topic                                                                   |
| User, or your tooling            | List mirror topics and their statuses                      | Destination cluster                        | ClusterOperator                                                                                                                                                                                                                                                                                                                                  | or   | - DESCRIBE: Cluster *and*<br/>- DESCRIBE: Topics (on specified topics)                                                                        |
| User, or your tooling            | `promote`, `failover`, `pause`, or `resume` a mirror topic | Destination cluster                        | ClusterOperator *and* ResourceOwner on Topics                                                                                                                                                                                                                                                                                                    | or   | - DESCRIBE: Cluster *and*<br/>- ALTER: Topics *and*<br/>- DESCRIBE: Topics                                                                    |
| User, or your tooling            | `reverse-and-start` and `reverse-and-pause` a mirror topic | Source cluster                             | CloudClusterAdmin *and* ResourceOwner on Topics                                                                                                                                                                                                                                                                                                  | or   | - ALTER: Cluster *and*<br/>- ALTER: Topics                                                                                                    |
| Cluster link                     | `reverse-and-start` and `reverse-and-pause` a mirror topic | Source cluster                             | ALTER: Cluster                                                                                                                                                                                                                                                                                                                                   | or   | - ALTER: Cluster *and*<br/>- ALTER: Topics                                                                                                    |
| User, or your tooling            | `truncate-and-restore` a mirror topic                      | Destination cluster                        | CloudClusterAdmin *and* ResourceOwner on Topics                                                                                                                                                                                                                                                                                                  | or   | - ALTER: Cluster *and*<br/>- ALTER: Topics                                                                                                    |
| Cluster link <sup>[1](#f1)</sup> | Mirror topics                                              | Source cluster                             | - DeveloperRead on Topics, and<br/>- DeveloperManage on Topics, or<br/>- CloudClusterAdmin (required for source-initiated links)                                                                                                                                                                                                                 | or   | - READ: Topics, and<br/>- DESCRIBE_CONFIGS: Topics                                                                                            |
| Cluster link <sup>[1](#f1)</sup> | Sync consumer offsets                                      | Source cluster                             | - DeveloperRead on Consumer Groups, and<br/>- DeveloperRead and DeveloperManage on Topics or<br/>- Operator on Consumer Groups, and<br/>- DeveloperRead and DeveloperManage on Consumer Topics or<br/>- CloudClusterAdmin (required for source-initiated links)<br/>- **Note** Bi-directional mode links also require Operator on<br/>  Cluster. | or   | - DESCRIBE: Topics, and<br/>- DESCRIBE: ConsumerGroups<br/>- **Note** Bi-directional mode links also require<br/>  DESCRIBE_CONFIGS: Cluster. |
| Cluster link                     | Sync ACLs                                                  | Source cluster                             | - Operator on Cluster, or<br/>- CloudClusterAdmin (required for source-initiated links)                                                                                                                                                                                                                                                          | or   | DESCRIBE: Cluster                                                                                                                             |
| Cluster link                     | Source-initiated cluster link to a Confluent Cloud cluster | Destination cluster                        | CloudClusterAdmin                                                                                                                                                                                                                                                                                                                                | or   | ALTER: Cluster                                                                                                                                |
| Cluster link                     | Source-initiated cluster link to a Confluent Cloud cluster | Source cluster                             | CloudClusterAdmin                                                                                                                                                                                                                                                                                                                                | or   | ALTER: Cluster                                                                                                                                |
* <a id='f1'>**[1]**</a> CloudClusterAdmin provides full read, write, and management privileges over all Kafka resources. If you use the strategy of least privilege, a principal requires both DeveloperRead and DeveloperManage to handle mirror topics or sync consumer offsets without needing full cluster administration rights. To work with a cluster link, you need either (DeveloperRead and DeveloperManage) or CloudClusterAdmin.

To learn more about the commands `reverse-and-start`, `reverse-and-pause`,
and `truncate-and-restore`, see [Reverse a source and mirror topic](mirror-topics-cc.md#reverse-source-and-mirror-topic) and
[Convert a mirror topic to a normal topic](mirror-topics-cc.md#convert-mirror-topic-to-normal-topic).

<a id="cluster-link-security-model"></a>

## Security model

The Cluster Linking security model separates permissions and credentials for
each lifecycle step, allowing teams to independently manage cluster link
operations on topics they own. This paradigm enables many teams to use cluster
link operations on the topics that they already own. It also allows the owner
of one cluster to share data over a cluster link with another team or
organization, while only giving that team or organization READ access to the
shareable, [mirror](mirror-topics-cc.md#mirror-topics-concepts) topics.

### Advantages

The advantages of this model are:

- Permission to create and manage a cluster link is managed by
  [role-based access control (RBAC)](#cluster-linking-with-rbac-cc) or
  [access control lists (ACLs)](../../security/access-control/acls/overview.md#acl-manage) on the destination cluster.
- Cluster link access to the source cluster data is managed—and can be
  restricted—by [role-based access control (RBAC)](#cluster-linking-with-rbac-cc) or [access control lists (ACLs)](../../security/access-control/acls/overview.md#acl-manage) on the source cluster. This allows the source cluster owner to
  secure the data leaving the cluster.
- Operations performed on a cluster link and mirror topics are available
  in [Confluent Cloud Audit Logs](../../monitoring/audit-logging/cloud-audit-log-concepts.md#cloud-audit-logs).
- The cluster link has its own credentials and RBAC role-bindings / ACLs on
  the source cluster. You can manage its READ access to the source cluster just
  like any other Kafka consumer. So, you can use your existing security
  workflows with cluster links.
  - If the source cluster is a Confluent Cloud cluster, Cluster Linking supports
    all valid authentication and authorization mechanisms on Confluent Cloud, and uses
    these concepts in the same manner as a Kafka client application:
    - An admin creates a [service account](../../security/authenticate/workload-identities/service-accounts/overview.md#service-accounts) for the
      cluster link, and creates a source cluster API key and secret for that
      service account.
    - Alternatively, the cluster link can be authenticated with
      [OAuth](../../security/authenticate/workload-identities/identity-providers/oauth/overview.md#oauth-overview) and its principal will be an identity
      pool.
  - If your source cluster is a Confluent Platform or open-source Apache Kafka cluster,
    the cluster link can use SASL/PLAIN, SASL/SCRAM, SASL/OAUTHBEARER (OAuth),
    and/or mTLS. It cannot use Kerberos.
- The cluster link itself requires only read ACLs on the source cluster. No
  ACLs or credentials are required on the destination cluster in Confluent Cloud. This
  simplifies management.
- When sharing data between teams, the owner of the source cluster can
  restrict READ access to the mirror topics on the destination cluster on a
  topic-by-topic basis.

When sending data between the source and destination clusters, Cluster Linking
uses Transport Layer Security (TLS) to encrypt data in transit.

If configured as such, Cluster Linking can also sync all client ACLs, or
a configurable subset, from the source cluster to the destination cluster.

### Building blocks

The building blocks of Cluster Linking are:

- A [cluster link](index.md#cloud-cluster-link-how-it-works), which connects a
  source cluster to a destination cluster
- A [mirror topic](mirror-topics-cc.md#mirror-topics-concepts), which exists on the
  destination cluster, and receives a copy of all messages that go to its
  source topic
- A [source topic](../../topics/overview.md#cloud-topics-manage), which is a regular topic that
  exists on the source cluster and is the source of data for the mirror topic

<a id="cluster-link-lifecycle-and-permissions"></a>

## Cluster Linking lifecycle and permissions

The Cluster Linking lifecycle has six phases: creating cluster links, creating
mirror topics, reading from source, writing to destination, modifying mirror
topics, and managing cluster links. Each phase requires different permissions.
The phases are:

- A user or client application creates a cluster link.
- A user or client application creates a mirror topic using the cluster link.
- The cluster link reads topic data, consumer offsets, and ACLs from the
  source cluster.
- The cluster link writes topic data, consumer offsets, and ACLs to the
  destination cluster.
- A user or client application modifies, promotes, or deletes the mirror topic.
- A user or client application modifies or deletes the cluster link.

![Diagram showing cluster linking lifecycle with user creating cluster link and mirror topic on destination cluster, cluster link reading from source cluster, and writing to destination cluster](images/cloud-cluster-linking-security-overview.png)

### Creating or modifying a cluster link

To create or modify a cluster link, a user must be authenticated and
authorized by either a [service account](../../security/authenticate/workload-identities/service-accounts/overview.md#service-accounts) or a Confluent Cloud
[user account](../../security/authenticate/user-identities/user-accounts/overview.md#user-accounts) for [role-based permissions](../../security/access-control/rbac/overview.md#cloud-rbac) on specified resources.

If the user is authenticated with a Confluent Cloud user account, they must have
the CloudClusterAdmin, EnvironmentAdmin, or OrganizationAdmin RBAC role over
the destination cluster in order to be authorized to create, list, view, or
modify cluster links.

If the user or client application uses a service account, that service
account needs an ACL to allow them to ALTER the destination cluster. To list
the cluster links that exist on a destination cluster, that service account
needs an ACL to allow them to DESCRIBE the destination cluster.

When you create a cluster link, you must give it a way to authenticate with the source cluster.
The permissions for that are described in the following sections.

### Creating or modifying a mirror topic

To create or modify a mirror topic, a user must be authenticated and
authorized by either a service account or a Confluent Cloud user account.

To create or modify a cluster link, a user must be authenticated and
authorized by either a service account or a Confluent Cloud user account.

If the user is authenticated with a Confluent Cloud user account, they must have
the CloudClusterAdmin, EnvironmentAdmin, or OrganizationAdmin RBAC role over
the destination cluster in order to be authorized to create or modify mirror
topics.

If the user or client application uses a service account, that service
account needs these ACLs on the destination cluster:

- An ACL to allow them to ALTER the destination cluster.
- An ACL to allow them to ALTERCONFIGS on the destination cluster.
- An ACL to allow them to CREATE the mirror topic. This ACL can be one that
  allows them to create all topics, or it can be scoped by topic names.

#### ACLs required to list and describe mirror topics

The `list mirrors` command lists the mirror topics on a cluster and/or a cluster link.
You can call this command through the [Confluent Cloud API for Cluster
Linking](https://docs.confluent.io/cloud/current/ccloud/cluster-linking-v-3/)
with GET /kafka/v3/clusters/<cluster-id>/links/<link-name>/mirrors (REST) or
from the [Confluent CLI](https://docs.confluent.io/confluent-cli/current/command-reference/overview.html)  with
`confluent kafka mirror list`.

The `describe mirror` command gives information about a specific mirror topic.
You can call this command through the Confluent Cloud API with GET
/kafka/v3/clusters/<cluster-id>/links/<link-name>/mirrors/<mirror-topic>
(REST) or from the Confluent CLI with `confluent kafka mirror describe
<mirror-topic>`.

To list and describe mirror topics, you need one of the following ACLs:

- The DESCRIBE ACL on a cluster resource, which provides access to both list
  and describe for all topics on the cluster.
- The DESCRIBE ACL on specific topics, which provides access to both list and
  describe for the specified topics only.

<a id="cluster-link-read-permissions-on-source-cluster-cc"></a>

### Permissions for the cluster link to read from the source cluster

For every mirror topic on a cluster link, the cluster link reads topic data
from the respective source topic. If configured to sync consumer offsets or
ACLs, the cluster link also reads those from the source cluster. To read this,
the cluster link must authenticate with the source cluster and be authorized to
perform these actions.

#### NOTE
ACL sync for Confluent Cloud is only possible between two Confluent Cloud
clusters in the same Confluent Cloud organization, as detailed in
[ACL syncing](index.md#cluster-link-acl-sync-limits-cc).

#### Cluster link authentication and authorization for Confluent Cloud source clusters

If the source cluster is a Confluent Cloud cluster, that means the cluster link must have:

- A **service account** that represents it, and
- An **API key and secret** to use with the source cluster

If you are using an API key and secret, the following details apply.

As a security best practice, you should create a service account to represent each cluster link. For example:

```bash
confluent iam service-account create <name> --description "For my first cluster link"
```

The service account will be tied to the ACLs on the source cluster so that
the cluster link can read the appropriate data.

You will then create an API key and secret on the source cluster for the service account, as shown in this example:

```bash
confluent api-key create --resource <source-cluster-id> --service-account <service-account-id>
```

When you create the cluster link, you will give it the API key and secret, which
it will use to authenticate with the source cluster.

It is possible to give the cluster link an API key from a shared service account or
a user’s Confluent Cloud account. This is not recommended for source clusters with
sensitive data, or for production use.

![Diagram illustrating cluster linking security model showing service account authentication with API key and secret on source cluster, with ACLs controlling read access to topics](images/cloud-cluster-linking-security-model.png)

In order to be authorized to read data and metadata, the cluster link’s service
account must have these ACLs on the source cluster:

- Allowed to READ and DESCRIBE_CONFIGS for all source topics you want to
  mirror.
  This will let the cluster link mirror topic data from the source topic to the mirror topic.
  You could allow the link to read all topics by passing in “\*”, or for specific topics whose
  names match a prefix, or for specific topic names. Here is an example CLI command to give the
  cluster link READ access to all topics:
  ```bash
  confluent kafka acl create --allow --service-account <service-account-id> --operations read,describe-configs --topic "*" --cluster <source-cluster-id>
  ```
- To sync ACLs (optional), the cluster link must have permissions to DESCRIBE the source cluster.
  Here is an example of how to specify these permissions.
  ```bash
  confluent kafka acl create --allow --service-account <service-account-id> --operations describe --cluster-scope --cluster <source-cluster-id>
  ```
- To sync consumer group offsets (optional), the cluster link must have permissions to DESCRIBE source topics,
  and READ and DESCRIBE consumer groups on the source cluster. Here is an example of how to
  specify these permissions, each of which has to be specified in a separate command:
  ```bash
  confluent kafka acl create --allow --service-account <service-account-id> --operations describe --topic "*" --cluster <source-cluster-id>
  ```

  ```bash
  confluent kafka acl create --allow --service-account <service-account-id> --operations read,describe --consumer-group "*" --cluster <source-cluster-id>
  ```
- If both [prefixing](https://docs.confluent.io/cloud/current/multi-cloud/cluster-linking/mirror-topics-cc.html#prefixing-mirror-topics-and-consumer-group-names) and
  [auto-create mirror topics](https://docs.confluent.io/cloud/current/multi-cloud/cluster-linking/mirror-topics-cc.html#auto-create-mirror-topics)
  are enabled, `DESCRIBE: Cluster` is required on the source cluster.

#### IMPORTANT
**Permission validation timing**

Permissions are validated once during cluster link establishment and again upon
reconnection. However, permissions are not periodically validated for an active
cluster link. If permissions are revoked while a link is actively mirroring, the
link will continue operating until it reconnects or encounters an authorization error.

#### Summary of ACLs a cluster link needs on the source cluster

| Capability                                                            | Required ACLs on Source Cluster                                                          |
|-----------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| Mirror data from a source topic to a mirror topic                     | READ and DESCRIBE_CONFIGS for the source topic                                           |
| Sync ACLs from source cluster to destination cluster                  | DESCRIBE on the source cluster                                                           |
| Sync a consumer group’s offsets from a source topic to a mirror topic | DESCRIBE on the source topic, READ and DESCRIBE the consumer group on the source cluster |
| Enable both prefixing and auto-create mirror topics                   | DESCRIBE on the source cluster                                                           |
| Create or modify a cluster link (if this is a source-initiated link)  | ALTER: Cluster on the source cluster                                                     |

#### Providing the cluster link with an API key and secret

For testing or development, you can use a short-hand way to create a
cluster link with an API key and secret in the Confluent CLI:

```none
confluent kafka link create <link_name> --source-api-key <api-key> --source-api-secret <api-secret>
```

Using the CLI short-hand is not recommended for a cluster link in production because
the terminal history could reveal your API key and secret.

Rather, you should pass the following three properties to your cluster link’s configuration:

```properties
sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username='<api-key>' password='<api-secret>';
security.protocol=SASL_SSL
sasl.mechanism=PLAIN
```

If you create the cluster link with the CLI, you can put those three lines
in a configuration file, along with any other properties to configure on the
link,
and pass the file name to the command with the `--config` flag. For example:

```bash
confluent kafka link create <link_name> --config <path/to/file.config> ...
```

If you create the command via a REST API call, you can add the three properties
to your array of configs:

```properties
{
  "source_cluster_id": "<source cluster's ID>",
  "configs": [
    {
      "name": "security.protocol",
      "value": "SASL_SSL"
    },
    {
      "name": "sasl.mechanism",
      "value": "PLAIN"
    },
    {
      "name": "sasl.jaas.config",
      "value": "org.apache.kafka.common.security.plain.PlainLoginModule required username='<api-key>' password='<api-secret>';"
    },
    ...
  ],
  ...
}
```

The security credentials stored on the link are encrypted and cannot be
retrieved by a user. There is no way for someone to query the cluster
link to get its API key or secret.

#### Changing or rotating the security credentials on a cluster link

If you need to change or rotate the security credentials on a cluster link,
you can simply update the link’s `sasl.jaas.config` property with the new API key
and secret. For example, if you create a new file called `new-creds.config` with
an updated API key and secret:

```properties
# new-creds.config has this:
sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username='<api-key>' password='<api-secret>';
```

Then, you can run this command to specify that the cluster link use the new credentials in `new-creds.config`

```properties
confluent kafka link configuration update <link-name> --config new-creds.config
```

#### NOTE
If the cluster link loses authorization to read data from the
source cluster, the cluster link may be unavailable but the destination
topics will continue in an `ACTIVE` state of mirroring. When
authorization is restored, mirror topics will be accessible.

### Writing to the destination cluster

On Confluent Cloud, cluster links don’t need any extra permissions to write data to the
destination cluster. Because they exist on the destination cluster, they already
have the appropriate permissions.

<a id="cloud-cluster-linking-tls"></a>

## Transport Layer Security (TLS)

Cluster Linking encrypts data in transit using TLS 1.2 or higher. For a
cluster link between two Confluent Cloud clusters, data in transit is encrypted using
one-way TLS v1.2. In the Java community, this is referred to as one-way SSL.

For a cluster link from a Confluent Platform or Kafka cluster to a Confluent Cloud cluster,
data in transit must use one-way TLS. In the Java community, this is referred
to as one-way SSL. It will default to the latest version of TLS that both
clusters have enabled. TLS 1.2 and 1.3
are enabled by default in Kafka.

Older versions of SSL can be enabled, but this is discouraged due to known
security vulnerabilities.

<a id="cloud-cluster-linking-mtls"></a>

## mutual TLS (mTLS) authentication

Cluster Linking can use mTLS to provide two-way verification for some,
but not all, data exchanges:

- Confluent Cloud to Confluent Cloud does not use mTLS; it uses TLS and SASL as described
  in [Transport Layer Security (TLS)](#cloud-cluster-linking-tls).
- Data coming into Confluent Cloud from open-source Kafka can be configured to
  use mTLS.
- Data coming into Confluent Cloud from Confluent Platform can be configured to use either mTLS
  or source-initiated cluster links with TLS+SASL. mTLS can be used for
  source-initiated cluster links only in hybrid scenarios where the source
  cluster is Confluent Platform and destination cluster is a [Dedicated](../../clusters/cluster-types.md#dedicated-cluster) Confluent Cloud cluster.

When you use mTLS or certificates, you must configure the Confluent Cloud cluster
to authenticate to the Confluent Platform or Kafka source cluster using a certificate,
keystore, and truststore.
These must be stored on the cluster link’s configuration properties in PEM format (a Privacy Enhanced Mail Base64 encoded format).
Pass this configuration in when creating the cluster link in the Confluent Cloud Console, the REST API, or the Confluent CLI.
To learn more about PEM files and possible configurations, see the
[Apache Kafka KIP that introduced PEM file support](https://cwiki.apache.org/confluence/display/KAFKA/KIP-651+-+Support+PEM+format+for+SSL+certificates+and+private+key).

Use these configuration properties. Not all may be required, depending on
your specific mTLS or certificate-based authentication configuration and use
case:

```properties
security.protocol=SSL
ssl.truststore.type=PEM
ssl.keystore.type=PEM
ssl.keystore.certificate.chain
ssl.keystore.key
ssl.key.password
ssl.truststore.certificates
```

Make sure that your PEM format uses newlines (`\n`). Here’s an example
configuration:

```properties
security.protocol=SSL
ssl.keystore.type=PEM
ssl.keystore.certificate.chain=-----BEGIN CERTIFICATE-----\nxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX\nxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX ... xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX\nxXxXxXxXxXxXxXx -----END CERTIFICATE-----
ssl.keystore.key=-----BEGIN ENCRYPTED PRIVATE KEY-----\nxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX\nxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX ... xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX\nxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX\nxXxXxXxXxXxXxXxX -----END ENCRYPTED PRIVATE KEY-----
ssl.key.password=<REDACTED>
ssl.truststore.type=PEM
ssl.truststore.certificates=-----BEGIN CERTIFICATE-----\nxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX\nxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX ... xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX\nxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxX\nxXxXxXxXxXxXx -----END CERTIFICATE-----
```

Only Public-Key Cryptography Standards #8 (PKCS #8) keys are supported for the
private key specified in `ssl.keystore.key`. If the key is encrypted, the key
password must be specified using `ssl.key.password`.

#### NOTE
For [Confluent CLI versions
v3.51.0](https://docs.confluent.io/confluent-cli/current/release-notes.html#confluent-cli-v3-51-0-release-notes) or later,
`\n` can be used in certificates, and `\n` is required in between
multiple certificates.

<a id="cloud-cluster-linking-oauth"></a>

## OAuth

OAuth authenticates cluster links to source or remote Confluent Cloud, Confluent Platform, or Kafka
clusters. This workflow works the same as it would for a Kafka consumer reading
from the source cluster. To learn more, see [Use OAuth/OIDC to Authenticate to Confluent Cloud](../../security/authenticate/workload-identities/identity-providers/oauth/overview.md#oauth-overview).

### Confluent CLI example

1. Create a file of link configurations; for example, `oauth-link.config`, with OAuth authentication configuration details
   along with any other cluster link configurations:
   ```bash
   security.protocol=SASL_SSL
   sasl.oauthbearer.token.endpoint.url=https://myidp.example.com/oauth2/default/v1/token
   sasl.login.callback.handler.class=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginCallbackHandler
   sasl.mechanism=OAUTHBEARER
   sasl.jaas.config= \
     org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
       clientId='<client-id>'
       scope='<requested-scope>'
       clientSecret='<client-secret>'
       extension_logicalCluster='<cluster-id>'
       extension_identityPoolId='<pool-id>';
   # additional cluster link configurations, like consumer offset sync, can go here
   ```
2. Pass this file in to `--config` when creating the cluster link. For example:
   ```bash
   confluent kafka link create oauth-link --config oauth-link.config \
     --source-cluster lkc-123456 \
     --source-bootstrap-server pkc-12345.us-west-2.aws.confluent.cloud:9092
   ```

### REST API example

In the [POST request to create the cluster link](cluster-links-cc.md#cluster-link-create-with-rest-api), include the OAuth configurations in the standard format:

```bash
{
  "name": "<config-name>",
  "value": <config-value>
}
```

For example:

```bash
{
  "source_cluster_id": "<source-cluster-id>",
  "configs": [
    {
      "name": "security.protocol",
      "value": "SASL_SSL"
    },
    {
      "name": "bootstrap.servers",
      "value": "<source-bootstrap-server>"
    },
    {
      "name": "sasl.mechanism",
      "value": "OAUTHBEARER"
    },
    {
      "name": "sasl.oauthbearer.token.endpoint.url",
      "value": "https://myidp.example.com/oauth2/default/v1/token"
    },
    {
      "name": "sasl.login.callback.handler.class",
      "value": "org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginCallbackHandler"
    },
    {
      "name": "sasl.jaas.config",
      "value": "org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required clientId='<client-id>' scope='<requested-scope>' clientSecret='<client-secret>' extension_logicalCluster='<cluster-id>' extension_identityPoolId='<pool-id>';"
    }
  ]
}
```

## Public internet exposure

Unless otherwise noted, Cluster Linking between two clusters on Confluent Cloud uses
public IP addresses and public DNS. However, this does not necessarily mean that
the cluster linked data goes over the public internet:

- Traffic between two clusters that are both on Amazon Web Services (AWS)
  always stays on AWS and never goes to the public internet. Per the [AWS
  documentation](https://aws.amazon.com/vpc/faqs/#:~:text=the%20Internet%20gateway.-,Q.,AWS%20use%20AWS's%20private%20network):
  “When using public IP addresses, all communication between instances and services hosted in AWS use AWS’s private network.”
- Traffic between two clusters that are both on Microsoft Azure always stays
  on Azure and never goes to the public internet. Per the [Azure
  documentation](https://learn.microsoft.com/en-us/azure/virtual-network/virtual-networks-udr-overview#:~:text=If%20the%20destination,is%20deployed%20in.):
  “If the destination address is for one of Azure’s services, Azure routes the traffic directly to the service over Azure’s
  backbone network, rather than routing the traffic to the Internet. Traffic between Azure services doesn’t traverse the Internet.”
- All traffic is encrypted in transit. See [Transport Layer Security (TLS)](#cloud-cluster-linking-tls).

#### NOTE
Traffic between a non Confluent Cloud cluster and a Confluent Cloud cluster
might not use public IP addresses and/or public DNS.

Cluster Linking in Confluent Cloud supports both single-cloud and multi-cloud
deployments for clusters with private networking.
In a single-cloud environment, replication uses the cloud provider’s routed backbone  (AWS, Azure , Google Cloud). When linking
clusters across clouds, data replication is encrypted and transmitted over authenticated connections.

Connectivity is controlled by allow-listing trusted Confluent IP addresses,
and only TLS traffic to known internal endpoints is permitted.
For Apache Kafka® clusters deployed in private networks, Cluster Linking enforces
[IP filtering](../../security/access-control/ip-filtering/overview.md#ip-filtering), [mutual TLS](../../security/authenticate/workload-identities/identity-providers/mtls/configure.md#configure-mtls),
and [SASL authentication on Confluent
Platform](/platform/current/security/authentication/sasl/overview.html) to ensure that only
authorized clusters within the same organization can replicate data.
Source-initiated replication to public Kafka clusters is permitted only after
verifying the originating network, mitigating the risk of data exfiltration.

## Practical examples

To see practical examples of how you might model security for different Cluster Linking
deployments, refer to these use case tutorials:

- [Data Sharing](topic-data-sharing.md#cloud-cluster-link-topic-data-sharing)
- [Cluster Linking Disaster Recovery and Failover on Confluent Cloud](dr-failover.md#cloud-cluster-linking-dr)

## Audit logs

Whenever a user or application tries to create or delete a cluster link or a
mirror topic, authentication and authorization events are created in
[Confluent Cloud Audit Logs](../../monitoring/audit-logging/cloud-audit-log-concepts.md#cloud-audit-logs).
This allows you to monitor Cluster Linking access and activity throughout Confluent Cloud.

<a id="cluster-linking-with-rbac-cc"></a>

## Using role-based access control (RBAC) with Cluster Linking

The following demo shows using Cluster Linking with Confluent Cloud RBAC,
followed by a summary of the roles needed on different resources.

### Demo

This short video shows how to set up a cluster link across clusters with RBAC
enabled, and make topic data available across clusters with different owners.

<iframe width="560" height="315" src="https://www.youtube.com/embed/RKzFJ1M_GkE" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

In the example, the owner of a Webstore cluster gives the Logistics cluster
owner role-based access to all topics prefixed with `public`, such as orders,
clicks, and products data.

The Logistics owner can then mirror Webstore topics on the Logistics cluster as
if they were native, and get visibility into that external, streaming data.

### Confluent Cloud RBAC roles

To enable secure Cluster Linking on Confluent Cloud, grant RBAC roles to
principals as described in this section, or [grant specific ACLs as
previously described](#cloud-cluster-link-security).

At least one of the following RBAC roles is required to create a cluster link:

- [ResourceOwner](../../security/access-control/rbac/predefined-rbac-roles.md#resourceowner-role) on the Cluster
- [CloudClusterAdmin](../../security/access-control/rbac/predefined-rbac-roles.md#cloudclusteradmin-role) on the Cluster
- [EnvironmentAdmin](../../security/access-control/rbac/predefined-rbac-roles.md#environmentadmin-role) on the cluster’s Environment
- [OrganizationAdmin](../../security/access-control/rbac/predefined-rbac-roles.md#organizationadmin-role) on the cluster’s Organization

The Cluster Link service account requires one of the following sets of Confluent Cloud RBAC roles:

- Recommended: [DeveloperRead](../../security/access-control/rbac/predefined-rbac-roles.md#developerread-role) and [DeveloperManage](../../security/access-control/rbac/predefined-rbac-roles.md#developermanage-role) on the source cluster topics to be mirrored
- Not recommended for production: Any of the roles listed earlier for
  creating a cluster link

### ACLs and consumer offset sync

To sync ACLs, the cluster link must have the following role:

- [Operator](../../security/access-control/rbac/predefined-rbac-roles.md#operator-role) on the cluster

To sync consumer offsets, the cluster link must have one of the following roles:

- [Operator](../../security/access-control/rbac/predefined-rbac-roles.md#operator-role) on the cluster, or
- [DeveloperRead](../../security/access-control/rbac/predefined-rbac-roles.md#developerread-role) on the consumer groups

## Related content

- [User account types](../../security/authenticate/user-identities/user-accounts/overview.md#user-accounts)
- [Service Accounts on Confluent Cloud](../../security/authenticate/workload-identities/service-accounts/overview.md#service-accounts)
- [ACL concepts](/platform/current/kafka/authorization.html#acl-concepts)
- [How to use a custom truststore when connecting to Confluent Cloud](https://support.confluent.io/hc/en-us/articles/360040325391)