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 de gerenciamento de acesso aos recursos SQL do Azure para usuários e aplicativos em seu locatário Microsoft Entra.

Observação

O Microsoft Entra ID era anteriormente conhecido como Azure Active Directory (Azure AD).

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

Neste tutorial, você aprenderá a:

• Atribuir uma identidade ao servidor lógico
• Atribuir a função de Leitores de Diretório à identidade do servidor
• Registre um aplicativo 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 de banco de dados Microsoft Entra com a entidade de serviço

Pré-requisitos

• Uma implantação do Banco de Dados SQL do Azure existente. Para este tutorial, supomos que você tenha um Banco de Dados SQL em funcionamento.
• As permissões Global Administrator ou Privileged Role Administrator do Microsoft Entra no locatário em que seu banco de dados SQL reside.
• A versão mais recente do módulo Az.Sql do PowerShell.
• A versão mais recente do módulo Microsoft.Graph do 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 recurso Microsoft Entra ID no portal do 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 lógico no 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 agora deve mostrar PrincipalId, Type e TenantId. A identidade atribuída é a PrincipalId.

4. Também é possível verificar a identidade acessando o portal do Azure.

   • No recurso Microsoft Entra ID, acesse Aplicativos empresariais. 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 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 a ID do Microsoft Entra forem revogadas ou a identidade do servidor for excluída, a autenticação do Microsoft Entra deixará de funcionar.

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

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

Observação

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

O script a seguir concede permissão aos Leitores do Diretório do Microsoft Entra para uma identidade que representa o servidor lógico do 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 **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'."
}

Observação

A saída desse script indica se a identidade está designada à função Leitores de Diretório. O script poderá ser executado novamente se você não tiver certeza de que a permissão foi concedida.

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

Em ambientes de produção, uma prática de gerenciamento comum é atribuir a função de 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 privilégio mínimo e ignora a necessidade de um Administrador Global ou Administrador de Função Privilegiada conceder a função de Leitores de Diretório individualmente a cada instância do SQL. Para obter mais informações sobre esse recurso, confira Função Leitores de Diretório no Microsoft Entra ID para o SQL do Azure.

Criar um aplicativo no Microsoft Entra ID

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

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 posteriormente neste tutorial.

Para registrar seus aplicativos:

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

   

   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 do cliente para o aplicativo entrar. Siga carregar um certificado ou criar um segredo para fazer logon. Registre o segredo do cliente para DBOwnerApp para uso futuro neste tutorial.

Para obter mais informações, examine Usar o portal para criar um aplicativo do Microsoft Entra e uma entidade 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 a seu Banco de Dados SQL usando uma identidade do Microsoft Entra que tenha permissões para criar outros usuários.

Importante

Somente usuários do Microsoft Entra podem criar outros usuários do Microsoft Entra no Banco de Dados SQL do Azure. Nenhum usuário com base na autenticação SQL, inclusive o administrador do servidor, pode criar um usuário Microsoft Entra. O administrador do Microsoft Entra é o único usuário que pode criar inicialmente outros usuários do Microsoft Entra no Banco de Dados SQL. Depois que o administrador do Microsoft Entra criar 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, é necessária, no mínimo, a permissão SQL ALTER ANY USER. Essa permissão também é herdada por meio da associação em db_owner e 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 do 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 DBOwnerApp como administrador do Microsoft Entra. Isso pode ser feito por meio do portal do Azure, do PowerShell ou dos comandos da CLI do Azure. Para obter mais informações, consulte Provisionar 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 entidade de serviço do 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.

   # 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 de entidade de serviço Microsoft Entra para Banco de Dados SQL do Azure. Modifique o script para executar a instrução DDL CREATE USER [myapp] FROM EXTERNAL PROVIDER. O mesmo script pode ser usado para criar um usuário ou grupo 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
   

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

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

Próximas etapas

• Criar entidade de serviço do Microsoft Entra com o SQL do Azure
• O que são identidades gerenciadas para recursos do Azure?
• Como usar identidades gerenciadas para o Serviço de Aplicativo e o Azure Functions
• Autenticação de entidade de serviço do Microsoft Entra para banco de dados SQL — exemplo de código
• Objetos de entidade de serviço e aplicativo no Microsoft Entra ID
• Criar uma entidade de serviço do Azure com o Azure PowerShell
• Função Leitores de Diretório no Microsoft Entra ID para SQL do Azure