Hub documentation
Gestión de tokens
Gestión de tokens
Esta función forma parte de los planes Team & Enterprise.
Tokens Management permite a los administradores de la organización supervisar los tokens de acceso dentro de su organización, garantizando un acceso seguro a los recursos de la organización.
Para la experiencia de los miembros cuando las políticas de gestión de tokens están en vigor, incluido cómo verificar el estado de un token, qué errores esperar y cómo afectan la denegación y la revocación a un token, consulte Tokens in organizations with token management policies.
Visualización y gestión de tokens de acceso
La función de lista de tokens muestra todos los tokens de acceso dentro de su organización. Los administradores pueden:
- Monitorear el uso de tokens e identificar o prevenir posibles riesgos de seguridad:
- Acceso no autorizado a recursos privados (“fugas”)
- Ámbitos de acceso demasiado amplios
- Higiene de tokens subóptima (p. ej., tokens que no se han rotado en mucho tiempo)
- Identificar tokens inactivos o no utilizados
Los tokens de gran granularidad muestran sus permisos específicos:
Los tokens revocados se ocultan de la lista de forma predeterminada. Utilice el interruptor Mostrar tokens revocados situado sobre la lista para incluirlos en la vista.
Se muestra una insignia de estado REVOKED para cualquier token revocado, independientemente de la política de tokens de la organización. Las insignias PENDING, APPROVED y DENIED solo aparecen en organizaciones con la política “Require administrator approval” activada, ya que esos estados solo se crean mediante el flujo de aprobación.
Política de tokens
Los administradores de organizaciones de Team & Enterprise pueden aplicar las siguientes políticas:
| Política | Tokens de acceso sin ámbito (lectura/escritura) | Fine-Grained Tokens |
|---|---|---|
| Permitir el acceso mediante tokens de acceso de usuario (predeterminado) | Autorizado | Autorizado |
| Solo acceso mediante tokens de grano fino | No autorizado | Autorizado |
| Requiere aprobación del administrador | No autorizado | No autorizado sin aprobación (excepto los creados por un administrador) |
Revisión de la autorización de tokens
Cuando la política de tokens está configurada en “Require administrator approval”, los administradores de la organización pueden revisar los detalles de todos los tokens de grano fino que acceden a recursos propiedad de la organización y aprobar o denegar el acceso. Cuando un nuevo token entra en el estado pendiente, hasta 50 administradores de la organización con direcciones de correo electrónico confirmadas reciben una notificación con un enlace directo a la página de revisión del token. No se envía ninguna notificación cuando un token se aprueba automáticamente (p. ej., porque el creador es un administrador de la organización).
- Los tokens Pending están a la espera de una decisión del administrador
- Los tokens Aprobados han sido autorizados y están activos
- Los tokens Denied han sido bloqueados para acceder a los recursos de la organización
Cuando un token se aprueba o se deniega, el propietario del token recibe una notificación por correo electrónico.
La denegación no es permanente: un token denegado puede ser aprobado posteriormente por un administrador, lo que restaura su acceso. Del mismo modo, un token ya aprobado puede ser denegado en cualquier momento, lo que elimina inmediatamente su acceso basado en la aprobación.
Los nombres de los tokens solo son visibles para los administradores cuando la política “Require administrator approval” está habilitada.
Lo que ven los miembros cuando están bloqueados
Los miembros cuyos tokens están pendientes o denegados reciben un error 403 al acceder a los recursos de la organización: “Debido a la política de tokens de la organización, su token debe ser aprobado por la organización antes de que pueda acceder a este recurso.”
El mensaje de error es el mismo para los estados pendientes y denegados. Para ver el estado, los miembros pueden ir a la página de edición del token individual. La página de configuración de gestión de tokens del administrador de la organización muestra insignias de estado para todos los tokens de los miembros.
Denegar vs. Revocar
Los administradores tienen dos formas de eliminar el acceso de un token a una organización:
| Aspecto | Denegar | Revocar |
|---|---|---|
| Plan | Equipo y empresa | Plan Enterprise y superior |
| Alcance | Funciona dentro del flujo de trabajo de aprobación | Independientemente de la política de tokens |
| Efecto | Bloquea o elimina el acceso basado en aprobación | Elimina el acceso de forma forzada, independientemente de la política o del estado del token |
| ¿Reversible? | Sí: un token denegado puede aprobarse más adelante | No — el estado de revocación persiste incluso si la política cambia |
| Token en otro lugar | Sin efecto fuera de la organización | Sin efecto fuera de la organización |
Use deny al gestionar el acceso dentro del flujo de trabajo de aprobación (el token pasa a un estado denied y puede volver a aprobarse más adelante). Use revoke cuando necesite cortar permanentemente el acceso de un token a la organización.
Listado de tokens a través de la API
La lista de tokens mostrada en la interfaz de configuración también está disponible de forma programática:
# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token
curl -H "Authorization: Bearer ${ADMIN_HF_TOKEN}" \
"https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens"La respuesta es un array de tokens de acceso de miembros. Consulte la referencia de OpenAPI para el esquema completo: GET /api/organizations/<name>/settings/tokens
Por defecto, los tokens revocados se ocultan; pase q=status:all para incluirlos, como el interruptor Mostrar tokens revocados en la interfaz.
Revocación de tokens
Esta función forma parte del plan Enterprise y de los planes superiores.
Los administradores de la organización pueden revocar el token de acceso de cualquier miembro desde la página de detalles del token. La revocación está disponible independientemente de si la organización utiliza la política “Require administrator approval”. Un token revocado ya no puede acceder a los recursos de la organización, pero sigue funcionando en otros lugares. El propietario del token recibe una notificación por correo electrónico al revocarlo.
Los tokens revocados permanecen revocados incluso si la política de tokens de la organización se modifica o desactiva posteriormente. La revocación es permanente a nivel de organización: no existe una acción para desrevocar. Si un miembro necesita que se restablezca su acceso, debe eliminar el token revocado y crear uno nuevo. Si la organización utiliza la política “Require administrator approval”, el nuevo token comenzará en el estado pendiente y requerirá la aprobación de un administrador.
Los miembros cuyos tokens han sido revocados reciben un error 403 con el mensaje: “Su token ha sido revocado por el administrador de la organización, ya no puede acceder a los recursos de la organización. Póngase en contacto con ellos para obtener más información.” Este mensaje se muestra independientemente de si la organización utiliza la política “Require administrator approval”.
Revocación a través de la API
Los administradores también pueden revocar un token de forma programática utilizando su id de token. Esto es útil para flujos de trabajo automatizados, donde un token debe revocarse de inmediato.
# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token
# TOKEN_ID is the 24-character id shown on the org token settings page (or returned by the tokens listing API)
curl -X POST "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens/${TOKEN_ID}/revoke" \
-H "Authorization: Bearer ${ADMIN_HF_TOKEN}"Un administrador no puede revocar su propio token: una solicitud cuyo id de token coincide con el token utilizado para la autenticación se rechaza con un error 403.
Este punto de solo revoca el acceso del token a tu organización; el token sigue funcionando para los demás recursos de su propietario. Para invalidar un token filtrado en todas partes, usa
POST /api/credentials/revokeen su lugar, que no requiere autenticación y acepta un lote de valores de token en bruto.
Emisión de tokens programática
Esta función forma parte del plan Enterprise y de los planes superiores.
Para las organizaciones que necesitan emitir tokens de acceso de forma programática para sus miembros (por ejemplo, para plataformas internas, pipelines de CI/CD o integraciones personalizadas), consulte OAuth Token Exchange. Esta función del plan Enterprise permite a sus servicios de backend emitir tokens con alcance limitado para los miembros de la organización sin requerir el consentimiento interactivo del usuario.
Cuentas de servicio
Esta función forma parte del plan Enterprise y de los planes superiores.
Para el acceso automatizado que pertenece a la organización en lugar de a un miembro individual, los administradores pueden crear cuentas de servicio y emitir tokens de granularidad fina con un alcance limitado a los recursos de su organización.
Update on GitHub