Compartir a través de

Uso de entidades de servicio e identidades administradas en Azure DevOps

  • Artículo

Azure DevOps Services

Nota:

Azure Active Directory (Azure AD) ahora es el identificador de Microsoft Entra. Para obtener más información, consulte Nuevo nombre para Azure AD.

Agregue entidades de servicio e identidades administradas Microsoft Entra como identidades de aplicación a las organizaciones de Azure DevOps Services para concederles acceso a los recursos de la organización. Para muchos equipos, esta característica puede ser una alternativa viable y preferida a los tokens de acceso personal (PAT) al autenticar las aplicaciones que impulsan los flujos de trabajo de automatización de la empresa.

Acerca de las entidades de servicio e identidades administradas

Las entidades de servicio son objetos de seguridad dentro de una aplicación de Microsoft Entra que definen lo que una aplicación puede hacer en un inquilino determinado. Están configurados en el Azure Portal durante el proceso de registro de la aplicación y configurados para acceder a los recursos de Azure, como Azure DevOps. Al agregar entidades de servicio a su organización y configurar permisos sobre ellos, podemos determinar si una entidad de servicio está autorizada para acceder a los recursos de la organización y cuáles.

Las identidades administradas son otra característica de Microsoft Entra que actúa de forma similar a las entidades de servicio de una aplicación. Estos objetos proporcionan identidades para los recursos de Azure y permiten una manera sencilla de que los servicios que admiten la autenticación de Microsoft Entra compartan credenciales. Son una opción atractiva porque Microsoft Entra ID se encarga de la administración y rotación de credenciales. Aunque la configuración de una identidad administrada podría tener un aspecto diferente en Azure Portal, Azure DevOps trata ambos objetos de seguridad igual que una nueva identidad de aplicación en una organización con permisos definidos. En el resto de este artículo, nos referimos a identidades administradas y entidades de servicio indistintamente como entidad de servicio, a menos que se especifique.

Siga estos pasos para autenticar estas identidades en Azure DevOps para permitirles realizar acciones en nombre de sí mismas.

Configuración de identidades administradas y entidades de servicio

La implementación puede variar, pero en un nivel alto, los pasos siguientes le ayudarán a empezar a usar entidades de servicio en el flujo de trabajo. Para continuar, considere consultar una de nuestras aplicaciones de ejemplo.

1. Creación de una nueva identidad administrada o una entidad de servicio de aplicación

Cree una entidad de servicio de aplicación o una identidad administrada en el Azure Portal.

Opción 1: Crear un principal de servicio de aplicación

Al crear un nuevo registro de aplicación, se crea un objeto de aplicación en microsoft Entra ID. La entidad de servicio de la aplicación es una representación de este objeto de aplicación para un inquilino determinado. Al registrar una aplicación como una aplicación multiinquilino, hay un objeto de entidad de servicio único que representa el objeto de aplicación para cada inquilino al que se agrega la aplicación.

Información adicional:

Opción 2: Crear una entidad administrada

La creación de identidades administradas en la Azure Portal difiere significativamente de la configuración de aplicaciones con entidades de servicio. Antes de comenzar el proceso de creación, primero debe tener en cuenta qué tipo de identidad administrada desea crear:

  • Identidad administrada asignada por el sistema: Algunos servicios de Azure permiten habilitar una identidad administrada directamente en una instancia de servicio. Al habilitar una identidad administrada asignada por el sistema, se crea una identidad en Microsoft Entra ID. La identidad está vinculada al ciclo de vida de esa instancia de servicio. Por tanto, cuando se elimina el recurso, Azure elimina automáticamente la identidad. Por diseño, solo ese recurso de Azure puede usar esta identidad para solicitar tokens de Microsoft Entra ID.
  • Identidad administrada asignada por el usuario También puede crear una identidad administrada como un recurso de Azure independiente mediante la creación de una identidad administrada asignada por el usuario y asignarla a una o varias instancias de un servicio de Azure. En las identidades administradas asignadas por el usuario, la identidad se administra independientemente de los recursos que la utilicen.

Para obtener más información, consulte los siguientes artículos y vídeos:

