This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. You can process personal data for this feature as outlined in theCloud Data Processing Addendum, subject to the obligations and restrictions described in the agreement under which you access Google Cloud. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Cloud SQL for SQL Server integration with Microsoft Entra IDprovides centralized identity and access management (IAM) for yourdatabases using your existingMicrosoft Entra IDtenant.

This integration offers the following benefits:

• Centralized authentication. Lets users and applications sign in totheir Cloud SQL for SQL Server instances using their existing Microsoft EntraID identities without re-entering a password. This capability eliminates theneed to manage separate SQL Server-specific logins and passwords.

• Enhanced security. Helps you enforce your organization's existingsecurity policies, such as multi-factor authentication (MFA) and conditionalaccess (CA) rules, at the database level.

• Simplified user management. When a user's Microsoft Entra ID accountis disabled or removed, the user's database access is automatically revoked.This capability helps simplify offboarding and access reviews.

Prerequisites for integration

To use Cloud SQL for SQL Server integration with Microsoft Entra ID, your instancemust meet the following requirements:

1. You must have an existing SQL Server 2022 instance or create a new one.

   Microsoft Entra ID authentication is only supported on SQL Server 2022; it isnot available on SQL Server 2017 or SQL Server 2019.

2. Enable Microsoft Entra ID authentication.

   Before you enable Microsoft Entra ID authentication, complete the following stepsin your Azure portal:

   1. Find your Microsoft Entra tenant ID.

   2. Create a new application registration in Microsoft Entra ID.

      Cloud SQL for SQL Server uses this application to communicate with your MicrosoftEntra tenant ID. When you create the application, note the application orclient ID.

   3. Grant permissions for the application to read directory data:

      1. Select the application registration you just created, then clickAPI permissions.
      2. SelectAdd a permission >Microsoft Graph >Application permissions.
      3. Grant one of the following permission sets:
         • Option 1.
           • Directory.Read.All
         • Option 2. Provides more specific permissions.
           • Application.Read.All
           • Group.Read.All
           • User.Read.All
      4. Grant tenant-wide administrator consentto allow the application to use these permissions.

Network connectivity

Microsoft Entra ID is a public service that uses public endpoints forauthentication. In order for Microsoft Entra ID authentication to work properly,your Cloud SQL instance must be able to make outbound connections to these publicendpoints. The following sections discuss next steps, based on your instance'snetwork connectivity configuration:

• Instances with a public IP
• Instances with a private IP

Instances with a public IP

If your Cloud SQL instance is configured with a public IP address, ithas built-in, outbound access to the internet.

While no additional network configuration is required for Microsoft Entra IDauthentication to work, reviewLimitations before you continue.

Instances with a private IP

If your Cloud SQL instance is configured with only a private IP address,it doesn't have direct access to the internet. You must configure an egress pathto allow the instance to reach Microsoft's public identity endpoints. MicrosoftEntra ID integration configuration depends on how your private instance isconfigured:

• Private Service Connect
• Private services access (PSA)

Private Service Connect

If your Cloud SQL instance is configured to use a private IP address,we recommend usingPrivate Service Connectto enable Microsoft Entra ID, as it eliminates certain overhead maintenance taskssuch as the following:

• Managingbastion host VMs.
• Maintaining routes.
• Creating overly broad routes like those required for PSA connectivity.

Before you continue, review thelimitations for using Microsoft Entra ID.

To enable connectivity, you need to configureCloud network address translation (Cloud NAT) in theconsumer VPC. This allows the PSC-enabled instance to use the Cloud NAT gatewayfor outbound traffic to public Microsoft endpoints. Once enabled, internal routingrestricts traffic so that only Microsoft Entra ID-related traffic reaches yourCloud NAT instance.

To enable connectivity, complete the following required steps:

1. Create a PSC-enabled instance.
2. Configure outbound connectivity for your Cloud SQL instance.
3. Create a Cloud NAT gateway.

