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

Azure DevOps Services

Cuando se trabaja con un gran conjunto de tokens de acceso personal (PAT) de su propiedad, puede resultar complejo administrar el mantenimiento de estos tokens solo mediante la interfaz de usuario.

Con el ciclo de vida API de Administración PAT, puede administrar fácilmente las PAT asociadas a las organizaciones mediante procesos automatizados. Este amplio conjunto de API le permite administrar las 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 autentica con un token de Azure Active Directory (Azure AD) y realiza llamadas con pat lifecycle API. Si solo desea ver la lista completa de puntos de conexión disponibles, consulte la referencia de API aquí.

Requisitos previos

Para usar la API, debe autenticarse con un Azure AD token. 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 Azure AD con una suscripción de Azure activa.
• En función de las directivas de seguridad del inquilino, es posible que sea necesario conceder permisos a la aplicación 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 usarla.

Autenticación con tokens Azure Active Directory (Azure AD)

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

La Biblioteca de autenticación de Microsoft (MSAL) incluye varios flujos de autenticación compatibles que puede usar dentro de la aplicación para adquirir y actualizar Azure AD tokens. 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.

Para usar la biblioteca MSAL para adquirir y actualizar automáticamente Azure AD de acceso, debe:

• Tener un inquilino Azure AD con una suscripción de Azure activa
• Registro de una aplicación en su Azure AD inquilino
• Agregar Azure DevOps permisos a la aplicación

Una vez que tenga una aplicación con un flujo de autenticación de trabajo para controlar Azure AD tokens, puede usar estos tokens para realizar llamadas al ciclo de vida de PAT API de Administración. En la sección siguiente, se muestra cómo crear una aplicación que autentica a un usuario con un token de acceso de Azure AD mediante la biblioteca MSAL y llama a nuestro ciclo de vida de PAT API de Administración.

Siga cualquiera de los dos ejemplos para empezar:

• Clone nuestra aplicación flask de Python de ejemplo y configúrela con el inquilino y la organización de ADO.
• Genere una aplicación de ejemplo en el Azure Portal para el lenguaje que prefiera y configúrela para el ciclo de vida de PAT API de Administración

Clonación de nuestra 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 que se puede configurar para usarla con su inquilino de Azure AD y Azure DevOps organización. La aplicación de ejemplo usa el flujo de código de autenticación de MSAL para adquirir un token Azure AD acceso.

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 Azure AD, configurar el ejemplo para usar el inquilino de Azure AD y ejecutar la aplicación clonada.

Generación de una aplicación de inicio Azure Portal 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 Graph API de Microsoft. Los usuarios tendrán que actualizar la configuración de la aplicación para que apunte al punto de conexión del ciclo de vida de PAT API de Administración.

Para seguir este enfoque, siga las instrucciones de inicio rápido para el tipo de aplicación que prefiera en la página principal Azure AD desarrollo de documentos. Le mostraremos 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

1. Una vez que haya registrado la aplicación en un inquilino de Azure AD que tenga una suscripción de Azure activa, vaya a la aplicación registrada en Azure Active Directory - Registros de aplicaciones en el Azure Portal.

   

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

   

3. Seleccione Add a permission (Agregar un permiso) y seleccione Azure DevOps - check user_impersonation - select Add permissions (Agregar permisos).

   

4. Seleccione Inicio rápido en el panel de navegación izquierdo.

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

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

7. Asegúrese de que ha cumplido los requisitos previos necesarios y, a continuación, Azure Portal realizar 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".

   

8. Descargue la aplicación de inicio rápido y extraiga 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 está configurada 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 API de Administración 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 de Microsoft Graph. Tendremos que modificar el archivo de configuración generado para que llame al ciclo de vida de PAT API de Administración en su lugar.

Para ello, es necesario hacer algunas cosas:

1. Actualice la variable de configuración ENDPOINT a 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 Azure DevOps y a todos sus ámbitos.

En el ejemplo siguiente se muestra cómo se ha hecho esta configuración para la aplicación de inicio rápido Python Flask que se generó a través de la 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 la 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 usará finalmente 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.

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

1. Una vez que haya descargado la aplicación de inicio rápido, instalado sus dependencias y probado que se ejecuta en el 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 Graph API predeterminada de Microsoft:

   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 dirección URL Azure DevOps de la colección y al punto ENDPOINT 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 variable para que haga referencia al recurso de 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 SCOPE 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 de la variable y agregue el nombre de inquilino específico en AUTHORITY "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 coincide con lo siguiente, con la dirección app_config.py 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 que haya comprobado que tiene, no dude en modificar el contenido de y el 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 'app.py''ms-identity-python-webapp-master\templates' 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.

Actualización automática de un token Azure AD acceso automático

Una vez que la aplicación está configurada correctamente 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 los dos ejemplos anteriores actualizará automáticamente el token una vez que expire. La actualización del token impide que el usuario tenga que 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 el token de actualización.

Exploración del ciclo de API de Administración PAT

En la aplicación GitHub ejemplo anterior y las aplicaciones de inicio rápido, la aplicación se ha configurado previamente para realizar solicitudes con los tokens de Azure AD que ha adquirido. Para obtener más información sobre los puntos de conexión, los parámetros que aceptan y lo que se devuelve en las respuestas, consulte la documentación de referencia de API.

Preguntas más frecuentes

P: ¿Por qué necesito autenticación con un token Azure AD autenticación? ¿Por qué un PAT no es suficiente?

Un: Con este ciclo de API de Administración PAT, hemos abierto la posibilidad de crear nuevos PAT y revocar los existentes. En las manos equivocadas, 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 Azure AD autenticación, esperamos que esta API eficaz sea más segura frente a este uso no autorizado.

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

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

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

Un: Nos encanta que quiera usar la API en el lenguaje que prefiera. Si tiene una solicitud de un ejemplo, diríjase a nuestra página de Community 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 buscarla 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?

Un: Esta API de token y la API de administración de tokens,aunque similares, sirven a diferentes casos de uso y audiencias:

• Esta API de token es en gran medida para los usuarios que desean administrar las PAT que poseen en una canalización automatizada. Esta API lo permite. Ofrece la posibilidad de crear nuevos tokens y actualizar los existentes.
• La API de administrador de tokens está pensada para los administradores de la organización. Los administradores pueden usar esta API para recuperar y revocar las autorizaciones de OAuth, incluidos los tokens de acceso personal (PAT) y los tokens de sesión autodescriptos, de los usuarios de sus organizaciones.

P: ¿Cómo se pueden regenerar o rotar las PAT a través de la API? He visto esa opción en la interfaz de usuario, pero no veo un método similar en la API.

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

1. Comprenda los metadatos del PAT mediante una llamada GET.
2. Cree un nuevo PAT con los metadatos de PAT antiguos mediante una llamada POST.
3. Revocar el PAT antiguo mediante una llamada DELETE

P: Veo un mensaje emergente "Need admin approval" (Necesito aprobación del administrador) cuando intento continuar con el uso de esta aplicación. ¿Cómo puedo usar esta aplicación sin la aprobación del administrador?

Un: Parece que el inquilino ha establecido directivas de seguridad que requieren que a la aplicación se le concedan 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 usarla.

Pasos siguientes