Hugging Face's logo

Hub documentation

Hugging Faceでサインイン

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Hugging Faceでサインイン

HF OAuth / OpenID connect フローを使用して、任意のウェブサイトやアプリで「HFでサインイン」フローを作成できます。

これにより、ユーザーはHFアカウントを使用して、次のようなボタンをクリックすることで、あなたのウェブサイトやアプリにサインインできるようになります。

Sign in with Hugging Face

このボタンをクリックすると、ユーザーにはアプリの権限を承認するための権限モーダルが表示されます:

OAuthアプリの作成

設定でアプリケーションを作成できます:

組織所有のOAuthアプリ

この機能は、Team & Enterprise プランの一部です。

OAuthアプリは、個人アカウントではなく組織によって所有されることもできます。チームで共同でメンテナンスするアプリには、単一のメンバーのアカウントに依存せず、組織に留まるため、この方式が有用です。

Organization の管理者は、Organization 設定の OAuth Apps セクション (https://huggingface.co/organizations/<your-org>/settings/applications) から、Organization が所有するアプリを作成および管理できます。Organization のすべての管理者は、アプリの編集、クライアントシークレットのローテーション、削除を行うことができます。アプリのリストには、各アプリを作成したメンバーが表示され、アプリへの変更は Organization の 監査ログ に記録されます。

同じページには、設定されている場合、その組織のToken Exchange アプリもリストされています。

組織への移管セクションから、所有する既存の OAuth アプリを、管理者として所属する組織に移管することもできます。対象の組織は、Team プランまたは Enterprise プランである必要があります。移管後、そのアプリは組織のすべての管理者によって管理されます。クライアント ID、クライアントシークレット、既存の認可およびトークンは変更されないため、ウェブサイトやアプリは変更なしで引き続き動作します。設定ページから移管を元に戻すことはできません。

パブリックOAuthアプリ（シークレットなし）

クライアントシークレットなしでOAuthアプリを作成または使用できます。これは、シークレットの管理が困難なネイティブアプリ、CLI、その他のコンテキストで便利です。

  • アプリ作成時: 新しいOAuthアプリを作成する際、シークレットなしで作成するオプションを選択できます。
  • 作成後: 既存のアプリでは、アプリ設定からクライアントシークレットを削除できます。これにより、アプリはパブリックアプリとして動作します。

パブリックアプリは、クライアント ID のみを使用して認証を行います（例: PKCE を使用したデバイスコードフローまたは認可コードフロー）。シークレットを持つアプリは、必要に応じてシークレットを引き続き使用できます（例: トークンリクエスト用のAuthorization: Basic）。

リダイレクトURI

認可リクエストで送信されるredirect_uriは、アプリに登録されたリダイレクト URI のいずれかと完全に一致する必要があります。

LoopbackリダイレクトURIは唯一の例外です。httpスキームを使用するloopbackホスト（localhost、127.0.0.1または[::1]）の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はCIMD（Client ID Metadata Documents）をサポートしており、これによりWebサイト用の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"] — リダイレクトURIを参照してください。

これは、エフェメラル環境やMCPクライアントにおいて特に有用です。Hugging Chatでの実装例を参照してください。

デバイスコードOAuth

Device code flowは、ユーザーが別のデバイス（例：スマートフォンやブラウザ）で短いコードを入力することにより、1つのデバイス（例：CLI）でアプリを認証できるようにします。アプリを実行しているデバイスにリダイレクトURIやブラウザは不要です。

サンプルスクリプトによるテスト

以下のスクリプトを使用して、デバイスコード方式のOAuthアプリをテストできます。<Client ID>をアプリのクライアントIDに置き換えてください。パブリックアプリ（シークレットなし）の場合、スクリプトはそのまま動作します。シークレット付きのアプリの場合、デバイスリクエストとトークンリクエストの両方に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"

クライアントシークレットを持つOAuthアプリの場合、デバイスコードリクエストとトークンリクエストの両方にAuthorization: Basicヘッダー（Base64エンコードされたclient_id:client_secretを含む）を含める必要があります。

現在サポートされているスコープ

現在サポートされているスコープは以下の通りです:

  • openid: アクセストークンに加えてIDトークンを受信します。
  • profile: ユーザーのプロファイル情報（ユーザー名、アバターなど）を読み取ります
  • email: ユーザーのメールアドレスを読み取ります。
  • read-billing: ユーザーが支払い方法を設定しているかどうかを確認します。
  • read-memberships: ユーザーが所属する組織および各組織における役割を読み取ります。これにより、組織の設定やリソースへのアクセス権は付与されません。
  • read-repos: ユーザーの個人リポジトリを読み取ります。
  • gated-repos: ユーザーがアクセス権限を付与されたパブリックのゲート付きリポジトリの内容を読み取ります。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 メタデータで利用可能です。

追加のスコープが必要な場合は、お問い合わせください。

組織のリソースへのアクセス

デフォルトでは、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 など）は、文字列の配列を含むクレームからグループのメンバーシップを同期でき、groupsクレームで設定されることがよくあります。これを使用して、Hugging Face の組織をアプリ内のロールやグループにマッピングできます。各組織の詳細（ID、ロールなど）については、代わりにorgsフィールドを使用してください。

いくつかの注意点を以下に示します。

  • groupsクレームは、IDトークンではなく、userinfoエンドポイントでのみ返されます。
  • 組織名が含まれており、IDではありません。組織がリネームされた場合、その旧名を使用しているマッピングは一致しなくなります。
  • リソースグループは含まれません。有料プランの組織では、ユーザーのリソースグループとロールがorgs[].resourceGroupsにリストされます。

ブランディング

ボタンのデザインは自由に決めてください。以下に、ご提供いただいたSVG画像をいくつか示します。

MarkdownまたはHTMLに統合するための説明付きのバッジをご覧ください。

Sign in with Hugging Face Sign in with Hugging Face

Sign in with Hugging Face Sign in with Hugging Face

Sign in with Hugging Face Sign in with Hugging Face

Sign in with Hugging Face Sign in with Hugging Face

組織向けトークン交換 (RFC 8693)

この機能はEnterpriseプランの一部です。

Token Exchange は、組織がインタラクティブなユーザーの同意を必要とせずに、そのメンバーのアクセストークンをプログラムで発行できるようにします。これは、組織メンバーに代わって Hugging Face リソースにアクセスする必要がある内部ツール、自動化パイプライン、エンタープライズ統合の構築に特に有用です。

CI/CD ワークフロー（GitHub Actions、GitLab CI、CircleCI など）からのキーレス認証のみが必要で、メンバーごとのトークン発行は不要な場合は、Trusted Publishersを参照してください。この機能も/oauth/tokenを使用しますが、CI プロバイダーが発行した OIDC のid_tokenをサブジェクト トークンとして使用します（Enterprise プランは不要、クライアント認証情報も不要）。

この機能は、トークン交換シナリオのための標準プロトコルである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 サポートにお問い合わせください。

設定が完了すると、以下を受け取れます:

  • クライアント ID（例: a1b2c3d4-e5f6-7890-abcd-ef1234567890）
  • Client Secret（これを安全に保管してください！）

組織管理者は、OAuth アプリの作成後、クライアントシークレットの更新やトークンの有効期間の設定など、アプリの管理を行うことができます。このアプリは、組織設定のOAuth Appsセクションにリスト表示され、その変更内容は組織の監査ログに記録されます。

認証

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アプリの認証情報を慎重に保護してください。クライアントシークレットへのアクセス権限を持つ者は、あなたの組織のすべてのメンバーに対してトークンを発行できます。

エラー応答

エラー説明
invalid_clientクライアントがトークン交換の使用を許可されていません。または、アプリが組織にバインドされていません
invalid_grantバインドされた組織にユーザーが見つかりません
invalid_scope要求されたスコープは有効ではありません

リファレンス

グラントタイプ:

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

リクエストパラメータ（subject_token_type）:

値説明
urn:huggingface:token-type:user-emailメールアドレスでユーザーを識別します

レスポンスフィールド（issued_token_type）:

値説明
urn:ietf:params:oauth:token-type:access_tokenアクセストークンが発行されたことを示します

関連ドキュメント:

Update on GitHub

←Hub API エンドポイント