Integração com o Microsoft Entra ID

A integração do Cloud SQL para SQL Server com o Microsoft Entra ID oferece gerenciamento de identidade e acesso (IAM) centralizado para seus bancos de dados usando o locatário atual do Microsoft Entra ID.

Essa integração oferece os seguintes benefícios:

  • Autenticação centralizada. Permite que usuários e aplicativos façam login nas instâncias do Cloud SQL para SQL Server usando as identidades do Microsoft Entra ID sem precisar digitar uma senha novamente. Esse recurso elimina a necessidade de gerenciar logins e senhas separados específicos do SQL Server.

  • Segurança reforçada. Ajuda a aplicar as políticas de segurança da sua organização, como autenticação multifator (MFA) e regras de acesso condicional (CA), no nível do banco de dados.

  • Gerenciamento simplificado de usuários: Quando a conta do Microsoft Entra ID de um usuário é desativada ou removida, o acesso ao banco de dados do usuário é revogado automaticamente. Esse recurso ajuda a simplificar o desligamento e as análises de acesso.

Pré-requisitos para integração

Para usar a integração do Cloud SQL para SQL Server com o Microsoft Entra ID, sua instância precisa atender aos seguintes requisitos:

  1. É necessário ter uma instância ou criar uma nova.

    A autenticação do Microsoft Entra ID só é compatível com o SQL Server 2022 ou versões mais recentes. Ela não está disponível no SQL Server 2017 ou no SQL Server 2019.

  2. Ative a autenticação do Microsoft Entra ID.

    Antes de ativar a autenticação do Microsoft Entra ID, siga estas etapas no portal do Azure:

    1. Encontre seu ID de locatário do Microsoft Entra.

    2. Crie um novo registro de aplicativo no Microsoft Entra ID.

      O Cloud SQL para SQL Server usa esse aplicativo para se comunicar com o ID do locatário do Microsoft Entra. Ao criar o aplicativo, anote o ID do aplicativo ou do cliente.

    3. Conceda permissões para o aplicativo ler os dados do diretório:

      1. Selecione o registro do aplicativo que você acabou de criar e clique em Permissões da API.
      2. Selecione Adicionar uma permissão > Microsoft Graph > Permissões do aplicativo.
      3. Conceda um dos seguintes conjuntos de permissões:
        • Opção 1.
          • Directory.Read.All
        • Opção 2. Oferece permissões mais específicas.
          • Application.Read.All
          • Group.Read.All
          • User.Read.All
      4. Conceda o consentimento do administrador em todo o locatário para permitir que o aplicativo use essas permissões.

Conectividade de rede

O Microsoft Entra ID é um serviço público que usa endpoints públicos para autenticação. Para que a autenticação do Microsoft Entra ID funcione corretamente, sua instância do Cloud SQL precisa ser capaz de fazer conexões de saída com esses endpoints públicos. As seções a seguir discutem as próximas etapas, com base na configuração de conectividade de rede da instância:

Instâncias com um IP público

Se a instância do Cloud SQL estiver configurada com um endereço IP público, ela terá acesso integrado de saída à Internet.

Embora nenhuma configuração de rede extra seja necessária para que a autenticação do Microsoft Entra ID funcione, consulte as Limitações antes de continuar.

Instâncias com um IP particular

Se a instância do Cloud SQL estiver configurada apenas com um endereço IP privado, ela não terá acesso direto à Internet. É preciso configurar um caminho de saída para permitir que a instância alcance os endpoints de identidade pública da Microsoft. A configuração da integração do Microsoft Entra ID depende de como sua instância privada está configurada:

Private Service Connect

Se a instância do Cloud SQL estiver configurada para usar um endereço IP particular, recomendamos o uso do Private Service Connect para ativar o Microsoft Entra ID, já que ele elimina certas tarefas de manutenção de sobrecarga, como as seguintes:

  • Gerenciar VMs de bastion host.
  • Manter rotas.
  • Criar rotas excessivamente amplas, como as necessárias para a conectividade do PSA.

Antes de continuar, consulte as limitações do uso do Microsoft Entra ID.

