Administración de tokens de acceso personal (PAT) mediante la API REST

Artículo
10/23/2023

Azure DevOps Services

Cuando se trabaja con un gran conjunto de tokens de acceso personal (PAT) que posee, puede ser complejo administrar el mantenimiento de estos tokens mediante la interfaz de usuario sola.

Mediante la API de administración del ciclo de vida de PAT, puede administrar fácilmente los PAT asociados a sus organizaciones mediante procesos automatizados. Este amplio conjunto de API le permite administrar los PAT que posee, lo que le permite crear nuevos tokens de acceso personal y renovar o expirar los tokens de acceso personal existentes.

En este artículo, le mostraremos cómo configurar una aplicación que se autentique con un token de Microsoft Entra y realice llamadas con la API de ciclo de vida de PAT. Si desea ver la lista completa de puntos de conexión disponibles, consulte la referencia de API.

Requisitos previos

Para usar la API, debe autenticarse con un token de Microsoft Entra, que se puede realizar a través de OAuth de Id. de Microsoft Entra. Obtenga más información sobre cómo hacerlo en la siguiente sección de autenticación.

Para ello, se deben cumplir algunos requisitos previos:

Debe tener un inquilino de Microsoft Entra con una suscripción de Azure activa.
En función de las directivas de seguridad de su inquilino, es posible que la aplicación tenga que conceder permisos para acceder a los recursos de la organización. En este momento, la única manera de continuar con el uso de esta aplicación en este inquilino es pedir a un administrador que conceda permiso a la aplicación antes de poder usarlo.

Autenticación con tokens de Microsoft Entra

A diferencia de otras API de Azure DevOps Services, los usuarios deben proporcionar un token de acceso de Microsoft Entra para usar esta API en lugar de un token pat. Los tokens de Microsoft Entra son un mecanismo de autenticación más seguro que el uso de PAT. Dada la capacidad de esta API para crear y revocar PAT, queremos asegurarnos de que esta funcionalidad eficaz se proporciona solo a los usuarios permitidos.

Para adquirir y actualizar tokens de acceso de Microsoft Entra, debe:

Importante

Las soluciones "en nombre de la aplicación" (como el flujo de "credenciales de cliente") y cualquier flujo de autenticación que no emita un token de acceso de Microsoft Entra no es válido para su uso con esta API. Si la autenticación multifactor está habilitada en el inquilino de Microsoft Entra, definitivamente debe usar el flujo de "código de autorización".

Precaución

Tener un inquilino de Microsoft Entra con una suscripción de Azure activa es un requisito previo para usar esta API.

Una vez que tenga una aplicación con un flujo de autenticación en funcionamiento para controlar los tokens de Microsoft Entra, puede usar estos tokens para realizar llamadas a la API de administración del ciclo de vida de PAT.

Para llamar directamente a la API, debe proporcionar un token de acceso de Microsoft Entra como token Bearer en Authorization el encabezado de la solicitud. Para ver los ejemplos y una lista completa de las solicitudes disponibles, consulte la referencia de la API de PAT.

En la sección siguiente, le mostramos cómo crear una aplicación que autentique a un usuario con un token de acceso de Microsoft Entra mediante la biblioteca MSAL y llame a nuestra API de administración del ciclo de vida de PAT.

La Biblioteca de autenticación de Microsoft (MSAL) incluye varios flujos de autenticación compatibles que puede usar en la aplicación para adquirir y actualizar tokens de Microsoft Entra. Puede encontrar una lista completa de los flujos de MSAL en la documentación de "flujos de autenticación" de la biblioteca de autenticación de Microsoft. Puede encontrar una guía para elegir el método de autenticación adecuado para la aplicación en Elección del método de autenticación adecuado para Azure DevOps.

Siga uno de los dos ejemplos para empezar:

Clone nuestra aplicación de Python Flask de ejemplo y configúrela con el inquilino y la organización de ADO
Generación de una aplicación de ejemplo en Azure Portal para el idioma que prefiera y configuración para la API de administración del ciclo de vida de PAT

Clonación de la aplicación web de Python Flask

