Partilhar 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 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.

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 e redefinir uma entidade de serviço com o Azure PowerShell.

Atenção

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 "service principal"

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

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.

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 palavra-passe

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 de entidade 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 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 de contém os New-AzADServicePrincipal membros e Id , que podem ser usados para entrar com a entidade de DisplayName 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 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 autenticação baseada em certificado são criadas com o CertValue parâmetro. 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 contém as New-AzADServicePrincipal propriedades e Id , que podem ser usadas para entrar com a entidade de DisplayName serviço. Os clientes que entram com a entidade de serviço também precisam acessar a chave privada do certificado.

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 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, 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 corresponda ao valor fornecido. O nome de exibição de uma entidade 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:

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

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 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 de 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 permissões da nova entidade 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 uma entidade de serviço utilizando 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 você esquecer as credenciais de uma entidade de serviço, use 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 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 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.

  • Last updated on