Uso de tokens de acceso personal

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018

Puede usar un token de acceso personal (PAT) como contraseña alternativa para autenticarse en Azure DevOps. En este artículo, le mostramos cómo crear, usar, modificar y revocar PAT para Azure DevOps.

En el vídeo siguiente se muestra cómo crear y usar un PAT.

Acerca de los PAT

Un token de acceso personal contiene las credenciales de seguridad de Azure DevOps. Un PAT le identifica, las organizaciones accesibles y ámbitos de acceso. Por lo tanto, son tan críticos como las contraseñas, por lo que debe tratarlas de la misma manera.

Si trabaja en herramientas de Microsoft, la cuenta de Microsoft (MSA) o Microsoft Entra ID es un enfoque aceptable y bien compatible. Sin embargo, si trabaja con herramientas de terceros que no admiten cuentas de Microsoft o de Microsoft Entra, o no quiere proporcionar sus credenciales principales a la herramienta, utilice el PAT para limitar el riesgo.

Puede crear y administrar los PAT mediante una de las siguientes maneras:

  • la interfaz de usuario en la configuración de usuario, que se describe en detalle en este artículo
  • a través de la API de administración del ciclo de vida de PAT

Para configurar PAT para herramientas que no son de Microsoft, use administradores de credenciales de Git o créelos manualmente. Se recomienda revisar nuestra guía de autenticación para ayudarle a elegir el mecanismo de autenticación correcto. En el caso de proyectos más pequeños que requieren una solución menos sólida, los PAT son una alternativa sencilla. A menos que los usuarios usen un administrador de credenciales, tienen que escribir sus credenciales cada vez.