Le hemos proporcionado una aplicación web de Python Flask de ejemplo para esta API que puede descargar en GitHub y se puede configurar para usarla con el inquilino de Microsoft Entra y la organización de Azure DevOps. La aplicación de ejemplo usa el flujo de código de autenticación de MSAL para adquirir un token de acceso de Microsoft Entra.

Importante

Se recomienda empezar a trabajar con la aplicación web de Python Flask de ejemplo en GitHub, pero si prefiere usar otro lenguaje o tipo de aplicación, use la opción Inicio rápido para volver a crear una aplicación de prueba equivalente.

Una vez que haya clonado la aplicación de ejemplo, siga las instrucciones del archivo LÉAME del repositorio. El archivo LÉAME explica cómo registrar una aplicación en el inquilino de Microsoft Entra, configurar el ejemplo para usar el inquilino de Microsoft Entra y ejecutar la aplicación clonada.

Generación de una aplicación de Azure Portal de inicio rápido

En su lugar, puede generar una aplicación de ejemplo con el código MSAL generado mediante la opción Inicio rápido en la página de la aplicación en Azure Portal. La aplicación de prueba de inicio rápido sigue el flujo de código de autorización, pero lo hace con un punto de conexión de Microsoft Graph API. Los usuarios deberán actualizar la configuración de la aplicación para que apunte al punto de conexión de la API de administración del ciclo de vida de PAT.

Para seguir este enfoque, siga las instrucciones de inicio rápido para el tipo de aplicación que prefiera en la página principal del desarrollo de documentos de Microsoft Entra ID. Le guiaremos por un ejemplo en el que hemos hecho esto para una aplicación de inicio rápido de Python Flask.

Ejemplo: Introducción a una aplicación de inicio rápido de Python Flask

Una vez que haya registrado la aplicación en un inquilino de Microsoft Entra que tenga una suscripción activa de Azure, vaya a la aplicación registrada en Microsoft Entra ID ->App Registrations en Azure Portal.
Seleccione la aplicación y vaya a Permisos de API.
Seleccione Add a permission (Agregar un permiso ) y seleccione Azure DevOps -> check user_impersonation -> select Add permissions (Agregar permisos).
Seleccione Inicio rápido en el panel de navegación izquierdo.
Seleccione el tipo de aplicación: en Python Flask, seleccione Aplicación web.
Seleccione la plataforma de la aplicación. En este tutorial, seleccione "Python".
Asegúrese de que ha cumplido los requisitos previos necesarios y, a continuación, permita que Azure Portal realice los cambios necesarios para configurar la aplicación. La dirección URL de respuesta será la dirección URL de redireccionamiento que se estableció en la creación de la aplicación + "/getAToken".
Descargue la aplicación De inicio rápido y extraiga los archivos.
Instale los requisitos de la aplicación y ejecute la aplicación para asegurarse de que tiene todas las dependencias necesarias. La aplicación se configura inicialmente para alcanzar un punto de conexión en Microsoft Graph API. Obtenga información sobre cómo cambiar este punto de conexión al punto de conexión base de LA API de administración del ciclo de vida de PAT siguiendo las instrucciones de configuración de la sección siguiente.

Configuración de una aplicación de inicio rápido

Una vez que el usuario haya descargado e instalado la aplicación de inicio rápido, se configurará para usar un punto de conexión de API de prueba desde Microsoft Graph. En su lugar, es necesario modificar el archivo de configuración generado para que llame a PAT Lifecycle Management API.

Sugerencia

Usamos la colección y la organización indistintamente en estos documentos. Si una variable de configuración necesita un nombre de colección, reemplácelo por el nombre de la organización.

Para ello, necesitamos hacer algunas cosas:

Actualización de la variable de configuración ENDPOINT a https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview para las API de administración del ciclo de vida de PAT
Actualice la variable de configuración SCOPE a "499b84ac-1321-427f-aa17-267ca6975798/.default" para hacer referencia al recurso de Azure DevOps y a todos sus ámbitos.

En el ejemplo siguiente se muestra cómo hemos hecho esta configuración para la aplicación Python Flask de inicio rápido que hemos generado a través de Azure Portal en la sección anterior.

