Creación de una entidad de servicio de Azure con la CLI de AzureCreate an Azure service principal with the Azure CLI

Las herramientas automatizadas que usan los servicios de Azure deberán tener siempre permisos restringidos.Automated tools that use Azure services should always have restricted permissions. En lugar de que las aplicaciones inicien sesión como un usuario con privilegios totales, Azure ofrece las entidades de servicio.Instead of having applications sign in as a fully privileged user, Azure offers service principals.

Una entidad de servicio de Azure es una identidad creada para su uso con aplicaciones, servicios hospedados y herramientas automatizadas que acceden a los recursos de Azure.An Azure service principal is an identity created for use with applications, hosted services, and automated tools to access Azure resources. Este acceso está restringido por los roles asignados a la entidad de servicio, lo que permite controlar a qué recursos pueden tener acceso y en qué nivel.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 seguridad, se recomienda usar siempre entidades de servicio con las herramientas automatizadas, en lugar de permitirles iniciar sesión con una identidad de usuario.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.

En este artículo se muestra los pasos para crear una entidad de servicio, obtener información sobre ella y restablecerla con la CLI de Azure.This article shows you the steps for creating, getting information about, and resetting a service principal with the Azure CLI.

Creación de una entidad de servicioCreate a service principal

Cree una entidad de servicio con el comando az ad sp create-for-rbac.Create a service principal with the az ad sp create-for-rbac command. Al crear una entidad de servicio, elija el tipo de autenticación de inicio de sesión que usa.When creating a service principal, you choose the type of sign-in authentication it uses.

Hay dos tipos de autenticación disponibles para las entidades de servicio: Autenticación basada en contraseña y autenticación basada en certificado.There are two types of authentication available for service principals: Password-based authentication, and certificate-based authentication.

Nota

Si su cuenta no tiene permisos suficientes para crear una entidad de servicio, az ad sp create-for-rbac devolverá un mensaje de error que contiene el texto "Privilegios insuficientes para completar la operación".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." Póngase en contacto con el administrador de Azure Active Directory para crear a una entidad de servicio.Contact your Azure Active Directory admin to create a service principal.

Advertencia

Cuando se crea una entidad de servicio mediante el comando az ad sp create-for-rbac, la salida incluye las credenciales que se deben proteger.When you create a service principal using the az ad sp create-for-rbac command, the output includes credentials that you must protect. Asegúrese de no incluir estas credenciales en el código ni en el control de código fuente.Be sure that you do not include these credentials in your code or check the credentials into your source control. Considere también la posibilidad de usar identidades administradas para evitar tener que usar credenciales.As an alternative, consider using managed identities if available to avoid the need to use credentials.

De forma predeterminada, az ad sp create-for-rbac asigna el rol Colaborador a la entidad de servicio en el ámbito de la suscripción.By default, az ad sp create-for-rbac assigns the Contributor role to the service principal at the subscription scope. Para reducir el riesgo de poner en peligro una entidad de servicio, asígnele un rol más específico y restrinja el ámbito a un recurso o a un grupo de recursos.To reduce your risk of a compromised service principal, assign a more specific role and narrow the scope to a resource or resource group. Para obtener más información, consulte Pasos para agregar una asignación de roles.See Steps to add a role assignment for more information.

En una versión futura, az ad sp create-for-rbac no creará una asignación de roles Colaborador de forma predeterminada.In a future release, az ad sp create-for-rbac will NOT create a Contributor role assignment by default. Si es necesario, utilice el argumento --role para crear explícitamente una asignación de roles.If needed, use the --role argument to explicitly create a role assignment.

Autenticación basada en contraseñaPassword-based authentication

La autenticación basada en contraseña no tiene ningún parámetro de autenticación y se usa con una contraseña aleatoria que se crea automáticamente.Without any authentication parameters, password-based authentication is used with a random password created for you.

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

Importante

A partir de la CLI de Azure 2.0.68, ya no se admite el parámetro --password para crear una entidad de servicio con una contraseña definida por el usuario, para impedir el uso accidental de contraseñas no seguras.As of Azure CLI 2.0.68, the --password parameter to create a service principal with a user-defined password is no longer supported to prevent the accidental use of weak passwords.

