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

  • Artículo
  • Tiempo de lectura: 8 minutos

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.

Advertencia

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.

De forma predeterminada, New-AzADServicePrincipal asigna el rol Colaborador a la entidad de servicio en el ámbito de la suscripción. 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. Para obtener más información, consulte Pasos para agregar una asignación de roles.

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.

Nota

Si su cuenta no tiene permisos suficientes para crear una entidad de servicio, New-AzADServicePrincipal 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.

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

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 contiene el miembro Secret, que es un SecureString 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 permitirá exportar el secreto:

$BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($sp.Secret)
$UnsecureSecret = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)

Para las contraseñas proporcionadas por el usuario, el parámetro PasswordCredential toma objetos Microsoft.Azure.Commands.ActiveDirectory.PSADPasswordCredential. Estos objetos deben tener valores StartDate y EndDate válidos, y tomar Password en texto sin formato. Al crear una contraseña, asegúrese de que seguir las reglas y restricciones de contraseñas de Azure Active Directory. No use una contraseña débil ni reutilice las contraseñas.

Import-Module -Name Az.Resources # Imports the PSADPasswordCredential object
$credentials = New-Object Microsoft.Azure.Commands.ActiveDirectory.PSADPasswordCredential -Property @{StartDate=Get-Date; EndDate=Get-Date -Year 2024; Password=<Choose a strong password>}
$sp = New-AzAdServicePrincipal -DisplayName ServicePrincipalName -PasswordCredential $credentials

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

También puede usar el parámetro KeyCredential, que toma objetos PSADKeyCredential. Estos objetos deben tener un valor StartDate válido, EndDate y el miembro CertValue establecido en una cadena ASCII codificada en base64 del certificado público.

$cert = <public certificate as base64-encoded string>
$credentials = New-Object -TypeName Microsoft.Azure.Commands.ActiveDirectory.PSADKeyCredential -Property @{StartDate=Get-Date; EndDate=Get-Date -Year 2024; KeyId=New-Guid; CertValue=$cert}
$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName -KeyCredential $credentials

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

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. 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 roles (RBAC) y los roles, consulte RBAC: roles integrados.

En este ejemplo 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 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.

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 más instrucciones sobre cómo importar un certificado a un almacén de credenciales al que PowerShell tenga acceso, consulte Inicio de sesión con Azure PowerShell.

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 si 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 ejemplo siguiente para comprobar que no exista una aplicación de Azure Active Directory 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.