Compartilhar via

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

As ferramentas automatizadas que usam os serviços do Azure sempre devem ter permissões restritas. Em vez de fazer com que os aplicativos entrem como um usuário totalmente privilegiado, o Azure oferece 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 recursos do Azure. Esse acesso é restrito pelas funções atribuídas à entidade de serviço, fornecendo controle sobre quais recursos podem ser acessados e em qual nível. Por motivos de segurança, é sempre recomendável usar entidades de serviço com ferramentas automatizadas em vez de permitir que elas façam logon 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 credenciais que você deve proteger. Como alternativa, considere o uso de identidades gerenciadas para evitar a necessidade de usar credenciais.

Pré-requisitos

Criar um principal de serviço

Crie uma entidade de serviço com o cmdlet New-AzADServicePrincipal . Ao criar uma entidade de serviço, você escolhe o tipo de autenticação de entrada que ela usa.

Importante

Começando com o módulo do Az PowerShell versão 7.x, New-AzADServicePrincipal não atribui mais a função Colaborador à entidade de serviço por padrão. Para atribuir uma função específica a uma entidade de serviço, consulte 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 da ID do Microsoft Entra em que a configuração do usuário os usuários podem registrar aplicativos foi definida como Não, você deve ser membro de uma das seguintes funções internas da ID do Microsoft Entra (que têm a ação: microsoft.directory/applications/createAsOwner ou microsoft.directory/applications/create):

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

Há dois tipos de autenticação disponíveis para entidades de serviço: autenticação baseada em senha e autenticação baseada 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, consulte Gerenciar funções de entidade de serviço.

Sem outros parâmetros de autenticação, a autenticação baseada em senha é usada e uma senha aleatória é criada para você. Se você quiser autenticação baseada em senha, esse método será recomendado.

$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName

O objeto retornado contém a PasswordCredentials.SecretText propriedade que contém a senha gerada. Certifique-se de armazenar 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 exportar o segredo:

$sp.PasswordCredentials.SecretText

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

Importante

Entrar com uma entidade de serviço requer a ID do locatário na qual a entidade de serviço foi criada. Para obter o locatário ativo quando a entidade de serviço foi criada, execute o seguinte comando 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, consulte 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 CertValue parâmetro. 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 codificado em texto. 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 New-AzADServicePrincipal contém as Id propriedades e DisplayName as quais podem ser usadas para entrar com a entidade de serviço. Os clientes que entrarem com a entidade de serviço também precisam ter acesso à chave privada do certificado.

Importante

Entrar com uma entidade de serviço requer a ID do locatário na qual a entidade de serviço foi criada. Para obter o locatário ativo quando a entidade de serviço foi criada, execute o seguinte comando 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 para o 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, é recomendável usar um dos argumentos opcionais de filtragem do lado do servidor:

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

Gerenciar funções de entidade de serviço

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

Para obter mais informações sobre Role-Based RBAC (Controle de Acesso) e funções, consulte RBAC: Funções internas.

O exemplo a seguir 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 levam a ID do objeto da entidade de serviço. Eles pegam a ID do aplicativo associada, que é gerada no momento da criação. Para obter a ID do aplicativo para uma entidade de serviço, use Get-AzADServicePrincipal.

Observação

Se sua conta não tiver permissão para atribuir uma função, você verá uma mensagem de erro informando que 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 de uma entidade de serviço, a função Colaborador deve ser removida.

As alterações podem ser verificadas listando as funções atribuídas:

Get-AzRoleAssignment -ServicePrincipalName ServicePrincipalName

Entrar usando uma entidade de serviço

Teste as credenciais e as permissões da nova entidade de serviço entrando. Para entrar com uma entidade de serviço, você precisa do applicationId valor associado a ela e do locatário em que ela foi criada.

Para entrar com uma entidade de serviço usando uma 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 requer que o Azure PowerShell possa recuperar informações de um repositório de certificados local com base em uma impressão digital de 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 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 novas credenciais, talvez você queira remover as credenciais existentes para impedir a entrada com elas. Para fazer isso, use o cmdlet Remove-AzADSpCredential :

Remove-AzADSpCredential -DisplayName ServicePrincipalName

$newCredential = New-AzADSpCredential -ServicePrincipalName ServicePrincipalName

Resolução de problemas

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

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 anteriormente uma entidade de serviço 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.

Você pode usar o exemplo a seguir para verificar se um aplicativo Microsoft Entra com o mesmo nome não existe:

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 nova entidade de serviço que você está tentando criar.