Criar uma entidade de serviço do Azure com a CLI do AzureCreate an Azure service principal with Azure CLI

Ferramentas automatizadas que usam os serviços do Azure devem sempre ter permissões restritas.Automated tools that use Azure services should always have restricted permissions. Em vez de os aplicativos entrarem como um usuário com privilégio total, o Azure oferece as entidades de serviço.Instead of having applications sign in as a fully privileged user, Azure offers service principals.

Uma entidade de serviço do Azure é uma identidade criada para uso com aplicativos, serviços hospedados e ferramentas automatizadas para acessar os recursos do Azure.An Azure service principal is an identity created for use with applications, hosted services, and automated tools to access Azure resources. Esse acesso é restrito pelas funções atribuídas à entidade de serviço, oferecendo a você o controle sobre quais recursos poderão ser acessados e em qual nível.This access is restricted by the roles assigned to the service principal, giving you control over which resources can be accessed and at which level. Por motivos de segurança, é sempre recomendado usar entidades de serviço com ferramentas automatizadas em vez de permitir a entrada com uma identidade de usuário.For security reasons, it's always recommended to use service principals with automated tools rather than allowing them to log in with a user identity.

Este artigo mostra as etapas para criar, obter informações e redefinir uma entidade de serviço com a CLI do Azure.This article shows you the steps for creating, getting information about, and resetting a service principal with the Azure CLI.

Criar uma entidade de serviçoCreate a service principal

Crie uma entidade de serviço com o comando az ad sp create-for-rbac.Create a service principal with the az ad sp create-for-rbac command. Ao criar uma entidade de serviço, você pode escolher o tipo de autenticação de entrada usada.When creating a service principal, you choose the type of sign-in authentication it uses.

Observação

Se sua conta não tiver permissão para criar uma entidade de serviço, az ad sp create-for-rbac mostrará uma mensagem de erro “Privilégios insuficientes para concluir a operação”.If your account doesn't have permission to create a service principal, az ad sp create-for-rbac will return an error message containing "Insufficient privileges to complete the operation." Entre em contato com o administrador do Azure Active Directory para criar uma entidade de serviço.Contact your Azure Active Directory admin to create a service principal.

Há dois tipos de autenticação disponíveis para as entidades de serviço: A autenticação baseada em senha e em certificado.There are two types of authentication available for service principals: Password-based authentication, and certificate-based authentication.

Autenticação baseada em senhaPassword-based authentication

Sem parâmetros de autenticação, a autenticação baseada em senha é usada com uma senha aleatória criada para você.Without any authentication parameters, password-based authentication is used with a random password created for you. Caso queira uma autenticação baseada em senha, esse método é recomendado.If you want password-based authentication, this method is recommended.

az ad sp create-for-rbac --name ServicePrincipalName

Para uma senha fornecida pelo usuário, use o argumento --password.For a user-supplied password, use the --password argument. Quando criar uma senha, certifique-se de seguir as Regras e restrições de senha do Azure Active Directory.When creating a password, make sure you follow the Azure Active Directory password rules and restrictions. Não use uma senha fraca, nem reutilize uma senha.Don't use a weak password or reuse a password.

az ad sp create-for-rbac --name ServicePrincipalName --password <Choose a strong password>

Importante

Por motivos de segurança, o argumento --password para a criação da entidade de serviço será preterido em uma versão futura.For security reasons, the --password argument for service principal creation will be deprecated in a future release. Se você quiser usar a autenticação baseada em senha, evite --password e deixe a CLI gerar uma senha segura para você.If you want to use password-based authentication, avoid --password and let the CLI generate a secure password for you.

A saída para uma entidade de serviço com a autenticação por senha inclui a chave password.The output for a service principal with password authentication includes the password key. Certifique-se de que tenha copiado esse valor já que não será possível recuperá-lo posteriormente.Make sure you copy this value - it can't be retrieved. Se você esquecer a senha, redefina as credenciais da entidade de serviço.If you forget the password, reset the service principal credentials.

As chaves appId e tenant aparecem na saída do az ad sp create-for-rbac e são usadas na autenticação da entidade de serviço.The appId and tenant keys appear in the output of az ad sp create-for-rbac and are used in service principal authentication. Registre seus valores, mas eles podem ser recuperados a qualquer momento com o comando az ad sp list.Record their values, but they can be retrieved at any point with az ad sp list.

Autenticação baseada em certificadoCertificate-based authentication

