Administración de tokens de acceso personal

Acerca de personal access token

Personal access tokenes una alternativa al uso de contraseñas para la autenticación a GitHub cuando se usa la GitHub API o la línea de comandos.

Los Personal access tokens están destinados a acceder a GitHub recursos en su nombre. Para acceder a los recursos en nombre de una organización o para integraciones de larga duración, debe usar un GitHub App. Para más información, consulta Acerca de la creación de aplicaciones de GitHub.

Un token tiene las mismas funcionalidades para acceder a los recursos y realizar acciones en esos recursos que las que tiene el propietario del token, y está limitado aún más por los ámbitos o permisos que se le hayan concedido. Un token no puede conceder funcionalidades de acceso adicionales a un usuario. Por ejemplo, personal access token se puede configurar con un admin:org ámbito, pero si el propietario del token no es propietario de la organización, el token no proporcionará acceso administrativo a la organización.

Tipos de personal access token

GitHub actualmente admite dos tipos de personal access tokens: fine-grained personal access tokens y personal access tokens (classic). GitHub recomienda usar fine-grained personal access tokens en lugar de personal access tokens (classic) siempre que sea posible.

Tanto fine-grained personal access tokens como personal access tokens (classic) están vinculados al usuario que los generó y se quedarán inactivos si el usuario pierde el acceso al recurso.

Los propietarios de la organización pueden establecer una directiva para restringir el acceso de personal access tokens (classic) a su organización y los propietarios de empresas pueden restringir el acceso de personal access tokens (classic) a la empresa o a las organizaciones que pertenecen a la empresa. Para más información, consulta Establecimiento de una directiva de token de acceso personal en la organización.

Fine-grained personal access token

Fine-grained personal access tokens tienen varias ventajas de seguridad sobre personal access tokens (classic), pero también tienen limitaciones que pueden impedir que las use en todos los escenarios. Estos límites y nuestros planes para corregirlos se pueden encontrar en la sección siguiente.

Si puede usar un fine-grained personal access token para su escenario, se beneficiará de estas mejoras:

• Cada token solo puede acceder a los recursos que pertenecen a un único usuario u organización.
• Cada token puede limitarse incluso más para acceder solo a repositorios específicos para ese usuario u organización.
• A cada token se le conceden permisos específicos y granulares, que ofrecen más control que los ámbitos de permisos concedidos a personal access tokens (classic).
• Los propietarios de la organización pueden exigir la aprobación de cualquier fine-grained personal access token que pueda acceder a los recursos de la organización.
• Los propietarios de la empresa pueden exigir la aprobación de cualquier fine-grained personal access token que pueda acceder a los recursos de las organizaciones propiedad de la empresa.

Fine-grained personal access tokens limitaciones

Fine-grained personal access tokens no admite todas las características de personal access tokens (classic). Estas brechas de características no son permanentes: GitHub está trabajando para cerrarlas. Puedes revisar nuestro plan de desarrollo público para obtener más detalles sobre cuándo se admitirán estos escenarios.

Las principales lagunas en fine-grained personal access tokens son:

• Uso de fine-grained personal access token para contribuir a los repositorios públicos en los que el usuario no es miembro.

• Uso fine-grained personal access token para contribuir a repositorios en los que el usuario es un colaborador externo o de repositorio.

• Uso fine-grained personal access token para acceder a varias organizaciones a la vez.

• Uso de fine-grained personal access token para acceder a los recursos de la empresa a la que pertenece el usuario.

• Uso fine-grained personal access token para llamar a las API que administran la cuenta Enterprise.

• Uso fine-grained personal access token para acceder a paquetes.

• Uso fine-grained personal access token para llamar a la API de comprobaciones.

• Uso fine-grained personal access token para acceder a Proyectos propiedad de una cuenta de usuario.

Todas estas brechas se resolverán con el tiempo, ya que GitHub continúa invirtiendo en patrones de acceso más seguros.

Personal access tokens (classic)

Los Personal access tokens (classic) son menos seguros. Sin embargo, algunas características solo funcionarán con personal access tokens (classic):

• Solo los personal access tokens (classic) tienen acceso de escritura para los repositorios públicos que no son de tu propiedad o de una organización de la que no eres miembro.
• Solo los personal access tokens (classic) tienen acceso de escritura automáticamente para los repositorios internos que son propiedad de la empresa. Es necesario conceder acceso a los Fine-grained personal access token a los repositorios internos.
• Los colaboradores externos solo pueden usar personal access tokens (classic) para acceder a los repositorios de la organización en los que son colaboradores.
• Solo los personal access tokens (classic) pueden acceder a empresas. (Los Fine-grained personal access token puede acceder a organizaciones que son propiedad de empresas).
• Algunos puntos de conexión de API REST solo están disponibles con un personal access tokens (classic). Para comprobar si un punto de conexión también admite fine-grained personal access token, consulta la documentación de ese punto de conexión, o bien Puntos de conexión disponibles para tokens de acceso personal específicos.

Si decide usar un personal access token (classic), tenga en cuenta que concederá acceso a todos los repositorios de las organizaciones a las que tiene acceso, así como a todos los repositorios de su cuenta personal.

