Partilhar via

Criar um principal 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 façam login como um utilizador totalmente privilegiado, o Azure oferece princípios 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 é restrito pelas funções atribuídas ao principal do serviço, dando-lhe controlo sobre quais recursos podem ser acedidos e em que 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 login com uma identidade de usuário.

Este artigo mostra as etapas para criar, obter informações sobre, e redefinir 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 "service principal"

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 login que utiliza.

Importante

A partir da versão 7.x do módulo Az PowerShell, New-AzADServicePrincipal já não atribui 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

Caso a sua conta não tenha permissão para criar uma entidade de serviço, New-AzADServicePrincipal irá retornar uma mensagem de erro contendo "Privilégios insuficientes para concluir a operação". Contacte o administrador do Microsoft Entra para criar um principal de serviço.

Num diretório do Microsoft Entra ID onde a configuração de utilizadores Utilizadores podem registar aplicações foi definida como Não, deve ser membro de uma das seguintes funções predefinidas 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 senha

Importante

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

Sem quaisquer 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 é recomendado.

$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName

O objeto retornado contém a propriedade PasswordCredentials.SecretText que contém a senha gerada. Certifique-se de armazenar esse valor em algum lugar seguro para autenticar com a entidade de serviço. O respetivo valor não será apresentado na saída da consola. Caso percas a palavra-passe, redefine 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, qualquer um dos quais pode ser utilizado para efetuar login com o principal de serviço.

Importante

Iniciar sessão com um principal de serviço requer o ID do locatário sob o qual o principal de serviço foi criado. Para obter o inquilino 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 gerenciar atribuições de função, consulte Gerenciar funções principais de serviço.

As entidades de serviço que usam autenticação com base em certificado são criadas com o parâmetro CertValue. Este parâmetro usa uma cadeia de caracteres 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 há suporte para codificações binárias do certificado público. Estas instruções pressupõem 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 New-AzADServicePrincipal contém as propriedades Id e DisplayName, qualquer uma das quais pode ser usada para iniciar sessão com o principal de serviço. Os clientes que se autenticam com a entidade de serviço também precisam acessar a chave privada do certificado.

Importante

Iniciar sessão com um principal de serviço requer o ID do locatário sob o qual o principal de serviço foi criado. Para obter o inquilino 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 service principal existente

É possível obter uma lista de principais dos serviços do locatário ativo com Get-AzADServicePrincipal. Por predefinição, este comando devolve todas as identidades de serviço de um locatário. Para grandes organizações, pode demorar muito tempo a obter os resultados. Em alternativa, recomenda-se a utilização de 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 a apresentar de um principal de serviço é o valor definido com DisplayName durante a criação.
  • DisplayName solicita uma correspondência exata de um nome de entidade de serviço.

Gerenciar funções 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ção não usam a ID do objeto principal do serviço. Eles usam o ID do aplicativo associado, que é gerado no momento da criação. Para obter o identificador da aplicação de um principal de serviço, utilize 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. Quando se restringem as permissões de um principal de serviço, a função Contribuidor deve ser removida.

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

Get-AzRoleAssignment -ServicePrincipalName ServicePrincipalName

Iniciar sessão com uma identidade de serviço

Teste as credenciais e permissões do novo principal de serviço ao iniciar sessão. Para iniciar sessão com um principal de serviço, é necessário o valor applicationId associado a ele e o inquilino sob o qual foi criado.

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 requer que o Azure PowerShell possa recuperar informações de um armazenamento 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 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 novas credenciais, convém remover as credenciais existentes para impedir o login com elas. Para tal, utilize 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 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 você remover a entidade de serviço, o aplicativo ainda estará 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 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 o novo principal de serviço que está a tentar criar.