Para ativar a conectividade, configure a conversão de endereços de rede do Cloud (Cloud NAT) na VPC do consumidor. Isso permite que a instância com PSC use o gateway do Cloud NAT para o tráfego de saída para endpoints públicos da Microsoft. Depois de ativado, o roteamento interno restringe o tráfego para que apenas o tráfego relacionado ao Microsoft Entra ID chegue à instância do Cloud NAT.

Para ativar a conectividade, siga estas etapas:

  1. Crie uma instância ativada para PSC.
  2. Configure a conectividade de saída para sua instância do Cloud SQL.
  3. Criar um gateway do Cloud NAT.

Acesso privado a serviços

Se a instância do Cloud SQL estiver configurada para usar um endereço IP privado e você usar o PSA, as etapas a seguir serão necessárias para ativar a conectividade com o Microsoft Entra ID:

  1. Implante uma VM do Bastion Host na VPC.

    Ao criar uma VM de Bastion Host no projeto, o encaminhamento de IP precisa estar ativado. Se você criou uma VM de Bastion Host baseada em Linux, configure-a para realizar o encaminhamento de IP:

    sudo sysctl net.ipv4.conf.all.forwarding=1
sudo iptables --table nat --append POSTROUTING --out-interface  ens4 -j MASQUERADE

  2. Configure as rotas de rede necessárias para direcionar o tráfego de autenticação do Microsoft Entra ID da instância do Cloud SQL pelo host da VM do Bastion Host para acessar a Internet.

    Adicione as rotas correspondentes para cada endpoint do Microsoft Entra ID. Encontre os intervalos de IP atuais na seção AzureActiveDirectory no arquivo de recursos Intervalos de IP e tags de serviço do Azure. Por exemplo, os endpoints de login do Microsoft Entra ID, como login.microsoftonline.com, usam endereços IP nos intervalos 20.190.128.0/18 e 40.126.0.0/18.

    gcloud

    Para cada intervalo de IP do Microsoft Entra ID, crie duas rotas, substituindo VM_NAME e VM_ZONE pelo nome e pela zona reais da VM do Bastion Host:

    gcloud --project=PROJECT_ID compute routes create NAME \
  --network=NETWORK --destination-range=RANGE \
  --priority=998 --next-hop-gateway=default-internet-gateway

gcloud  --project=PROJECT_ID compute routes create NAME \
  --network=NETWORK --destination-range=RANGE --priority=999 \
  --next-hop-instance=VM_NAME --next-hop-instance-zone=VM_ZONE \
  --next-hop-ilb=ILB_VALUE

    Substitua:

    • PROJECT_ID: o ID do projeto em que a instância do Cloud SQL está.
    • NAME: o nome da rota que você quer criar.
    • NETWORK: o nome da rede em que a instância do Cloud SQL reside.
    • RANGE: o intervalo de IP que você quer usar.
    • VM_NAME: o nome da VM do Bastion Host que você quer incluir.
    • VM_ZONE: a zona da VM do Bastion Host que você quer incluir, como us-central1.

    • ILB_VALUE: opcional. O nome ou endereço IP de uma regra de encaminhamento para um balanceador de carga TCP/UDP interno. Se você configurou um balanceador de carga na frente das VMs do bastion host, inclua a flag --next-hop-ilb nesse comando.

      Para mais informações, consulte Balanceadores de carga de rede de passagem interna como próximos saltos.

    Veja um exemplo:

    gcloud  --project=my-customer-project compute routes create my-route-1 --network=default --destination-range=20.20.32.0/27 --priority=998 --next-hop-gateway=default-internet-gateway

gcloud  --project=my-customer-project compute routes create my-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 o mesmo comando da etapa anterior para aplicar a mesma configuração e permitir o tráfego para verificações de revogação de certificado do Microsoft Entra ID. Use os intervalos de IP listados em Endereço IP de status do certificado DigiCert.

    Se você não concluir essa etapa, a autenticação do Microsoft Entra ID ainda poderá funcionar, mas também poderá haver atrasos ao abrir novas conexões.

Gerenciar a autenticação do Microsoft Entra ID