La salida para una entidad de servicio con autenticación por contraseña incluye la clave password.The output for a service principal with password authentication includes the password key. No olvide copiar este valor porque no se puede recuperar.Make sure you copy this value - it can't be retrieved. Si olvida la contraseña, restablezca las credenciales de la entidad de servicio.If you forget the password, reset the service principal credentials.

Las claves appId y tenant se muestran en la salida de az ad sp create-for-rbac y se usan en la autenticación de la entidad de servicio.The appId and tenant keys appear in the output of az ad sp create-for-rbac and are used in service principal authentication. Anote sus valores, aunque se pueden recuperar en cualquier momento con az ad sp list.Record their values, but they can be retrieved at any point with az ad sp list.

Autenticación basada en certificadosCertificate-based authentication

Para la autenticación basada en certificado, use el argumento --cert.For certificate-based authentication, use the --cert argument. Este argumento requiere que tenga un certificado.This argument requires that you hold an existing certificate. Asegúrese de que todas las herramientas que usan esta entidad de servicio tienen acceso a la clave privada del certificado.Make sure any tool that uses this service principal has access to the certificate's private key. Los certificados deben estar en formato ASCII, como PEM, CER o DER.Certificates should be in an ASCII format such as PEM, CER, or DER. Pase el certificado como una cadena o use el formato @path para cargar el certificado desde un archivo.Pass the certificate as a string, or use the @path format to load the certificate from a file.

Nota

Cuando se usa un archivo PEM, se debe anexar un valor de CERTIFICATE a PRIVATE KEY en el archivo.When using a PEM file, the CERTIFICATE must be appended to the PRIVATE KEY within the 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

Se puede agregar el argumento --keyvault para usar un certificado de Azure Key Vault.The --keyvault argument can be added to use a certificate in Azure Key Vault. En este caso, el valor --cert es el nombre del 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 crear un certificado autofirmado para la autenticación, use el 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

Salida de la consola:Console output:

Creating a role assignment under the scope of "/subscriptions/myId"
Please copy C:\myPath\myNewFile.pem to a safe place.
When you run 'az login', provide the file path in the --password argument
{
  "appId": "myAppId",
  "displayName": "myDisplayName",
  "fileWithCertAndPrivateKey": "C:\\myPath\\myNewFile.pem",
  "name": "http://myName",
  "password": null,
  "tenant": "myTenantId"
}

Contenido del nuevo archivo PEM:Contents of the new PEM file:

-----BEGIN PRIVATE KEY-----
myPrivateKeyValue
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
myCertificateValue
-----END CERTIFICATE-----

Nota

El comando az ad sp create-for-rbac --create-cert crea la entidad de servicio y un archivo PEM.The az ad sp create-for-rbac --create-cert command creates the service principal and a PEM file. El archivo PEM contiene los valores de PRIVATE KEY y CERTIFICATE con el formato correcto.The PEM file contains a correctly formatted PRIVATE KEY and CERTIFICATE.

Se puede agregar el argumento --keyvault para almacenar el certificado en Azure Key Vault.The --keyvault argument can be added to store the certificate in Azure Key Vault. Cuando se usa --keyvault, el argumento --cert también es necesario.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 almacene el certificado en Key Vault, la salida incluirá la clave fileWithCertAndPrivateKey.Unless you store the certificate in Key Vault, the output includes the fileWithCertAndPrivateKey key. Este valor de clave indica donde está almacenado el certificado generado.This key's value tells you where the generated certificate is stored. No olvide copiar el certificado en una ubicación segura o no podrá iniciar sesión con esta entidad de servicio.Make sure that you copy the certificate to a secure location, or you can't sign in with this service principal.

En el caso de los certificados almacenados en Key Vault, puede recuperar la clave privada del certificado con az keyvault secret show.For certificates stored in Key Vault, retrieve the certificate's private key with az keyvault secret show. En Key Vault, el nombre del secreto del certificado es el mismo que el nombre del certificado.In Key Vault, the name of the certificate's secret is the same as the certificate name. Si pierde el acceso a la clave privada de un certificado, restablezca las credenciales de la entidad de servicio.If you lose access to a certificate's private key, reset the service principal credentials.

