Creación de una entidad de servicio de Azure con Azure PowerShell

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.

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 muestra los pasos para crear una entidad de servicio, obtener información sobre ella y restablecerla con Azure PowerShell.

Precaución

Cuando se crea una entidad de servicio mediante el comando New-AzADServicePrincipal, la salida incluye las credenciales que se deben proteger. Como alternativa, considere la posibilidad de usar identidades administradas para evitar tener que usar credenciales.

Requisitos previos

Creación de una entidad de servicio

Cree una entidad de servicio con el cmdlet New-AzADServicePrincipal. Al crear una entidad de servicio, elija el tipo de autenticación de inicio de sesión que usa.

Importante

A partir de la versión 7.x del módulo de Az PowerShell, New-AzADServicePrincipal ya no asigna el rol colaborador a la entidad de servicio de forma predeterminada. Para asignar un rol específico a una entidad de servicio, consulte Pasos para agregar una asignación de roles.

Nota

Si su cuenta no tiene permisos suficientes para crear una entidad de servicio, New-AzADServicePrincipal devuelve un mensaje de error que contiene el texto "Privilegios insuficientes para completar la operación". Póngase en contacto con el administrador de Microsoft Entra para crear una entidad de servicio.

En un directorio de Microsoft Entra ID donde la configuración de usuario Los usuarios pueden registrar aplicaciones se ha establecido en No, debe ser miembro de uno de los siguientes roles integrados de Microsoft Entra ID (que tienen la acción: microsoft.directory/applications/createAsOwner o microsoft.directory/applications/create):

Para obtener más información sobre la configuración de usuario en Microsoft Entra ID, consulte Restringir quién puede crear aplicaciones.

Hay dos tipos de autenticación disponibles para las entidades de servicio: Autenticación basada en contraseña y autenticación basada en certificado.

Autenticación basada en contraseña

Importante

El rol predeterminado de una entidad de servicio de autenticación basada en contraseña es Colaborador. Este rol tiene permiso total para leer y escribir en una cuenta de Azure. Para más información sobre cómo administrar las asignaciones de roles, consulte Administración de roles de la entidad de servicio.

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. Si desea usar la autenticación basada en contraseña, se recomienda este método.

$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName

El objeto devuelto incluye la propiedad PasswordCredentials.SecretText, que contiene la contraseña generada. Asegúrese de que guarda este valor en algún lugar seguro para autenticar con la entidad de servicio. Su valor no se muestra en la salida de consola. Si pierde la contraseña, restablezca las credenciales de la entidad de servicio.

El código siguiente le permite exportar el secreto:

$sp.PasswordCredentials.SecretText

El objeto devuelto desde New-AzADServicePrincipal contiene los miembros Id y DisplayName, que se pueden usar para iniciar sesión con la entidad de servicio.

Importante

Iniciar sesión con una entidad de servicio requiere el identificador del inquilino con el que se ha creado la entidad de servicio. Para obtener el inquilino que estaba activo cuando se creó la entidad de servicio, ejecute el siguiente comando inmediatamente después de crear la entidad de servicio:

(Get-AzContext).Tenant.Id

Autenticación basada en certificados

Importante

No se asigna ningún rol predeterminado al crear una entidad de servicio de autenticación basada en certificado. Para más información sobre cómo administrar las asignaciones de roles, consulte Administración de roles de la entidad de servicio.

Las entidades de servicio que usan autenticación basada en certificado se crean con el parámetro CertValue. Este parámetro toma una cadena ASCII codificada en base64 del certificado público. Esto se representa mediante un archivo PEM, o CRT o CER codificado por texto. No se admiten codificaciones binarias del certificado público. En estas instrucciones se da por hecho que ya tiene un certificado disponible.

$cert = <public certificate as base64-encoded string>
$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName -CertValue $cert

El objeto devuelto desde New-AzADServicePrincipal contiene las propiedades Id y DisplayName, que se pueden usar para iniciar sesión con la entidad de servicio. Los clientes que inicien sesión con la entidad de servicio también necesitan acceso a la clave privada del certificado.

Importante

Iniciar sesión con una entidad de servicio requiere el identificador del inquilino con el que se ha creado la entidad de servicio. Para obtener el inquilino que estaba activo cuando se creó la entidad de servicio, ejecute el siguiente comando inmediatamente después de crear la entidad de servicio:

(Get-AzContext).Tenant.Id

