Creación de una entidad de servicio de Azure con la CLI de Azure

Las herramientas automatizadas que usan los servicios de Azure deberán tener siempre permisos restringidos. En lugar de que las aplicaciones inicien sesión como un usuario con privilegios totales, Azure ofrece las entidades de servicio.

Qué es una entidad de servicio de Azure

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

En este artículo, se muestran los pasos para crear una entidad de servicio de Azure, obtener información sobre ella y restablecerla con la CLI de Azure.

1. Creación de una entidad de servicio

Cree una entidad de servicio de Azure con el comando az ad sp create-for-rbac.

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. Anote sus valores, aunque se pueden recuperar en cualquier momento con az ad sp list.

Al crear una entidad de servicio, elija el tipo de autenticación de inicio de sesión que usa. Hay dos tipos de autenticación disponibles para las entidades de servicio de Azure: autenticación basada en contraseña y autenticación basada en certificados.

Advertencia

Cuando se crea una entidad de servicio de Azure mediante el comando az ad sp create-for-rbac, la salida incluye las credenciales que se deben proteger. Asegúrese de no incluir estas credenciales en el código ni en el control de código fuente. Considere también la posibilidad de usar identidades administradas para evitar tener que usar credenciales.

Para reducir el riesgo de poner en peligro una entidad de servicio, asígnele un rol más específico y restrinja los ámbitos a un recurso o a un grupo de recursos. Para obtener más información, consulte Pasos para agregar una asignación de roles.

Autenticación basada en contraseña

Con la autenticación basada en contraseñas, se crea automáticamente una contraseña aleatoria. Si no especifica un valor para el parámetro --name, se creará automáticamente un nombre que contenga una marca de tiempo. Debe especificar un --scopes ya que este valor no tiene un valor predeterminado. Si lo prefiere, puede establecer la asignación de roles más adelante mediante az role assignment create.

# Create a service principal with required parameter
az ad sp create-for-rbac --scopes /subscriptions/mySubscriptionID

# Create a service principal for a resource group using a preferred name and role
az ad sp create-for-rbac --name myServicePrincipalName \
                         --role reader \
                         --scopes /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName

También puede crear una entidad de servicio mediante variables.

let "randomIdentifier=$RANDOM*$RANDOM"  
servicePrincipalName="msdocs-sp-$randomIdentifier"
roleName="azureRoleName"
subscriptionID=$(az account show --query id -o tsv)
# Verify the ID of the active subscription
echo "Using subscription ID $subscriptionID"
resourceGroup="myResourceGroupName"

echo "Creating SP for RBAC with name $servicePrincipalName, with role $roleName and in scopes /subscriptions/$subscriptionID/resourceGroups/$resourceGroup"
az ad sp create-for-rbac --name $servicePrincipalName --role $roleName --scopes /subscriptions/$subscriptionID/resourceGroups/$resourceGroup

La salida para una entidad de servicio con autenticación por contraseña incluye la clave password. No olvide copiar este valor porque no se puede recuperar. Si pierde la contraseña, restablezca las credenciales de la entidad de servicio.

Autenticación basada en certificados

Para la autenticación basada en certificado, use el parámetro --cert. Este parámetro requiere que tenga un certificado existente. Asegúrese de que todas las herramientas que usan esta entidad de servicio tienen acceso a la clave privada del certificado. Los certificados deben estar en formato ASCII, como PEM, CER o DER. Pase el certificado como una cadena o use el formato @path para cargar el certificado desde un archivo.

Nota

Cuando se usa un archivo PEM, se debe anexar un valor de CERTIFICATE a PRIVATE KEY en el archivo.

az ad sp create-for-rbac --name myServicePrincipalName \
                         --role roleName \
                         --scopes /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName \
                         --cert "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
az ad sp create-for-rbac --name myServicePrincipalName \
                         --role roleName \
                         --scopes /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName \
                         --cert @/path/to/cert.pem