Private services access

If your Cloud SQL instance is configured to use a private IP address and youuse PSA, the following steps are required to enable connectivity to MicrosoftEntra ID:

1. Deploy abastion host VM within your VPC.

   When you create a bastion host VM in your project, IP forwarding must beenabled. If you created a Linux-based bastion host VM, configure the bastionhost VM you just created to perform IP forwarding:

   sudosysctlnet.ipv4.conf.all.forwarding=1sudoiptables--tablenat--appendPOSTROUTING--out-interfaceens4-jMASQUERADE

   Caution: If service disruptions occur, this configuration doesn't persist.If the VM is restarted, then you need to re-apply the configuration. Toautomatically apply the configuration after a restart, we recommend schedulinga cron job.Note: To help reduce the risk of an outage, we recommend you deploy twobastion host VMs in separate zones. We also recommend you manage incomingtraffic to the bastion host VMs with aload balancer.

2. Configure the necessary network routes to direct Microsoft Entra IDauthentication traffic from your Cloud SQL instance through thebastion host VM host to reach the internet.

   Add the corresponding routes for each Microsoft Entra ID endpoint. You canfind the current IP ranges in theAzureActiveDirectory.ServiceEndpointsection in theAzure IP Ranges and Service Tagsresource file.

   Caution: Microsoft Entra ID endpoint IPs vary by region and may be changed byMicrosoft at any time. You must review and update these routes regularly, orcreate broader routes, such as/16 CIDR blocks, to accommodate potentialchanges.

   gcloud

   For each Microsoft Entra ID IP range, create two routes, replacingVM_NAME andVM_ZONE with the actual name and zoneof your bastion host VM:

   gcloud--project=PROJECT_IDcomputeroutescreateNAME\--network=NETWORK--destination-range=RANGE\--priority=998--next-hop-gateway=default-internet-gatewaygcloud--project=PROJECT_IDcomputeroutescreateNAME\--network=NETWORK--destination-range=RANGE--priority=999\--next-hop-instance=VM_NAME--next-hop-instance-zone=VM_ZONE\--next-hop-ilb=ILB_VALUE

   Replace the following:

   • PROJECT_ID: the ID of the project where your Cloud SQLinstance resides.
   • NAME: the name of the route you want to create.
   • NETWORK: the name of the network where your Cloud SQLinstance resides.
   • RANGE: the IP range you want to use.
   • VM_NAME: the name of the bastion host VM you want to include.
   • VM_ZONE: the zone of the bastion host VM you want to include, suchasus-central1.

   • ILB_VALUE: Optional. The name or IP address of a forwarding rulefor an internal TCP/UDP load balancer. If you configured a load balancer infront of your bastion host VMs, then you need to include the--next-hop-ilbflag in this command.

     For more information, seeInternal passthrough Network Load Balancers as next hops.

   An example might look like the following:

   gcloud--project=my-customer-projectcomputeroutescreatemy-route-1--network=default--destination-range=20.20.32.0/27--priority=998--next-hop-gateway=default-internet-gatewaygcloud--project=my-customer-projectcomputeroutescreatemy-route-2--network=default--destination-range=20.20.32.0/27--priority=999--next-hop-instance=my-bastion-vm--next-hop-instance-zone=us-central1-c--next-hop-ilb=fr-ilb1

3. Use the same command in the previous step to apply the same configuration toallow traffic for Microsoft Entra ID certificate revocation checks. Use theIP ranges listed atDigiCert Certificate Status IP address.

   If you don't complete this step, Microsoft Entra ID authentication mightstill work, but you might also experience delays when opening new connections.

Manage Microsoft Entra ID authentication

You can enable Entra ID authentication for a new or existing instance.

Create an instance with Microsoft Entra ID authentication enabled

You can enable Microsoft Entra ID authentication when you create a new Cloud SQL for SQL Serverinstance. You need to provide the specific Microsoft Entra tenant ID andapplication ID (client ID) of the App Registration you configured in your Azureportal.

