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 obrigar as aplicações a iniciarem sessão como um utilizador com privilégios máximos, o Azure disponibiliza 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.

Aviso

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 da versão 7.x do módulo Az PowerShell, New-AzADServicePrincipal já não atribui a função contribuidor ao principal de serviço por predefinição. Para atribuir uma função específica a um principal de serviço, veja Passos para adicionar uma atribuição de função.

Nota

Se a sua conta não tiver permissão para criar um principal de serviço, New-AzADServicePrincipal devolve uma mensagem de erro que contém "Privilégios insuficientes para concluir a operação". Contacte o seu administrador do Azure Active Directory para criar um principal de serviço.

Existem dois tipos de autenticação disponíveis para os principais de serviço: a autenticação baseada em palavra-passe e a 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 devolvido contém a PasswordCredentials.SecretText propriedade que contém a palavra-passe 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 seguinte permite-lhe 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 devolvido de New-AzADServicePrincipal contém as Id propriedades e DisplayName , que podem ser utilizadas para iniciar sessão com o principal de 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 o Controlo de Acesso Baseado em Funções (RBAC) e as funções, veja RBAC: Funções incorporadas.

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

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 a sua conta não tiver permissão para atribuir uma função, verá uma mensagem de erro a indicar que a sua conta "não tem autorização para executar a ação "Microsoft.Authorization/roleAssignments/write"". Contacte o administrador do Azure Active Directory para gerir 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 iniciar sessão com um principal de serviço, precisa do applicationId valor associado ao mesmo e do inquilino em que é 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 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 arquivo de credenciais acessível ao PowerShell, veja Sign in with Azure PowerShell (Iniciar sessão com o Azure PowerShell)

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 suporta credenciais definidas pelo utilizador ao repor a palavra-passe.

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 receber o erro: "New-AzADServicePrincipal: já existe outro objeto com o mesmo valor para a propriedade identifierUris." , certifique-se de que não existe já um principal de serviço com o mesmo nome.

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.

Pode utilizar o seguinte exemplo para se certificar de que não existe uma aplicação do Azure Active Directory com o mesmo nome:

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.