Las claves appId y tenant se muestran en la salida de az ad sp create-for-rbac y se usan en la autenticación de la entidad de servicio.The appId and tenant keys appear in the output of az ad sp create-for-rbac and are used in service principal authentication. Anote sus valores, aunque se pueden recuperar en cualquier momento con az ad sp list.Record their values, but they can be retrieved at any point with az ad sp list.

Recuperación de una entidad de servicio existenteGet an existing service principal

Para obtener una lista de las entidades de servicio de un inquilino, use az ad sp list.A list of the service principals in a tenant can be retrieved with az ad sp list. De forma predeterminada, este comando devuelve las primeras 100 entidades de servicio del inquilino.By default this command returns the first 100 service principals for your tenant. Para obtener todas las entidades de servicio del inquilino, use el argumento --all.To get all of a tenant's service principals, use the --all argument. Generar esta lista puede tardar tiempo, por lo que se recomienda filtrarla con uno de los argumentos siguientes: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 solicita las entidades de servicio que tengan un prefijo que coincida con el nombre proporcionado.--display-name requests service principals that have a prefix that match the provided name. El nombre para mostrar de una entidad de servicio es el valor que se establece con el parámetro --name durante la creación.The display name of a service principal is the value set with the --name parameter during creation. Si no ha configurado --name durante la creación de la entidad de servicio, el prefijo del nombre es azure-cli-.If you didn't set --name during service principal creation, the name prefix is azure-cli-.
  • --spn filtra por los nombres de entidad de servicio que coincidan exactamente.--spn filters on exact service principal name matching. El nombre de la entidad de servicio siempre empieza con https://.The service principal name always starts with https://. Si el valor utilizado para --name no era un URI, este valor https://, seguido por el nombre para mostrar.if the value you used for --name wasn't a URI, this value is https:// followed by the display name.
  • --show-mine solicita solo las entidades de servicio creadas por el usuario que ha iniciado sesión.--show-mine requests only service principals created by the signed-in user.
  • --filter toma un filtro OData y filtra en el lado del servidor.--filter takes an OData filter, and performs server-side filtering. Se recomienda este método frente al filtrado en el lado del cliente con el argumento --query de la CLI.This method is recommended over filtering client-side with the CLI's --query argument. Para más información acerca de los filtros OData, consulte la sintaxis de expresiones OData para filtros.To learn about OData filters, see OData expression syntax for filters.

La información que se devuelve para los objetos de entidad de servicio es detallada.The information returned for service principal objects is verbose. Para obtener solo la información necesaria para iniciar sesión, use la cadena de consulta [].{id:appId, tenant:appOwnerTenantId}.To get only the information necessary for sign-in, use the query string [].{id:appId, tenant:appOwnerTenantId}. Por ejemplo, para obtener la información de inicio de sesión de todas las entidades de servicio creadas por el usuario que haya iniciado la sesión actual: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 o az ad sp show obtienen el usuario y el inquilino, pero no los secretos de autenticación ni el método de autenticación.az ad sp list or az ad sp show get the user and tenant, but not any authentication secrets or the authentication method. Los secretos de los certificados de Key Vault se pueden recuperar con az keyvault secret show, pero no otros secretos que se almacenen de forma predeterminada.Secrets for certificates in Key Vault can be retrieved with az keyvault secret show, but no other secrets are stored by default. Si olvida un método de autenticación o un secreto, restablezca las credenciales de la entidad de servicio.If you forget an authentication method or secret, reset the service principal credentials.

Administración de roles de la entidad de servicioManage service principal roles

La CLI de Azure tiene los siguientes comandos para administrar las asignaciones de roles.The Azure CLI has the following commands to manage role assignments:

El rol predeterminado de una entidad de servicio es colaborador.The default role for a service principal is Contributor. Este rol tiene permiso total para leer y escribir en una cuenta de Azure.This role has full permissions to read and write to an Azure account. El rol Lector es más restrictivo y proporciona acceso de solo lectura.The Reader role is more restrictive, with read-only access. Para más información sobre el control de acceso basado en rol (RBAC), consulte RBAC: roles integrados.For more information on Role-Based Access Control (RBAC) and roles, see RBAC: Built-in roles.