É possível ativar a autenticação do Entra ID para uma instância nova ou atual.

Criar uma instância com a autenticação do Microsoft Entra ID ativada

É possível ativar a autenticação do Microsoft Entra ID ao criar uma nova instância do Cloud SQL para SQL Server. É necessário fornecer o ID do locatário do Microsoft Entra e o ID do aplicativo (ID do cliente) do registro do app que você configurou no portal do Azure.

Para mais informações, consulte Pré-requisitos.

gcloud 

gcloud sql instances create INSTANCE_NAME \
    --database-version=EDITION \
    --tier=TIER \
    --network=NETWORK
    --root-password=PASSWORD
    --entra-id-tenant-id=TENANT_ID \
    --entra-id-application-id=APPLICATION_ID

Substitua:

  • INSTANCE_NAME: o nome da instância que você quer criar.
  • EDITION: a edição da instância que você quer usar, como SQLSERVER_2025_STANDARD.
  • TIER: o nível da instância ou o tipo de máquina que você quer usar, como db-custom-2-3840.
  • NETWORK: o nome da rede que você quer usar.
  • PASSWORD: a senha da instância.
  • TENANT_ID: o ID do locatário do Microsoft Entra.
  • APPLICATION_ID: o ID do aplicativo ou do cliente.

Veja um exemplo:

gcloud sql instances create my-entraid-instance \
    --database-version=SQLSERVER_2025_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

REST v1

Nem todos os campos possíveis são mostrados na chamada de API básica abaixo. Para o protótipo de uma solicitação JSON, consulte Configurações.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o nome do projeto em que a instância que você quer criar será localizada.
  • INSTANCE_ID: o ID da instância que você quer criar.
  • EDITION: a edição da instância que você quer usar, como SQLSERVER_2022_STANDARD.
  • REGION: a região em que você quer que a instância resida, como us-central1.
  • PASSWORD: a senha da instância.
  • TIER: o nível da instância ou o tipo de máquina que você quer usar, como db-custom-2-3840.
  • NETWORK: o nome da rede que você quer usar.
  • TENANT_ID: o ID do locatário do Microsoft Entra.
  • APPLICATION_ID: o ID do aplicativo ou do cliente.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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

Nem todos os campos possíveis são mostrados na chamada de API básica abaixo. Para o protótipo de uma solicitação JSON, consulte Configurações.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o nome do projeto em que a instância que você quer criar será localizada.
  • INSTANCE_ID: o ID da instância que você quer criar.
  • EDITION: a edição da instância que você quer usar, como SQLSERVER_2022_STANDARD.
  • REGION: a região em que você quer que a instância resida, como us-central1.
  • PASSWORD: a senha da instância.
  • TIER: o nível da instância ou o tipo de máquina que você quer usar, como db-custom-2-3840.
  • NETWORK: o nome da rede que você quer usar.
  • TENANT_ID: o ID do locatário do Microsoft Entra.
  • APPLICATION_ID: o ID do aplicativo ou do cliente.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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"
}

Gerenciar a autenticação do Microsoft Entra ID em uma instância atual

É possível ativar, modificar ou desativar a configuração do Microsoft Entra ID em uma instância atual a qualquer momento.

Para modificar a configuração da instância, é necessário corrigir a instância com os valores novos ou excluídos do ID do locatário e do ID do cliente.

Esse processo não envolve a entrada ou saída de um domínio.

É possível atualizar os valores do ID do locatário e do ID do aplicativo sem ativar ou desativar a integração com o Microsoft Entra ID.

gcloud 

gcloud sql instances patch INSTANCE_NAME \
    --entra-id-tenant-id="NEW_TENANT_ID" \
    --entra-id-application-id="NEW_APPLICATION_ID"

Substitua:

  • INSTANCE_NAME: o nome da instância que você quer modificar.
  • NEW_TENANT_ID: o novo ID do locatário do Microsoft Entra. Para desativar o Microsoft Entra ID, deixe essa string vazia.
  • NEW_APPLICATION_ID: o novo ID do aplicativo ou do cliente. Para desativar o Microsoft Entra ID, deixe essa string vazia.