For more information, seePrerequisites.

gcloudbetasqlinstancescreateINSTANCE_NAME\--database-version=EDITION\--tier=TIER\--network=NETWORK--root-password=PASSWORD--entra-id-tenant-id=TENANT_ID\--entra-id-application-id=APPLICATION_ID

gcloudbetasqlinstancescreatemy-entraid-instance\--database-version=SQLSERVER_2022_STANDARD\--tier=db-custom-2-3840\--assign-ip\--root-password=D61Xv36f!0lE\--entra-id-tenant-id=7e281aab-e994-4c83-88ed-d1674477a39c\--entra-id-application-id=4c5ed2da-0478-4aaa-ab65-6dfd33ba8bfd

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

{  "databaseVersion":"EDITION",  "name":"INSTANCE_ID",  "region":"REGION",  "rootPassword":"PASSWORD",  "settings":  {    "tier":"TIER",    "ipConfiguration":      {        "privateNetwork":"NETWORK"      },    "entraidConfig":    {      "tenantId": "TENANT_ID",      "applicationId": "APPLICATION_ID"    }  }}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances" | Select-Object -Expand Content

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-01T19:13:21.834Z",  "operationType": "CREATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances

{  "databaseVersion":"EDITION",  "name":"INSTANCE_ID",  "region":"REGION",  "rootPassword":"PASSWORD",  "settings":  {    "tier":"TIER",    "ipConfiguration":      {        "privateNetwork":"NETWORK"      },    "entraidConfig":    {      "tenantId": "TENANT_ID",      "applicationId": "APPLICATION_ID"    }  }}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances" | Select-Object -Expand Content

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-01T19:13:21.834Z",  "operationType": "CREATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

Manage Microsoft Entra ID authentication on an existing instance

You can enable, modify, or disable the Microsoft Entra ID configuration on anexisting instance at any time.

gcloudbetasqlinstancespatchINSTANCE_NAME\--entra-id-tenant-id="NEW_TENANT_ID"\--entra-id-application-id="NEW_APPLICATION_ID"

gcloudbetasqlinstancespatchmy-existing-instance\--entra-id-tenant-id=7e281aab-e994-4c83-88ed-d1674477a39c\--entra-id-application-id=4c5ed2da-0478-4aaa-ab65-6dfd33ba8bfd

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

{  "settings":  {    "entraidConfig":    {      "tenantId": "NEW_TENANT_ID",      "applicationId": "NEW_APPLICATION_ID"    }  }}

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances" | Select-Object -Expand Content

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-01T19:13:21.834Z",  "operationType": "CREATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

PATCH https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances

{  "settings":  {    "entraidConfig":    {      "tenantId": "NEW_TENANT_ID",      "applicationId": "NEW_APPLICATION_ID"    }  }}

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances" | Select-Object -Expand Content

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-01T19:13:21.834Z",  "operationType": "CREATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

Add the certificate to the application

In order for your Microsoft Entra ID to authenticate your Cloud SQL for SQL Serverinstance, you must upload the Cloud SQL for SQL Server instance's public certificateto your Microsoft Entra ID App Registration.