Recuperación de una entidad de servicio existente

Se puede recuperar una lista de las entidades de servicio del inquilino activo con Get-AzADServicePrincipal. De forma predeterminada, este comando devuelve todas las entidades de servicio del inquilino. En organizaciones de gran tamaño, es posible que tarde mucho tiempo en devolver resultados. En su lugar, se recomienda usar uno de los argumentos de servidor opcionales de filtrado:

  • DisplayNameBeginsWith solicita las entidades de servicio que tengan un prefijo que coincida con el valor proporcionado. El nombre para mostrar de una entidad de servicio es el valor que se establece con DisplayName durante la creación.
  • DisplayName solicita la coincidencia exacta del nombre de la entidad de servicio.

Administración de roles de la entidad de servicio

Azure PowerShell tiene los siguientes cmdlets para administrar las asignaciones de roles:

Para más información sobre el control de acceso basado en rol (RBAC), consulte RBAC: roles integrados.

En el ejemplo siguiente, se agrega el rol Lector y se elimina el rol Colaborador:

New-AzRoleAssignment -ApplicationId <service principal application ID> -RoleDefinitionName 'Reader'
Remove-AzRoleAssignment -ObjectId <service principal object ID> -RoleDefinitionName 'Contributor'

Importante

Los cmdlets de asignación de roles no toman el identificador de objeto de la entidad de servicio. Toman el identificador de aplicación asociado, que se genera en tiempo de creación. Para obtener el identificador de aplicación de una entidad de servicio, use Get-AzADServicePrincipal.

Nota

Si su cuenta no tiene permisos para asignar un rol, verá un mensaje de error en el que se indica que su cuenta "no tiene autorización para realizar la acción Microsoft.Authorization/roleAssignments/write". Póngase en contacto con el administrador de Microsoft Entra para administrar roles.

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

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

Get-AzRoleAssignment -ServicePrincipalName ServicePrincipalName

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 el valor de applicationId asociado a ella, y el inquilino en el que se creó.

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

# Use the application ID as the username, and the secret as password
$credentials = Get-Credential
Connect-AzAccount -ServicePrincipal -Credential $credentials -Tenant <tenant ID>

La autenticación basada en certificados requiere que Azure PowerShell pueda recuperar información de un almacén de certificados local en función de una huella digital del certificado.

Connect-AzAccount -ServicePrincipal -Tenant <TenantId> -CertificateThumbprint <Thumbprint> -ApplicationId <ApplicationId>

Para obtener instrucciones sobre cómo importar un certificado en un almacén de credenciales accesible mediante PowerShell, consulte autenticación basada en certificados

Restablecimiento de las credenciales

Si olvida las credenciales de una entidad de servicio, utilice New-AzADSpCredential para agregar unas credenciales nuevas con una contraseña aleatoria. Este cmdlet no admite credenciales definidas por el usuario al restablecer la contraseña.

Importante

Antes de asignar las nuevas credenciales, quizás quiera quitar las credenciales existentes para evitar que se inicie sesión con ellas. Para ello, utilice el cmdlet Remove-AzADSpCredential:

Remove-AzADSpCredential -DisplayName ServicePrincipalName
$newCredential = New-AzADSpCredential -ServicePrincipalName ServicePrincipalName

Solución de problemas

Si recibe el error: "New-AzADServicePrincipal: Ya existe otro objeto con el mismo valor para la propiedad identifierUris" , compruebe que ya existe una entidad de servicio con el mismo nombre.

Get-AzAdServicePrincipal -DisplayName ServicePrincipalName

Si ya no se necesita la entidad de servicio existente, puede quitarla con el ejemplo siguiente.

Remove-AzAdServicePrincipal -DisplayName ServicePrincipalName

Este error también puede producirse cuando se ha creado previamente una entidad de servicio para una aplicación de Azure Active Directory. Si quita la entidad de servicio, la aplicación sigue estando disponible. Esta aplicación evita que cree otra entidad de servicio con el mismo nombre.

Puede usar el siguiente ejemplo para comprobar que no exista una aplicación de Microsoft Entra con el mismo nombre:

Get-AzADApplication -DisplayName ServicePrincipalName

Si existe una aplicación con el mismo nombre y ya no es necesaria, se puede quitar con el ejemplo siguiente.

Remove-AzADApplication -DisplayName ServicePrincipalName

De lo contrario, elija otro nombre para la nueva entidad de servicio que está intentando crear.