This page contains information to review before you start an integration. Afterreviewing the following information, including thelimitations,seeUse customer-managed Active Directory.

You can integrate Cloud SQL for SQL Server with customer-managed Microsoft ActiveDirectory (also referred to as customer-managed AD (CMAD)).

Authentication, authorization, and more are available through CMAD. For example,joining an instance to a CMAD domain lets you sign in using Windows Authenticationwith an AD-based identity. Integrating Cloud SQL for SQL Server with an AD domainhas the additional advantage of Google Cloud integration with your on-premisesAD domains.

Before you begin

You can integrate with CMAD,adding support for Windows Authenticationto an instance. However, before integrating, the following are required for yourGoogle Cloud project:

• For authentication to work, your Cloud SQL instances must have network connectivity to all relevant Active Directory domains. This includes the primary domain the instance joins, as well as any trusted or child domains containing users who need to access Cloud SQL for SQL Server. To enable this, ensure the following ports (both TCP and UDP) are open between your Cloud SQL instances and all of your domain controllers:53,88,135,389,445,464,3268,3269, and49152 through65535.
• You mustcreate an organizational unit (OU) to store all related integration objects.
  • Within this OU, you also need todelegate the following permissions to the administrator account:
    • Manage Computer objects (create object/delete object/modify object properties)
    • Manage User objects (create object/delete object/modify object properties)
  • We also recommend granting this administrator account permissions to manage DNS records, for example, by adding it to the DnsAdmins group.

    If you don't grant these permissions, the integration will still succeed. However, connecting to your instance will require you to manually create the necessary DNS records, as described in,Connect to an instance with a user.

    The alternative is to connect using the instance's IP address, which has limitations and won't work for connections from trusted domains.

• You must store your administrator credentials in aSecret Manager secret, using the following JSON format:

  {"credentials":[{"validAfterUTC":"VALID_AFTER_UTC_VALUE","administratorLogin":"ADMINISTRATOR_LOGIN_VALUE_1","administratorPassword":"ADMINISTRATOR_PASSWORD_VALUE_1"},{"validAfterUTC":"VALID_AFTER_UTC_VALUE_2","administratorLogin":"ADMINISTRATOR_LOGIN_VALUE_2","administratorPassword":"ADMINISTRATOR_PASSWORD_VALUE_2"}]}

  Replace the following:

  • VALID_AFTER_UTC_VALUE_1: the first UTC value you want to use, provided in the formatYYYY-MM-DDThh:mm:ssZ. An example might be2099-07-01T10:30:00Z.
  • ADMINISTRATOR_LOGIN_VALUE_1: the first administrator login you want to use, such asmyadmin. Don't include the domain name in the value. Entries similar tomyadmin@my-domain-name.com aren't supported.
  • ADMINISTRATOR_PASSWORD_VALUE_1: the administrator password.
  • VALID_AFTER_UTC_VALUE_2: the second UTC value you want to use, provided in the formatYYYY-MM-DDThh:mm:ssZ. An example might be2099-07-01T10:30:00Z.
  • ADMINISTRATOR_LOGIN_VALUE_2: the second administrator's login you want to use, such asmyadmin2. Similarly, don't include the domain name in the value. Entries similar tomyadmin2@my-domain-name.com aren't supported.
  • ADMINISTRATOR_PASSWORD_VALUE_2: the second administrator's password.

  This file can contain multiple credential entries to mitigate issues with slow propagation or to accommodate planned, upfront rotations.

  ThevalidAfterUTC field is optional, if it is not specified, then it will be assumed the credentials are always valid. We recommend keeping these credentials permanently available in Secret Manager and using automation to update the password if you rotate the credentials.

  While you can delete the secret after instance creation, be aware that future operations like cloning or adding a read replica will result in the new instance not being joined to the domain.

  Furthermore, deleting the original instance will leave orphaned objects, such as the computer account, in your CMAD.

• Have a list of DNS server IP addresses for your customer-managed Active Directory, which are typically your domain controllers. We recommend using static IP addresses for these servers.
• Assign Per-Product, Per-Project service accounts.

Create and configure a service account

To create a service account with the required permissions, verify the following:

• You mustenable the Cloud SQL Admin API.
• You must have the followingpermissions:
  • resourcemanager.projects.setIamPolicy
  • secretmanager.secrets.getIamPolicy
  • secretmanager.secrets.setIamPolicy

  You need a Per-Product, Per-Project Service account for each project that you plan to integrate with CMAD. Usegcloud CLI to create the account at the project level. The Per-Product, Per-Project Service account should be granted thesecretmanager.secrets.getIamPolicy andsecretmanager.secrets.setIamPolicy permissions for the secret created on the previous step. For additional information, seeSecret Manager permissions.

  We recommend creating acustom role with the permissions you need.