Para a autenticação baseada em certificado, use o argumento --cert.For certificate-based authentication, use the --cert argument. Esse argumento exige que você mantenha um certificado existente.This argument requires that you hold an existing certificate. Certifique-se de que todas as ferramentas que usam essa entidade de serviço tenham acesso à chave privada do certificado.Make sure any tool that uses this service principal has access to the certificate's private key. Os certificados devem estar no formato ASCII, como PEM, CER ou DER.Certificates should be in an ASCII format such as PEM, CER, or DER. Transmita o certificado como uma cadeia de caracteres ou use o formato @path para carregar o certificado de um arquivo.Pass the certificate as a string, or use the @path format to load the certificate from a file.

az ad sp create-for-rbac --name ServicePrincipalName --cert "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
az ad sp create-for-rbac --name ServicePrincipalName --cert @/path/to/cert.pem

O argumento --keyvault pode ser adicionado para usar o certificado no Azure Key Vault.The --keyvault argument can be added to use a certificate in Azure Key Vault. Nesse caso, o valor --cert é o nome do certificado.In this case, the --cert value is the name of the certificate.

az ad sp create-for-rbac --name ServicePrincipalName --cert CertName --keyvault VaultName

Para criar um certificado autoassinado para autenticação, use o argumento --create-cert:To create a self-signed certificate for authentication, use the --create-cert argument:

az ad sp create-for-rbac --name ServicePrincipalName --create-cert

O argumento --keyvault pode ser adicionado para armazenar o certificado no Azure Key Vault.The --keyvault argument can be added to store the certificate in Azure Key Vault. Ao usar --keyvault, o argumento --cert também será necessário.When using --keyvault, the --cert argument is required.

az ad sp create-for-rbac --name ServicePrincipalName --create-cert --cert CertName --keyvault VaultName

A menos que você armazene o certificado no cofre de chaves, a saída incluirá a chave fileWithCertAndPrivateKey.Unless you store the certificate in Key Vault, the output includes the fileWithCertAndPrivateKey key. O valor dessa chave informa onde o certificado gerado é armazenado.This key's value tells you where the generated certificate is stored. Certifique-se de copiar o certificado para um local seguro ou não será possível entrar com essa entidade de serviço.Make sure that you copy the certificate to a secure location, or you can't sign in with this service principal.

Para certificados armazenados no Key Vault, recupere a chave privada do certificado com o comando az keyvault secret show.For certificates stored in Key Vault, retrieve the certificate's private key with az keyvault secret show. No Key Vault, o nome do segredo do certificado é igual ao nome do certificado.In Key Vault, the name of the certificate's secret is the same as the certificate name. Se você perder o acesso à chave privada de um certificado, redefina as credenciais da entidade de serviço.If you lose access to a certificate's private key, reset the service principal credentials.

As chaves appId e tenant aparecem na saída do az ad sp create-for-rbac e são usadas na autenticação da entidade de serviço.The appId and tenant keys appear in the output of az ad sp create-for-rbac and are used in service principal authentication. Registre seus valores, mas eles podem ser recuperados a qualquer momento com o comando az ad sp list.Record their values, but they can be retrieved at any point with az ad sp list.

Obter uma entidade de serviço existenteGet an existing service principal

Uma lista das entidades de serviço em um locatário pode ser recuperada com o comando az ad sp list.A list of the service principals in a tenant can be retrieved with az ad sp list. Por padrão, esse comando retorna as 100 primeiras entidades de serviço do locatário.By default this command returns the first 100 service principals for your tenant. Para obter todas as entidades de serviço de um locatário, use o argumento --all.To get all of a tenant's service principals, use the --all argument. Obter essa lista pode levar muito tempo, portanto, é recomendável que você filtre a lista com um dos argumentos a seguir:Getting this list can take a long time, so it's recommended that you filter the list with one of the following arguments:

  • --display-name envia solicitações às entidades de serviço que têm um prefixo que corresponda ao nome fornecido.--display-name requests service principals that have a prefix that match the provided name. O nome de exibição de uma entidade de serviço é o valor definido com o parâmetro --name durante a criação.The display name of a service principal is the value set with the --name parameter during creation. Se você não definiu --name durante a criação da entidade de serviço, o prefixo do nome será azure-cli-.If you didn't set --name during service principal creation, the name prefix is azure-cli-.
  • --spn filtra a correspondência do nome exato da entidade de serviço.--spn filters on exact service principal name matching. O nome da entidade de serviço sempre começa com https://.The service principal name always starts with https://. se o valor usado para --name não era um URI, esse valor é https:// seguido do nome de exibição.if the value you used for --name wasn't a URI, this value is https:// followed by the display name.
  • --show-mine só envia solicitações às entidades de serviço criadas pelo usuário conectado.--show-mine requests only service principals created by the signed-in user.
  • --filter usa um filtro OData e realiza a filtragem do lado do servidor.--filter takes an OData filter, and performs server-side filtering. Esse método é recomendado para a filtragem do lado do cliente com o argumento --query da CLI.This method is recommended over filtering client-side with the CLI's --query argument. Para saber mais sobre os filtros do OData, confira Sintaxe de expressão do OData para filtros.To learn about OData filters, see OData expression syntax for filters.

