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

Aplica-se a:Banco de Dados SQL do Azure

Este artigo explica como configurar uma entidade de serviço para que ela possa criar usuários do Microsoft Entra no Banco de Dados SQL do Azure. Esse recurso permite a configuração programática do gerenciamento de acesso aos recursos SQL do Azure para usuários e aplicativos em seu locatário do Microsoft Entra.

Nota

Microsoft Entra ID é o novo nome para o Azure Ative Directory (Azure AD). Estamos atualizando a documentação neste momento.

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

Neste tutorial, irá aprender a:

• Atribuir uma identidade ao servidor lógico
• Atribuir a função Leitores de Diretório à identidade do servidor
• Registar uma aplicação no Microsoft Entra ID
• Criar um usuário de banco de dados para a entidade de serviço desse aplicativo no Banco de Dados SQL do Azure
• Criar um usuário do banco de dados Microsoft Entra com a entidade de serviço

Pré-requisitos

• Uma implantação existente do Banco de Dados SQL do Azure. Supomos que você tenha um Banco de Dados SQL funcional para este tutorial.
• Microsoft Entra Global Administrator ou Privileged Role Administrator permissões no locatário onde seu banco de dados SQL reside.
• A versão mais recente do módulo Az.Sql PowerShell.
• A versão mais recente do módulo Microsoft.Graph PowerShell.

Atribuir uma identidade ao servidor lógico

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

   • Substitua <TenantId> pelo ID do locatário.

   Connect-AzAccount -Tenant <TenantId>
   

   Registre o TenantId para uso futuro neste tutorial.

2. Gere uma identidade gerenciada atribuída ao sistema e atribua-a ao servidor lógico no Azure. Execute o seguinte comando do PowerShell:

   • Substitua <ResourceGroupName> e <ServerName> com 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> com os 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 deve mostrar PrincipalId, Typee TenantId. A identidade atribuída é o PrincipalId.

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

   • No recurso Microsoft Entra ID, vá para Aplicativos corporativos. Digite o nome do seu servidor lógico. A ID do objeto que aparece 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 a ID do Microsoft Entra para funções administrativas, o que inclui a criação de usuários e logons do Microsoft Entra e a expansão do grupo para aplicar permissões de usuário com base em sua associação ao grupo Microsoft Entra. Se as permissões de identidade do servidor para consultar o ID do Microsoft Entra forem revogadas ou a identidade do servidor for excluída, a autenticação do Microsoft Entra para de funcionar.

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

• Usuário.Read.All
• GroupMember.Read.All e
• Application.Read.All.

Nota

Esse script deve ser executado por uma ID Global Administrator do Microsoft Entra ou por um Privileged Role Administratorarquivo .

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

• Substitua <TenantId> pelo recolhido TenantId anteriormente.
• Substitua <ServerName> pelo 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 **Global Administrator** or **Privileged Role Administrator** 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'."
}

Nota

A saída desse script indica se a identidade está atribuída à função Leitores de Diretório . Você pode executar novamente o script se não tiver certeza se a permissão foi concedida.

Para obter uma abordagem semelhante sobre como atribuir a função Leitores de Diretório para Instância Gerenciada SQL, consulte Provisionar o administrador do Microsoft Entra (Instância Gerenciada SQL).

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

Criar um aplicativo no Microsoft Entra ID

Registe as suas candidaturas. Para registrar um aplicativo, você precisa de pelo menos a função Microsoft Entra ID Application Developer . Para obter mais informações sobre como atribuir funções, consulte Atribuir funções de usuário na ID do Microsoft Entra.

Este tutorial usa duas entidades de serviço. A primeira entidade de serviço, DBOwnerApp, é usada para criar outros usuários no banco de dados. A segunda entidade de serviço, myapp, é o aplicativo para o qual DBOwnerApp cria um usuário de banco de dados para mais tarde neste tutorial.

Para registar as suas candidaturas:

1. No portal do Azure, selecione Microsoft Entra ID>Registros do>aplicativo Novo registro.

   

   Depois que o registro do aplicativo é criado, o valor da ID do aplicativo (cliente) é gerado e exibido. Registre esse valor para uso futuro neste tutorial.

   

2. Crie um segredo de cliente para o aplicativo entrar. 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, consulte Usar o portal para criar um aplicativo Microsoft Entra e uma entidade de serviço que possa acessar recursos.

Criar o usuário principal do serviço

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

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

Importante

Somente os usuários do Microsoft Entra podem criar outros usuários do Microsoft Entra no Banco de Dados SQL do Azure. Nenhum usuário baseado na autenticação SQL, incluindo o administrador do servidor, pode criar um usuário do Microsoft Entra. O administrador do Microsoft Entra é o único usuário que pode inicialmente criar outros usuários do Microsoft Entra no Banco de dados SQL. Depois que o administrador do Microsoft Entra tiver criado outros usuários, qualquer usuário do Microsoft Entra com permissões adequadas poderá criar outros usuários do Microsoft Entra.

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 do Microsoft Entra, no mínimo, a ALTER ANY USER permissão SQL é necessária. Essa permissão também é herdada por meio da associação ao 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 ao DBOwnerApp que permitem criar outros usuários do Microsoft Entra no banco de dados.

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

   EXEC sp_addrolemember 'db_owner', [DBOwnerApp]
   GO
   

   Você pode atribuir a ALTER ANY USER permissão para 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. Isso pode ser feito usando o portal do Azure, o PowerShell ou os comandos da CLI do Azure. Para obter mais informações, consulte Provisionar o Microsoft Entra admin (Banco de dados SQL).

Criar um usuário com uma entidade de serviço

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

   • Substitua <TenantId> pelo recolhido TenantId anteriormente.
   • Substitua <ClientId> pelo recolhido ClientId anteriormente.
   • Substitua <ClientSecret> pelo segredo do cliente criado anteriormente.
   • Substitua <ServerName> pelo 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.

   # 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 System.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 System.Data.SqlClient.SqlCommand($ddlstmt, $conn)       
   
   Write-host "results"
   $command.ExecuteNonQuery()
   $conn.Close()
   

   Como alternativa, você pode usar o seguinte código: Autenticação da entidade de serviço do Microsoft Entra no Banco de Dados SQL do Azure. Modifique o script para executar a instrução CREATE USER [myapp] FROM EXTERNAL PROVIDERDDL . O mesmo script pode ser usado para criar um usuário ou grupo do Microsoft Entra 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
   

   Deverá ver um resultado semelhante a:

   name	type	type_desc	appId
   myapp	E	EXTERNAL_USER	6d228f48-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   

Próximos passos

• Principal de serviço do Microsoft Entra com o SQL do Azure
• O que são identidades geridas para recursos do Azure?
• Como usar identidades gerenciadas para o Serviço de Aplicativo e o Azure Functions
• Autenticação da entidade de serviço do Microsoft Entra no Banco de Dados SQL - Exemplo de código
• Objetos de aplicação e de principal de serviço no Microsoft Entra ID
• Criar uma entidade de serviço do Azure com o Azure PowerShell
• Função Leitores de Diretório na ID do Microsoft Entra para SQL do Azure