Veja um exemplo:

gcloud sql instances patch my-existing-instance \
    --entra-id-tenant-id=7e281aab-e994-4c83-88ed-d1674477a39c \
    --entra-id-application-id=4c5ed2da-0478-4aaa-ab65-6dfd33ba8bfd

REST v1

Nem todos os campos possíveis são mostrados na chamada de API básica abaixo. Para o protótipo de uma solicitação JSON, consulte Configurações.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto em que a instância que você quer modificar está localizada.
  • INSTANCE_ID: o ID da instância que você quer modificar.
  • TENANT_ID: o ID do locatário do Microsoft Entra. Para desativar o Microsoft Entra ID, deixe essa string vazia.
  • APPLICATION_ID: o ID do aplicativo ou do cliente. Para desativar o Microsoft Entra ID, deixe essa string vazia.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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

Nem todos os campos possíveis são mostrados na chamada de API básica abaixo. Para o protótipo de uma solicitação JSON, consulte Configurações.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto em que a instância que você quer modificar está localizada.
  • INSTANCE_ID: o ID da instância que você quer modificar.
  • TENANT_ID: o ID do locatário do Microsoft Entra. Para desativar o Microsoft Entra ID, deixe essa string vazia.
  • APPLICATION_ID: o ID do aplicativo ou do cliente. Para desativar o Microsoft Entra ID, deixe essa string vazia.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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"
}

Adicionar o certificado ao aplicativo

