Iniciar sesión con Hugging Face

Puedes usar el flujo de OAuth / OpenID connect de HF para crear un flujo de “Iniciar sesión con HF” en cualquier sitio web o App.

Esto permitirá a los usuarios iniciar sesión en tu sitio web o aplicación usando su cuenta de HF, haciendo clic en un botón similar a este:

Tras hacer clic en este botón, a tus usuarios se les mostrará un modal de permisos para autorizar tu aplicación:

Creación de una aplicación de oauth

Puedes crear tu aplicación en tus configuraciones:

Aplicaciones OAuth de propiedad de la organización

Esta función forma parte de los planes Team & Enterprise.

Las aplicaciones OAuth también pueden pertenecer a una organización en lugar de a una cuenta individual. Esto es útil para las aplicaciones que tu equipo mantiene de forma conjunta, ya que permanecen con la organización en lugar de depender de la cuenta de un solo miembro.

Los administradores de la organización pueden crear y gestionar aplicaciones propiedad de la organización desde la sección OAuth Apps de la configuración de la organización (https://huggingface.co/organizations/<your-org>/settings/applications). Todos los administradores de la organización pueden editar la aplicación, rotar su client secret o eliminarla. La lista de aplicaciones muestra qué miembro creó cada una, y los cambios en las aplicaciones se registran en los audit logs de la organización.

La misma página también lista la aplicación de intercambio de tokens de la organización, si se ha configurado.

También puedes transferir una aplicación OAuth existente que te pertenezca a una organización de la que seas administrador, desde la sección Transferir a una organización de la página de configuración de la aplicación. La organización debe estar en un plan Team o Enterprise. Después de la transferencia, la aplicación es gestionada por todos los administradores de la organización. Su client ID, client secret y las autorizaciones y tokens existentes permanecen sin cambios, por lo que tu sitio web o aplicación sigue funcionando sin modificaciones. La transferencia no se puede deshacer desde la página de configuración.

Aplicaciones OAuth públicas (sin secreto)

Puede crear o usar aplicaciones OAuth sin un secreto de cliente. Esto es útil para aplicaciones nativas, CLIs u otros contextos donde mantener un secreto no es práctico.

• Al crear la aplicación: Al crear una nueva aplicación de OAuth, puedes optar por crearla sin un secreto.
• Tras la creación: Para una aplicación existente, puedes eliminar el secreto del cliente en la configuración de la aplicación. La aplicación funcionará entonces como una aplicación pública.

Las aplicaciones públicas se autentican utilizando solo el ID de cliente (por ejemplo, en flujos de código de dispositivo o de código de autorización con PKCE). Las aplicaciones que tienen un secreto aún pueden usarlo cuando sea necesario (por ejemplo, Authorization: Basic para solicitudes de token).

URIs de redirección

El redirect_uri enviado en una solicitud de autorización debe coincidir exactamente con una de las URI de redirección registradas en su aplicación.

Las URI de redirección de loopback son la única excepción: para las URI que utilizan el esquema http en un host de loopback (localhost, 127.0.0.1 o [::1]), se acepta cualquier puerto en el momento de la solicitud, siempre que todos los demás componentes coincidan con una URI registrada. Esto sigue a RFC 8252 §7.3 / OAuth 2.1 y permite que las aplicaciones nativas, las CLIs y los clientes MCP registren una URI sin puerto, como http://localhost/callback, y luego escuchen en el puerto efímero que el sistema operativo les asigne (p. ej., http://localhost:49282/callback).

Hay algunas cosas que debes tener en cuenta:

• La excepción solo se aplica al esquema http. Las URI de redirección de https y de esquema personalizado (p. ej. myapp://callback) siempre requieren una coincidencia exacta, incluido el puerto.
• Los hosts de loopback se coinciden de forma individual: una solicitud a http://localhost:49282/callback no coincide con un http://127.0.0.1/callback registrado. Registre ambos si su aplicación puede utilizar cualquiera de los dos.
• Solo el puerto puede diferir. La ruta, la consulta y la información de usuario deben coincidir exactamente.

Si estás alojando en Spaces

Si alojas tu aplicación en Spaces, el flujo será aún más fácil de implementar (y está integrado directamente en Gradio); consulta nuestra guía de OAuth para Spaces.

Creación automática de la aplicación oauth

Hugging Face admite CIMD, también conocido como Documentos de metadatos del ID de cliente, lo que te permite crear una aplicación oauth para tu sitio web de forma automatizada:

• Agrega un punto final a tu sitio web en /.well-known/oauth-cimd que devuelva el siguiente JSON:

{
  client_id:                  "[your website url]/.well-known/oauth-cimd",
  client_name:                "Your Website",
  redirect_uris:              ["[your website url]/oauth/callback/huggingface"],
  token_endpoint_auth_method: "none",
  logo_uri:                  "https://....", // optional
  client_uri:                 "[your website url]", // optional
}

• Usa "[your website url]/.well-known/oauth-cimd" como ID de cliente y PCKE como mecanismo de autenticación

Las aplicaciones nativas y los clientes MCP que reciben el código de autorización en un puerto local pueden enumerar URI de bucle sin puerto en redirect_uris, por ejemplo, ["http://localhost/callback", "http://127.0.0.1/callback"] — consulte URI de redirección.

Esto resulta especialmente útil en entornos efímeros o clientes MCP. Consulta un ejemplo de implementación en Hugging Chat.

OAuth de código de dispositivo

El flujo de código de dispositivo permite a los usuarios autorizar una aplicación en un dispositivo (por ejemplo, una CLI) ingresando un código corto en otro dispositivo (por ejemplo, un teléfono o navegador). No se requiere una URI de redirección ni un navegador en el dispositivo donde se ejecuta la aplicación.

Pruebas con un script de ejemplo

Puede probar una aplicación OAuth de código de dispositivo con el siguiente script. Reemplace <Client ID> con el ID de cliente de su aplicación. Para aplicaciones públicas (sin secreto), el script funciona tal cual. Para aplicaciones con un secreto, agregue un encabezado Authorization: Basic (Base64 de client_id:client_secret) a ambas solicitudes, la de dispositivo y la de token.

#!/bin/bash
CLIENT_ID="<Client ID>"

# Step 1: Get device code
RESPONSE=$(curl -s -X POST https://huggingface.co/oauth/device \
  -d "client_id=$CLIENT_ID")

DEVICE_CODE=$(echo $RESPONSE | jq -r '.device_code')
USER_CODE=$(echo $RESPONSE | jq -r '.user_code')
VERIFICATION_URI=$(echo $RESPONSE | jq -r '.verification_uri')

echo "Device Code: $DEVICE_CODE"
echo "User Code: $USER_CODE"
echo ""
echo "Open: ${VERIFICATION_URI}"
echo "Enter the user code: $USER_CODE"
echo ""
read -p "Press Enter after authorizing..."

# Step 3: Get token
curl -X POST https://huggingface.co/oauth/token \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  -d "device_code=$DEVICE_CODE" \
  -d "client_id=$CLIENT_ID"

Para las aplicaciones de OAuth que tienen un secreto de cliente, incluye una cabecera Authorization: Basic (con client_id:client_secret codificado en Base64) tanto en la solicitud de código de dispositivo como en la solicitud de token.

Alcances actualmente admitidos

Los ámbitos actualmente admitidos son:

• openid: Recibe un token de ID además del token de acceso.
• profile: Lee la información del perfil del usuario (nombre de usuario, avatar, etc.)
• email: Lee la dirección de correo electrónico del usuario.
• read-billing: Saber si el usuario tiene un método de pago configurado.
• read-memberships: Lee las organizaciones a las que pertenece el usuario y su rol en cada una de ellas. Esto no otorga acceso a la configuración ni a los recursos de las organizaciones.
• read-repos: Lee los repositorios personales del usuario.
• gated-repos: Lee el contenido de los repositorios públicos con acceso restringido a los que el usuario ha sido autorizado. A diferencia de read-repos, esto no otorga acceso a repositorios privados.
• contribute-repos: Crea repositorios y accede a los creados por esta aplicación. No puede acceder a ningún otro repositorio a menos que se otorguen permisos adicionales.
• write-repos: Lee y escribe los repositorios personales del usuario.
• manage-repos: Gestionar por completo los repositorios personales del usuario, incluida su creación y eliminación.
• read-collections: Lee las colecciones personales del usuario.
• write-collections: Lee y escribe las colecciones personales del usuario, incluida su creación y eliminación.
• inference-api: Realiza solicitudes de inferencia a Inference Providers en nombre del usuario.
• read-endpoints: Ver los Inference Endpoints del usuario y realizar solicitudes de inferencia a su nombre.
• write-endpoints: Gestiona los Inference Endpoints del usuario, incluida su creación y eliminación. Incluye el acceso read-endpoints.
• jobs: Ejecutar jobs
• webhooks: Gestionar webhooks
• write-discussions: Abre discusiones y Pull Requests en nombre del usuario e interactúa con las discusiones (incluidas reacciones, publicación/edición de comentarios, cierre de discusiones, …). Para abrir Pull Requests en repositorios privados, también necesitas solicitar el ámbito read-repos.

Toda la demás información está disponible en los metadatos de OpenID.

Póngase en contacto con nosotros si necesita más permisos.

Acceso a los recursos de la organización

Por defecto, la aplicación de oauth no necesita acceder a los recursos de la organización.

Pero algunos ámbitos, como read-repos o read-billing, también se aplican a las organizaciones.

El usuario puede seleccionar a qué organizaciones otorgar acceso al autorizar la aplicación. Si se requiere acceso a una organización específica, se puede agregar orgIds=ORG_ID como parámetro de consulta a la URL de autorización de OAuth. El ID de la organización está disponible en el campo orgs[].sub de la respuesta de userinfo.

Sincronizar la membresía de la organización como grupos

La respuesta de userinfo (https://huggingface.co/oauth/userinfo) incluye una afirmación groups: los nombres de las organizaciones a las que pertenece el usuario, como un array de cadenas.

{
  "sub": "...",
  "preferred_username": "my-username",
  "groups": ["my-org", "another-org"],
  "orgs": [ ... ]
}

Muchos clientes OIDC (p. ej., Discourse, Grafana, Argo CD, Vault, Kubernetes) pueden sincronizar la pertenencia a grupos desde una afirmación que contiene un array de cadenas de texto, y a menudo se configuran con una afirmación groups. Puedes usarla para mapear las organizaciones de Hugging Face a roles o grupos en tu aplicación. Para más detalles sobre cada organización (ID, rol, etc.), usa en su lugar el campo orgs.

Hay algunas cosas que debes tener en cuenta:

• El claim groups solo se devuelve en el endpoint userinfo, no en el token de ID.
• Contiene nombres de organizaciones, no IDs. Si una organización cambia de nombre, los mapeos que usen su nombre anterior dejarán de coincidir.
• Los grupos de recursos no están incluidos. Para las organizaciones con un plan de pago, los grupos de recursos y roles del usuario se enumeran en orgs[].resourceGroups.

Marca

Puedes usar tu propio diseño para el botón. A continuación se muestran algunas imágenes SVG proporcionadas amablemente.

Echa un vistazo a nuestras insignias con explicaciones para integrarlas en markdown o HTML.

Intercambio de tokens para organizaciones (RFC 8693)

Esta función forma parte del plan Enterprise.

Token Exchange permite a las organizaciones emitir programáticamente tokens de acceso para sus miembros sin requerir el consentimiento interactivo del usuario. Esto resulta especialmente útil para crear herramientas internas, pipelines de automatización e integraciones empresariales que necesitan acceder a los recursos de Hugging Face en nombre de los miembros de la organización.

Si solo necesitas autenticación sin claves desde un flujo de CI/CD (GitHub Actions, GitLab CI, CircleCI, …) — sin emisión de tokens por miembro — consulta Trusted Publishers, que también utiliza /oauth/token pero toma un id_token OIDC emitido por tu proveedor de CI como token de sujeto (no requiere un plan Enterprise ni credenciales de cliente).

Esta función implementa RFC 8693 - OAuth 2.0 Token Exchange, un protocolo estándar para escenarios de intercambio de tokens.

Casos de uso

Token Exchange está diseñado para escenarios en los que su organización necesita:

• Construir plataformas internas: Crea paneles o portales que accedan a los recursos de Hugging Face en nombre de los miembros de tu equipo, sin que cada usuario tenga que autenticarse manualmente.
• Automatizar pipelines de CI/CD: Emita tokens de vida corta y con alcance limitado para flujos de trabajo automatizados que necesiten enviar modelos o conjuntos de datos a los repositorios de la organización.
• Integrar con sistemas de identidad empresariales: Conecte su proveedor de identidad existente con Hugging Face emitiendo tokens basados en su directorio interno de usuarios.
• Implementar controles de acceso personalizados: Crea middleware que emita tokens con ámbitos específicos según las políticas internas de tu organización.

Cómo funciona

1. Su organización tiene una aplicación OAuth vinculada a su organización con el privilegio token-exchange.
2. Su servicio de backend se autentica con esta aplicación de OAuth mediante credenciales de cliente.
3. Su servicio solicita un token de acceso para un miembro específico de la organización (identificado por correo electrónico).
4. Hugging Face verifica que el usuario sea miembro de su organización y emite un token con alcance limitado.
5. El token emitido solo puede acceder a recursos dentro del alcance de su organización.

Prerrequisitos

Para usar Token Exchange, necesitas una aplicación OAuth vinculada a una organización con el privilegio token-exchange. Contacta con el soporte de Hugging Face para configurar una aplicación OAuth elegible para tu organización.

Una vez configurado, recibirás:

• Un ID de cliente (p. ej., a1b2c3d4-e5f6-7890-abcd-ef1234567890)
• Un Client Secret (¡manténgalo seguro!)

Los administradores de la organización pueden gestionar la aplicación OAuth después de su creación, incluyendo la renovación del secreto del cliente y la configuración de la duración del token. La aplicación se lista en la sección OAuth Apps de la configuración de su organización, y los cambios realizados en ella se registran en los registros de auditoría de la organización.

Autenticación

Token Exchange usa la autenticación básica de HTTP con las credenciales de tu aplicación OAuth. Crea el encabezado de autorización codificando en Base64 tu client_id:client_secret:

# Create the authorization header
export CLIENT_ID="your-client-id"
export CLIENT_SECRET="your-client-secret"
export AUTH_HEADER=$(echo -n "${CLIENT_ID}:${CLIENT_SECRET}" | base64)

Emitir tokens por correo electrónico

Para emitir un token de acceso para un miembro de una organización usando su dirección de correo electrónico:

curl -X POST "https://huggingface.co/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic ${AUTH_HEADER}" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=user@yourorg.com" \
  -d "subject_token_type=urn:huggingface:token-type:user-email"

Respuesta

Una solicitud exitosa devuelve un token de acceso:

{
  "access_token": "hf_oauth_...",
  "token_type": "bearer",
  "expires_in": 28800,
  "scope": "openid profile email read-repos",
  "id_token": "eyJhbGciOiJS...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

El campo id_token se incluye cuando se solicita el ámbito openid.

A continuación, puede usar este token para realizar solicitudes de API en nombre del usuario:

curl "https://huggingface.co/api/whoami-v2" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Control de alcance

Por defecto, los tokens emitidos heredan todos los ámbitos configurados en la aplicación OAuth. Puede solicitar ámbitos específicos añadiendo el parámetro scope. Consulte Ámbitos actualmente admitidos para ver los valores disponibles.

Los permisos efectivos del token están limitados tanto por el ámbito solicitado como por el rol del usuario dentro de la organización.

curl -X POST "https://huggingface.co/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic ${AUTH_HEADER}" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=user@yourorg.com" \
  -d "subject_token_type=urn:huggingface:token-type:user-email" \
  -d "scope=openid profile"

Siga el principio de privilegio mínimo: solicite únicamente los ámbitos que su aplicación necesita realmente.

Consideraciones de seguridad

Los tokens emitidos mediante Token Exchange tienen restricciones de seguridad integradas:

• Alcance de la organización: Los tokens solo pueden acceder a recursos dentro de su organización (modelos, conjuntos de datos, Spaces y colecciones propiedad de la organización). Fuera de la organización, el acceso es de solo lectura y está limitado a: colecciones públicas de cualquier usuario u organización, y repositorios públicos con acceso restringido a los que se haya concedido acceso individualmente al usuario.
• Sin acceso personal: Los tokens no pueden acceder a los repositorios privados personales del usuario ni a los repositorios privados de otras organizaciones.
• De vida corta: Los tokens caducan a las 8 horas de forma predeterminada. Los administradores de la organización pueden configurar la duración del token (hasta 30 días) en la configuración de la aplicación OAuth. No se proporcionan tokens de actualización.
• Auditable: Todos los intercambios de tokens se registran y son visibles en los registros de auditoría de su organización.

Proteja cuidadosamente las credenciales de su aplicación OAuth. Cualquier persona con acceso a su secreto de cliente puede emitir tokens para cualquier miembro de su organización.

Respuestas de error

Referencia

Tipo de concesión:

urn:ietf:params:oauth:grant-type:token-exchange

Parámetro de solicitud (subject_token_type):

Campo de respuesta (issued_token_type):

Documentación relacionada:

• RFC 8693 - Intercambio de tokens de OAuth 2.0
• Registros de auditoría