Se puede agregar el parámetro --keyvault para usar un certificado de Azure Key Vault. En este caso, el valor --cert es el nombre del certificado.

az ad sp create-for-rbac --name myServicePrincipalName \
                         --role roleName \
                         --scopes /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName \
                         --cert certificateName \
                         --keyvault vaultName

Para crear un certificado autofirmado para la autenticación, use el parámetro --create-cert:

az ad sp create-for-rbac --name myServicePrincipalName \
                         --role roleName \
                         --scopes /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName \
                         --create-cert

Salida de la consola:

Creating a role assignment under the scopes 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 parameter
{
  "appId": "myAppId",
  "displayName": "myDisplayName",
  "fileWithCertAndPrivateKey": "C:\\myPath\\myNewFile.pem",
  "name": "http://myName",
  "password": null,
  "tenant": "myTenantId"
}

Contenido del nuevo archivo PEM:

-----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. El archivo PEM contiene los valores de PRIVATE KEY y CERTIFICATE con el formato correcto.

Se puede agregar el parámetro --keyvault para almacenar el certificado en Azure Key Vault. Cuando se usa --keyvault, el parámetro --cert es obligatorio.

az ad sp create-for-rbac --name myServicePrincipalName \
                         --role roleName \
                         --scopes /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName \
                         --create-cert \
                         --cert certificateName \
                         --keyvault vaultName

A menos que almacene el certificado en Key Vault, la salida incluirá la clave fileWithCertAndPrivateKey. Este valor de clave indica donde está almacenado el certificado generado. No olvide copiar el certificado en una ubicación segura o no podrá iniciar sesión con esta entidad de servicio.

Si pierde el acceso a la clave privada de un certificado, restablezca las credenciales de la entidad de servicio.

Recuperación de certificado desde Key Vault

En el caso del certificado almacenado en Key Vault, recupere el certificado con su clave privada del certificado con az keyvault secret show y conviértalo en un archivo PEM. En Key Vault, el nombre del secreto del certificado es el mismo que el nombre del certificado.

az keyvault secret download --file /path/to/cert.pfx --vault-name VaultName --name CertName --encoding base64
openssl pkcs12 -in cert.pfx -passin pass: -out cert.pem -nodes

2. Recuperación de una entidad de servicio existente

Para obtener una lista de las entidades de servicio de un inquilino, use az ad sp list. De forma predeterminada, este comando devuelve las primeras 100 entidades de servicio del inquilino. Para obtener todas las entidades de servicio del inquilino, use el parámetro --all. Generar esta lista puede tardar tiempo, por lo que se recomienda filtrarla con uno de los parámetros siguientes:

  • --display-name solicita las entidades de servicio que tengan un prefijo que coincida con el nombre proporcionado. El nombre para mostrar de una entidad de servicio es el valor que se establece con el parámetro --name durante la creación. Si no ha configurado --name durante la creación de la entidad de servicio, el prefijo del nombre es azure-cli-.
  • --spn filtra por los nombres de entidad de servicio que coincidan exactamente. El nombre de la entidad de servicio siempre empieza con https://. Si el valor utilizado para --name no era un URI, este valor https://, seguido por el nombre para mostrar.
  • --show-mine solicita solo las entidades de servicio creadas por el usuario que ha iniciado sesión.
  • --filter toma un filtro OData y filtra en el lado del servidor. Se recomienda este método frente al filtrado en el lado del cliente con el parámetro --query de la CLI. Para más información acerca de los filtros OData, consulte la sintaxis de expresiones OData para filtros.

