Hugging Face's logo

Hub documentation

Space에 HF 로그인 버튼 추가

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Space에 HF 로그인 버튼 추가

Space에서 OAuth/OpenID connect 앱을 자연스럽게 생성하고 연결하여 사용자가 HF 계정으로 로그인할 수 있는 내장된 로그인 플로우를 활성화할 수 있습니다.

이를 통해 Space에 새로운 사용 사례를 추가할 수 있습니다. 예를 들어, Storage Buckets와 결합하면 생성형 AI Space에서 사용자가 로그인하여 자신만 접근할 수 있는 이전 생성 결과를 조회할 수 있습니다.

이 가이드에서는 어떤 Space에도 Sign-In with HF 버튼을 통합하는 과정을 안내합니다. Gradio Space에서 이를 빠르고 간단하게 구현하는 방법을 찾고 있다면, 해당 내장 통합 기능을 확인해 보세요.

Spaces 외부의 웹사이트나 앱에서 HF OAuth 플로우를 사용하여 “HF로 로그인” 플로우를 만들 수도 있습니다. 일반적인 OAuth 페이지를 읽어보세요.

OAuth 앱 만들기

README.md 파일의 Space 메타데이터에 hf_oauth: true를 추가하기만 하면 됩니다.

다음은 Gradio Space의 메타데이터 예시입니다:

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

자세한 내용은 구성 참조 문서를 확인하세요.

이렇게 하면 다음 환경 변수가 스페이스에 추가됩니다:

  • OAUTH_CLIENT_ID: OAuth 앱의 클라이언트 ID(공개)
  • OAUTH_CLIENT_SECRET: OAuth 앱의 클라이언트 시크릿
  • OAUTH_SCOPES: OAuth 앱에서 접근할 수 있는 스코프입니다.
  • OPENID_PROVIDER_URL: OpenID 제공자의 URL입니다. OpenID 메타데이터는 {OPENID_PROVIDER_URL}/.well-known/openid-configuration에서 사용할 수 있습니다.

기타 환경 변수와 마찬가지로, 예를 들어 os.getenv("OAUTH_CLIENT_ID")를 사용하여 코드에서 사용할 수 있습니다.

리다이렉트 URL

Space를 대상으로 하는 한 어떤 redirect URL이든 사용할 수 있습니다.

SPACE_HOST은 환경 변수로 사용할 수 있습니다.

예를 들어, 리다이렉트 URI로 https://{SPACE_HOST}/login/callback를 사용할 수 있습니다.

범위

다음 스코프는 Spaces에 항상 포함됩니다:

  • openid: 액세스 토큰 외에 ID 토큰을 수신합니다.
  • profile: 사용자의 프로필 정보(사용자 이름, 아바타 등)를 읽습니다

이러한 스코프는 선택 사항이며, Space의 메타데이터에서 hf_oauth_scopes를 설정하여 추가할 수 있습니다:

  • email: 사용자의 이메일 주소를 읽습니다.
  • read-billing: 사용자가 결제 수단을 설정했는지 확인합니다.
  • read-memberships: 사용자가 속한 조직 및 각 조직에서의 역할을 읽습니다. 이 권한은 조직의 설정이나 리소스에 대한 액세스를 부여하지 않습니다.
  • read-repos: 사용자의 개인 저장소를 읽습니다.
  • gated-repos: 사용자가 접근 권한을 부여받은 공개 gated 리포지토리의 내용을 읽습니다. read-repos와 달리, 이 권한은 비공개 리포지토리에 대한 접근을 허용하지 않습니다.
  • contribute-repos: 저장소를 생성하고 이 앱이 생성한 저장소에 액세스합니다. 추가 권한이 부여되지 않는 한 다른 저장소에 액세스할 수 없습니다.
  • write-repos: 사용자의 개인 저장소를 읽고 씁니다.
  • manage-repos: 사용자의 개인 저장소를 생성 및 삭제하는 것을 포함하여 완전히 관리합니다.
  • read-collections: 사용자의 개인 컬렉션을 읽습니다.
  • write-collections: 사용자의 개인 컬렉션을 읽고 쓰며, 이를 생성하고 삭제합니다.
  • inference-api: 사용자를 대신하여 Inference Providers에 추론 요청을 보냅니다.
  • read-endpoints: 사용자의 Inference Endpoints를 확인하고, 사용자를 대신하여 해당 엔드포인트에 추론 요청을 보냅니다.
  • write-endpoints: 사용자의 Inference Endpoints를 관리하며, 이를 생성하고 삭제합니다. read-endpoints 액세스를 포함합니다.
  • jobs: jobs 실행
  • webhooks: webhooks 관리
  • write-discussions: 사용자를 대신하여 토론 및 Pull Request를 열고 토론에 상호작용(반응, 댓글 게시/편집, 토론 닫기 등)합니다. 비공개 저장소에서 Pull Request를 열려면 read-repos 스코프도 요청해야 합니다.

조직 리소스에 액세스

기본적으로 oauth 앱은 조직 리소스에 액세스할 필요가 없습니다.

하지만 read-repos나 read-billing와 같은 일부 스코프는 조직에도 적용됩니다.

사용자는 앱을 승인할 때 액세스 권한을 부여할 조직을 선택할 수 있습니다. 특정 조직에 대한 액세스가 필요한 경우, OAuth 승인 URL에 orgIds=ORG_ID를 쿼리 파라미터로 추가할 수 있습니다. ORG_ID는 userinfo 응답의 organizations.sub 필드에서 확인할 수 있는 조직 ID로 대체해야 합니다.

Space에 버튼 추가

이제 Space에 “Sign-in with HF” 버튼을 추가하는 데 필요한 모든 정보를 갖추셨습니다. 일부 라이브러리(Python, NodeJS)는 OpenID/OAuth 프로토콜 구현을 도와줍니다.

Gradio와 huggingface.js도 내장 지원 기능을 제공하여 Sign-in with HF 버튼 구현을 쉽게 만들어 줍니다. gradio와 huggingface.js의 관련 가이드를 확인해 보세요.

기본적으로 다음을 수행해야 합니다:

  • https://huggingface.co/oauth/authorize?redirect_uri={REDIRECT_URI}&scope=openid%20profile&client_id={CLIENT_ID}&state={STATE}로 사용자를 리디렉션하세요. 여기서 STATE는 나중에 검증해야 하는 랜덤 문자열입니다.
  • /auth/callback 또는 /login/callback(또는 사용자 정의 콜백 URL)에서 콜백을 처리하고 state 매개변수를 검증합니다.
  • code 쿼리 매개변수를 사용하여 https://huggingface.co/oauth/token에서 액세스 토큰과 ID 토큰을 가져옵니다 (POST 요청으로 client_id, code, grant_type=authorization_code, redirect_uri를 폼 데이터로, Authorization: Basic {base64(client_id:client_secret)}을 헤더로 전송).

Space를 iframe 외부에서 실행하는 경우를 제외하고, 로그인 페이지를 새 탭에서 열려면 버튼에 target=_blank를 사용해야 합니다. 그렇지 않으면 일부 브라우저에서 쿠키 관련 문제가 발생할 수 있습니다.

예:

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

←Spaces 구성 참조 주요 Spaces→