Hugging Face로 로그인

HF OAuth / OpenID connect 플로우를 사용하여 어떤 웹사이트나 앱에서도 “Sign in with HF” 플로우를 만들 수 있습니다.

이 기능을 사용하면 사용자는 다음과 유사한 버튼을 클릭하여 HF 계정으로 웹사이트 또는 앱에 로그인할 수 있습니다:

이 버튼을 클릭하면 사용자에게 앱 권한을 승인하도록 요청하는 권한 모달이 표시됩니다:

OAuth 앱 만들기

설정에서 애플리케이션을 생성할 수 있습니다:

조직 소유의 OAuth 앱

이 기능은 Team & Enterprise 플랜의 일부입니다.

OAuth 앱은 개인 계정 대신 조직이 소유할 수도 있습니다. 이는 팀이 함께 유지 관리하는 앱에 유용하며, 단일 멤버의 계정에 의존하지 않고 조직에 남아 있게 됩니다.

조직 관리자는 조직 설정의 OAuth Apps 섹션(https://huggingface.co/organizations/<your-org>/settings/applications)에서 조직 소유의 앱을 생성하고 관리할 수 있습니다. 조직의 모든 관리자는 해당 앱을 편집하거나, client secret을 회전하거나, 삭제할 수 있습니다. 앱 목록에는 각 앱을 생성한 멤버가 표시되며, 앱에 대한 변경 사항은 조직의 audit logs에 기록됩니다.

같은 페이지에는 설정된 경우 해당 조직의 Token Exchange 앱도 나열됩니다.

본인이 소유한 기존 OAuth 앱을 관리 권한이 있는 조직으로 이전할 수 있으며, 앱 설정 페이지의 조직으로 이전 섹션에서 수행할 수 있습니다. 대상 조직은 Team 또는 Enterprise 플랜에 가입되어 있어야 합니다. 이전이 완료되면 해당 앱은 조직의 모든 관리자에 의해 관리됩니다. 클라이언트 ID, 클라이언트 시크릿, 기존 승인 및 토큰은 그대로 유지되므로 웹사이트나 앱은 변경 없이 계속 작동합니다. 설정 페이지에서 이전을 되돌릴 수 없습니다.

공개 OAuth 앱(비밀 없음)

클라이언트 시크릿 없이 OAuth 앱을 생성하거나 사용할 수 있습니다. 이는 시크릿을 유지하는 것이 비현실적인 네이티브 앱, CLI 또는 기타 컨텍스트에서 유용합니다.

• 앱 생성 시: 새로운 OAuth 앱을 생성할 때, 시크릿 없이 생성하도록 선택할 수 있습니다.
• 생성 후: 기존 앱의 경우, 앱 설정에서 클라이언트 시크릿을 삭제할 수 있습니다. 그러면 해당 앱은 공개 앱으로 작동합니다.

공개 앱은 클라이언트 ID만 사용하여 인증합니다(예: PKCE를 사용하는 디바이스 코드 또는 인가 코드 플로우). 시크릿이 있는 앱은 필요할 때 시크릿을 계속 사용할 수 있습니다(예: 토큰 요청에 Authorization: Basic 사용).

리다이렉트 URI

인가 요청에 전송되는 redirect_uri는 앱에 등록된 리다이렉트 URI 중 하나와 정확히 일치해야 합니다.

Loopback redirect URI는 유일한 예외입니다: localhost, 127.0.0.1 또는 [::1]과 같은 loopback 호스트에서 http 스킴을 사용하는 URI의 경우, 요청 시점에 모든 다른 구성 요소가 등록된 URI와 일치하는 한 어떤 포트도 허용됩니다. 이는 RFC 8252 §7.3 / OAuth 2.1을 따르며, 네이티브 앱, CLI 및 MCP 클라이언트가 http://localhost/callback과 같은 포트가 없는 URI를 등록한 후 운영 체제가 할당하는 임의의 임시 포트(예: http://localhost:49282/callback)에서 리스닝할 수 있도록 합니다.

다음 사항을 유의하세요:

• 이 예외는 http 스킴에만 적용됩니다. https 및 사용자 정의 스킴(예: myapp://callback) 리다이렉트 URI는 포트 포함을 항상 정확한 일치로 요구합니다.
• Loopback 호스트는 개별적으로 일치합니다: http://localhost:49282/callback에 대한 요청은 등록된 http://127.0.0.1/callback과 일치하지 않습니다. 앱이 둘 중 하나를 사용할 수 있다면 둘 다 등록하세요.
• 포트만 다를 수 있습니다. 경로, 쿼리, userinfo는 여전히 정확히 일치해야 합니다.

Spaces에서 호스팅하는 경우

앱을 Spaces에 호스팅하는 경우, 플로우를 구현하는 것이 훨씬 쉬워지며(Gradio에 직접 내장되어 있음); Spaces OAuth 가이드를 확인해 보세요.

자동화된 oauth 앱 생성

Hugging Face는 Client ID Metadata Documents라고도 알려진 CIMD를 지원하여 웹사이트용 oauth 앱을 자동으로 생성할 수 있습니다:

• 웹사이트에 /.well-known/oauth-cimd 엔드포인트를 추가하여 다음 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
}

• 클라이언트 ID로 "[your website url]/.well-known/oauth-cimd"를 사용하고, 인증 메커니즘으로 PCKE를 사용하세요

로컬 포트에서 인가 코드를 수신하는 네이티브 앱 및 MCP 클라이언트는 redirect_uris에 포트가 없는 루프백 URI를 나열할 수 있습니다. 예를 들어 ["http://localhost/callback", "http://127.0.0.1/callback"] — Redirect URIs를 참조하세요.

일회성 환경이나 MCP 클라이언트에서 특히 유용합니다. Hugging Chat의 구현 예시를 참고하세요.

Device code OAuth

Device code flow는 사용자가 짧은 코드를 다른 장치(예: 휴대폰 또는 브라우저)에 입력하여 한 장치(예: CLI)에서 앱을 승인할 수 있도록 합니다. 앱을 실행하는 장치에는 redirect URI나 브라우저가 필요하지 않습니다.

샘플 스크립트로 테스트

다음 스크립트로 device-code OAuth 앱을 테스트할 수 있습니다. <Client ID>를 앱의 client ID로 교체하세요. 공개 앱(비밀번호 없음)의 경우, 스크립트를 그대로 사용할 수 있습니다. 비밀번호가 있는 앱의 경우, device 요청과 token 요청 모두에 Authorization: Basic 헤더(client_id:client_secret의 Base64)를 추가해야 합니다.

#!/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"

client secret가 있는 OAuth 앱의 경우, device code 요청과 token 요청 모두에 Authorization: Basic 헤더(Base64로 인코딩된 client_id:client_secret 포함)를 포함해야 합니다.

현재 지원되는 범위

현재 지원되는 스코프는 다음과 같습니다:

• openid: 액세스 토큰 외에 ID 토큰을 수신합니다.
• profile: 사용자의 프로필 정보(사용자 이름, 아바타 등)를 읽습니다
• 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 스코프도 요청해야 합니다.

그 외 모든 정보는 OpenID metadata에서 확인할 수 있습니다.

추가 범위가 필요하신 경우, 저희에게 연락해 주세요.

조직 리소스에 액세스

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

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

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

조직 멤버십을 그룹으로 동기화

userinfo 응답(https://huggingface.co/oauth/userinfo)에는 groups 클레임이 포함되어 있습니다. 이 클레임은 사용자가 속한 조직의 이름을 문자열 배열로 제공합니다.

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

많은 OIDC 클라이언트(예: Discourse, Grafana, Argo CD, Vault, Kubernetes)는 문자열 배열을 포함하는 claim에서 그룹 멤버십을 동기화할 수 있으며, groups claim으로 구성된 경우가 많습니다. 이를 사용하여 Hugging Face 조직을 애플리케이션의 역할 또는 그룹으로 매핑할 수 있습니다. 각 조직에 대한 세부 정보(ID, 역할 등)는 orgs 필드를 사용하세요.

다음 사항을 유의하세요:

• groups 클레임은 ID 토큰이 아닌 userinfo 엔드포인트에서만 반환됩니다.
• 조직 ID가 아닌 조직 이름을 포함합니다. 조직 이름이 변경되면, 이전 이름을 사용하는 매핑은 더 이상 일치하지 않습니다.
• 리소스 그룹은 포함되지 않습니다. 유료 플랜의 조직에 대해 사용자의 리소스 그룹과 역할은 orgs[].resourceGroups에 나열됩니다.

브랜딩

버튼 디자인은 자유롭게 선택할 수 있습니다. 아래에는 유용하게 제공된 몇 가지 SVG 이미지가 있습니다.

마크다운 또는 HTML에 통합하는 방법에 대한 설명이 포함된 배지를 확인해 보세요.

조직용 토큰 교환 (RFC 8693)

이 기능은 Enterprise 플랜의 일부입니다.

Token Exchange는 조직이 조직 구성원을 대신하여 Hugging Face 리소스에 액세스할 때 상호작용적인 사용자 동의 없이 액세스 토큰을 프로그래매틱으로 발급할 수 있도록 합니다. 이는 조직 구성원을 대신하여 Hugging Face 리소스에 액세스해야 하는 내부 도구, 자동화 파이프라인, 엔터프라이즈 통합을 구축하는 데 특히 유용합니다.

CI/CD 워크플로(GitHub Actions, GitLab CI, CircleCI, …)에서 키리스 인증만 필요하고 멤버별 토큰 발급이 필요하지 않다면, /oauth/token을 사용하되 CI 제공자가 발급한 OIDC id_token을 subject token으로 사용하는 Trusted Publishers를 참고하세요(Enterprise 플랜 불필요, client credentials 불필요).

이 기능은 토큰 교환 시나리오를 위한 표준 프로토콜인 RFC 8693 - OAuth 2.0 Token Exchange를 구현합니다.

사용 사례

Token Exchange는 조직이 다음이 필요한 시나리오를 위해 설계되었습니다:

• 내부 플랫폼 구축: 각 사용자가 수동으로 인증할 필요 없이 팀 구성원을 대신하여 Hugging Face 리소스에 접근하는 대시보드나 포털을 만듭니다.
• CI/CD 파이프라인 자동화: 조직 저장소에 모델 또는 데이터셋을 푸시해야 하는 자동화 워크플로우에는 단기적이고 범위가 제한된 토큰을 발급하세요.
• 엔터프라이즈 ID 시스템과 통합: 내부 사용자 디렉토리를 기반으로 토큰을 발급하여 기존 ID 제공자와 Hugging Face를 연결합니다.
• 사용자 정의 액세스 제어 구현: 조직의 내부 정책에 따라 특정 스코프가 포함된 토큰을 발급하는 미들웨어를 구축합니다.

작동 방식

1. 조직에는 token-exchange 권한이 있는 OAuth 애플리케이션이 연결되어 있습니다.
2. 백엔드 서비스는 이 OAuth 앱을 사용하여 클라이언트 자격 증명으로 인증합니다.
3. 서비스는 특정 조직 멤버(이메일로 식별)에 대한 액세스 토큰을 요청합니다.
4. Hugging Face는 사용자가 해당 조직의 멤버인지 확인한 후 스코프가 지정된 토큰을 발급합니다.
5. 발급된 토큰은 조직의 범위 내 리소스에만 액세스할 수 있습니다.

필수 조건

Token Exchange를 사용하려면 token-exchange 권한이 있는 조직 연결 OAuth 애플리케이션이 필요합니다. 조직에 적합한 OAuth 앱을 설정하려면 Hugging Face 지원팀에 문의하세요.

구성하면 다음을 받게 됩니다:

• Client ID(예: a1b2c3d4-e5f6-7890-abcd-ef1234567890)
• Client Secret(이것은 안전하게 보관하세요!)

조직 관리자는 생성 후 OAuth 앱을 관리할 수 있으며, 여기에는 클라이언트 시크릿을 새로고침하고 토큰 지속 시간을 구성하는 작업이 포함됩니다. 해당 앱은 조직 설정의 OAuth Apps 섹션에 나열되며, 앱에 대한 변경 사항은 조직의 audit logs에 기록됩니다.

인증

Token Exchange는 OAuth 앱 자격 증명을 사용하여 HTTP Basic Authentication을 사용합니다. client_id:client_secret을 Base64로 인코딩하여 인증 헤더를 생성합니다:

# 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)

이메일로 토큰 발급

이메일 주소를 사용하여 조직 멤버의 액세스 토큰을 발급하려면:

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"

응답

성공적인 요청은 액세스 토큰을 반환합니다:

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

openid 스코프가 요청되면 id_token 필드가 포함됩니다.

이 토큰을 사용하여 사용자를 대신해 API 요청을 보낼 수 있습니다:

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

범위 제어

기본적으로 발급된 토큰은 OAuth 앱에 구성된 모든 스코프를 상속합니다. scope 매개변수를 추가하여 특정 스코프를 요청할 수 있습니다. 사용 가능한 값은 현재 지원되는 스코프를 참조하세요.

토큰의 유효한 권한은 요청된 스코프와 조직 내 사용자 역할에 의해 모두 제한됩니다.

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"

최소 권한 원칙을 따르세요: 애플리케이션이 실제로 필요한 스코프만 요청하세요.

보안 고려 사항

Token Exchange를 통해 발급된 토큰에는 내장된 보안 제한이 있습니다:

• 조직 범위: 토큰은 조직 내 리소스(조직이 소유한 모델, 데이터셋, Spaces, 컬렉션)에만 접근할 수 있습니다. 조직 외부에서는 읽기 전용 접근만 가능하며, 다음으로 제한됩니다. 모든 사용자 또는 조직의 공개 컬렉션, 그리고 해당 사용자에게 개별적으로 접근 권한이 부여된 공개 게이트드 리포지토리.
• 개인 액세스 없음: 토큰은 사용자의 개인 비공개 저장소 또는 다른 조직의 비공개 저장소에 액세스할 수 없습니다.
• 단기 유효: 토큰은 기본적으로 8시간 후 만료됩니다. 조직 관리자는 OAuth 앱 설정에서 토큰 유효 기간(최대 30일)을 설정할 수 있습니다. 리프레시 토큰은 제공되지 않습니다.
• 감사 가능: 모든 토큰 교환은 기록되며 조직의 감사 로그에서 확인할 수 있습니다.

OAuth 앱 자격 증명을 주의 깊게 보호하세요. 클라이언트 시크릿에 접근할 수 있는 사람은 조직의 모든 멤버에 대해 토큰을 발급할 수 있습니다.

오류 응답

참고

권한 유형:

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

요청 매개변수(subject_token_type):

응답 필드 (issued_token_type):

관련 문서:

• RFC 8693 - OAuth 2.0 토큰 교환
• 감사 로그