Creación de un PAT

  1. Inicie sesión en su organización (https://dev.azure.com/{yourorganization}).

  2. En la página principal, abra la configuración de usuario y seleccione Tokens de acceso personal.

    Screenshot showing selection, Personal Access Tokens.

  3. Seleccione + New Token (+ Nuevo token).

    Screenshot showing selection, New Token.

  4. Asigne un nombre al token, seleccione la organización en la que desea usar el token y, a continuación, establezca el token para que expire automáticamente después de un número establecido de días.

    Screenshot showing entry of basic token information.

  5. Seleccione los ámbitos de este token para autorizar las tareas específicas.

    Por ejemplo, para crear un token para permitir que un agente de compilación y versión se autentique en Azure DevOps Services, limite el ámbito del token a grupos de agentes (leer y administrar). Para leer eventos de registro de auditoría y administrar y eliminar secuencias, seleccione Leer registro de auditoría y, a continuación, seleccione Crear.

    Screenshot showing selected scopes for a PAT.

    Nota:

    Es posible que esté restringido a la creación de PAT de ámbito completo. Si es así, el administrador de Azure DevOps en Microsoft Entra ID ha habilitado una directiva que le limita a un conjunto de ámbitos definido por el personalizado específico. Para obtener más información, consulte Administración de PAT con directivas o Restricción de la creación de PAT de ámbito completo. Para un PAT definido personalizado, el ámbito necesario para acceder a la API de gobernanza de componentes, vso.governance, no se puede seleccionar en la interfaz de usuario.

  6. Cuando haya terminado, copie el token y almacénelo en una ubicación segura. Para su seguridad, no se vuelve a mostrar.

    Screenshot showing how to copy the token to your clipboard.

Advertencia

Trate el token de acceso personal como si fuera su contraseña y no lo divulgue.

  1. Inicie sesión en el portal web (https://{server}:8080/tfs/).

  2. En la página principal, abra su perfil. Vaya a los detalles de seguridad.

Screenshot showing home page, opening your profile, and the Security button.

  1. Cree un token de acceso personal.

Screenshot showing adding a personal access token.

  1. Asigne un nombre al token. Seleccione una duración para el token.

    Si tiene más de una organización, también puede seleccionar la organización en la que desea usar el token.

    Screenshot showing information entry, including token name and lifespan.

  2. Seleccione los ámbitos de este token para autorizar las tareas específicas.

    Por ejemplo, para crear un token para habilitar una compilación y un agente de versión para autenticarse, limite el ámbito del token a grupos de agentes (leer, administrar).

  3. Cuando haya terminado, asegúrese de copiar el token. Para su seguridad, no se vuelve a mostrar. Use este token como contraseña. Seleccione Close (Cerrar).

    Screenshot showing created token.

Use el PAT en cualquier lugar donde se requieran las credenciales de usuario para la autenticación en Azure DevOps.

Importante

En el caso de las organizaciones respaldadas por microsoft Entra ID, tiene 90 días para iniciar sesión con el nuevo PAT; de lo contrario, se considera inactivo. Para obtener más información, consulte Frecuencia de inicio de sesión de usuario para el acceso condicional.

Notificaciones

Los usuarios reciben dos notificaciones durante la vigencia de un PAT: uno tras la creación y el otro siete días antes de la expiración.

Después de crear un PAT, recibirá una notificación similar al ejemplo siguiente. Esta notificación confirma que el PAT se agregó a su organización.

Screenshot showing PAT created notification.

En la imagen siguiente se muestra un ejemplo de la notificación de siete días antes de que expire el PAT.

Screenshot showing PAT near expiration notification.

Notificación inesperada

Si recibe una notificación PAT inesperada, es posible que un administrador o una herramienta hayan creado una PAT en su nombre. Algunos ejemplos:

  • Cuando se conecta a un repositorio de Git de Azure DevOps a través de git.exe. crea un token con un nombre para mostrar como "git: https://MyOrganization.visualstudio.com/ en MyMachine".
  • Cuando usted o un administrador configuran una implementación de aplicación web de App de Azure Service, crea un token con un nombre para mostrar como "Service Hooks: : App de Azure Service: : Deploy web app".
  • Cuando usted o un administrador configuran pruebas de carga web como parte de una canalización, crea un token con un nombre para mostrar como "WebAppLoadTestCDIntToken".
  • Cuando se configura una extensión de mensajería de integración de Microsoft Teams, crea un token con un nombre para mostrar como "Integración de Microsoft Teams".

Advertencia

Si cree que existe un PAT en error, le sugerimos que revoque el PAT. A continuación, cambie la contraseña. Como usuario de Microsoft Entra, consulte con el administrador para ver si su organización se usó desde un origen o ubicación desconocidos. Consulte también las preguntas más frecuentes sobre cómo proteger accidentalmente un PAT en un repositorio público de GitHub.

Usar un PAT

Su PAT es su identidad y le representa cuando lo usa, al igual que una contraseña.

Git

Las interacciones de Git requieren un nombre de usuario, que puede ser cualquier cosa excepto la cadena vacía. Para usar un PAT con autenticación http básica, use Base64-encode para y $MyPat, que se incluye en el siguiente bloque de código.

En PowerShell, escriba el código siguiente.

$MyPat = 'yourPAT'

$B64Pat = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("`:$MyPat"))

git -c http.extraHeader="Authorization: Basic $B64Pat" clone https://dev.azure.com/yourOrgName/yourProjectName/_git/yourRepoName


Para mantener el token más seguro, use administradores de credenciales para que no tenga que escribir las credenciales cada vez. Se recomienda el Administrador de credenciales de Git. Se requiere Git para Windows .

Repositorios existentes

En el caso de los repositorios existentes, si ya ha agregado el origen mediante el nombre de usuario, ejecute primero el siguiente comando.

git remote remove origin

De lo contrario, ejecute el siguiente comando.

git remote add origin https://<PAT>@<company_machineName>.visualstudio.com:/<path-to-git-repo> path to git repo = <project name>/_git/<repo_name> git push -u origin --all

Uso de un PAT en el código

Puede usar un PAT en el código.

Si desea proporcionar el PAT a través de un encabezado HTTP, conviértalo primero en una cadena Base64. En el ejemplo siguiente se muestra cómo convertir a Base64 mediante C#.


Authorization: Basic BASE64_USERNAME_PAT_STRING

A continuación, se puede proporcionar la cadena resultante como un encabezado HTTP en el formato siguiente.

En el ejemplo siguiente se usa la clase HttpClient en C#.

public static async void GetBuilds()
{
    try
    {
        var personalaccesstoken = "PATFROMWEB";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Accept.Add(
                new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
                Convert.ToBase64String(
                    System.Text.ASCIIEncoding.ASCII.GetBytes(
                        string.Format("{0}:{1}", "", personalaccesstoken))));

            using (HttpResponseMessage response = client.GetAsync(
                        "https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=5.0").Result)
            {
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.ToString());
    }
}

Sugerencia

Al usar variables, agregue un $ al principio de la cadena, como en el ejemplo siguiente.

public static async void GetBuilds()
{
   try
  {
      var personalaccesstoken = "PATFROMWEB";

      using (HttpClient client = new HttpClient())
       {
           client.DefaultRequestHeaders.Accept.Add(
              new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

           client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
               Convert.ToBase64String(
                   System.Text.ASCIIEncoding.ASCII.GetBytes(
                       string.Format("{0}:{1}", "", personalaccesstoken))));

          using (HttpResponseMessage response = client.GetAsync(
                       $"https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=5.0").Result)
           {
               response.EnsureSuccessStatusCode();
               string responseBody = await response.Content.ReadAsStringAsync();
               Console.WriteLine(responseBody);
           }
       }
   }
   catch (Exception ex)
   {
       Console.WriteLine(ex.ToString());
   }
}

Cuando el código funciona, es un buen momento para cambiar de autenticación básica a OAuth.

Para obtener más información y ejemplos de cómo usar PAT, consulte los siguientes artículos:

Si habilita la autenticación básica de IIS, los PAT no son válidos. Para obtener más información, consulte Uso de la autenticación básica de IIS local.

Modificación de un PAT

Puede volver a generar o ampliar un PAT y modificar su ámbito. Después de la regeneración, el PAT anterior ya no está autorizado.

  1. En la página principal, abra la configuración del usuario y, a continuación, seleccione Perfil.

    Screenshot showing sequence of buttons to select to modify a PAT.

  2. En Seguridad, seleccione Tokens de acceso personal. Seleccione el token que desea modificar y, a continuación , Editar.

    Screenshot showing highlighted Edit button to modify PAT.

  3. Edite el nombre del token, la expiración del token o el ámbito de acceso asociado al token y, a continuación, seleccione Guardar.

    Screenshot showing modified PAT.

Revocar un PAT

Puede revocar un PAT en cualquier momento, por diversos motivos.

  1. En la página principal, abra la configuración del usuario y, a continuación, seleccione Perfil.

    Screenshot showing sequence of buttons to select, Team Services, Preview page, and revoke a PAT.

  2. En Seguridad, seleccione Tokens de acceso personal. Seleccione el token para el que desea revocar el acceso y, a continuación, seleccione Revocar.

    Screenshot showing selection to revoke a single token or all tokens.

  3. Seleccione Revocar en el cuadro de diálogo de confirmación.

    Screenshot showing confirmation screen to revoke PAT.

Preguntas más frecuentes

P: ¿Qué ocurre con un PAT si una cuenta de usuario está deshabilitada?

R: Una vez que un usuario ha quitado de Azure DevOps, el PAT se invalida en un plazo de 1 hora. Si su organización está conectada al identificador de Entra de Microsoft, el PAT también se invalida en el identificador de Microsoft Entra, ya que pertenece al usuario. Se recomienda que el usuario gire su PAT a otra cuenta de usuario o servicio para mantener los servicios en ejecución.

P: ¿Hay alguna manera de renovar un PAT a través de la API REST?

R: Sí, hay una manera de renovar, administrar y crear PAT mediante nuestras API de administración del ciclo de vida de PAT. Para obtener más información, consulte Administración de PAT mediante la API REST y nuestras preguntas más frecuentes.

P: ¿Puedo usar la autenticación básica con todas las API REST de Azure DevOps?

R: No. Puede usar la autenticación básica con la mayoría de las API REST de Azure DevOps, pero las organizaciones y los perfiles solo admiten OAuth. Para más información, consulte Administración de PAT mediante la API REST.

P: ¿Qué ocurre si se comprueba accidentalmente mi PAT en un repositorio público en GitHub?

R: Azure DevOps examina los PAT protegidos en repositorios públicos en GitHub. Cuando encontramos un token filtrado, enviamos inmediatamente una notificación por correo electrónico detallada al propietario del token y registramos un evento en el registro de auditoría de la organización de Azure DevOps. A menos que deshabilite la directiva Revocar automáticamente tokens de acceso personal filtrados, revocamos inmediatamente el PAT filtrado. Animamos a los usuarios afectados a mitigar inmediatamente revocando el token filtrado y reemplazandolo por un nuevo token.

Para obtener más información, consulte Revocación automática de PAT filtradas.

P: ¿Puedo usar un token de acceso personal como ApiKey para publicar paquetes NuGet en una fuente de Azure Artifacts mediante la línea de comandos dotnet/nuget.exe?

R: No. Azure Artifacts no admite el paso de un token de acceso personal como ApiKey. Al usar un entorno de desarrollo local, se recomienda instalar el Proveedor de credenciales de Azure Artifacts para autenticarse con Azure Artifacts. Para obtener más información, vea los ejemplos siguientes: dotnet, NuGet.exe. Si desea publicar los paquetes mediante Azure Pipelines, use la tarea Autenticación de NuGet para autenticarse con el ejemplo de fuente.

P: ¿Por qué mi PAT detuvo el trabajo?

R: La autenticación pat requiere que inicie sesión periódicamente en Azure DevOps mediante el flujo de autenticación completo. Una vez cada 30 días es suficiente para muchos, pero es posible que tenga que iniciar sesión con más frecuencia que eso en función de la configuración de Microsoft Entra. Si el PAT deja de funcionar, pruebe primero a iniciar sesión en su organización, asegurándose de que pasa por el símbolo del sistema de autenticación completo. Si su PAT todavía no funciona después de eso, compruebe si su PAT ha expirado.