Tutorial: Criar usuários Microsoft Entra usando aplicativos Microsoft Entra

Applies to:Banco de Dados SQL do Azure

Este artigo explica como configurar um principal de serviço para que ele possa criar usuários do Microsoft Entra no Banco de Dados SQL do Azure. Essa funcionalidade permite que você gerencie programaticamente o acesso a recursos de SQL do Azure para usuários e aplicativos em seu locatário Microsoft Entra.

Para obter mais informações sobre Microsoft Entra autenticação para SQL do Azure, consulte Use Microsoft Entra authentication.

Neste tutorial, você aprenderá a:

Pré-requisitos

• Uma implantação existente do banco de dados SQL do Azure. Este tutorial pressupõe que você tenha um Banco de Dados SQL funcionando.
• Microsoft Entra Privileged Role Administrator permissões no locatário em que o banco de dados SQL reside.
• A versão mais recente do módulo Az.Sql do PowerShell.
• A versão mais recente do Microsoft. Graph módulo do PowerShell.

Atribuir uma identidade ao servidor lógico

1. Conecte-se ao Azure, especificando o locatário Microsoft Entra que hospeda seu banco de dados SQL. A ID do Locatário pode ser encontrada na página Overview do recurso Microsoft Entra ID no portal Azure. Copie a ID do Locatário e execute o seguinte comando do PowerShell:

   • Substitua <TenantId> pela ID de Locatário.

   Connect-AzAccount -Tenant <TenantId>
   

   Registre o TenantId para uso futuro neste tutorial.

2. Gere uma identidade gerenciada atribuída pelo sistema e atribua-a ao servidor logical em Azure. Execute o seguinte comando do PowerShell:

   • Substitua <ResourceGroupName> e <ServerName> por seus recursos no comando Set-AzSqlServer. Se o nome do servidor for myserver.database.windows.net, substitua <ServerName> por myserver.

   Set-AzSqlServer -ResourceGroupName <ResourceGroupName> -ServerName <ServerName> -AssignIdentity
   

3. Verifique se a identidade do servidor foi atribuída com êxito. Execute o seguinte comando do PowerShell:

   • Substitua <ResourceGroupName> e <ServerName> pelos seus recursos. Se o nome do servidor for myserver.database.windows.net, substitua <ServerName> por myserver.

   $xyz = Get-AzSqlServer -ResourceGroupName <ResourceGroupName> -ServerName <ServerName>
   $xyz.identity
   

   Sua saída mostra PrincipalId, Typee TenantId. A identidade atribuída é a PrincipalId.

4. Você também pode verificar a identidade acessando o Azure portal.

   • No recurso Microsoft Entra ID, acesse Enterprise applications. Digite o nome do servidor lógico. A ID do objeto que é exibida no recurso é a ID da identidade do servidor primário.

   

Adicionar identidade do servidor à função Leitores de Diretório

A identidade do servidor requer permissões para consultar o Microsoft Entra ID para funções administrativas, o que inclui a criação de usuários e logons do Microsoft Entra e a expansão dos grupos para aplicar permissões de usuário com base na associação de grupo do Microsoft Entra. Se as permissões de identidade do servidor para consultar Microsoft Entra ID forem revogadas ou a identidade do servidor for excluída, Microsoft Entra autenticação deixará de funcionar.

Atribua permissões de consulta Microsoft Entra para a identidade do servidor adicionando-a à função Directory Readers ou atribuindo as seguintes permissões de Microsoft Graph de nível inferior:

• User.Read.All
• GroupMember.Read.All e
• Application.Read.All.

O script a seguir concede a permissão Microsoft Entra Leitores de Diretório a uma identidade que representa o servidor lógico para Banco de Dados SQL do Azure.

• Substitua <TenantId> pelo TenantId coletado anteriormente.
• Substitua <ServerName> pelo seu nome do servidor lógico. Se o nome do servidor for myserver.database.windows.net, substitua <ServerName> por myserver.

# This script grants "Directory Readers" permission to a service principal representing a logical server for Azure SQL Database
# It can be executed only by a user who is a member of the **Privileged Role Administrator** or higher role.
# To check if the "Directory Readers" role was granted, re-execute this script

Import-Module Microsoft.Graph.Authentication
$ServerIdentityName = "<ServerName>"    # Enter your logical server name
$TenantId = "<TenantId>"                # Enter your tenant ID

Connect-MgGraph -TenantId "<TenantId>" -Scopes "RoleManagement.ReadWrite.Directory,Application.Read.All"

