Entre com sua conta do Hugging Face

Você pode usar o fluxo de OAuth / OpenID connect do HF para criar um fluxo de “Entrar com HF” em qualquer site ou aplicativo.

Isso permitirá que os usuários façam login no seu site ou aplicativo usando sua conta do HF, clicando em um botão semelhante a este:

Após clicar neste botão, seus usuários verão um modal de permissões para autorizar seu aplicativo:

Criando um aplicativo oauth

Você pode criar seu aplicativo em suas configurações:

Aplicativos OAuth pertencentes à organização

Este recurso faz parte dos planos Team & Enterprise.

Aplicativos OAuth também podem ser pertencentes a uma organização em vez de uma conta individual. Isso é útil para aplicativos mantidos em conjunto pela sua equipe, pois eles permanecem com a organização em vez de depender da conta de um único membro.

Administradores de organização podem criar e gerenciar aplicativos pertencentes à organização na seção OAuth Apps das configurações da organização (https://huggingface.co/organizations/<your-org>/settings/applications). Todos os administradores da organização podem editar o aplicativo, rotacionar seu client secret ou excluí-lo. A lista de aplicativos mostra qual membro criou cada aplicativo, e as alterações nos aplicativos são registradas nos audit logs da organização.

A mesma página também lista o Token Exchange app da organização, caso um tenha sido configurado.

Você também pode transferir um aplicativo OAuth existente que você possui para uma organização da qual você é administrador, a partir da seção Transferir para uma organização na página de configurações do aplicativo. A organização deve estar em um plano Team ou Enterprise. Após a transferência, o aplicativo é gerenciado por todos os administradores da organização. Seu client ID, client secret e as autorizações e tokens existentes permanecem os mesmos, portanto, seu site ou aplicativo continua funcionando sem alterações. A transferência não pode ser desfeita a partir da página de configurações.

Aplicativos OAuth públicos (sem segredo)

Você pode criar ou usar aplicativos OAuth sem um segredo de cliente. Isso é útil para aplicativos nativos, CLIs ou outros contextos em que manter um segredo é impraticável.

• Na criação do aplicativo: Ao criar um novo aplicativo OAuth, você pode optar por criá-lo sem um segredo.
• Após a criação: Para um aplicativo existente, você pode excluir o segredo do cliente nas configurações do aplicativo. O aplicativo funcionará então como um aplicativo público.

Aplicativos públicos se autenticam usando apenas o ID do cliente (por exemplo, em fluxos de código de dispositivo ou de código de autorização com PKCE). Aplicativos que possuem um segredo ainda podem usar o segredo quando necessário (por exemplo, Authorization: Basic para solicitações de token).

URIs de redirecionamento

O redirect_uri enviado em uma solicitação de autorização deve corresponder exatamente a um dos URIs de redirecionamento registrados no seu aplicativo.

URIs de redirecionamento de loopback são a única exceção: para URIs que usam o esquema http em um host de loopback (localhost, 127.0.0.1 ou [::1]), qualquer porta é aceita no momento da solicitação, desde que todos os outros componentes correspondam a uma URI registrada. Isso segue o RFC 8252 §7.3 / OAuth 2.1 e permite que aplicativos nativos, CLIs e clientes MCP registrem uma URI sem porta, como http://localhost/callback, e depois escutem em qualquer porta efêmera que o sistema operacional lhes atribuir (por exemplo, http://localhost:49282/callback).

Algumas coisas a ter em mente:

• A exceção se aplica apenas ao esquema http. URIs de redirecionamento com https e esquemas personalizados (por exemplo, myapp://callback) sempre exigem uma correspondência exata, incluindo a porta.
• Hosts de loopback são correspondidos individualmente: uma solicitação para http://localhost:49282/callback não corresponde a um http://127.0.0.1/callback registrado. Registre ambos se o seu aplicativo puder usar qualquer um deles.
• Apenas a porta pode diferir. O caminho, a consulta e o userinfo ainda devem corresponder exatamente.

Se você estiver hospedando em Spaces

Se você hospedar seu aplicativo no Spaces, o fluxo será ainda mais fácil de implementar (e embutido diretamente no Gradio); consulte nosso guia de OAuth do Spaces.

Criação automatizada de aplicativo oauth

O Hugging Face suporta CIMD, também conhecido como Client ID Metadata Documents, o que permite criar um aplicativo oauth para o seu site de forma automatizada:

• Adicione um endpoint ao seu site em /.well-known/oauth-cimd que retorne o seguinte 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
}

• Use "[your website url]/.well-known/oauth-cimd" como client ID e PCKE como mecanismo de autenticação

Aplicativos nativos e clientes MCP que recebem o código de autorização em uma porta local podem listar URIs de loopback sem porta em redirect_uris, por exemplo, ["http://localhost/callback", "http://127.0.0.1/callback"] — consulte URIs de redirecionamento.

Isso é particularmente útil para ambientes efêmeros ou clientes MCP. Veja um exemplo de implementação no Hugging Chat.

OAuth de código de dispositivo

O fluxo de código de dispositivo permite que os usuários autorizem um aplicativo em um dispositivo (por exemplo, uma CLI) inserindo um código curto em outro dispositivo (por exemplo, um celular ou navegador). Não é necessário um URI de redirecionamento nem um navegador no dispositivo em que o aplicativo está sendo executado.

Testando com um script de exemplo

Você pode testar um aplicativo OAuth de código de dispositivo com o script a seguir. Substitua <Client ID> pelo ID do cliente do seu aplicativo. Para aplicativos públicos (sem segredo), o script funciona como está. Para aplicativos com segredo, adicione um cabeçalho Authorization: Basic (Base64 de client_id:client_secret) tanto nas solicitações de dispositivo quanto nas 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 aplicativos OAuth que possuem um segredo de cliente, inclua um cabeçalho Authorization: Basic (com client_id:client_secret codificado em Base64) tanto na solicitação do código de dispositivo quanto na solicitação do token.

Escopos atualmente suportados

Os escopos atualmente suportados são:

• openid: Receba um token de ID em adição ao token de acesso.
• profile: Lê as informações do perfil do usuário (nome de usuário, avatar, etc.)
• email: Lê o endereço de e-mail do usuário.
• read-billing: Saber se o usuário tem um método de pagamento configurado.
• read-memberships: Lê as organizações às quais o usuário pertence e seu papel em cada uma delas. Isso não concede acesso às configurações ou recursos das organizações.
• read-repos: Lê os repositórios pessoais do usuário.
• gated-repos: Lê o conteúdo de repositórios públicos com acesso restrito (gated) para os quais o usuário foi autorizado. Diferentemente de read-repos, isso não concede acesso a repositórios privados.
• contribute-repos: Cria repositórios e acessa aqueles criados por este aplicativo. Não pode acessar nenhum outro repositório, a menos que permissões adicionais sejam concedidas.
• write-repos: Lê e grava nos repositórios pessoais do usuário.
• manage-repos: Gerencia totalmente os repositórios pessoais do usuário, incluindo a criação e a exclusão deles.
• read-collections: Lê as coleções pessoais do usuário.
• write-collections: Lê e grava as coleções pessoais do usuário, incluindo a criação e a exclusão delas.
• inference-api: Faça solicitações de inferência para Inference Providers em nome do usuário.
• read-endpoints: Exibe os Inference Endpoints do usuário e faz solicitações de inferência a eles em nome do usuário.
• write-endpoints: Gerencia os Inference Endpoints do usuário, incluindo a criação e a exclusão deles. Inclui acesso read-endpoints.
• jobs: Executar jobs
• webhooks: Gerenciar webhooks
• write-discussions: Abre discussões e Pull Requests em nome do usuário, bem como interage com discussões (incluindo reações, publicação/edição de comentários, fechamento de discussões, …). Para abrir Pull Requests em repositórios privados, você precisa solicitar também o escopo read-repos.

Todas as outras informações estão disponíveis no metadados OpenID.

Entre em contato conosco se precisar de escopos adicionais.

Acessando recursos da organização

Por padrão, o aplicativo oauth não precisa acessar recursos da organização.

Mas alguns escopos, como read-repos ou read-billing, também se aplicam a organizações.

O usuário pode selecionar quais organizações conceder acesso ao autorizar o aplicativo. Se você exigir acesso a uma organização específica, pode adicionar orgIds=ORG_ID como um parâmetro de consulta à URL de autorização do OAuth. O ID da organização está disponível no campo orgs[].sub da resposta de userinfo.

Sincronizando a filiação à organização como grupos

A resposta de userinfo (https://huggingface.co/oauth/userinfo) inclui uma claim groups: os nomes das organizações às quais o usuário pertence, como um array de strings.

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

Muitos clientes OIDC (por exemplo, Discourse, Grafana, Argo CD, Vault, Kubernetes) podem sincronizar a associação a grupos a partir de uma claim contendo um array de strings e frequentemente são configurados com uma claim groups. Você pode usá-la para mapear organizações do Hugging Face para papéis ou grupos no seu aplicativo. Para mais detalhes sobre cada organização (ID, papel, etc.), use o campo orgs em vez disso.

Algumas coisas a ter em mente:

• A afirmação groups é retornada apenas pelo endpoint userinfo, não no token de ID.
• Ele contém nomes de organizações, não IDs. Se uma organização for renomeada, os mapeamentos que usam seu nome antigo deixarão de corresponder.
• Os grupos de recursos não estão incluídos. Para organizações em um plano pago, os grupos de recursos e as funções do usuário estão listados em orgs[].resourceGroups.

Identidade visual

Você é livre para usar seu próprio design para o botão. Abaixo estão algumas imagens SVG gentilmente fornecidas.

Confira nossos selos com explicações para integrá-los em markdown ou HTML.

Troca de Token para Organizações (RFC 8693)

Este recurso faz parte do plano Enterprise.

O Token Exchange permite que as organizações emitam programaticamente tokens de acesso para seus membros, sem exigir o consentimento interativo do usuário. Isso é particularmente útil para a construção de ferramentas internas, pipelines de automação e integrações corporativas que precisam acessar recursos do Hugging Face em nome dos membros da organização.

Se você precisa apenas de autenticação sem chave a partir de um workflow de CI/CD (GitHub Actions, GitLab CI, CircleCI, …) — sem emissão de tokens por membro — consulte Trusted Publishers, que também usa /oauth/token, mas utiliza um id_token OIDC emitido pelo seu provedor de CI como token de assunto (não requer plano Enterprise, nem credenciais de cliente).

Este recurso implementa o RFC 8693 - OAuth 2.0 Token Exchange, um protocolo padrão para cenários de troca de tokens.

Casos de uso

O Token Exchange foi projetado para cenários em que sua organização precisa:

• Construir plataformas internas: Crie painéis ou portais que acessem recursos do Hugging Face em nome dos membros da sua equipe, sem exigir que cada usuário autentique manualmente.
• Automatize pipelines de CI/CD: Emita tokens de curta duração e com escopo limitado para fluxos de trabalho automatizados que precisam enviar modelos ou conjuntos de dados para repositórios da organização.
• Integrar com sistemas de identidade corporativos: Conecte seu provedor de identidade existente ao Hugging Face emitindo tokens com base no seu diretório interno de usuários.
• Implementar controles de acesso personalizados: Crie um middleware que emita tokens com escopos específicos com base nas políticas internas da sua organização.

Como funciona

1. Sua organização possui um aplicativo OAuth vinculado à sua organização com o privilégio token-exchange.
2. Seu serviço de backend autentica-se neste aplicativo OAuth usando credenciais de cliente.
3. Seu serviço solicita um token de acesso para um membro específico da organização (identificado por e-mail).
4. O Hugging Face verifica se o usuário é membro da sua organização e emite um token com escopo definido.
5. O token emitido pode acessar apenas recursos dentro do escopo da sua organização.

Pré-requisitos

Para usar o Token Exchange, você precisa de um aplicativo OAuth vinculado a uma organização com o privilégio token-exchange. Entre em contato com o suporte da Hugging Face para configurar um aplicativo OAuth elegível para a sua organização.

Uma vez configurado, você receberá:

• Um ID do cliente (por exemplo, a1b2c3d4-e5f6-7890-abcd-ef1234567890)
• Um Client Secret (mantenha-o seguro!)

Administradores de organização podem gerenciar o aplicativo OAuth após a criação, incluindo a atualização do segredo do cliente e a configuração da duração do token. O aplicativo é listado na seção OAuth Apps das configurações da sua organização, e as alterações nele são registradas nos logs de auditoria da organização.

Autenticação

O Token Exchange usa a autenticação básica HTTP com as credenciais do seu aplicativo OAuth. Crie o cabeçalho de autorização codificando em Base64 o seu 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)

Emitindo tokens por e-mail

Para emitir um token de acesso para um membro da organização usando seu endereço de e-mail:

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"

Resposta

Uma solicitação bem-sucedida retorna um token de acesso:

{
  "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"
}

O campo id_token é incluído quando o escopo openid é solicitado.

Em seguida, você pode usar esse token para fazer solicitações de API em nome do usuário:

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

Controle de escopo

Por padrão, os tokens emitidos herdam todos os escopos configurados no aplicativo OAuth. Você pode solicitar escopos específicos adicionando o parâmetro scope. Consulte Escopos atualmente suportados para os valores disponíveis.

As permissões efetivas do token são limitadas tanto pelo escopo solicitado quanto pelo papel do usuário dentro da organização.

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 o princípio do menor privilégio: solicite apenas os escopos que seu aplicativo realmente precisa.

Considerações de segurança

Tokens emitidos via Token Exchange possuem restrições de segurança integradas:

• Escopo da organização: Os tokens só podem acessar recursos dentro da sua organização (modelos, conjuntos de dados, Spaces e coleções pertencentes à organização). Fora da organização, o acesso é somente leitura e limitado a: coleções públicas de qualquer usuário ou organização e repositórios públicos com controle de acesso aos quais o usuário tenha sido individualmente autorizado.
• Sem acesso pessoal: Os tokens não podem acessar os repositórios privados pessoais do usuário nem repositórios privados de outras organizações.
• Curta duração: Os tokens expiram após 8 horas por padrão. Os administradores da organização podem configurar a duração do token (até 30 dias) nas configurações do aplicativo OAuth. Nenhum token de atualização é fornecido.
• Auditável: Todas as trocas de tokens são registradas e visíveis nos logs de auditoria da sua organização.

Proteja com cuidado as credenciais do seu aplicativo OAuth. Qualquer pessoa com acesso ao seu segredo de cliente pode emitir tokens para qualquer membro da sua organização.

Respostas de erro

Referência

Tipo de concessão:

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

Parâmetro da requisição (subject_token_type):

Campo de resposta (issued_token_type):

Documentação relacionada:

• RFC 8693 - Exchange de Token do OAuth 2.0
• Registros de auditoria