La información que se devuelve para los objetos de entidad de servicio es detallada. Para obtener solo la información necesaria para iniciar sesión, use la cadena de consulta [].{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:

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. 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. Si olvida un método de autenticación o un secreto, restablezca las credenciales de la entidad de servicio.

3. Administración de roles de una entidad de servicio

La CLI de Azure tiene los siguientes comandos para administrar las asignaciones de roles.

El rol Colaborador tiene permisos completos para leer y escribir en una cuenta de Azure. El rol Lector es más restrictivo y proporciona acceso de solo lectura. Para más información sobre el control de acceso basado en rol (RBAC), consulte RBAC: roles integrados.

En este ejemplo se agrega el rol Lector y se elimina el rol Colaborador:

az role assignment create --assignee appID \
                          --role Reader \
                          --scope /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName

az role assignment delete --assignee appID \
                          --role Contributor \
                          --scope /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName

Agregar un rol no restringe los permisos asignados previamente. Al restringir los permisos de una entidad de servicio, el rol Colaborador se debe eliminar si se asignó anteriormente.

Para comprobar los cambios, puede obtener una lista de los roles asignados:

az role assignment list --assignee appID

4. Inicio de sesión mediante una entidad de servicio

Para probar las credenciales y los permisos de la nueva entidad de servicio, inicie sesión. Para iniciar sesión con una entidad de servicio, necesita los valores de appId, tenant y las credenciales.

Para iniciar sesión con una entidad de servicio con una contraseña:

az login --service-principal --username appID --password PASSWORD --tenant tenantID

Para iniciar sesión con un certificado, debe estar disponible localmente en un archivo PEM o DER, en formato ASCII. Cuando se usa un archivo PEM, se deben anexar los valores de CERTIFICATE y PRIVATE KEY en el archivo.

az login --service-principal --username appID --tenant tenantID --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.

5. Creación de un recurso mediante una entidad de servicio

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:

Para iniciar sesión con una entidad de servicio, necesita los valores de appID, tenantID y password devueltos como respuesta al crear la entidad de servicio.

  1. Inicie sesión como la entidad de servicio.

    az login --service-principal --username appID --password PASSWORD --tenant tenantID
    
  2. Cree un grupo de recursos que contenga todos los recursos utilizados para el mismo inicio rápido, tutorial o proyecto de desarrollo.

    az group create --location westus --name myResourceGroupName
    
  3. Cree una cuenta de almacenamiento.

    Para Azure Storage, los valores válidos para el parámetro <KIND> son:

    • BlobStorage
    • BlockBlobStorage
    • FileStorage
    • Storage
    • StorageV2
    az storage account create --name myStorageAccountName --resource-group myResourceGroupName --kind <KIND> --sku F0 --location westus --yes
    
  4. Obtenga las claves de recursos, las que usa en el código para autenticarse en la cuenta de Azure Storage.

    az storage account keys list --name myStorageAccountName --resource-group myResourceGroupName
    

6. Restablecimiento de credenciales

Si pierde las credenciales de una entidad de servicio, utilice az ad sp credential reset. El comando reset toma los mismos parámetros que az ad sp create-for-rbac.

az ad sp credential reset --name myServicePrincipal_appID_or_name

7. Solución de problemas

Privilegios insuficientes

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". Póngase en contacto con el administrador de Azure Active Directory para crear a una entidad de servicio.

Inquilino no válido

Si ha especificado un identificador de suscripción no válido, aparecerá el mensaje de error "La solicitud no tenía una suscripción o un proveedor de recursos de nivel de inquilino válido". Si usa variables, use el comando echo de Bash para ver el valor que se pasa al comando de referencia. Use az account set para cambiar la suscripción o consulte Administración de suscripciones de Azure con la CLI de Azure.

Grupo de recursos no encontrado

Si ha especificado un nombre de grupo de recursos no válido, verá el mensaje de error "No se encontró el grupo de recursos "name"." Si usa variables, use el comando echo de Bash para ver el valor que se pasa a la suscripción y a los comandos de referencia. Use az group list para ver los grupos de recursos de la suscripción actual o consulte Administración de grupos de recursos de Azure con la CLI de Azure.

Autorización para realizar una acción

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.

Vea también