# Get Microsoft Entra "Directory Readers" role and create if it doesn't exist
$roleName = "Directory Readers"
$role = Get-MgDirectoryRole -Filter "DisplayName eq '$roleName'"
if ($role -eq $null) {
    # Instantiate an instance of the role template
    $roleTemplate = Get-MgDirectoryRoleTemplate -Filter "DisplayName eq '$roleName'"
    New-MgDirectoryRoleTemplate -RoleTemplateId $roleTemplate.Id
    $role = Get-MgDirectoryRole -Filter "DisplayName eq '$roleName'"
}

# Get service principal for server
$roleMember = Get-MgServicePrincipal -Filter "DisplayName eq '$ServerIdentityName'"
$roleMember.Count
if ($roleMember -eq $null) {
    Write-Output "Error: No service principal with name '$($ServerIdentityName)' found, make sure that ServerIdentityName parameter was entered correctly."
    exit
}
if (-not ($roleMember.Count -eq 1)) {
    Write-Output "Error: Multiple service principals with name '$($ServerIdentityName)'"
    Write-Output $roleMember | Format-List DisplayName, Id, AppId
    exit
}

# Check if service principal is already member of Directory Readers role
$isDirReader = Get-MgDirectoryRoleMember -DirectoryRoleId $role.Id -Filter "Id eq '$($roleMember.Id)'"

if ($isDirReader -eq $null) {
    # Add principal to Directory Readers role
    Write-Output "Adding service principal '$($ServerIdentityName)' to 'Directory Readers' role'..."
    $body = @{
        "@odata.id"= "https://graph.microsoft.com/v1.0/directoryObjects/{$($roleMember.Id)}"
    }
    New-MgDirectoryRoleMemberByRef -DirectoryRoleId $role.Id -BodyParameter $body
    Write-Output "'$($ServerIdentityName)' service principal added to 'Directory Readers' role'."
} else {
    Write-Output "Service principal '$($ServerIdentityName)' is already member of 'Directory Readers' role'."
}

Para obter uma abordagem semelhante sobre como atribuir a função Directory Readers para Instância Gerenciada de SQL, consulte Set Microsoft Entra admin.

Em ambientes de produção, uma prática de gerenciamento comum é atribuir a função Leitores de Diretório a um grupo atribuível a funções no Microsoft Entra ID. Em seguida, os proprietários do grupo podem adicionar identidades gerenciadas ao grupo. Isso mantém o princípio de privilégio mínimo e ignora a necessidade de um Administrador de Funções Com Privilégios conceder a função Leitores de Diretório individualmente a cada instância do SQL. Para obter mais informações sobre esse recurso, consulte A função Leitores de Diretórios em Microsoft Entra ID para SQL do Azure.

Criar um aplicativo no Microsoft Entra ID

Registre seus aplicativos. Para registrar um aplicativo, você precisa, pelo menos, da função Microsoft Entra ID Application Developer. Para obter mais informações sobre como atribuir funções, consulte Assign funções de usuário no Microsoft Entra ID.

Este tutorial usa dois principais de serviço. O primeiro serviço principal, DBOwnerApp, é usado para criar outros usuários no banco de dados. A segunda entidade de serviço, myapp, é o aplicativo para o qual DBOwnerApp criará um usuário de banco de dados posteriormente neste tutorial.

Para registrar seus aplicativos:

1. No portal do Azure, selecione Microsoft Entra ID>Registros de aplicativo>New registration.

   

   Após a criação do registro do aplicativo, o valor de ID do Aplicativo (cliente) é gerado e exibido. Registre esse valor para uso futuro neste tutorial.

   

2. Crie um segredo de cliente para a autenticação do aplicativo. Siga carregar um certificado ou criar um segredo para entrar. Registre o segredo do cliente para DBOwnerApp para uso futuro neste tutorial.

Para obter mais informações, verifique Use o portal para criar um aplicativo Microsoft Entra e um principal de serviço que possa acessar recursos.

Crie o usuário da entidade de serviço

Adicione a entidade de serviço recém-criada, DBOwnerApp, como usuário no Banco de Dados SQL e atribua permissões a ela.

Conecte-se ao Banco de Dados SQL usando uma identidade Microsoft Entra que tenha permissões para criar outros usuários.

1. Crie o usuário DBOwnerApp no Banco de Dados SQL usando o seguinte comando T-SQL:

   CREATE USER [DBOwnerApp] FROM EXTERNAL PROVIDER
   GO
   

