Criar uma entidade de serviço do Azure com o Azure PowerShell

  • Artigo

Ferramentas automatizadas que usam os serviços do Azure devem sempre ter permissões restritas. Em vez de os aplicativos entrarem como um usuário com privilégio total, o Azure oferece as entidades de serviço.

Uma entidade de serviço do Azure é uma identidade criada para uso com aplicativos, serviços hospedados e ferramentas automatizadas para acessar os recursos do Azure. Esse acesso é restrito pelas funções atribuídas à entidade de serviço, oferecendo a você o controle sobre quais recursos poderão ser acessados e em qual nível. Por motivos de segurança, é sempre recomendado usar entidades de serviço com ferramentas automatizadas em vez de permitir a entrada com uma identidade de usuário.

Este artigo mostra as etapas para criar, obter informações e redefinir uma entidade de serviço com o Azure PowerShell.

Cuidado

Quando você cria uma entidade de serviço usando o comando New-AzADServicePrincipal, a saída inclui as credenciais que você precisa proteger. Como alternativa, considere usar identidades gerenciadas para evitar a necessidade de usar credenciais.

Pré-requisitos

Criar uma entidade de serviço

Criar uma entidade de serviço com o cmdlet New-AzADServicePrincipal. Ao criar uma entidade de serviço, você pode escolher o tipo de autenticação de entrada usada.

Importante

A partir do módulo do Az PowerShell versão 7.x, por padrão, New-AzADServicePrincipal não atribui mais a função Colaborador à entidade de serviço. Para atribuir uma função específica a uma entidade de serviço, confira Etapas para adicionar uma atribuição de função.

Observação

Se a sua conta não tem permissão para criar uma entidade de serviço, New-AzADServicePrincipal retorna a mensagem de erro "Privilégios insuficientes para concluir a operação". Entre em contato com o administrador do Microsoft Entra para criar uma entidade de serviço.

Em um diretório do Microsoft Entra ID no qual a configuração de usuário Os usuários podem registrar aplicativos foi definida como Não, você deve ser membro de uma das seguintes funções internas do Microsoft Entra ID (que têm a ação: microsoft.directory/applications/createAsOwner ou microsoft.directory/applications/create):

Para obter mais informações sobre as configurações de usuário no Microsoft Entra ID, consulte Restrinja quem pode criar aplicativos.

Há dois tipos de autenticação disponíveis para as entidades de serviço: A autenticação baseada em senha e em certificado.

Autenticação baseada em senha

Importante

A função padrão de uma entidade de serviço de autenticação baseada em senha é Colaborador. Essa função tem permissões completas para ler e gravar em uma conta do Azure. Para obter informações sobre como gerenciar atribuições de função, confira Gerenciar funções de entidade de serviço.

Sem outros parâmetros de autenticação, usa-se a autenticação baseada em senha, com uma senha aleatória criada para você. Caso queira uma autenticação baseada em senha, esse método é recomendado.

$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName

O objeto retornado contém a propriedade PasswordCredentials.SecretText que contém a senha gerada. Armazene esse valor em algum lugar seguro para autenticar com a entidade de serviço. Seu valor não será exibido na saída do console. Se você perder a senha, redefina as credenciais da entidade de serviço.

O código a seguir permite que você exporte o segredo:

$sp.PasswordCredentials.SecretText

O objeto retornado por New-AzADServicePrincipal contém os membros Id e DisplayName, os quais podem ser usados para entrar com a entidade de serviço.

Importante

Para entrar com uma entidade de serviço é preciso ter a ID do locatário que serviu de base para a criação da entidade de serviço. Para obter o locatário ativo de quando a entidade de serviço foi criada, execute o comando seguinte imediatamente após a criação da entidade de serviço:

(Get-AzContext).Tenant.Id

Autenticação baseada em certificado

Importante

Não há nenhuma função padrão atribuída ao criar uma entidade de serviço de autenticação baseada em certificado. Para obter informações sobre como gerenciar atribuições de função, confira Gerenciar funções de entidade de serviço.

As entidades de serviço que usam a autenticação baseada em certificado são criadas com o parâmetro CertValue. Esse parâmetro usa uma cadeia de caracteres ASCII codificada em base64 do certificado público. Isso é representado por um arquivo PEM ou por um CRT ou CER com texto codificado. Não há suporte para codificações binárias do certificado público. Essas instruções pressupõem que você já tenha um certificado disponível.

$cert = <public certificate as base64-encoded string>
$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName -CertValue $cert

O objeto retornado por New-AzADServicePrincipal contém as propriedades Id e DisplayName, as quais podem ser usadas para entrar com a entidade de serviço. Os clientes que entram com a entidade de serviço também precisam acessar a chave privada do certificado.

Importante

Para entrar com uma entidade de serviço é preciso ter a ID do locatário que serviu de base para a criação da entidade de serviço. Para obter o locatário ativo de quando a entidade de serviço foi criada, execute o comando seguinte imediatamente após a criação da entidade de serviço:

