PolarDB:Connect a PolarDB for MySQL cluster to a self-managed Active Directory domain

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_client plugin 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:

1. Configure an AD domain controller on an ECS instance (optional — skip if you have an existing AD domain)

2. Open the required ports on the AD controller security group (optional — skip if already configured)

3. Configure the AD domain server in PolarDB

4. Configure the client user in PolarDB

5. 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.

1. 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.

2. Open Server Manager.

3. 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.

   

4. After the installation completes, click Close.

5. In the left-side navigation pane, click AD DS. In the upper-right corner, click More.

   

6. 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.

   

7. After the system restarts, open Server Manager again.

8. 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.

   

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

   

10. Enter a logon username (for example, polardbmtestuser) and click Next.

    

11. Set the password, select Password never expires, click Next, then click Finish.

    

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

    

13. Repeat Steps 9–12 to create a second user named polardbm. In this example, polardbmtestuser is used for client access and polardbm is 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.

1. Log on to the ECS console.

2. In the left-side navigation pane, choose Instances & Images > Instances.

3. In the top navigation bar, select the region where the AD controller ECS instance resides.

4. Click the ECS instance ID to open the instance details page.

5. Click the Security Groups tab. Find the security group and click Manage Rules in the Operation column.

6. 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

1. Go to the Clusters page in the PolarDB for MySQL console. Select the region, then click the cluster ID.

2. In the left-side navigation pane, choose Settings and Management > Accounts. Click the AD Domain Services tab.

   

3. 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 ktpass command 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 polardbm and 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.

   

   

4. 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 ktpass command shown in the console. In the command: Confirm the command completes without errors. Then run setspn to verify the SPN mapping for polardbm.

   • Replace -out xxx.keytab with your desired keytab filename.

   • Replace -pass yourPassword with the password you set for the polardbm user in Step 1.

   

5. Copy the keytab file to your local computer.

6. 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

1. In the left-side navigation pane, choose Settings and Management > Accounts. Click the AD Domain Services tab, then click Configure Client Info.

   

2. 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.

   

3. Click OK.

   After the configuration is submitted, the cluster enters the Maintaining Instance state.

4. 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.

1. 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

2. Request a Kerberos ticket for the client user:

   kinit polardbmtestuser

   Enter the user's AD password when prompted.

3. 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_client plugin. The --plugin-dir flag specifies the directory containing both authentication_kerberos_client.so and its dependency authentication_oci_client.so.

   ./mysql -h <primary-address> -P 3306 --default-auth=authentication_kerberos_client --plugin-dir=/root/mysql-client/plugin --user=polardbmtestuser

   Replace <primary-address> with the primary address of your PolarDB for MySQL cluster. A successful connection confirms that Kerberos authentication is working end-to-end.