Asegúrese de seguir las instrucciones para proteger el secreto de cliente, que se inserta inicialmente en texto sin formato en el archivo de configuración de la aplicación. Como procedimiento recomendado, quite la variable de texto sin formato del archivo de configuración y use una variable de entorno o Azure KeyVault para proteger el secreto de su aplicación.

En su lugar, puede optar por usar un certificado en lugar de un secreto de cliente. El uso de certificados es la opción recomendada si la aplicación finalmente se usará en producción. Las instrucciones para usar un certificado se pueden encontrar en el paso final de la configuración de la aplicación de inicio rápido.

Precaución

Nunca deje un secreto de cliente de texto sin formato en el código de la aplicación de producción.

Ejemplo: Configuración de una aplicación de inicio rápido de Python Flask para la API de administración del ciclo de vida de PAT

Una vez que haya descargado la aplicación de inicio rápido, haya instalado sus dependencias y probado que se ejecuta en su entorno, abra el archivo en el app_config.py editor que prefiera. El archivo debe ser similar al siguiente fragmento de código; para mayor claridad, se han quitado los comentarios que hacen referencia a la configuración predeterminada de Microsoft Graph API:

import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret,
# like Azure Key Vault. Or, use an environment variable as described in Flask's documentation:
# https://flask.palletsprojects.com/en/1.1.x/config/#configuring-from-environment-variables
# CLIENT_SECRET = os.getenv("CLIENT_SECRET")
# if not CLIENT_SECRET:
#     raise ValueError("Need to define CLIENT_SECRET environment variable")

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set
# in the app's registration in the Azure portal.

ENDPOINT = 'https://graph.microsoft.com/v1.0/users'  

SCOPE = ["User.ReadBasic.All"]

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

Actualice el identificador de cliente o el secreto de cliente a la aplicación con el identificador de cliente y el secreto de cliente del registro de la aplicación. Cuando esté en producción, asegúrese de proteger el secreto de cliente mediante una variable de entorno, Azure KeyVault o cambiando a un certificado.
```
CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret.
```

Cambie la variable a la ENDPOINT dirección URL de la colección de Azure DevOps y el punto de conexión de API. Por ejemplo, para una colección denominada "testCollection", el valor sería:

# Fill in the url to the user's ADO collection + the PAT lifecycle management API endpoint here

ENDPOINT = 'https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview'

Para una colección denominada "testCollection", este punto de conexión sería:

ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview'

Cambie la SCOPE variable para hacer referencia al recurso de la API de Azure DevOps; la cadena de caracteres es el identificador de recurso de la API de Azure DevOps y el ámbito ".default" hace referencia a todos los ámbitos de ese identificador de recurso.
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```
Si la aplicación está configurada para un inquilino específico (en lugar de la configuración multiinquilino), use el valor alternativo para la AUTHORITY variable, agregando el nombre de inquilino específico en "Enter_the_Tenant_Name_Here".
```
# For single-tenant app:
AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"