As informações retornadas para objetos da entidade de serviço são detalhadas.The information returned for service principal objects is verbose. Para obter apenas as informações necessárias para entrar, use a cadeia de consulta [].{"id":"appId", "tenant":"appOwnerTenantId"}.To get only the information necessary for sign-in, use the query string [].{"id":"appId", "tenant":"appOwnerTenantId"}. Por exemplo, para obter as informações de logon para todas as entidades de serviço criadas pelo usuário conectado no momento:For example, to get the sign-in information for all service principals created by the currently logged in user:

az ad sp list --show-mine --query '[].{"id":"appId", "tenant":"appOwnerTenantId"}'

Importante

az ad sp list ou az ad sp show obtêm o usuário e o locatário, mas não os segredos de autenticação nem o método de autenticação.az ad sp list or az ad sp show get the user and tenant, but not any authentication secrets or the authentication method. Os segredos para certificados no Key Vault podem ser recuperados com o comando az keyvault secret show, mas, por padrão, nenhum outro segredo será armazenado.Secrets for certificates in Key Vault can be retrieved with az keyvault secret show, but no other secrets are stored by default. Se você esquecer o método de autenticação ou o segredo, redefina as credenciais da entidade de serviço.If you forget an authentication method or secret, reset the service principal credentials.

Gerenciar funções da entidade de serviçoManage service principal roles

A CLI do Azure oferece os seguintes comandos para gerenciar as atribuições de função:The Azure CLI has the following commands to manage role assignments:

A função padrão para uma entidade de serviço é Colaborador.The default role for a service principal is Contributor. Essa função tem permissões completas para ler e gravar em uma conta do Azure.This role has full permissions to read and write to an Azure account. A função Leitor é mais restritiva, com acesso somente leitura.The Reader role is more restrictive, with read-only access. Para obter mais informações sobre o Controle de Acesso Baseado em Função (RBAC) e funções, confira RBAC: funções internas.For more information on Role-Based Access Control (RBAC) and roles, see RBAC: Built-in roles.

Esse exemplo adiciona a função Leitor e exclui a função Colaborador:This example adds the Reader role and removes the Contributor one:

az role assignment create --assignee APP_ID --role Reader
az role assignment delete --assignee APP_ID --role Contributor

Observação

Caso sua conta não tenha 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 Azure Active Directory para gerenciar funções.If your account doesn't have permission to assign a role, you see an error message that your account "does not have authorization to perform action 'Microsoft.Authorization/roleAssignments/write'." Contact your Azure Active Directory admin to manage roles.

Adicionar uma função não restringe as permissões atribuídas anteriormente.Adding a role doesn't restrict previously assigned permissions. Ao restringir as permissões da entidade de serviço, a função Colaborador deverá ser removida.When restricting a service principal's permissions, the Contributor role should be removed.

Para verificar as alterações, liste as funções atribuídas:The changes can be verified by listing the assigned roles:

az role assignment list --assignee APP_ID

Entrar usando uma entidade de serviçoSign in using a service principal

Teste as novas credenciais e permissões da entidade de serviço iniciando a sessão.Test the new service principal's credentials and permissions by signing in. Para entrar com uma entidade de serviço, você precisa de appId, tenant e das credenciais.To sign in with a service prinicpal, you need the appId, tenant, and credentials.

Para entrar com uma entidade de serviço usando a senha:To sign in with a service principal using a password:

az login --service-principal --username APP_ID --password PASSWORD --tenant TENANT_ID

Para entrar com um certificado, ele deve estar disponível localmente como um arquivo PEM ou DER, no formato ASCII:To sign in with a certificate, it must be available locally as a PEM or DER file, in ASCII format:

az login --service-principal --username APP_ID --tenant TENANT_ID --password /path/to/cert

Para saber mais sobre como entrar com uma entidade de serviço, confira Entrar com a CLI do Azure.To learn more about signing in with a service principal, see Sign in with the Azure CLI.

Redefinir credenciaisReset credentials

Se você esquecer as credenciais de uma entidade de serviço, use o comando az ad sp credencial reset.If you forget the credentials for a service principal, use az ad sp credential reset. O comando reset tem os mesmos argumentos que az ad sp create-for-rbac.The reset command takes the same arguments as az ad sp create-for-rbac.

az ad sp credential reset --name APP_ID