Para que o Microsoft Entra ID autentique sua instância do Cloud SQL para SQL Server, faça upload do certificado público da instância do Cloud SQL para SQL Server no registro do app do Microsoft Entra ID.

  1. Depois de ativar a autenticação do Microsoft Entra ID na instância, crie um certificado específico para o Microsoft Entra ID.

    gcloud 

    gcloud sql ssl entraid-certs create --instance=INSTANCE_NAME

    Substitua:

    • INSTANCE_NAME: o nome da instância para a qual você quer criar um certificado.

    REST v1

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projeto em que a instância está localizada.
    • INSTANCE_ID: o ID da instância.

    Método HTTP e URL: 

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

    {
  "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

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projeto em que a instância está localizada.
    • INSTANCE_ID: o ID da instância.

    Método HTTP e URL: 

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

    {
  "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. Recupere os detalhes da instância para conferir os detalhes do certificado que você acabou de criar:

    gcloud 

    gcloud sql ssl entraid-certs list --instance=INSTANCE_NAME --format="value(ssl_cert.cert)"

    Substitua:

    • INSTANCE_NAME: o nome da instância associada ao certificado que você acabou de criar.

    REST v1

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projeto em que a instância está localizada.
    • INSTANCE_ID: o ID da instância.

    Método HTTP e URL: 

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

    Esse comando imprime um certificado que pode ser salvo em um arquivo e, posteriormente, enviado para o portal do Azure.

    Remova todos os caracteres de nova linha incorporados do arquivo e separe manualmente cada nova linha. Caso contrário, o upload do arquivo vai falhar.

    Por exemplo, você pode receber uma string de texto semelhante a esta:

    Line1\Line2\Line3

    É necessário separar manualmente cada linha, como no exemplo a seguir:

    Line1
Line2
Line3

    Se preferir não realizar essa tarefa manualmente, use o seguinte comando:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-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'

    Substitua:

    • PROJECT_ID: o ID do projeto em que a instância está localizada.
    • INSTANCE_NAME: o nome da instância associada ao certificado que você acabou de criar.

    REST v1beta4

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projeto em que a instância está localizada.
    • INSTANCE_ID: o ID da instância.

    Método HTTP e URL: 

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

    Esse comando imprime um certificado que pode ser salvo em um arquivo e, posteriormente, enviado para o portal do Azure.

    Remova todos os caracteres de nova linha incorporados do arquivo e separe manualmente cada nova linha. Caso contrário, o upload do arquivo vai falhar.

    Por exemplo, você pode receber uma string de texto semelhante a esta:

    Line1\Line2\Line3

    É necessário separar manualmente cada linha, como no exemplo a seguir:

    Line1
Line2
Line3

    Se preferir não realizar essa tarefa manualmente, use o seguinte comando:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-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'

    Substitua:

    • PROJECT_ID: o ID do projeto em que a instância está localizada.
    • INSTANCE_NAME: o nome da instância associada ao certificado que você acabou de criar.

  3. Adicione o certificado ao portal do Azure.

    1. Acesse App Registration no portal do Azure.
    2. Abra Certificados e chaves secretas.
    3. Selecione Fazer upload do certificado. Procure o arquivo de certificado que você recuperou da instância e adicione-o.
    4. Clique em OK.

Alternar o certificado do Microsoft Entra ID

Você precisa fazer a rotação do certificado do Microsoft Entra ID antes que ele expire. Recomendamos iniciar esse processo pelo menos uma semana antes da data de validade programada:

  1. Siga as etapas em Adicionar o certificado ao aplicativo para criar um novo certificado inativo na instância do Cloud SQL para SQL Server e, em seguida, faça upload dele para o Microsoft Entra ID usando o portal do Azure. Isso não afeta o certificado ativo atual.

  2. Ative o novo certificado na instância do Cloud SQL para SQL Server, o que aciona o Cloud SQL para SQL Server para começar a usar o novo certificado em todas as novas autenticações.

    gcloud 

    gcloud sql ssl entraid-certs rotate --instance=INSTANCE_NAME

    Substitua:

    • INSTANCE_NAME: o nome da instância associada ao certificado que você quer alternar.

    REST v1

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projeto em que a instância está localizada.
    • INSTANCE_ID: o ID da instância.

    Método HTTP e URL: 

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

    REST v1beta4

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projeto em que a instância está localizada.
    • INSTANCE_ID: o ID da instância.

    Método HTTP e URL: 

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

  3. Sua instância agora usa o novo certificado.

    É possível remover com segurança o certificado antigo do registro do app do Microsoft Entra ID e da instância do Cloud SQL para SQL Server. Para mais informações, consulte Adicionar e gerenciar credenciais de aplicativos no Microsoft Entra ID.

Reverter o certificado do Microsoft Entra ID

Se você tiver problemas após a rotação para um novo certificado, poderá reverter para o certificado anterior.

Para realizar uma reversão, o certificado anterior ainda precisa ser válido e confiável para o registro do app do Microsoft Entra ID.

Os comandos a seguir reativam imediatamente o certificado anterior especificado na instância do Cloud SQL para SQL Server.

gcloud 

gcloud sql ssl entraid-certs rollback --instance=INSTANCE_NAME

Substitua:

  • INSTANCE_NAME: o nome da instância associada ao certificado que você quer reverter.

REST v1

Nem todos os campos possíveis são mostrados na chamada de API básica abaixo. Para o protótipo de uma solicitação JSON, consulte Configurações.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto em que a instância está localizada.
  • INSTANCE_ID: o ID da instância em que você quer reverter o certificado.
  • CERTIFICATE_NAME: o nome do novo certificado que você quer usar para substituir o antigo, como sha1Fingerprint.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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

Nem todos os campos possíveis são mostrados na chamada de API básica abaixo. Para o protótipo de uma solicitação JSON, consulte Configurações.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto em que a instância está localizada.
  • INSTANCE_ID: o ID da instância em que você quer reverter o certificado.
  • CERTIFICATE_NAME: o nome do novo certificado que você quer usar para substituir o antigo, como sha1Fingerprint.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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"
}

Criar o login inicial do Microsoft Entra ID

Depois de ativar a autenticação do Microsoft Entra ID na instância, você precisa criar seus logins do Microsoft Entra ID.

  1. Crie o primeiro login do Microsoft Entra ID.

    Esse login inicial, que representa um usuário ou grupo do Microsoft Entra ID, não pode ser criado usando T-SQL. É preciso criá-lo usando a CLI gcloud ou a API Cloud SQL Admin:

    gcloud 

    gcloud sql users create USER_NAME --instance=INSTANCE_NAME --type=ENTRAID_USER

    Substitua:

    • USER_NAME: o nome do usuário do Cloud SQL para SQL Server que você quer criar.
    • INSTANCE_NAME: o nome da instância em que você quer criar logins do Microsoft Entra ID.
    • ENTRAID_USER: o nome de usuário do Microsoft Entra ID.

    Veja um exemplo:

    gcloud sql users create myentraiduser@mytenant.com --instance=my-entraid-instance --type=ENTRAID_USER

    REST v1

    Nem todos os campos possíveis são mostrados na chamada de API básica abaixo. Para o protótipo de uma solicitação JSON, consulte Configurações.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projeto em que a instância está localizada.
    • INSTANCE_ID: o ID da instância que você quer atualizar.
    • USER_NAME: o nome do usuário do Cloud SQL para SQL Server que você quer criar.
    • ENTRAID_USER: o nome de usuário do Microsoft Entra ID.

    Método HTTP e URL: 

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

    Corpo JSON da solicitação:

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

    {
  "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

    Nem todos os campos possíveis são mostrados na chamada de API básica abaixo. Para o protótipo de uma solicitação JSON, consulte Configurações.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projeto em que a instância está localizada.
    • INSTANCE_ID: o ID da instância que você quer atualizar.
    • USER_NAME: o nome do usuário do Cloud SQL para SQL Server que você quer criar.
    • ENTRAID_USER: o nome de usuário do Microsoft Entra ID.

    Método HTTP e URL: 

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

    Corpo JSON da solicitação:

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

    {
  "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"
}

    Depois que o login inicial do Microsoft Entra ID for criado, será possível se conectar ao banco de dados como esse usuário.

  2. Criar logins subsequentes do Microsoft Entra ID.

    É possível criar e gerenciar outros logins do Microsoft Entra ID, conforme observado na etapa anterior.

    Como alternativa, se você preferir usar outra ferramenta, como o SQL Server Management Studio (SSMS), primeiro conceda ao login inicial a permissão para gerenciar outros logins:

    GRANT ALTER ANY LOGIN TO [ENTRA_ID_USER] AS CustomerDbRootRole

    Substitua ENTRAID_USER pelo nome de usuário do Microsoft Entra ID.

    Depois que as permissões forem concedidas, esse login poderá criar e gerenciar outros logins do Microsoft Entra ID usando comandos T-SQL padrão. Um exemplo de comando pode ser semelhante ao seguinte:

    CREATE LOGIN [<<ENTRA_ID_USER>>] FROM EXTERNAL PROVIDER

    Substitua ENTRAID_USER pelo nome de usuário do Microsoft Entra ID.

    Para criar usuários com base em logins do Microsoft Entra ID ou conceder permissões, use comandos T-SQL padrão.

    Para mais informações, incluindo como criar um login usando a sintaxe adequada, consulte Configurar a autenticação do Microsoft Entra para o SQL Server com o registro do app.

Práticas recomendadas

Para ajudar a isolar permissões e definir melhor os limites de segurança, recomendamos criar um registro de aplicativo exclusivo do Microsoft Entra ID para cada instância do Cloud SQL para SQL Server. A revogação das credenciais do aplicativo não afeta outras instâncias não relacionadas.

Para mais informações, consulte Como registrar um aplicativo no Microsoft Entra ID.

Solução de problemas

As seções a seguir ajudam a resolver problemas que podem surgir ao gerenciar a integração do Microsoft Entra ID.

Problemas de conectividade de rede com instâncias de IP particular

Talvez você tenha alguns dos seguintes problemas durante a configuração da integração:

  • Operações lentas para criar logins do Microsoft Entra ID
  • Não é possível criar logins do Microsoft Entra ID
  • Não é possível se conectar à instância usando a autenticação do Microsoft Entra ID

Para ajudar a resolver esses problemas, faça o seguinte teste de conectividade:

  1. No mesmo projeto e VPC do Google Cloud e na mesma região da instância do Cloud SQL para SQL Server, crie uma VM de teste configurada apenas com um IP privado.

  2. Conecte-se à VM que você acabou de criar usando o protocolo de área de trabalho remota (RDP) ou o protocolo Secure Shell (SSH). Em seguida, execute os comandos a seguir para testar a acessibilidade. Estas etapas podem ser aplicadas a VMs baseadas em Linux e Windows:

    curl -4iv login.microsoftonline.com
curl -4iv graph.microsoft.com
curl -4iv ocsp.digicert.com

Se não for possível acessar nenhum desses endpoints, seja devido a tempos limite ou erros de conexão recusada, verifique o seguinte na configuração de rede:

  • Para o Private Service Connect, verifique se o Cloud NAT está configurado corretamente para permitir o acesso de saída à Internet.
  • Para acesso a serviços particulares, verifique as rotas personalizadas e a configuração dos Bastion Hosts.
  • Verifique as regras de firewall da VPC para garantir que o tráfego de saída para esses domínios não esteja bloqueado.

Mensagens de erro comuns

Talvez você encontre o seguinte erro de login durante a autenticação do Microsoft Entra ID:

Login failed for user ""

Para resolver esse problema, verifique se há um login do SQL Server para esse usuário do Microsoft Entra ID.

Migração do Microsoft Active Directory

Nos cenários a seguir, é possível ativar a autenticação do Microsoft Entra ID sem desativar a autenticação do Microsoft Active Directory:

Logging

Para relatórios sobre erros e avisos básicos, como se o Microsoft Entra ID está ativado, use o registro padrão sqlserver.err. Para informações mais detalhadas de monitoramento e solução de problemas, use o registro entraid.log, que oferece informações como:

  • Fornece o estado de conectividade de cada endpoint necessário.
  • Informa detalhes sobre as permissões de API ausentes.
  • Indica o número de dias que faltam para o certificado do cliente expirar.
  • Fornece erros internos específicos, como falhas na aquisição de tokens, que podem ajudar a localizar a causa de um problema.

As entradas de registro são atualizadas diariamente ou sempre que um estado muda.

Réplicas de leitura

  • Se você adicionar uma réplica de leitura a uma instância principal que tenha o Microsoft Entra ID ativado, a réplica de leitura será configurada automaticamente para usar o Microsoft Entra ID.
  • Se a instância principal tiver o Microsoft Entra ID ativado e você restaurar um backup para essa instância, a réplica de leitura associada será configurada automaticamente para usar o Microsoft Entra, já que a identidade não muda.
  • As mudanças no ID do locatário, no ID do aplicativo ou nos certificados da instância principal são propagadas automaticamente para as réplicas de leitura associadas à instância.

Pools de leitura gerenciados

  • As mudanças no ID do locatário, no ID do aplicativo ou nos certificados da instância principal são propagadas automaticamente para os pools de leitura gerenciados associados à instância.

Instâncias clonadas e restauração para uma instância diferente

A integração do Microsoft Entra ID não é configurada automaticamente para a nova instância nos seguintes cenários:

  • Um clone da instância principal.
  • Um backup restaurado em uma instância que não é a principal.

Nesses casos, é necessário ativar manualmente o Microsoft Entra ID na nova instância e reenviar o certificado para o aplicativo do Microsoft Entra ID. Esse requisito é uma medida de segurança para ajudar a evitar que várias instâncias não relacionadas usem a mesma identidade de aplicativo.

Limitações

  • A autenticação do Microsoft Entra ID só é compatível com o SQL Server 2022 ou versões mais recentes. Ela não está disponível no SQL Server 2017 ou no SQL Server 2019.
  • Se você clonar uma instância ou restaurar um backup em uma instância diferente, a integração do Microsoft Entra ID não será configurada automaticamente na nova instância.
  • Para ativar a autenticação do Microsoft Entra ID em uma instância regional com um IP público e acesso a serviços particulares, a instância precisa ser configurada para uso com uma rota de acesso a serviços particulares de uma VM de bastion.
  • Para ativar a autenticação do Microsoft Entra ID em uma instância regional que usa o Private Service Connect e o acesso a serviços privados, sua instância precisa ser configurada para uso com uma rota de acesso a serviços privados de uma VM de bastião.

A seguir