PolarDB for MySQL integrates with Active Directory (AD) to support Kerberos authentication. Once connected, users log in to your PolarDB for MySQL cluster using their AD credentials — no separate database password required. This is useful for enterprises that enforce centralized identity management and single sign-on (SSO) across their infrastructure.
Limitations
Before you begin, note the following constraints:
-
Feature availability: This feature is in canary release. Apply for a trial before proceeding.
-
Database engine version: MySQL 8.0.1 only.
-
Minor version: V8.0.1.1.44.2 or later. For upgrade instructions, see Version management.
-
Edition: Enterprise Edition only.
-
Series: Cluster Edition only.
-
Network: The PolarDB for MySQL cluster must connect to the AD domain controller over a private network. All components — the cluster, AD controller ECS instance, and client ECS instance — must reside in the same virtual private cloud (VPC).
-
MySQL client: Only MySQL official clients version 8.0.26 or later support the
authentication_kerberos_clientplugin required for Kerberos login.
How it works
The setup involves three components:
-
AD domain controller (on an ECS instance): Acts as the Kerberos Key Distribution Center (KDC). Authenticates users and issues Kerberos tickets.
-
PolarDB for MySQL cluster: The service being protected. Uses a keytab file to verify client tickets without contacting the KDC on every connection.
-
Client (on an ECS instance): Requests a Kerberos ticket from the KDC, then presents it to authenticate against the PolarDB for MySQL cluster.
A Service Principal Name (SPN) in the format ServiceType/HostName@REALM uniquely identifies the PolarDB service instance in the Kerberos realm. The keytab file stores the mapping between the SPN and its encryption key, allowing the cluster to validate tickets independently.
Prerequisites
Before you begin, ensure that you have:
-
An ECS instance to host the AD domain controller, running Windows Server 2016 or later (English language). This example uses Windows Server 2022.
-
An ECS instance to host the client, residing in the same VPC as both the PolarDB for MySQL cluster and the AD controller ECS instance.
-
An Alibaba Cloud account with access to the PolarDB for MySQL console.
If you already have a working AD domain and client environment, skip Steps 1 and 2 and go directly to Step 3: Configure the AD domain server in PolarDB.
Overview
The end-to-end setup consists of five steps:
-
Configure an AD domain controller on an ECS instance (optional — skip if you have an existing AD domain)
-
Open the required ports on the AD controller security group (optional — skip if already configured)
-
Authenticate from the client and connect (optional — skip if your client environment is already configured for Kerberos)
Step 1: (Optional) Configure an AD domain controller
Skip this step if you already have an AD domain.
-
Log on to the ECS instance running Windows Server 2022 using Remote Desktop.
Install the AD domain controller on Windows Server 2016 or later. This example uses Windows Server 2022.
-
Open Server Manager.
-
Click Add roles and features and configure the following settings:
Page Setting Installation type Keep the default settings. Server selection Keep the default settings. Server roles Select Active Directory Domain Services. In the dialog box, click Add Features. Also select DNS Server and click Add Features. Make sure the ECS instance uses a static IP address — a dynamic IP makes the DNS server unavailable. Features Keep the default settings. AD DS Keep the default settings. DNS server Keep the default settings. Confirmation Click Install. 
-
After the installation completes, click Close.
-
In the left-side navigation pane, click AD DS. In the upper-right corner, click More.

-
In the Action column, click Promote this server to a domain. Configure the following settings:
Page Setting Deployment configuration Select Add a new forest and specify the domain name. 
Domain controller options Specify and confirm the password for Directory Services Restore Mode (DSRM). 
DNS options Clear Create DNS delegation. 
Additional options Keep the default settings. Paths Keep the default settings. Review options Keep the default settings. Prerequisites check Click Install. The system restarts automatically after installation. 
-
After the system restarts, open Server Manager again.
-
In the left-side navigation pane, click AD DS. In the server list, right-click the domain controller and select Active Directory Users and Computers.

-
In the left-side navigation pane, expand polardb.domain and click Users. Right-click Users and select New > User.

-
Enter a logon username (for example,
polardbmtestuser) and click Next.
-
Set the password, select Password never expires, click Next, then click Finish.

-
Double-click the user you created. In the Account options section, enable the options for Kerberos AES encryption support.

-
Repeat Steps 9–12 to create a second user named
polardbm. In this example,polardbmtestuseris used for client access andpolardbmis used for server-side authentication in the PolarDB for MySQL cluster.
Step 2: (Optional) Open required ports on the AD controller
Skip this step if the security group is already configured.
The AD domain controller requires a dedicated security group. Avoid sharing it with other ECS instances, as a large number of ports need to be open.
-
Log on to the ECS console.
-
In the left-side navigation pane, choose Instances & Images > Instances.
-
In the top navigation bar, select the region where the AD controller ECS instance resides.
-
Click the ECS instance ID to open the instance details page.
-
Click the Security Groups tab. Find the security group and click Manage Rules in the Operation column.
-
On the Inbound tab, click Quick Add and open the following ports:
Protocol Port or range Service TCP 88 Kerberos authentication TCP 135 RPC (Remote Procedure Call) TCP/UDP 389 LDAP (Lightweight Directory Access Protocol) TCP 445 CIFS (Common Internet File System) TCP 3268 Global Catalog TCP/UDP 53 DNS TCP 49152–65535 Default dynamic port range (example: 49152/65535)
Step 3: Configure the AD domain server in PolarDB
-
Go to the Clusters page in the PolarDB for MySQL console. Select the region, then click the cluster ID.
-
In the left-side navigation pane, choose Settings and Management > Accounts. Click the AD Domain Services tab.