2. Incorporación de una entidad de servicio a una organización de Azure DevOps

Una vez configuradas las entidades de servicio en el Centro de administración de Microsoft Entra, debe hacer lo mismo en Azure DevOps agregando las entidades de servicio a su organización. Puede agregarlos a través de la página Usuarios o con las API ServicePrincipalEntitlements. Puesto que no pueden iniciar sesión de forma interactiva, una cuenta de usuario que pueda agregar usuarios a una organización, un proyecto o un equipo debe agregarlos. Estos usuarios incluyen administradores de colecciones de proyectos (PCA) o administradores de proyectos y administradores de equipo cuando está habilitada la directiva "Permitir que los administradores de equipos y proyectos inviten a nuevos usuarios ".

Sugerencia

Para agregar una entidad de servicio a la organización, escriba el nombre para mostrar de la aplicación o la identidad administrada. Si decide agregar una entidad de servicio mediante programación a través de la API ServicePrincipalEntitlements, asegúrese de pasar el identificador de objeto de la entidad de servicio y no el identificador de objeto de la aplicación.

Si es un PCA, también puede conceder a una entidad de servicio acceso a proyectos específicos y asignar una licencia. Si no es un PCA, debe ponerse en contacto con el PCA para actualizar las pertenencias a proyectos o los niveles de acceso a licencias.

Captura de pantalla de las entidades de servicio y las identidades administradas en el Centro de usuarios.

Nota:

Solo puede agregar una identidad administrada o una entidad de servicio para el inquilino al que está conectada la organización. Las entidades de servicio se pueden hacer multiinquilino para acceder a varios inquilinos a la vez. Las identidades administradas solo pueden pertenecer a un solo inquilino. Para acceder a una identidad administrada en un inquilino diferente, consulte la solución alternativa en las preguntas más frecuentes.

3. Establecer permisos en una entidad de servicio

Una vez agregadas las entidades de servicio a la organización, puede tratarlas de forma similar a las cuentas de usuario estándar. Puede asignar permisos directamente en una entidad de servicio, agregarlos a grupos de seguridad y equipos, asignarlos a cualquier nivel de acceso y quitarlos de la organización. También puede usar Service Principal Graph APIs para realizar operaciones CRUD en entidades de servicio.

Establecer estos permisos puede diferir de cómo se usa para configurar los permisos de aplicación en una aplicación de Microsoft Entra para otros recursos de Azure. Azure DevOps no depende de la configuración "Permisos de aplicación" disponible para los registros de aplicaciones a través de Azure Portal. Estos permisos de aplicación se conceden a un principal de servicio para todas las organizaciones asociadas a un inquilino, sin tener conocimiento de los permisos de organización, proyecto u objeto disponibles en Azure DevOps. Para ofrecer a las entidades de servicio permisos más granulares, nos basamos en nuestro propio modelo de permisos en lugar de en identificadores de Entra de Microsoft.

4. Administrar una entidad de servicio

La administración de entidades de servicio difiere de las cuentas de usuario de las siguientes maneras clave:

  • Las entidades de servicio no tienen correos electrónicos y, como tal, no se pueden invitar a una organización por correo electrónico.
  • Actualmente, las reglas de grupo para las licencias no se aplican a las entidades de servicio. Si desea asignar un nivel de acceso a una entidad de servicio, es mejor hacerlo directamente.
  • Las entidades de servicio se pueden agregar a los grupos de Microsoft Entra (en Azure Portal). Actualmente existe una limitación técnica que impide que podamos mostrarlas en una lista de miembros del grupo de Microsoft Entra. Esta limitación no es cierta para los grupos de Azure DevOps. Dicho esto, una entidad de servicio todavía hereda los permisos de grupo establecidos sobre un grupo de Microsoft Entra al que pertenecen.
  • Los usuarios de un grupo de Microsoft Entra no forman parte de una organización de Azure DevOps inmediatamente porque un administrador crea un grupo y le agrega un grupo de Microsoft Entra. Tenemos un proceso denominado "materialización" que se produce una vez que un usuario de un grupo de Microsoft Entra inicia sesión en la organización por primera vez. Un usuario que inicia sesión en una organización nos permite determinar qué usuarios deben concederse una licencia. Dado que el inicio de sesión no es posible para las entidades de servicio, un administrador debe agregarlo explícitamente a una organización, como se ha descrito anteriormente.
  • No se puede modificar el nombre para mostrar de una entidad de servicio ni un avatar en Azure DevOps.
  • Las entidades de servicio obtienen licencias de cada organización a las que se agregan, incluso si se selecciona de facturación de varias organizaciones.