(Get-AzContext).Tenant.Id

Obter uma entidade de serviço existente

Uma lista de entidades de serviço do locatário ativo pode ser recuperada com Get-AzADServicePrincipal. Por padrão, esse comando retorna todas as entidades de serviço em um locatário. Para grandes organizações, pode levar muito tempo para retornar resultados. Em vez disso, recomenda-se usar um dos argumentos de filtragem opcionais do lado do servidor:

  • DisplayNameBeginsWith solicita entidades de serviço que tenham um prefixo que corresponda ao valor fornecido. O nome de exibição de uma entidade de serviço é o valor definido com DisplayName durante a criação.
  • DisplayName solicita uma correspondência exata de um nome da entidade de serviço.

Gerenciar funções da entidade de serviço

O Azure PowerShell tem os seguintes cmdlets para gerenciar atribuições de função:

Para obter mais informações sobre o Controle de Acesso Baseado em Função (RBAC) e funções, confira RBAC: funções internas.

O seguinte exemplo adiciona a função Leitor e remove a função Colaborador:

New-AzRoleAssignment -ApplicationId <service principal application ID> -RoleDefinitionName 'Reader'
Remove-AzRoleAssignment -ObjectId <service principal object ID> -RoleDefinitionName 'Contributor'

Importante

Os cmdlets de atribuição de função não usam a ID de objeto da entidade de serviço. Eles usam a ID do aplicativo associado, que é gerada no momento da criação. Para obter a ID do aplicativo para uma entidade de serviço, use Get-AzADServicePrincipal.

Observação

Caso sua conta não tenha permissão para atribuir uma função, você verá uma mensagem de erro informando que a sua conta "não tem autorização para executar a ação 'Microsoft.Authorization/roleAssignments/write'". Entre em contato com o administrador do Microsoft Entra para gerenciar funções.

Adicionar uma função não restringe as permissões atribuídas anteriormente. Ao restringir as permissões da entidade de serviço, a função Colaborador deverá ser removida.

Para verificar as alterações, liste as funções atribuídas:

Get-AzRoleAssignment -ServicePrincipalName ServicePrincipalName

Entrar usando uma entidade de serviço

Teste as novas credenciais e permissões da entidade de serviço iniciando a sessão. Para entrar com uma entidade de serviço, você precisa do valor applicationId associado a ela e do locatário com base no qual ela é criada.

Para entrar com uma entidade de serviço usando a senha:

# Use the application ID as the username, and the secret as password
$credentials = Get-Credential
Connect-AzAccount -ServicePrincipal -Credential $credentials -Tenant <tenant ID>

A autenticação baseada em certificado exige que o Azure PowerShell possa recuperar informações de um repositório de certificados local com base em uma impressão digital do certificado.

Connect-AzAccount -ServicePrincipal -Tenant <TenantId> -CertificateThumbprint <Thumbprint> -ApplicationId <ApplicationId>

Para obter instruções sobre como importar um certificado para um repositório de credenciais acessível pelo PowerShell, consulte Autenticação baseada em certificado

Redefinir credenciais

Se você esquecer as credenciais de uma entidade de serviço, use o comando New-AzADSpCredential para adicionar uma nova credencial com uma senha aleatória. Esse cmdlet não dá suporte a credenciais definidas pelo usuário ao redefinir a senha.

Importante

Antes de atribuir quaisquer novas credenciais, talvez seja interessante remover as credenciais existentes para evitar entrar com elas. Para fazer isso, use o cmdlet Remove-AzADSpCredential:

Remove-AzADSpCredential -DisplayName ServicePrincipalName

$newCredential = New-AzADSpCredential -ServicePrincipalName ServicePrincipalName

Solução de problemas

Se você receber o erro: "New-AzADServicePrincipal: Outro objeto com o mesmo valor para a propriedade identifierUris já existe." Verifique se não existe uma entidade de serviço com o mesmo nome.

Get-AzAdServicePrincipal -DisplayName ServicePrincipalName

Se a entidade de serviço existente não for mais necessária, você poderá removê-la usando o exemplo a seguir.

Remove-AzAdServicePrincipal -DisplayName ServicePrincipalName

Esse erro também pode ocorrer quando você criou uma entidade de serviço anteriormente para um aplicativo do Azure Active Directory. Se você remover a entidade de serviço, o aplicativo ainda estará disponível. Esse aplicativo impede que você crie outra entidade de serviço com o mesmo nome.

Use o seguinte exemplo para verificar se não existe um aplicativo do Microsoft Entra com o mesmo nome:

Get-AzADApplication -DisplayName ServicePrincipalName

Se um aplicativo com o mesmo nome existir e não for mais necessário, ele poderá ser removido usando o exemplo a seguir.

Remove-AzADApplication -DisplayName ServicePrincipalName

Caso contrário, escolha um nome alternativo para a entidade de serviço que você está tentando criar.