# For multi-tenant app:
AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"
```

Compruebe que el archivo final app_config.py coincide con lo siguiente, con el CLIENT_ID, el identificador de inquilino y la dirección URL de la colección. Por motivos de seguridad, asegúrese de que el CLIENT_SECRET se ha movido a una variable de entorno, Azure KeyVault o se ha intercambiado con un certificado para la aplicación registrada:

import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

# Note that the CLIENT_SECRET has been removed and moved to an environment variable or Azure KeyVault

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set in the app's registration in the Azure portal.

ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview' 
# Used to configure user's collection URL and the desired API endpoint

SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
# Means "All scopes for the Azure DevOps API resource"

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

Vuelva a ejecutar la aplicación para probar que puede obtener todos los tokens PAT para el usuario solicitante. Una vez que haya comprobado que tiene, no dude en modificar el contenido de 'app.py' y el 'ms-identity-python-webapp-master\templates' directorio para admitir el envío de solicitudes al resto de los puntos de conexión de la API de administración del ciclo de vida de PAT. Para obtener un ejemplo de una aplicación de inicio rápido de Python Flask que se ha modificado para admitir solicitudes a todos los puntos de conexión de api de administración del ciclo de vida de PAT, consulte este repositorio de ejemplo en GitHub.

Actualizar automáticamente un token de acceso de Microsoft Entra

Una vez configurada correctamente la aplicación y el usuario ha adquirido un token de acceso, el token se puede usar durante un máximo de una hora. El código MSAL proporcionado en ambos ejemplos anteriores actualizará automáticamente el token una vez que expire. La actualización del token impide que el usuario necesite iniciar sesión de nuevo y adquirir un nuevo código de autorización. Sin embargo, es posible que los usuarios tengan que volver a iniciar sesión después de 90 días una vez que expire su token de actualización.

Exploración de la API de administración del ciclo de vida de PAT

En la aplicación de ejemplo de GitHub anterior y las aplicaciones de inicio rápido, la aplicación se ha configurado previamente para realizar solicitudes con los tokens de Microsoft Entra que ha adquirido. Para más información sobre los puntos de conexión, qué parámetros aceptan y qué se devuelven en las respuestas, consulte los documentos de referencia de API.

Preguntas más frecuentes

P: ¿Por qué necesito autenticarse con un token de Microsoft Entra? ¿Por qué un PAT no es suficiente?

R: Con esta API de administración del ciclo de vida de PAT, hemos abierto la capacidad de crear nuevas PAT y revocar las PAT existentes. En las manos incorrectas, los actores malintencionados podrían usar esta API para crear varios puntos de entrada en los recursos de ADO de la organización. Al aplicar la autenticación de Microsoft Entra, esperamos que esta API eficaz sea más segura frente a este uso no autorizado.

P: ¿Es necesario tener un inquilino de Microsoft Entra con una suscripción de Azure activa para usar esta API?

R: Desafortunadamente, esta API solo está disponible para los usuarios que forman parte de un inquilino de Microsoft Entra con una suscripción activa de Azure.

P: ¿Puedo obtener un ejemplo de esta aplicación de ejemplo para otro tipo de lenguaje, marco o aplicación?

R: Nos encanta que quiera usar la API en el idioma que prefiera. Si tiene una solicitud de ejemplo, diríjase a nuestra comunidad de desarrollo para ver si otra persona tiene un ejemplo para compartir. Si tiene una aplicación de ejemplo que le gustaría compartir con el público de Azure DevOps más grande, háganoslo saber y podemos examinar su circulación en estos documentos más ampliamente.

P: ¿Cuál es la diferencia entre esta API de token y la API de administración de tokens?

R: Esta API de token y la API de administración de tokens, mientras que son similares, sirven diferentes casos de uso y audiencias:

Esta API de token es principalmente para los usuarios que quieren administrar los PAT que poseen en una canalización automatizada. Esta API permite. Ofrece la posibilidad de crear nuevos tokens y actualizar los existentes.
La API de administración de tokens está pensada para los administradores de la organización. Administración pueden usar esta API para recuperar y revocar autorizaciones de OAuth, incluidos los tokens de acceso personal (PAT) y los tokens de sesión autodescriptiva, de los usuarios de sus organizaciones.

P: ¿Cómo puedo volver a generar o girar pats a través de la API? Vi esa opción en la interfaz de usuario, pero no veo un método similar en la API.

R: ¡Gran pregunta! La funcionalidad "Regenerar" disponible en la interfaz de usuario realmente realiza algunas acciones, que son totalmente replicables a través de la API.

Para rotar el PAT, debe hacer lo siguiente:

Descripción de los metadatos del PAT mediante una llamada GET ,
Cree un nuevo PAT con los metadatos del PAT anterior mediante una llamada POST ,
Revocar el PAT antiguo mediante una llamada DELETE

P: Veo una ventana emergente "Necesita aprobación de administrador" cuando intento continuar con el uso de esta aplicación. ¿Cómo puedo usar esta aplicación sin aprobación de administrador?

R: Parece que el inquilino ha establecido directivas de seguridad que requieren que la aplicación tenga permisos para acceder a los recursos de la organización. En este momento, la única manera de continuar con el uso de esta aplicación en este inquilino es pedir a un administrador que conceda permiso a la aplicación antes de poder usarlo.

Pasos siguientes

Más información sobre los puntos de conexión de la API de administración del ciclo de vida de PAT