To create a service account withgcloud CLI, run the following command:

gcloudbetaservicesidentitycreate--service=sqladmin.googleapis.com
--project=PROJECT_ID

That command returns a service account name in the following format:

service-PROJECT_ID@gcp-sa-cloud-sql.iam.gserviceaccount.com

Here is an example of a service account name:

service-333445@gcp-sa-cloud-sql.iam.gserviceaccount.com

To grant the necessary permission for integration, run the following command:

gcloudiamrolescreatesecretIamPolicyManager--project=PROJECT_ID
--permissions="secretmanager.secrets.getIamPolicy,secretmanager.secrets.setIamPolicy"

Then, run the following command:

gcloudsecretsadd-iam-policy-bindingADCredentials--project="722300452883"
--member="serviceAccount:service-SQL_PROJECT_NUMBER@gcp-sa-cloud-sql.iam.gserviceaccount.com"
--role="projects/PROJECT-ID/roles/secretIamPolicyManager"

For more information, seegcloud beta services identity create.

Best practices for integrating with CMAD

When integrating with CMAD, we recommend completing the following steps.

Prerequisites for integration

Use the Active Directory Diagnosis toolto troubleshoot AD setup issues with your on-premises domain and Cloud SQL for SQL Serverinstances in Google Cloud console. Skip steps related to Managed Service for Microsoft Active Directory.

Topologies for integrating with CMAD

Cloud SQL for SQL Server doesn't support domain local groups. However, the followingalternatives are available:

• Add global groups or individual user logins directly in SQL Server.
• Use universal groups if all groups and users belong to the same forest.

Cloud SQL for SQL Server doesn't support domain local groups as logins. To grantpermissions to domain users, you must use global or universal groups instead, asdescribed in this section.

Option 1: Add user accounts and groups as logins to SQL Server

If you have multiple domains, in multiple forests, and you have multiple globalgroups, you can add all of the individual user accounts, and the global anduniversal groups, directly as logins to SQL Server. As an example of Option 1,see the following diagram:

Option 2: Define a universal group in one of your domains

If your domains are in the same forest, you can define a universal group in oneof your domains. Then you can add all of the individual user accounts, and theglobal and universal groups, as children of that defined universal group, andadd the defined universal group as a SQL Server login. As an example of Option 2,see the following diagram:

Limitations and alternatives

The following limitations apply when integrating with CMAD:

• Cloud SQL for SQL Server instances using Private Service Connect (PSC) for private connectivity are not supported. Useprivate services access (PSA) instead.
• Domain local groups are not supported, but you can add global groups or individual user logins directly in SQL Server. Alternatively, you can use universal groups when all groups and users belong to the same forest.
• If there are any additional trusted domains and you plan to access SQL Server instances with user names from there, then they need to be connected through a two-way trust. One-way and external trusts are not supported.
• In general, new users created through the Google Cloud console are assigned theCustomerDbRootRole role, which has thisSQL Server Agent fixed database role:SQLAgentUserRole. However, users created through SQL Server directly, such as CMAD users, can't be granted this role, or use SQL Server Agent, because the MSDB database where this role must be granted is protected.
• Fully qualified domain names (FQDNs) aren't supported by SQL Server. Therefore, use domain names (short names), rather than FQDNs, when you create SQL Server logins. For example, if your domain name isad.mydomain.com, then create SQL Server logins forad\user, rather than forad.mydomain.com\user.
• To access SQL Server instances, always use FQDNs. For example, you could use an FQDN similar toprivate.myinstance.us-central1.myproject.cloudsql.mydomain.com. Netbios names aren't supported, nor are any short names if DNS suffixes are omitted.
• SQL Server logins based on Active Directory users and groups can't be managed from the Google Cloud console.
• Windows Authentication won't work with an external trust. The returned error might be the following:

    "The target principal name is incorrect. Cannot generate SSPI context."

  Additionally, as related toMicrosoft's recommendations, use a forest trust instead of an external trust for Kerberos authentication.
• The latest version of the secret is always used. The secret must be active and can't be destroyed.

If the connection fails and one of your certificates was created beforeMarch 15, 2025, you must rotate theserver certificateagain and try the connection again.

Unsupported for integration

The following features are unsupported when integrating with CMAD:

• Domain local groups.
• NTLM authentication.
• Login with an IP address from domains connected through a trust relationship.
• Instances with long names (more than 63 characters).

Monitoring

cloudsql.googleapis.com/database/active_directory/domain_reachable

This metric reports if the CMAD is reachable fromthe Cloud SQL instance. It's a useful tool to help troubleshoot network issues:

cloudsql.googleapis.com/database/active_directory/instance_available

What's next

• Use customer-managed Active Directory (CMAD)
• Use the Active Directory Diagnosis tool