5. Obtener un token de ID de Microsoft Entra

(a) Adquirir un token de Microsoft Entra ID mediante programación

Para adquirir un token de acceso para una identidad administrada, siga la documentación de Microsoft Entra ID. Consulte los ejemplos de entidades de servicio e identidades administradas.

El token de acceso devuelto es un token web JSON (JWT) con los roles definidos, que se pueden usar para acceder a los recursos de la organización mediante el token como Portador.

(b) Adquirir un token de ID de Microsoft Entra con la CLI de Azure

En el caso de las operaciones ad hoc, es posible que sea más fácil adquirir un token de Microsoft Entra ID único a través de la CLI de Azure. Este enfoque es preferible para las operaciones que no necesitan un token persistente que se rote periódicamente, como las llamadas API o las operaciones de clonación de Git.

Requisitos previos

  • Identificador de inquilino e identificador de suscripción de Azure: asegúrese de que la suscripción está asociada al inquilino conectado a la organización de Azure DevOps a la que intenta acceder. Si no conoce el inquilino o el identificador de suscripción, puede encontrarlo en el Azure Portal.
  • Identificador de cliente y secreto de cliente de la aplicación de Azure
  • CLI de Azure

Estas instrucciones son proporcionadas por la documentación de Databricks y se pueden encontrar más detalles en su página.

  1. Inicie sesión en la CLI de Azure como entidad de servicio mediante el comando az devops login.
  2. Siga las instrucciones en pantalla y termine de iniciar sesión.
# To authenticate a service principal with a password or cert:
az login --service-principal -u <app-id> -p <password-or-cert> --tenant <tenant>

# To authenticate a managed identity:
az login --identity
  1. Para establecer la suscripción correcta para la entidad de servicio que ha iniciado sesión, escriba el comando:
az account set -s <subscription-id>
  1. Generar un token de acceso Microsoft Entra ID con el az account get-access-token ID de recurso Azure DevOps: 499b84ac-1321-427f-aa17-267ca6975798.
$accessToken = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv
  1. Ahora, puede usar az cli comandos por lo habitual. Vamos a intentar llamar a una API de Azure DevOps incluyendo en los encabezados un token Bearer:
$apiVersion = "7.1-preview.1"
$uri = "https://dev.azure.com/${yourOrgname}/_apis/projects?api-version=${apiVersion}"
$headers = @{
    Accept = "application/json"
    Authorization = "Bearer $accessToken"
}
Invoke-RestMethod -Uri $uri -Headers $headers -Method Get | Select-Object -ExpandProperty value ` | Select-Object id, name

Nota:

Use el identificador de aplicación de Azure DevOps, no nuestro URI de recursos, para generar tokens.

6. Usar el token de Microsoft Entra ID para autenticarse en los recursos de Azure DevOps

En el siguiente ejemplo de vídeo, pasamos de autenticarse con un PAT a usar un token de una entidad de servicio. Comenzamos con un secreto de cliente para la autenticación y, a continuación, pasamos a usar un certificado de cliente.

Otro ejemplo muestra cómo conectarse a Azure DevOps mediante una identidad administrada asignada por el usuario dentro de una función de Azure.

Para seguir estos ejemplos, busque el código de la aplicación en nuestra colección de aplicaciones de ejemplo.

Puede encontrar algunos escenarios comunes para la autenticación con entidades de servicio además de realizar llamadas a la API REST de Azure DevOps en estos documentos:

Diferencias entre las entidades de servicio y los usuarios

  • No se puede modificar el nombre para mostrar de una entidad de servicio ni un avatar en Azure DevOps.
  • Una entidad de servicio cuenta como una licencia para cada organización a la que se une, incluso con facturación de varias organizaciones.
  • Las entidades de servicio no pueden ser propietarios de la organización ni crear organizaciones.
  • Las entidades de servicio no pueden crear tokens, como tokens de acceso personal (PAT) o claves SSH. Pueden generar sus propios tokens de identificación de Microsoft Entra ID para llamar a las API REST de Azure DevOps.
  • Las entidades de servicio no admiten Azure DevOps OAuth.

Preguntas más frecuentes

P: ¿Por qué debo usar una entidad de servicio o una identidad administrada en lugar de un PAT?

R: Muchos de nuestros clientes buscan una entidad de servicio o una identidad administrada para reemplazar un PAT existente (token de acceso personal). Estas PAT suelen pertenecer a una cuenta de servicio (cuenta de equipo compartida) que las usa para autenticar una aplicación con recursos de Azure DevOps. Las PAT deben rotarse de forma laboriosa cada una de las veces (mínimo 180 días). Los PAT almacenados incorrectamente pueden caer en manos equivocadas, y su vida útil, que a menudo es más larga, puede durar. Los tokens de Microsoft Entra expiran cada hora, lo que limita el factor de riesgo general cuando se filtra. Para escenarios comunes de PAT, compartimos algunos ejemplos sobre cómo podría explorar usar un token de Microsoft Entra en su lugar.

No puede usar una entidad de servicio para crear un token de acceso personal.

P: ¿Cuáles son los límites de frecuencia en las entidades de servicio e identidades administradas?

R: Las entidades de servicio y las identidades administradas tienen los mismos límites de velocidad que los usuarios.

P: ¿El uso de esta característica costará más?

R: Las entidades de servicio y las identidades administradas tienen un precio similar al de los usuarios, en función del nivel de acceso. Un cambio importante se refiere a cómo tratamos la "facturación de varias organizaciones" para las entidades de servicio. Los usuarios se cuentan como una sola licencia, independientemente del número de organizaciones en las que se encuentra. Las entidades de servicio se cuentan como una licencia por cada organización en la que se encuentra el usuario. Este escenario es similar al estándar "facturación basada en asignaciones de usuarios".

P: ¿Puedo agregar una identidad administrada desde un inquilino diferente a mi organización?

R: Solo puede agregar una identidad administrada desde el mismo inquilino al que está conectada la organización. Sin embargo, tenemos una solución alternativa que le permite configurar una identidad administrada en el "inquilino de recursos", donde están todos los recursos. A continuación, puede habilitarlo para que lo use una entidad de servicio en el "inquilino de destino", donde está conectada la organización. Siga estos pasos como solución alternativa:

  1. Cree una identidad administrada asignada por el usuario en Azure Portal para el inquilino de recursos.
  2. Conéctelo a una máquina virtual y asígnele esta identidad administrada .
  3. Cree un almacén de claves y genere un certificado (no puede ser de tipo "PEM"). Al generar este certificado, también se genera un secreto con el mismo nombre, que usamos más adelante.
  4. Conceda acceso a la identidad administrada para que pueda leer la clave privada desde el almacén de claves. Cree una directiva de acceso en el almacén de claves con los permisos "Get/List" (en "Permisos secretos" y busque la identidad administrada en "Seleccionar entidad de seguridad".
  5. Descargue el certificado creado en formato "CER", lo que garantiza que no contenga la parte privada del certificado.
  6. Cree un nuevo registro de aplicación en el inquilino de destino.
  7. Cargue el certificado descargado en esta nueva aplicación en la pestaña "Certificados y secretos".
  8. Agregue la entidad de servicio de esta aplicación a la organización de Azure DevOps a la que queremos que acceda y recuerde configurar la entidad de servicio con los permisos necesarios.
  9. Obtenga un token de acceso de Microsoft Entra desde este principal del servicio que utiliza el certificado de identidad adminstrada con este ejemplo de código:

Nota:

Renueva periódicamente tus certificados.

public static async Task<string> GetSecret(string keyVaultName, string secretName)
{
	var keyVaultUri = new Uri("https://" + keyVaultName + ".vault.azure.net");
	var client = new SecretClient(keyVaultUri, new ManagedIdentityCredential());
	var keyVaultSecret = await client.GetSecretAsync(secretName);

	var secret = keyVaultSecret.Value;
	return secret.Value;
}

private static async Task<AuthenticationResult> GetAppRegistrationAADAccessToken(string applicationClientID, string appTenantId)
{
	IConfidentialClientApplication app;

	byte[] privateKeyBytes = Convert.FromBase64String(GetSecret(keyVaultName, secretName));
	X509Certificate2 certificateWithPrivateKey = new X509Certificate2(privateKeyBytes, (string)null, X509KeyStorageFlags.MachineKeySet);

	app = ConfidentialClientApplicationBuilder.Create(applicationClientID)
		.WithCertificate(certificateWithPrivateKey)
		.WithAuthority(new Uri(string.Format(CultureInfo.InvariantCulture, "https://login.microsoftonline.com/{0}", appTenantId)))
		.Build();
	app.AddInMemoryTokenCache();

	string AdoAppClientID = "499b84ac-1321-427f-aa17-267ca6975798/.default";
	string[] scopes = new string[] { AdoAppClientID };

	var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();

	return result;
}

Posibles errores

El repositorio de Git con el nombre o el identificador '{repoName}' no existe o no tiene permisos para la operación que está intentando.

Asegúrese de que la entidad de servicio tenga al menos una licencia "básica" para acceder a los repositorios. Una licencia de "parte interesada" no es suficiente.

No se pudo crear la entidad de servicio con el identificador de objeto '{provided objectId}'

No hay ninguna entidad de servicio con en provided objectId el inquilino conectado a su organización. Una razón común es que se pasa el identificador de objeto del registro de la aplicación, en lugar del identificador de objeto de su entidad de servicio. Recuerde que una entidad de servicio es un objeto que representa la aplicación para un inquilino determinado, no es la propia aplicación. service principal object ID Puede encontrarse en la página "Aplicaciones empresariales" de su inquilino. Busque el nombre de la aplicación y seleccione el resultado "Aplicación empresarial" que devuelve. Este resultado es la página de la entidad de servicio o la aplicación empresarial y puede usar el identificador de objeto que se encuentra en esta página para crear una entidad de servicio en Azure DevOps.

Acceso denegado: {ID of the caller identity} necesita los permisos siguientes en el recurso Usuarios para realizar esta acción: Agregar usuarios

Este error puede deberse a uno de los siguientes motivos:

  • No es el propietario de la organización, el administrador de colecciones de proyectos ni un proyecto o administrador de equipo.
  • Es administrador de proyectos o equipos, pero la directiva "Permitir que los administradores de equipos y proyectos inviten a nuevos usuarios" está deshabilitada.
  • Es un administrador de proyecto o equipo que puede invitar a nuevos usuarios, pero está intentando asignar una licencia al invitar a un nuevo usuario. Los administradores del proyecto o del equipo no pueden asignar una licencia a los nuevos usuarios. Cualquier nuevo usuario invitado se agrega en el nivel de acceso predeterminado para los nuevos usuarios. Póngase en contacto con un PCA para cambiar el nivel de acceso de licencia.

Graph List API de Azure DevOps devuelve una lista vacía, aunque sabemos que hay entidades de servicio en la organización

Graph List API de Azure DevOps podría devolver una lista vacía, incluso si todavía hay más páginas de usuarios que devolver. continuationToken Use para recorrer en iteración las listas y, finalmente, puede encontrar una página donde se devuelven las entidades de servicio. Si se devuelve un continuationToken , significa que hay más resultados disponibles a través de la API. Aunque tenemos planes para mejorar esta lógica, en este momento, es posible que los primeros resultados X devuelvan vacíos.

TF401444: inicie sesión al menos una vez como {tenantId'tenantId\servicePrincipalObjectId'} en un explorador web para habilitar el acceso al servicio.

Si no se ha invitado a la entidad de servicio a la organización, es posible que se produzca el siguiente error. Asegúrese de que la entidad de servicio se agrega a la organización adecuada y tiene todos los permisos necesarios para acceder a los recursos necesarios.