-
Click Configure Server Info in AD Domain and set the following parameters: After you fill in Server hostname and Domain name, the console displays a suggested
ktpasscommand for generating the keytab file.The Server service name, Server hostname, and Domain name values together form a Kerberos SPN in the format
ServiceType/HostName@REALM. SPNs uniquely identify service instances in the Kerberos realm, ensuring clients can securely reach the intended service.Parameter Description Server service name The service type to be requested. Defaults to polardbmand cannot be modified.Server hostname The hostname of the service. Defaults to the cluster ID and cannot be modified. Domain name The root domain name of the self-managed AD domain. Example: POLARDB.DOMAIN. If you use your own AD domain (for example, Azure Active Directory, now known as Microsoft Entra ID), enter its domain name.Server user in AD domain The AD user account used for server-side authentication. Example: polardbm.

-
Generate the keytab file on the AD controller ECS instance. A keytab file is a binary file that stores mappings between SPNs and their encryption keys. It allows the PolarDB for MySQL cluster to authenticate Kerberos tickets without contacting the KDC on every connection. Open Windows PowerShell on the AD controller ECS instance. Run the
ktpasscommand shown in the console. In the command:
Confirm the command completes without errors. Then run setspnto verify the SPN mapping forpolardbm.-
Replace
-out xxx.keytabwith your desired keytab filename. -
Replace
-pass yourPasswordwith the password you set for thepolardbmuser in Step 1.

-
-
Copy the keytab file to your local computer.
-
Back in the PolarDB console, click Select File to upload the keytab file, then click OK.
After the configuration is submitted, the cluster enters the Maintaining Instance state.

Step 4: Configure the client user in PolarDB
-
In the left-side navigation pane, choose Settings and Management > Accounts. Click the AD Domain Services tab, then click Configure Client Info.

-
In the Create client user in AD domain dialog box, set the following parameters:
Parameter Description Client user The name of the Kerberos-authenticated user to create in the PolarDB for MySQL cluster. This must match the client user you created in the AD domain. Example: polardbmtestuser.Domain name The root domain name of the self-managed AD domain. Example: POLARDB.DOMAIN.
-
Click OK.
After the configuration is submitted, the cluster enters the Maintaining Instance state.
-
To verify the user was created, choose Settings and Management > Accounts and click the User Account tab. The new user appears in the list. Note the following about AD domain users:
-
Permissions can be modified.
-
The password cannot be changed and the user cannot be deleted directly. To delete the user, remove them from the client information on the AD Domain Services tab first.

-
Step 5: (Optional) Authenticate from the client and connect
Skip this step if your client ECS instance is already configured for Kerberos authentication.
Perform the following operations on the client ECS instance.
-
Configure the Kerberos client by editing
/etc/krb5.conf:# To opt out of the system crypto-policies configuration of krb5, remove the # symlink at /etc/krb5.conf.d/crypto-policies which will not be recreated. includedir /etc/krb5.conf.d/ [logging] default = FILE:/var/log/krb5libs.log kdc = FILE:/var/log/krb5kdc.log admin_server = FILE:/var/log/kadmind.log # Set default_realm to the root domain name of the self-managed AD domain. # This example uses POLARDB.DOMAIN. [libdefaults] dns_lookup_realm = false ticket_lifetime = 24h renew_lifetime = 7d forwardable = true rdns = false pkinit_anchors = FILE:/etc/pki/tls/certs/ca-bundle.crt spake_preauth_groups = edwards25519 default_realm = POLARDB.DOMAIN default_ccache_name = KEYRING:persistent:%{uid} # Set kdc and admin_server to the AD domain controller address. # Add ad.polardb.domain to /etc/hosts, bound to the IP of the AD controller ECS instance. # The default KDC port is 88. [realms] POLARDB.DOMAIN = { kdc = ad.polardb.domain:88 admin_server = ad.polardb.domain:88 } # Map domain suffixes to the Kerberos realm. [domain_realm] .polardb.domain = POLARDB.DOMAIN polardb.domain = POLARDB.DOMAIN -
Request a Kerberos ticket for the client user:
kinit polardbmtestuserEnter the user's AD password when prompted.
-
Connect to the PolarDB for MySQL cluster using the primary address:
Only MySQL official clients version 8.0.26 or later support the
authentication_kerberos_clientplugin. The--plugin-dirflag specifies the directory containing bothauthentication_kerberos_client.soand its dependencyauthentication_oci_client.so../mysql -h <primary-address> -P 3306 --default-auth=authentication_kerberos_client --plugin-dir=/root/mysql-client/plugin --user=polardbmtestuserReplace
<primary-address>with the primary address of your PolarDB for MySQL cluster. A successful connection confirms that Kerberos authentication is working end-to-end.