Hugging Face's logo

Hub documentation

Adicionando um botão de Sign-In with HF ao seu Space

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Adicionando um botão de Sign-In with HF ao seu Space

Você pode habilitar um fluxo de login integrado no seu Space criando e associando de forma transparente um aplicativo OAuth/OpenID connect para que os usuários façam login com sua conta do HF.

Isso habilita novos casos de uso para o seu Space. Por exemplo, quando combinado com Storage Buckets, um Space de IA generativa pode permitir que os usuários façam login para acessar suas gerações anteriores, acessíveis apenas a eles.

Este guia o levará pelo processo de integrar um botão Sign-In with HF em qualquer Space. Se você está buscando um método rápido e simples para implementar isso em um Space Gradio, dê uma olhada na sua integração embutida.

Você também pode usar o fluxo de OAuth da HF para criar um fluxo de “Entrar com HF” em qualquer site ou aplicativo, fora dos Spaces. Leia nossa página geral sobre OAuth.

Criar um aplicativo OAuth

Tudo o que você precisa fazer é adicionar hf_oauth: true aos metadados do seu Space no arquivo README.md.

Aqui está um exemplo de metadados para um Espaço do Gradio:

title: Gradio Oauth Test
emoji: 🏆
colorFrom: pink
colorTo: pink
sdk: gradio
sdk_version: 3.40.0
python_version: 3.10.6
app_file: app.py

hf_oauth: true
# optional, default duration is 8 hours/480 minutes. Max duration is 30 days/43200 minutes.
hf_oauth_expiration_minutes: 480
# optional, see "Scopes" below. "openid profile" is always included.
hf_oauth_scopes:
 - read-repos
 - gated-repos
 - write-repos
 - manage-repos
 - inference-api
# optional, restrict access to members of specific organizations
hf_oauth_authorized_org: ORG_NAME
hf_oauth_authorized_org:
  - ORG_NAME1
  - ORG_NAME2

Você pode consultar a documentação de referência de configuração para mais informações.

Isso adicionará as seguintes variáveis de ambiente ao seu espaço:

  • OAUTH_CLIENT_ID: o ID do cliente do seu aplicativo OAuth (público)
  • OAUTH_CLIENT_SECRET: o segredo do cliente do seu aplicativo OAuth
  • OAUTH_SCOPES: escopos acessíveis pelo seu aplicativo OAuth.
  • OPENID_PROVIDER_URL: A URL do provedor OpenID. Os metadados do OpenID estarão disponíveis em {OPENID_PROVIDER_URL}/.well-known/openid-configuration.

Como qualquer outra variável de ambiente, você pode usá-las no seu código usando, por exemplo, os.getenv("OAUTH_CLIENT_ID").

URLs de redirecionamento

Você pode usar qualquer URL de redirecionamento que desejar, desde que ela aponte para o seu Space.

Observe que SPACE_HOST está disponível como uma variável de ambiente.

Por exemplo, você pode usar https://{SPACE_HOST}/login/callback como URI de redirecionamento.

Escopos

Os seguintes escopos são sempre incluídos para Spaces:

  • 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.)

Esses escopos são opcionais e podem ser adicionados definindo hf_oauth_scopes nos metadados do seu Space:

  • 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.

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. Você deve substituir ORG_ID pelo ID da organização, que está disponível no campo organizations.sub da resposta de userinfo.

Adicionando o botão ao seu Space

Agora você tem todas as informações para adicionar um botão “Sign-in with HF” ao seu Space. Algumas bibliotecas (Python, NodeJS) podem ajudar você a implementar o protocolo OpenID/OAuth.

Gradio e huggingface.js também oferecem suporte nativo, o que torna a implementação do botão Sign-in with HF muito simples; você pode conferir os guias associados com gradio e com huggingface.js.

Basicamente, você precisa:

  • Redirecione o usuário para https://huggingface.co/oauth/authorize?redirect_uri={REDIRECT_URI}&scope=openid%20profile&client_id={CLIENT_ID}&state={STATE}, onde STATE é uma string aleatória que você precisará verificar posteriormente.
  • Trate o callback em /auth/callback ou /login/callback (ou sua própria URL de callback personalizada) e verifique o parâmetro state.
  • Use o parâmetro de consulta code para obter um token de acesso e um token de id de https://huggingface.co/oauth/token (requisição POST com client_id, code, grant_type=authorization_code e redirect_uri como dados de formulário, e com Authorization: Basic {base64(client_id:client_secret)} como cabeçalho).

Você deve usar target=_blank no botão para abrir a página de login em uma nova aba, a menos que execute o espaço fora do seu iframe. Caso contrário, você pode encontrar problemas com cookies em alguns navegadores.

Exemplos:

Exemplo de código JS:

import { oauthLoginUrl, oauthHandleRedirectIfPresent } from "@huggingface/hub";

const oauthResult = await oauthHandleRedirectIfPresent();

if (!oauthResult) {
  // If the user is not logged in, redirect to the login page
  window.location.href = await oauthLoginUrl();
}

// You can use oauthResult.accessToken, oauthResult.userInfo among other things
console.log(oauthResult);
Update on GitHub

←Referência de Configuração do Spaces Espaços em destaque→