Compartir vía

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

  • Artículo

Azure DevOps Services

Cuando estás trabajando con un gran conjunto de tokens de acceso personal (PATs) que posees, es posible que sea complejo administrar el mantenimiento de estos tokens mediante la interfaz de usuario únicamente.

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 sus PAT, lo que le permite crear nuevas PAT y renovar o expirar las PAT existentes.

En este artículo, se muestra cómo configurar una aplicación que se autentica mediante un token de Microsoft Entra y hace llamadas con la API de ciclo de vida de PAT.

Importante

No puede usar entidades de servicio ni identidades administradas para crear o revocar PAT.

Requisitos previos

A diferencia de otras API de Azure DevOps Services, los usuarios deben proporcionar una token de acceso de Microsoft Entra para usar esta API. Dada la capacidad de esta API para crear y revocar PAT, queremos asegurarnos de que esta eficaz funcionalidad solo esté disponible para tokens de Microsoft Entra más seguros.

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

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

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, proporcione un token de acceso de Microsoft Entra como token Bearer en el Authorization encabezado de la solicitud. Para obtener más información y una lista completa de las solicitudes disponibles, consulte la referencia de la API de PAT.

En la siguiente sección, se muestra cómo crear una aplicación que autentique a un usuario con un token de acceso de Microsoft Entra. La aplicación usa la biblioteca de autenticación de Microsoft (MSAL) y llama a nuestra API de administración del ciclo de vida de PAT.

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

Le proporcionamos una aplicación web de Python Flask de ejemplo para esta API que puede descargar en GitHub y 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 autorizació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 clonada 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 deben 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. Se explica el ejemplo siguiente con una aplicación de inicio rápido de Python Flask.

  1. Una vez que registre la aplicación en un inquilino de Microsoft Entra con una suscripción de Azure activa, vaya a la aplicación registrada en Microsoft Entra ID ->Registros de aplicaciones, en Azure Portal.

    Captura de pantalla que muestra el identificador de Entra de Microsoft abierto, registros de aplicaciones.

  2. Seleccione la aplicación y vaya a Permisos de API.

    Captura de pantalla que muestra la selección de una aplicación y la navegación a Permisos de API.

  3. Seleccione Agregar un permiso, Azure DevOps -> y después seleccione los ámbitos que necesite. En este caso, las API de administración del ciclo de vida de PAT solo admiten user_impersonation, pero otras API pueden solicitar ámbitos más granulares que puede encontrar en la página de referencia individual de cada API. Una vez seleccionados todos los ámbitos, haga clic en Agregar permisos.

    Captura de pantalla que muestra cómo agregar el permiso de Azure DevOps user_impersonation.

  4. Seleccione Inicio rápido.

  5. Seleccione el tipo de aplicación: en Python Flask, seleccione Aplicación web.

  6. Seleccione la plataforma de la aplicación. Para este tutorial, seleccione Python.

  7. Asegúrese de cumplir 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 es la dirección URL de redireccionamiento que se estableció en la creación de la aplicación + "/getAToken".

    Captura de pantalla que muestra cómo permitir que Azure Portal realice los cambios necesarios para configurar la aplicación.

  8. Descargue la aplicación De inicio rápido y extraiga los archivos.

    Captura de pantalla que muestra la descarga de la aplicación de inicio rápido y la extracción de los archivos.

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

    Captura de pantalla que muestra la instalación de los requisitos de la aplicación y la ejecución de la aplicación.

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

Una vez que el usuario descarga e instala la aplicación de inicio rápido, se configura para usar un punto de conexión de API de prueba desde Microsoft Graph. Modifique el archivo de configuración generado para que llame a PAT Lifecycle Management API en su lugar.

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.

Realice las siguientes tareas:

  1. 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
  2. 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 se usa 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.

  1. Una vez que descargue la aplicación de inicio rápido, instale sus dependencias y pruebe 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 quitaron 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

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

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

  4. 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 .default ámbito hace referencia a todos los ámbitos de ese identificador de recurso.

    SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]

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

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

  7. Vuelva a ejecutar la aplicación para probar que puede obtener todos los tokens PAT para el usuario solicitante. Una vez comprobado, puede 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 modificó 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 adquirió 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 actualiza automáticamente el token una vez que expira. 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 deban iniciar sesión de nuevo después de 90 días una vez que expire su token de actualización.

Preguntas más frecuentes (P+F)

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

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?

Esta API de token de y la API de administración de tokens de , aunque 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. Los administradores 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.

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

Para rotar el PAT, siga estos pasos:

  1. Descripción de los metadatos del PAT mediante una llamada GET ,
  2. Cree un nuevo PAT con los metadatos del PAT anterior mediante una llamada POST ,
  3. 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?

Parece que tu arrendatario tiene políticas de seguridad que requieren que tu 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.

P: ¿Por qué veo un error como "Las entidades de servicio no pueden realizar esta acción" cuando intento llamar a la API de administración del ciclo de vida de PAT mediante una entidad de servicio o una identidad administrada?

R: No se permiten las entidades de servicio ni las identidades administradas. 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.