En este ejemplo se agrega el rol Lector y se elimina el rol 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

Nota

Si su cuenta no tiene permisos para asignar un rol, verá un mensaje de error indicando que su cuenta "no tiene autorización para realizar la acción Microsoft.Authorization/roleAssignments/write". Póngase en contacto con el administrador de Azure Active Directory para administrar los roles.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.

Agregar un rol no restringe los permisos asignados previamente.Adding a role doesn't restrict previously assigned permissions. Al restringir los permisos de una entidad de servicio, el rol Colaborador se debe eliminar.When restricting a service principal's permissions, the Contributor role should be removed.

Para comprobar los cambios, puede obtener una lista de los roles asignados:The changes can be verified by listing the assigned roles:

az role assignment list --assignee APP_ID

Inicio de sesión mediante una entidad de servicioSign in using a service principal

Para probar las credenciales y los permisos de la nueva entidad de servicio, inicie sesión.Test the new service principal's credentials and permissions by signing in. Para iniciar sesión con una entidad de servicio, necesita los valores de appId, tenant y las credenciales.To sign in with a service principal, you need the appId, tenant, and credentials.

Para iniciar sesión con una entidad de servicio con una contraseña:To sign in with a service principal using a password:

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

Para iniciar sesión con un certificado, debe estar disponible localmente en un archivo PEM o DER, en formato ASCII.To sign in with a certificate, it must be available locally as a PEM or DER file, in ASCII format. Cuando se usa un archivo PEM, se deben anexar los valores de CERTIFICATE y PRIVATE KEY en el archivo.When using a PEM file, the PRIVATE KEY and CERTIFICATE must be appended together within the file.

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

Para más información acerca de inicio de sesión con una entidad de servicio, consulte Inicio de sesión con la CLI de Azure.To learn more about signing in with a service principal, see Sign in with the Azure CLI.

Creación de un recurso mediante una entidad de servicioCreate a resource using service principal

En la sección siguiente se proporciona un ejemplo de cómo crear un recurso para Azure Storage con una entidad de servicio, mediante los siguientes comandos:The following section provides an example of how to create an resource for Azure Storage with a service principal, using the following commands:

Para iniciar sesión con una entidad de servicio, necesita los valores de appId, tenant y password devueltos como respuesta al crear la entidad de servicio.To sign in with a service principal, you need the appId, tenant, and password returned as the response when you created your service principal.

  1. Inicie sesión como la entidad de servicio.Log in as the service principal.

    az login --service-principal --username APP_ID --password PASSWORD --tenant TENANT_ID
    
  2. Cree un grupo de recursos que contenga todos los recursos utilizados para el mismo inicio rápido, tutorial o proyecto de desarrollo.Create a resource group to hold all resources used for the same quickstart, tutorial, or development project.

    az group create --location WESTUS --name MY_RESOURCE_GROUP
    
  3. Cree un recurso para un servicio de Azure.Create a resource to an Azure service. Reemplace <SERVICENAME> por el nombre del servicio de Azure.Replace <SERVICENAME> with the name of the Azure service.

    Para Azure Storage, los valores válidos para el parámetro <KIND> son:For Azure Storage, valid values for the <KIND> parameter are:

    • BlobStorageBlobStorage
    • BlockBlobStorageBlockBlobStorage
    • FileStorageFileStorage
    • StorageStorage
    • StorageV2StorageV2
    az storage account create --name MY_RESOURCE_<SERVICENAME> --resource-group MY_RESOURCE_GROUP --kind <KIND> --sku F0 --location WESTUS --yes
    
  4. Obtenga las claves de recurso del nuevo recurso, que se usa en el código para autenticarse en el servicio de Azure.Get resource keys for the new resource, which you use in your code to authenticate to the Azure service.

    az storage account keys list --name MY_RESOURCE_<SERVICENAME> --resource-group MY_RESOURCE_GROUP
    

Restablecimiento de las credencialesReset credentials

Si olvida las credenciales de una entidad de servicio, utilice az ad sp credential reset.If you forget the credentials for a service principal, use az ad sp credential reset. El comando reset toma los mismos 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

Vea tambiénSee also