Partilhar via

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

  • Artigo

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, dando a você controle sobre quais recursos podem ser acessados 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 usando o comando New-AzADServicePrincipal, a saída inclui credenciais que deve proteger. Como alternativa, considere usar identidades gerenciadas para evitar a necessidade de usar credenciais.

Pré-requisitos

Criar uma entidade de serviço

Crie um service principal 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

A partir da versão 7.x do módulo Az PowerShell, New-AzADServicePrincipal já não atribui 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, veja Passos para adicionar uma atribuição de função.

Observação

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". Contacte o administrador do Microsoft Entra para criar um principal de serviço.

Em um diretório de ID do Microsoft Entra onde a configuração do usuário Usuários podem registrar aplicativos foi definida como Não, é necessário que seja membro de um dos seguintes papéis internos 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 padrão para uma entidade de serviço de autenticação baseada em senha é Colaborador. Essa função tem permissões totais 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 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. Seu valor não será exibido na saída do console. 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 retornado de New-AzADServicePrincipal contém os membros Id e DisplayName, qualquer um dos quais pode ser usado para iniciar sessão com o principal de serviço.

Importante

A entrada com uma entidade de serviço requer a ID do locatário sob a 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 criação da entidade de serviço:

(Get-AzContext).Tenant.Id

Autenticação baseada em certificado

Importante

Não há nenhum papel padrão atribuído ao criar um principal de serviço de autenticação baseado 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 baseada 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. Isso é representado por um arquivo PEM ou 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 entram com a entidade de serviço também precisam acessar a chave privada do certificado.

Importante

Iniciar sessão com uma entidade de serviço requer o ID de locatário sob o qual a entidade de serviço foi criada. Para obter o inquilino 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 inquilino ativo pode ser obtida com Get-AzADServicePrincipal. Por predefinição, este 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 o uso de um dos argumentos opcionais de filtragem do lado do servidor:

  • DisplayNameBeginsWith solicita entidades de serviço que tenham um prefixo que correspondam ao valor fornecido. O nome para exibição 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 tem os seguintes cmdlets para gerenciar atribuições de função:

  • pt-PT: Obter-AzAtribuicaoDeFunção
  • Novo-AzRoleAssignment
  • Remove-AzRoleAssignment

Para obter mais informações sobre Role-Based controle de acesso (RBAC) e funções, consulte RBAC: funções integradas.

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 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 um de função não restringir permissões atribuídas anteriormente. Ao restringir as permissões de uma entidade de serviço, a função de Colaborador deve ser removida.

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

Get-AzRoleAssignment -ServicePrincipalName ServicePrincipalName

Entrar usando um principal de serviço

Teste as credenciais e permissões da nova entidade de serviço ao iniciar sessão. Para entrar com uma entidade de serviço, precisas do valor applicationId associado a ela e do inquilino sob o qual foi criada.

Para iniciar sessão utilizando um principal de serviço com 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 de autenticação baseada em certificado

Redefinir credenciais

Se se esquecer das credenciais de um principal de serviço, utilize New-AzADSpCredential para adicionar uma nova credencial com uma senha 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 fazer isso, use o cmdlet Remove-AzADSpCredential:

Remove-AzADSpCredential -DisplayName ServicePrincipalName

$newCredential = New-AzADSpCredential -ServicePrincipalName ServicePrincipalName

Solução de problemas

Se receber o erro: "New-AzADServicePrincipal: Outro objeto com o mesmo valor para a propriedade identifierUris 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 Ative Directory. Se você remover a entidade de serviço, o aplicativo ainda estará disponível. Este 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.