2. Para criar outros usuários Microsoft Entra, no mínimo, a permissão sql ALTER ANY USER é necessária. Essa permissão também é herdada por meio da associação em db_owner e por meio da atribuição como administrador do Microsoft Entra. Os exemplos a seguir demonstram três opções diferentes para atribuir permissões a DBOwnerApp que permitem criar outros usuários Microsoft Entra no banco de dados.

   Você pode adicionar DBOwnerApp à função db_owner com sp_addrolemember:

   EXEC sp_addrolemember 'db_owner', [DBOwnerApp]
   GO
   

   Você pode atribuir a permissão ALTER ANY USER a DBOwnerApp como o seguinte exemplo de T-SQL:

   GRANT ALTER ANY USER TO [DBOwnerApp]
   GO
   

   Você pode definir o DBOwnerApp como o administrador do Microsoft Entra. Use os comandos Azure portal, PowerShell ou CLI do Azure. Para obter mais informações, consulte Set Microsoft Entra admin.

Criar um usuário com um principal de serviço

1. Use o script a seguir para criar um usuário principal do serviço Microsoft Entra myapp usando a entidade de serviço DBOwnerApp:

   • Substitua <TenantId> pelo TenantId coletado anteriormente.
   • Substitua <ClientId> pelo ClientId coletado anteriormente.
   • Substitua <ClientSecret> pelo segredo do cliente criado anteriormente.
   • Substitua <ServerName> pelo seu nome do servidor lógico. Se o nome do servidor for myserver.database.windows.net, substitua <ServerName> por myserver.
   • Substitua <database name> pelo nome do Banco de Dados SQL.

   Observação

   O script a seguir requer o Microsoft. Data.SqlClient assembly. Instale-o do pacote NuGet e carregue a DLL com Add-Type -Path "path\to\Microsoft.Data.SqlClient.dll" antes de executar o script.

   # PowerShell script for creating a new SQL user called myapp using application DBOwnerApp with secret
   # DBOwnerApp is an admin for the server
   
   # Download latest  MSAL  - https://www.powershellgallery.com/packages/MSAL.PS
   Import-Module MSAL.PS
   
   $tenantId = "<TenantId>"   # Microsoft Entra tenant ID where DBOwnerApp resides
   $clientId = "<ClientId>"   # Application (client) ID recorded earlier for DBOwnerApp
   $clientSecret = "<ClientSecret>"   # Client secret for DBOwnerApp
   $scopes = "https://database.windows.net/.default" # The endpoint
   
   $result = Get-MsalToken -RedirectUri $uri -ClientId $clientId -ClientSecret (ConvertTo-SecureString $clientSecret -AsPlainText -Force) -TenantId $tenantId -Scopes $scopes
   
   $Tok = $result.AccessToken
   #Write-host "token"
   $Tok
   
   $SQLServerName = "<ServerName>"    # Logical server name
   $DatabaseName = "<database name>"   # Azure SQL database name
   
   Write-Host "Create SQL connection string"
   $conn = New-Object Microsoft.Data.SqlClient.SqlConnection
   $conn.ConnectionString = "Data Source=$SQLServerName.database.windows.net;Initial Catalog=$DatabaseName;Connect Timeout=30"
   $conn.AccessToken = $Tok
   
   Write-host "Connect to database and execute SQL script"
   $conn.Open()
   $ddlstmt = 'CREATE USER [myapp] FROM EXTERNAL PROVIDER;'
   Write-host " "
   Write-host "SQL DDL command"
   $ddlstmt
   $command = New-Object -TypeName Microsoft.Data.SqlClient.SqlCommand($ddlstmt, $conn)
   
   Write-host "results"
   $command.ExecuteNonQuery()
   $conn.Close()
   

   Como alternativa, você pode usar o seguinte código: autenticação do principal de serviço do Microsoft Entra para o Banco de Dados SQL do Azure. Modifique o script para executar a instrução DDL CREATE USER [myapp] FROM EXTERNAL PROVIDER. Use o mesmo script para criar um Microsoft Entra usuário ou grupo em seu banco de dados.

2. Verifique se o usuário myapp existe no banco de dados, executando o seguinte comando:

   SELECT name, type, type_desc, CAST(CAST(sid as varbinary(16)) as uniqueidentifier) as appId
   FROM sys.database_principals
   WHERE name = 'myapp'
   GO
   

   Você deverá ver uma saída semelhante a:

   name    type    type_desc    appId
   myapp    E    EXTERNAL_USER    aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
   

Conteúdo relacionado

• principais de serviço do Microsoft Entra com SQL do Azure
• O que são identidades gerenciadas para recursos de Azure?
• Como usar identidades gerenciadas para o Serviço de Aplicativo e Azure Functions
• Microsoft Entra autenticação da entidade de serviço para o BD SQL – Exemplo de código
• Aplicações e objetos de principal de serviço no Microsoft Entra ID
• Criar um principal de serviço do Azure com o Azure PowerShell
• A função leitores de diretório no Microsoft Entra ID para SQL do Azure