Manteniendo sus personal access token a salvo

Personal access tokenson como contraseñas y comparten los mismos riesgos de seguridad inherentes. Antes de crear un nuevo personal access token, considere si hay un método más seguro de autenticación disponible para usted:

• Para acceder GitHub desde la línea de comandos, puede usar GitHub CLI o Git Credential Manager en lugar de crear un personal access token.
• Al usar un personal access token en un flujo de trabajo de GitHub Actions, considere si puede usar en su lugar el elemento integrado de GITHUB_TOKEN. Para más información, consulta Uso de GITHUB_TOKEN para la autenticación en flujos de trabajo.

Si estas opciones no son posibles y debe crear un personal access token, considere la posibilidad de usar otro servicio de la CLI para almacenar el token de forma segura.

Al usar un personal access token en un script, puede almacenar su token como secreto y ejecutar su script a través de GitHub Actions. Para obtener más información, consulte Uso de secretos en Acciones de GitHub.

Para más información sobre los procedimientos recomendados, consulta Protección de las credenciales de API.

Crear un fine-grained personal access token

1. En la esquina superior derecha de cualquier página en GitHub, haz clic en la fotografía de perfil y luego en Settings.

2. En la barra lateral de la izquierda, haz clic en Developer settings.

3. En la barra lateral izquierda, en la sección Personal access tokens, haz clic en Tokens de acceso detallado.

4. Haga clic en Generate new token (Generar nuevo token).

5. En Nombre del token, escribe un nombre para el token.

6. En Expiración, selecciona cuándo expirará el token. Se permiten tiempos infinitos, pero pueden bloquearse por una directiva de duración máxima establecida por la organización o propietario de la empresa. Para obtener más información, consulte Aplicar una directiva de duración máxima para personal access tokens.

7. Opcionalmente, en Descripción, agrega una nota para describir el propósito del token.

8. En Propietario del recurso, selecciona un propietario del recurso. El token solo podrá acceder a los recursos que pertenecen al propietario del recurso seleccionado. Las organizaciones de las que es miembro no aparecerán si la organización ha bloqueado el uso de fine-grained personal access tokens. Para obtener más información, consulte Establecimiento de una directiva de token de acceso personal en la organización.

9. Opcionalmente, si el propietario del recurso es una organización que requiere aprobación para los fine-grained personal access token, debajo del propietario del recurso, en el cuadro, introduzca una justificación para la solicitud.

10. En Acceso al repositorio, selecciona los repositorios a los que quieres que acceda el token. Debes elegir el acceso mínimo al repositorio que satisfaga tus necesidades. Los tokens siempre incluyen acceso de solo lectura a todos los repositorios públicos en GitHub.

11. Si elegiste Solo repositorios seleccionados en el paso anterior, en la lista desplegable Repositorios seleccionados, elige los repositorios a los que quieres que acceda el token.

12. En Permisos, selecciona los permisos que se concederán al token. En función del propietario del recurso y del acceso al repositorio que hayas especificado, hay permisos de repositorio, de organización y de cuenta. Debes elegir los permisos mínimos que necesites.

    El documento de referencia de la API REST para cada punto de conexión indica si el punto de conexión funciona con fine-grained personal access tokens y indica qué permisos son necesarios para que el token use el punto de conexión. Algunos puntos de conexión pueden requerir varios permisos y algunos puntos de conexión pueden requerir uno de varios permisos. Para obtener información general sobre los puntos fine-grained personal access token de conexión de la API REST a los que puede acceder con cada permiso, consulte Permisos necesarios para los tokens de acceso personal específicos.

13. Haga clic en Generar token.

Si ha seleccionado una organización como propietario del recurso y la organización requiere aprobación para fine-grained personal access tokens, su token se marcará como pending hasta que lo revise un administrador de la organización. El token solo podrá leer los recursos públicos hasta que se apruebe. Si eres propietario de la organización, tu solicitud se aprobará automáticamente. Para más información, consulta Revisión y revocación de tokens de acceso personal en la organización.

Relleno previo de detalles fine-grained personal access token mediante parámetros de URL

Puede compartir plantillas para un fine-grained personal access token a través de vínculos. Almacenar los detalles del token de esta manera facilita la automatización de los flujos de trabajo y la mejora de la experiencia del desarrollador al dirigir a los usuarios a la creación de tokens con campos pertinentes ya completados.

Cada campo admitido se puede establecer mediante un parámetro de consulta específico. Todos los parámetros son opcionales y validados por el formulario de generación de tokens para asegurarse de que las combinaciones de permisos y el propietario del recurso tienen sentido.

Aquí se muestra una plantilla de dirección URL de ejemplo, con saltos de línea para la legibilidad:

https://github.com/settings/personal-access-tokens/new
  ?name=Repo-reading+token
  &description=Just+contents:read
  &target_name=octodemo
  &expires_in=45
  &contents=read

https://github.com/settings/personal-access-tokens/new
  ?name=Repo-reading+token
  &description=Just+contents:read
  &target_name=octodemo
  &expires_in=45
  &contents=read