1. After you enable Microsoft Entra ID authentication on your instance,create an instance-specific certificate for Microsoft Entra ID.

   Caution: This certificate is valid for 3 years from its creation date. You areresponsible for manually rotating this certificate before it expires to preventan authentication outage.

   gcloud

   gcloudbetasqlsslentraid-certscreate--instance=INSTANCE_NAME

   Replace the following:

   • INSTANCE_NAME: the name of the instance for which you want to createa certificate.

   REST v1

   Before using any of the request data, make the following replacements:

   • PROJECT_ID: the ID of the project where your instance is located.
   • INSTANCE_ID: the ID of the instance.

   HTTP method and URL:

   POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/addEntraIdCertificate

   To send your request, expand one of these options:

   curl (Linux, macOS, or Cloud Shell)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

   Execute the following command:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d "" \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/addEntraIdCertificate"

   PowerShell (Windows)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

   Execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/addEntraIdCertificate" | Select-Object -Expand Content

   You should receive a JSON response similar to the following:

   {  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-01T19:13:21.834Z",  "operationType": "CREATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

   REST v1beta4

   Before using any of the request data, make the following replacements:

   • PROJECT_ID: the ID of the project where your instance is located.
   • INSTANCE_ID: the ID of the instance.

   HTTP method and URL:

   POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/addEntraIdCertificate

   To send your request, expand one of these options:

   curl (Linux, macOS, or Cloud Shell)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

   Execute the following command:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d "" \
        "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/addEntraIdCertificate"

   PowerShell (Windows)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

   Execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/addEntraIdCertificate" | Select-Object -Expand Content

   You should receive a JSON response similar to the following:

   {  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-01T19:13:21.834Z",  "operationType": "CREATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

2. Get the details for the certificate you just created by retrieving theinstance's details:

   gcloud

   gcloudbetasqlsslentraid-certslist--instance=INSTANCE_NAME--format="value(ssl_cert.cert)"

   Replace the following:

   • INSTANCE_NAME: the name of the instance associated with thecertificate you just created.

   REST v1

   Before using any of the request data, make the following replacements:

   • PROJECT_ID: the ID of the project where your instance is located.
   • INSTANCE_ID: the ID of the instance.

   HTTP method and URL:

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/listEntraIdCertificates

   To send your request, expand one of these options:

   curl (Linux, macOS, or Cloud Shell)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

   Execute the following command:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/listEntraIdCertificates"

   PowerShell (Windows)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

   Execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/listEntraIdCertificates" | Select-Object -Expand Content

   You should receive a successful status code (2xx) and an empty response.

   This command prints a certificate you can save to a file and then laterupload to the Azure portal.

   You must remove all embedded newline characters from the file and manuallyseparate each new line. Failure to do so causes the file upload to fail.

   For example, you might receive a text string similar to the following:

   Line1\Line2\Line3

   You must manually separate each line, similar to the following:

   Line1Line2Line3

   Alternatively, if you don't want to perform this task manually, use the followingcommand:

   curl-XGET-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json; charset=utf-8"\-H"x-goog-user-project:PROJECT_ID""https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME/listEntraIdCertificates"-s|jq-r'.certs[0].cert'

   Replace the following:

   • PROJECT_ID: the project ID where your instance is located.
   • INSTANCE_NAME: the name of the instance associated with thecertificate you just created.

   REST v1beta4

   Before using any of the request data, make the following replacements:

   • PROJECT_ID: the ID of the project where your instance is located.
   • INSTANCE_ID: the ID of the instance.

   HTTP method and URL:

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/listEntraIdCertificates

   To send your request, expand one of these options:

   curl (Linux, macOS, or Cloud Shell)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

   Execute the following command:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/listEntraIdCertificates"

   PowerShell (Windows)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

   Execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/listEntraIdCertificates" | Select-Object -Expand Content

   You should receive a successful status code (2xx) and an empty response.

   This command prints a certificate you can save to a file and then laterupload to the Azure portal.

   You must remove all embedded newline characters from the file and manuallyseparate each new line. Failure to do so causes the file upload to fail.

   For example, you might receive a text string similar to the following:

   Line1\Line2\Line3

   You must manually separate each line, similar to the following:

   Line1Line2Line3

   Alternatively, if you don't want to perform this task manually, use the followingcommand:

   curl-XGET-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json; charset=utf-8"\-H"x-goog-user-project:PROJECT_ID""https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME/listEntraIdCertificates"-s|jq-r'.certs[0].cert'

   Replace the following:

   • PROJECT_ID: the project ID where your instance is located.
   • INSTANCE_NAME: the name of the instance associated with thecertificate you just created.

3. Add your certificate to the Azure portal.

   1. Navigate to yourApp Registration in the Azure portal.
   2. OpenCertificates & secrets.
   3. SelectUpload certificate. Browse to the certificate file you retrievedfrom your instance, and add it.
   4. ClickOK.

Rotate the Microsoft Entra ID certificate

You must rotate the Microsoft Entra ID certificate before it expires. We recommendstarting this process at least one week before the scheduled expiration date:

1. Follow the steps inAdd the certificate to the applicationto create a new, inactive certificate on your Cloud SQL for SQL Server instance andthen upload it to Microsoft Entra ID using the Azure portal. This doesn'timpact the current active certificate.

2. Activate the new certificate on the Cloud SQL for SQL Server instance, whichtriggers Cloud SQL for SQL Server to start using the new certificate for all newauthentications.

   gcloud

   gcloudbetasqlsslentraid-certsrotate--instance=INSTANCE_NAME

   Replace the following:

   • INSTANCE_NAME: the name of the instance associated with thecertificate you want to rotate.

   REST v1

   Before using any of the request data, make the following replacements:

   • PROJECT_ID: the ID of the project where your instance is located.
   • INSTANCE_ID: the ID of the instance.

   HTTP method and URL:

   POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/rotateEntraIdCertificate

   To send your request, expand one of these options:

   curl (Linux, macOS, or Cloud Shell)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

   Execute the following command:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d "" \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/rotateEntraIdCertificate"

   PowerShell (Windows)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

   Execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/rotateEntraIdCertificate" | Select-Object -Expand Content

   You should receive a successful status code (2xx) and an empty response.

   REST v1beta4

   Before using any of the request data, make the following replacements:

   • PROJECT_ID: the ID of the project where your instance is located.
   • INSTANCE_ID: the ID of the instance.

   HTTP method and URL:

   POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/rotateEntraIdCertificate

   To send your request, expand one of these options:

   curl (Linux, macOS, or Cloud Shell)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

   Execute the following command:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d "" \
        "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/rotateEntraIdCertificate"

   PowerShell (Windows)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

   Execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/rotateEntraIdCertificate" | Select-Object -Expand Content

   You should receive a successful status code (2xx) and an empty response.

3. Your instance now uses the new certificate.

   You can safely remove the old certificate from your Microsoft Entra ID AppRegistration and from the Cloud SQL for SQL Server instance. For more information,seeAdd and manage application credentials in Microsoft Entra ID.

Roll back the Microsoft Entra ID certificate

If you experience issues after rotating to a new certificate, you can roll backto the previous certificate.

To perform a rollback, the previous certificate must still be valid and muststill be trusted by your Microsoft Entra ID App Registration.

The following commands immediately reactivate the specified previous certificateon your Cloud SQL for SQL Server instance.

gcloudbetasqlsslentraid-certsrollback--instance=INSTANCE_NAME

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/rollbackEntraIdCertificate

{  {  "RotateEntraIdCertificateContext": {"nextVersion": "CERTIFICATE_NAME"}  }}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/rollbackEntraIdCertificate"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/rollbackEntraIdCertificate" | Select-Object -Expand Content

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-01T19:13:21.834Z",  "operationType": "CREATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/rollbackEntraIdCertificate

{  {  "RotateEntraIdCertificateContext": {"nextVersion": "CERTIFICATE_NAME"}  }}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/rollbackEntraIdCertificate"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/rollbackEntraIdCertificate" | Select-Object -Expand Content

{  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-01T19:13:21.834Z",  "operationType": "CREATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

Create the initial Microsoft Entra ID login

After enabling Microsoft Entra ID authentication on the instance, you need tocreate your Microsoft Entra ID logins.

1. Create the first Microsoft Entra ID login.

   This initial login, which represents a Microsoft Entra ID user or group,can't be created using T-SQL. You must create it using either the gcloud CLIor the Cloud SQL Admin API:

   gcloud

   gcloudsqluserscreateUSER_NAME--instance=INSTANCE_NAME--type=ENTRAID_USER

   Replace the following:

   • USER_NAME: the name of the Cloud SQL for SQL Server user you want tocreate.
   • INSTANCE_NAME: the name of the instance for which you want tocreate Microsoft Entra ID logins.
   • ENTRAID_USER: the Microsoft Entra ID username.

   An example might look like the following:

   gcloudsqluserscreatemyentraiduser@mytenant.com--instance=my-entraid-instance--type=ENTRAID_USER

   REST v1

   Not all possible fields are shown in the following basic API call. For aprototype of a JSON request, seeSettings.

   Before using any of the request data, make the following replacements:

   • PROJECT_ID: the ID of the project where the instance is located.
   • INSTANCE_ID: the ID of the instance for which you want to update.
   • USER_NAME: the name of the Cloud SQL for SQL Server user you want to create.
   • ENTRAID_USER: the Microsoft Entra ID username.

   HTTP method and URL:

   POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users

   Request JSON body:

   {  "name": "USER_NAME"  "type": "ENTRAID_USER"}

   To send your request, expand one of these options:

   curl (Linux, macOS, or Cloud Shell)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

   Save the request body in a file namedrequest.json, and execute the following command:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users"

   PowerShell (Windows)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

   Save the request body in a file namedrequest.json, and execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users" | Select-Object -Expand Content

   You should receive a JSON response similar to the following:

   {  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-01T19:13:21.834Z",  "operationType": "CREATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

   REST v1beta4

   Not all possible fields are shown in the following basic API call. For aprototype of a JSON request, seeSettings.

   Before using any of the request data, make the following replacements:

   • PROJECT_ID: the ID of the project where the instance is located.
   • INSTANCE_ID: the ID of the instance for which you want to update.
   • USER_NAME: the name of the Cloud SQL for SQL Server user you want to create.
   • ENTRAID_USER: the Microsoft Entra ID username.

   HTTP method and URL:

   POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users

   Request JSON body:

   {  "name": "USER_NAME"  "type": "ENTRAID_USER"}

   To send your request, expand one of these options:

   curl (Linux, macOS, or Cloud Shell)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

   Save the request body in a file namedrequest.json, and execute the following command:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users"

   PowerShell (Windows)

   Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

   Save the request body in a file namedrequest.json, and execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users" | Select-Object -Expand Content

   You should receive a JSON response similar to the following:

   {  "kind": "sql#operation",  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",  "status": "PENDING",  "user": "user@example.com",  "insertTime": "2020-01-01T19:13:21.834Z",  "operationType": "CREATE",  "name": "OPERATION_ID",  "targetId": "INSTANCE_ID",  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",  "targetProject": "PROJECT_ID"}

   Once the initial Microsoft Entra ID login is created, you can connect to thedatabase as that user.

2. Create subsequent Microsoft Entra ID logins.

   You can create and manage additional Microsoft Entra ID logins as noted in theprevious step.

   Alternatively, if you prefer to use another tool such asSQL Server Management Studio (SSMS),you must first grant the initial login the permission to manage other logins:

   GRANTALTERANYLOGINTO[ENTRA_ID_USER]ASCustomerDbRootRole

   ReplaceENTRAID_USER with the Microsoft Entra ID username.

   Once permissions are granted, this login can create and manage other MicrosoftEntra ID logins using standard T-SQL commands. An example command might besimilar to the following:

   CREATELOGIN[<<ENTRA_ID_USER>>]FROMEXTERNALPROVIDER

   ReplaceENTRAID_USER with the Microsoft Entra ID username.

   To create users based on Microsoft Entra ID logins, or to grant permissions,use standard T-SQL commands.

   For more information, including how to create a login using the proper syntax,seeSet up Microsoft Entra authentication for SQL Server with app registration.

Best practices

To help isolate permissions and to better define security boundaries, we stronglyencourage you to create a unique Microsoft Entra ID application registration foreach Cloud SQL for SQL Server instance. Revoking the application's credentials won'timpact other, unrelated instances.

For more information, seeHow to register an application in Microsoft Entra ID.

Troubleshooting

The following sections help address issues you might encounter while managingMicrosoft Entra ID integration.

Network connectivity issues with private IP instances

You might experience some of the following issues during integration setup:

• Slow operations to create Microsoft Entra ID logins
• Unable to create Microsoft Entra ID logins
• Unable to connect to the instance using Microsoft Entra ID authentication

To help address these issues, perform the following connectivity test:

1. Within the same Google Cloud project and VPC, and in the same region as yourCloud SQL for SQL Server instance, create a test VM configured with only a private IP.

2. Connect to the VM you just created using either the remote desktop protocol(RDP) or secure shell protocol (SSH). Then, run the following commands to testreachability. These steps can be applied to both Linux-based and Windows-basedVMs:

   curl-4ivlogin.microsoftonline.comcurl-4ivgraph.microsoft.comcurl-4ivocsp.digicert.com

If you can't reach any of these endpoints, whether due to timeouts or refusedconnection errors, check your network configuration for the following:

• For Private Service Connect, make sure Cloud NAT is correctlyconfigured to allow outbound internet access.
• For private services access, verify your custom routes and bastion hostsconfiguration.
• Check your VPC Firewall rules to ensure egress traffic to these domains isn'tblocked.

Common error messages

You might encounter the following login error during Microsoft Entra IDauthentication:

Login failed for user ""

To resolve this issue, make sure that a SQL Server login exists for thisMicrosoft Entra ID user.

Migration from Microsoft Active Directory

In the following scenarios, you can enable Microsoft Entra ID authenticationwithout disabling the existing Microsoft Active Directory authentication:

• Performing a phased migration. Moving authentication authority fromMicrosoft Active Directory to Microsoft Entra ID using eithercustomer-managed Active Directory (CMAD) orManaged Service for Microsoft Active Directory.
• Using a hybrid environment. Keeping both Microsoft Active Directory andMicrosoft Entra ID enabled simultaneously.

Read replicas

• If you add a read replica to a primary instance that has Microsoft Entra IDenabled, the read replica is automatically configured to use Microsoft Entra ID.
• If the primary instance has Microsoft Entra ID enabled, and you restore abackup to that instance, its associated read replica is automatically configuredto use Microsoft Entra, as the identity doesn't change.

Cloned instances and restoring to a different instance

Microsoft Entra ID integration isn't automatically configured to the new instancein the following scenarios:

• A clone of the primary instance.
• A backup restored to an instance that isn't the primary.

In such cases, you must manually enable Microsoft Entra ID on the new instanceand then re-upload its certificate to the Microsoft Entra ID application. Thisrequirement is a security measure to help prevent multiple, unrelated instancesfrom using the same application identity.

Limitations

• Microsoft Entra ID authentication is only supported on SQL Server 2022; it isnot available on SQL Server 2017 or SQL Server 2019.
• If you clone an instance or restore a backup to a different instance,Microsoft Entra ID integration isn't automatically configured on the new instance.For more information, seeBackup and recovery.
• Microsoft Entra ID authentication isn't supported forhigh availability (HA) instancesconfigured with a public IP.
• Microsoft Entra ID authentication isn't supported forPSC-enabled primaryinstances, nor their corresponding read replica instances.
• Avoid rotating Microsoft Entra ID certificates on primary instances that havereplicas attached. If you rotate the primary instance's certificate, the replicacertificates won't be updated.
• Microsoft Entra ID integration with Cloud SQL for SQL Server can be configuredusing the gcloud CLI or the Cloud SQL Admin API. The integration can't bemanaged using Terraform.

What's next

• Learn more aboutMicrosoft Entra ID