Migrate ACLs from mTLS to OAuth in Confluent Platform

This guide provides step-by-step instructions for migrating Access Control Lists (ACLs) from mTLS (mutual TLS) to OAuth authentication in your Confluent Platform clusters. This migration can help improve security and simplify authentication management in your Confluent Platform environment.

You can migrate your access control lists (ACLs) from mTLS ACLs to OAuth ACLs in Confluent Platform. If you ensure that the principal is the same, there is no need to change anything with the ACLs.

For example, the Confluent Platform cluster in the diagram below is configured to support both mTLS and OAuth authentication. To migrate the ACLs, you need to create OAuth ACLs for the mTLS principals. Client App2 uses mTLS to authenticate to the Confluent Platform cluster, and the ACLs are evaluated based on the mTLS principal. For Client App1, the ACLs are evaluated based on the OAuth principal. If the principal is the same, the ACLS do not need to be changed, but are evaluated based on the OAuth principal. As long as you update the clients and services to use OAuth tokens, the ACLs continue to work.

Before upgrade, ACLs from mTLS used in Confluent Platform

As long as you update the clients and services to use OAuth tokens, the ACLs continue to work. In the following diagram, the ACLs are evaluated based on the OAuth principal.

After upgrade, ACLs from OAuth used in Confluent Platform

Steps to migrate ACLs from mTLS to OAuth

If the principals (user identities) remain the same when moving from mTLS to OAuth, no changes to the ACLs are necessary. The ACLs will continue to work as before, but are evaluated based on the OAuth principal instead of the mTLS principal.

To migrate your access control lists (ACLs) from mTLS ACLs to OAuth ACLs in Confluent Platform, you need to follow these general steps.

Step 1 - Ensure OAuth is configured

Before migrating your ACLs, ensure that OAuth is properly configured and operational in your environment. This involves setting up an identity provider (IdP) and configuring your Confluent Platform cluster to validate OAuth tokens.

Step 2 - Review and update existing ACLs

Review your existing ACLs to understand your current access control permissions:

  • Identify principal mapping: Determine how your mTLS principals map to OAuth principals. In most cases, if you’ve set up your OAuth configuration correctly, these should be the same.
  • No changes needed if principals match: If the mTLS principals match the OAuth principals, no changes to the ACLs are necessary. The existing ACLs work with OAuth authentication.
  • Identify discrepancies: If there are cases where the principals don’t match between mTLS and OAuth, note these for further action. These are the only instances where you might need to create new ACLs or modify existing ones.
  • Document current ACLs: It’s a good practice to document your current ACL permissions before proceeding with the migration. This can serve as a reference point and aid in troubleshooting if needed.

In most cases, the goal is not to “migrate” ACLs, but to ensure that your existing ACLs work seamlessly with OAuth authentication.

List existing ACLs

To list existing ACLs, use the following Confluent CLI command:

confluent kafka acl list

This will display all ACLs currently in place, including those based on mTLS principals. For more information on using the Confluent CLI, see confluent kafka acl list [CLI Reference].

Principal formats in mTLS and OAuth

The format of the principal is not inherently different between mTLS and OAuth. In both cases, the principal format is typically User:<username>. For example:

Principal: User:client1

This format can be used for both mTLS and OAuth authentication, assuming you configured your identity mapping correctly.

The key difference is in how the username is derived:

  • In mTLS, the username is typically extracted from the client certificate’s Distinguished Name (DN).
  • In OAuth, the username is typically extracted from a claim in the OAuth token (for example, the sub claim).

Your Confluent Server broker configuration determines how these identities are mapped to the User:<username> format. If configured correctly, the principal can remain the same when migrating from mTLS to OAuth, meaning no changes to ACLs are necessary.

However, if your configuration results in different usernames between mTLS and OAuth, you need to update your ACLs accordingly.

Make ACL changes on a running cluster

ACL changes can be made on a running Kafka cluster without requiring a restart. This allows for dynamic updates to access controls as needed during and after the migration process.

  • Real-time updates: ACL changes take effect immediately after they are applied.
  • No downtime required: You can add, modify, or remove ACLs without interrupting cluster operations.
  • Incremental migration: This allows for a gradual transition, updating ACLs for specific clients or resources as needed.

However, keep in mind:

  • Caching: Some clients might cache authentication results. Ensure that client applications are configured to refresh their authentication status regularly.
  • Monitoring: After making ACL changes, monitor your cluster closely to ensure the changes have the intended effect and don’t unintentionally disrupt operations.
  • Testing: If possible, test your ACL changes in a non-production environment before applying them to a production cluster.

Remember, while ACL changes can be made dynamically, you need to plan and execute these changes carefully to maintain the security and functionality of your Confluent Platform environment.

Step 3 - Monitor and adjust

Monitor your Confluent Platform cluster for any access issues and adjust the ACLs as necessary. Ensure that all new clients and services use OAuth for authentication.

After migrating ACLs and updating clients to use OAuth:

  • Test access for each client using OAuth tokens.
  • Verify that all expected operations (read, write, etc.) are permitted.
  • Confirm that unauthorized access is still properly restricted.
  • You can use Confluent Control Center or Confluent CLI to review the applied ACLs.

Troubleshooting

If you encounter issues during or after the migration, consider the following:

  • Verify OAuth configuration: Ensure that your OAuth settings are correct and that your identity provider is properly configured.
  • Check ACL mappings: Confirm that the OAuth principals correctly map to the intended mTLS principals.
  • Review logs: Check Confluent Platform logs for any authentication or authorization errors.
  • Test with both authentication methods: If possible, test access using both mTLS and OAuth to isolate any issues.

For further assistance, contact Confluent support.

Related content