Criar um principal de serviço do Azure com o Azure PowerShell

  • Artigo

As ferramentas automatizadas que utilizam serviços do Azure devem ter sempre permissões restritas. Em vez de ter as informações de início de sessão das aplicações como um utilizador totalmente privilegiado, o Azure oferece os principais de serviço.

Um principal de serviço do Azure é uma identidade criada para ser utilizada com aplicações, serviços alojados e ferramentas automatizadas para aceder aos recursos do Azure. Este acesso é restringido pelas funções atribuídas ao principal de serviço, o que lhe permite assumir o controlo dos recursos que podem ser acedidos e em que nível. Por motivos de segurança, é sempre recomendado utilizar os principais de serviço com ferramentas automatizadas, em vez de permitir que iniciem sessão com uma identidade de utilizador.

Este artigo mostra-lhe os passos para criar, obter informações e repor um principal de serviço com o Azure PowerShell.

Atenção

Quando cria um principal de serviço com o comando New-AzADServicePrincipal, a saída inclui credenciais que tem de proteger. Como alternativa, considere utilizar identidades geridas para evitar a necessidade de usar credenciais.

Pré-requisitos

Criar um principal de serviço

Crie um principal de serviço com o cmdlet New-AzADServicePrincipal. Quando cria um principal de serviço, escolhe o tipo de autenticação de início de sessão que o mesmo utiliza.

Importante

A partir do módulo Az PowerShell versão 7.x, New-AzADServicePrincipal não atribui mais a função de 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.

Nota

Se sua conta não tiver permissão para criar uma entidade de serviço, New-AzADServicePrincipal retornará uma mensagem de erro contendo "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 de ID do Microsoft Entra onde a configuração de usuário 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 do usuário no Microsoft Entra ID, consulte Restringir 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 palavra-passe

Importante

A função predefinida para um principal de serviço de autenticação baseada em palavra-passe é Contribuidor. Esta função tem permissões completas para ler e escrever numa conta do Azure. Para obter informações sobre como gerir atribuições de funções, consulte Gerir funções do principal de serviço.

Na ausência de outros parâmetros de autenticação, a autenticação baseada em palavra-passe é utilizada e é criada uma palavra-passe aleatória para si. Se estiver interessado na autenticação baseada em palavra-passe, este é o método recomendado.

$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName

O objeto retornado contém a PasswordCredentials.SecretText propriedade que contém a senha gerada. Certifique-se de que armazena este valor num local seguro para efetuar a autenticação com o principal de serviço. O respetivo valor não será apresentado na saída da consola. Se perder a palavra-passe, reponha as credenciais do principal de serviço.

O código a seguir permite exportar o segredo:

$sp.PasswordCredentials.SecretText

O objeto devolvido a partir de New-AzADServicePrincipal contém os membros Id e DisplayName, que podem ser utilizados para iniciar sessão com o principal de serviço.

Importante

O início de sessão com um principal de serviço requer o ID de inquilino no qual o principal de serviço foi criado. Para obter o inquilino que estava ativo quando o principal de serviço foi criado, execute o seguinte comando imediatamente após a criação do principal de serviço:

(Get-AzContext).Tenant.Id

Autenticação baseada em certificado

Importante

Não é atribuída nenhuma função predefinida quando é criado um principal de serviço de autenticação baseada em certificado. Para obter informações sobre como gerir atribuições de funções, consulte Gerir funções do principal de serviço.

Os principais de serviço que utilizam a autenticação baseada em certificado são criados com o parâmetro CertValue. Este parâmetro aceita uma cadeia ASCII codificada em base64 do certificado público. Isto é representado por um ficheiro PEM ou por um CRT ou CER codificado em texto. Não são suportadas codificações binárias do certificado público. Estas instruções partem do princípio de que já tem um certificado disponível.

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

O objeto retornado de contém as Id propriedades e DisplayName , que podem ser usadas para entrar com a entidade de New-AzADServicePrincipal serviço. Os clientes que iniciam sessão com o principal de serviço também precisam de acesso à chave privada do certificado.

Importante

O início de sessão com um principal de serviço requer o ID de inquilino no qual o principal de serviço foi criado. Para obter o inquilino que estava ativo quando o principal de serviço foi criado, execute o seguinte comando imediatamente após a criação do principal de serviço:

(Get-AzContext).Tenant.Id

Obter um principal de serviço existente

É possível obter uma lista de principais de serviço do inquilino ativo com Get-AzADServicePrincipal. Por predefinição, este comando devolve todos os principais de serviço de um inquilino. Para as organizações de grande dimensão, a devolução dos resultados pode ser muito demorada. Em alternativa, recomenda-se a utilização de um dos argumentos de filtragem opcionais do lado do servidor:

  • DisplayNameBeginsWith pede principais de serviço que tenham um prefixo correspondente ao valor fornecido. O nome a apresentar de um principal de serviço é o valor definido com DisplayName durante a criação.
  • DisplayName pede uma correspondência exata de um nome do principal do serviço.

Gerir funções de principais de serviço

O Azure PowerShell dispõe dos seguintes cmdlets para gerir as atribuições de funções:

Para obter mais informações sobre controlo de acesso baseado em funções (RBAC) e as funções, veja RBAC: funções incorporadas.

O exemplo a seguir adiciona a função Reader e remove a função Contributor :

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ções não aceitam o ID do objeto do principal de serviço. Aceitam o ID da aplicação associada, gerado no momento da criação. Para obter o ID da aplicação de um principal de serviço, utilize Get-AzADServicePrincipal.

Nota

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. Quando restringir as permissões de um principal de serviço, a função Contribuidor deve ser removida.

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

Get-AzRoleAssignment -ServicePrincipalName ServicePrincipalName

Iniciar sessão com um principal de serviço

Teste as credenciais e permissões do novo principal de serviço iniciando sessão. Para entrar com uma entidade de serviço, você precisa do applicationId valor associado a ela e do locatário sob o qual ela foi criada.

Para iniciar sessão com um principal de serviço através de uma palavra-passe:

# 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 precisa que o Azure PowerShell tenha a capacidade de obter informações de um arquivo de certificados local com base num thumbprint 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

Repor credenciais

Se se esquecer das credenciais de um principal de serviço, utilize New-AzADSpCredential para adicionar uma credencial nova com uma palavra-passe aleatória. Este cmdlet não oferece suporte a credenciais definidas pelo usuário ao redefinir a senha.

Importante

Antes de atribuir credenciais novas, convém remover as credenciais existentes para evitar iniciar sessão com as mesmas. Para tal, utilize 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 identificador de propriedadeUris já existe.", verifique se uma entidade de serviço com o mesmo nome ainda não existe.

Get-AzAdServicePrincipal -DisplayName ServicePrincipalName

Se o principal de serviço existente já não for necessário, pode removê-lo utilizando o seguinte exemplo.

Remove-AzAdServicePrincipal -DisplayName ServicePrincipalName

Este erro também pode ocorrer quando tiver criado anteriormente um principal de serviço para uma aplicação do Azure Active Directory. Se remover o principal de serviço, a aplicação continuará disponível. Esta aplicação impede que crie outro principal 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 realmente existir uma aplicação com o mesmo nome, mas esta já não for necessária, pode ser removida utilizando o seguinte exemplo.

Remove-AzADApplication -DisplayName ServicePrincipalName

Caso contrário, escolha um nome alternativo para o novo principal de serviço que está a tentar criar.