Prueba la dirección URL para crear un token con contents:read y metadata:read, con el nombre y la descripción especificados y una fecha de expiración de 45 días en el futuro. Verá un mensaje de error que indica Cannot find the specified resource owner: octodemo ya que no eres miembro de la organización octodemo.

A continuación se muestran algunas direcciones URL de ejemplo que generan los tokens que vemos con más frecuencia:

• Leer el contenido del repositorio
• Acceso de push a repositorios
• Acceso a GitHub Models
• Actualizar código y abrir una solicitud de incorporación de cambios
• Administrar licencias de Copilot en una organización
• Realiza solicitudes en Copilot

Parámetros de consulta admitidos

Para crear tu propia plantilla de token, sigue los detalles del parámetro de consulta proporcionados en esta tabla:

Permisos

Cada permiso admitido se establece con su nombre como parámetro de consulta, con el valor que especifica el nivel de acceso deseado. Los niveles de acceso válidos son read, write y admin. Algunos permisos solo admiten read, otros solo admiten write y solo algunos tienen admin. Usa tantos permisos como sea necesario, con el formato &contents=read&pull_requests=write&....

No es necesario incluir ambos read y write para un permiso en la dirección URL, write siempre incluye read y admin siempre incluye write.

Permisos de cuenta

Los permisos de cuenta solo se usan cuando el usuario actual se establece como propietario del recurso.

Permisos del repositorio

Los permisos del repositorio funcionan tanto para los propietarios de recursos de usuario como para los de la organización.

Permisos de organización

Los permisos de la organización solo se pueden usar si el propietario del recurso es una organización.

Crear un personal access token (classic)

1. En la esquina superior derecha de cualquier página en GitHub, haz clic en la fotografía de perfil y luego en Settings.

2. En la barra lateral de la izquierda, haz clic en Developer settings.

3. En la barra lateral izquierda, en Personal access tokens, haga clic en Tokens (clásico).

4. Seleccione Generar nuevo token y, a continuación, haga clic en Generar nuevo token (clásico).

5. En el campo "Nota", asigna un nombre descriptivo al token.

6. Para conceder una expiración al token, selecciona Expiración y, a continuación, elige una opción predeterminada o haz clic en Personalizado para especificar una fecha.

7. Selecciona los ámbitos que quieres concederle a este token. A fin de usar el token para acceder a repositorios desde la línea de comandos, seleccione repo. Un token sin alcances asignados solo puede acceder a información pública. Para más información, consulta Ámbitos para las aplicaciones de OAuth.

8. Haga clic en Generar token.

9. Opcionalmente, para copiar el nuevo token en el Portapapeles, haga clic en .

Eliminación de un personal access token

Debe eliminar un personal access token si ya no es necesario. Si elimina un personal access token que se usó para crear una clave de implementación, también se eliminará la clave de implementación.

1. En la esquina superior derecha de cualquier página en GitHub, haz clic en la fotografía de perfil y luego en Settings.
2. En la barra lateral de la izquierda, haz clic en Developer settings.
3. En la barra lateral izquierda, en Personal access tokens, haz clic en Tokens detallados o en Tokens (clásicos), dependiendo del tipo de personal access token que desees eliminar.
4. A la derecha de personal access token, que desea eliminar, haga clic en Eliminar.

Uso de un personal access token en la línea de comandos

Una vez que tenga personal access token, puede escribirlo en lugar de la contraseña al realizar operaciones de Git a través de HTTPS.

Por ejemplo, para clonar un repositorio en la línea de comandos, escribirías el comando git clone. A continuación, se te pedirá que escribas tu nombre de usuario y contraseña. Cuando se le solicite la contraseña, escriba su personal access token en lugar de una contraseña.

$ git clone https://HOSTNAME/USERNAME/REPO.git
Username: YOUR-USERNAME
Password: YOUR-PERSONAL-ACCESS-TOKEN

Aunque es necesario escribir el nombre de usuario junto con personal access token, el nombre de usuario no se utiliza para la autenticación. En su lugar, personal access token se usa para autenticarse. Si no escribes un nombre de usuario, recibirás un mensaje de error que indica que las credenciales no son válidas.

Personal access tokensolo se puede usar para las operaciones de Git HTTPS. Si en el repositorio se usa una dirección URL remota SSH, tendrá que cambiarlo de SSH a HTTPS.

Si no se te solicita tu nombre de usuario y contraseña, tus credenciales pueden estar almacenadas en la caché de tu computadora. Puede actualizar las credenciales en la cadena de claves para reemplazar la contraseña antigua por el token.

En lugar de escribir personal access token manualmente para cada operación de Git HTTPS, puede almacenar su personal access token en caché con un cliente de Git. Git almacenará tus credenciales temporalmente en la memoria hasta que haya pasado un intervalo de vencimiento. También puedes almacenar el token en un archivo de texto simple que pueda leer Git antes de cada solicitud. Para más información, consulta Almacenamiento en caché de las credenciales de GitHub en Git.

Información adicional

• Acerca de la autenticación para GitHub
• Vencimiento y revocación de tokens