# Hugging Faceでサインイン

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

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

![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-xl-dark.svg)

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

![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/oauth-accept-application.png)

## OAuthアプリの作成

[設定](https://huggingface.co/settings/applications/new)でアプリケーションを作成できます:

	
	

### 組織所有のOAuthアプリ

> [!WARNING]
> この機能は、Team & Enterprise プランの一部です。

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

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

	
	

同じページには、設定されている場合、その組織の[Token Exchange アプリ](#token-exchange-for-organizations-rfc-8693)もリストされています。

**組織への移管**セクションから、所有する既存の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](https://datatracker.ietf.org/doc/html/rfc8252#section-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でホスティングしている場合

> [!TIP]
> アプリを Spaces にホストしている場合、フローの実装はさらに簡単になります（Gradio に直接組み込まれています）。[Spaces OAuth ガイド](https://huggingface.co/docs/hub/spaces-oauth)をご覧ください。

### 自動OAuthアプリの作成

Hugging FaceはCIMD（[Client ID Metadata Documents](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)）をサポートしており、これによりWebサイト用のoauthアプリを自動で作成できます：

- `/.well-known/oauth-cimd` というエンドポイントをウェブサイトに追加し、以下の JSON を返すようにしてください。

```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](#redirect-uris)を参照してください。

これは、エフェメラル環境やMCPクライアントにおいて特に有用です。Hugging Chatでの[実装例](https://github.com/huggingface/chat-ui/pull/1978)を参照してください。

## デバイスコードOAuth

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

![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/oauth-device-first-step.png)

![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/oauth-device-second-step.png)

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

以下のスクリプトを使用して、デバイスコード方式のOAuthアプリをテストできます。`<Client ID>`をアプリのクライアントIDに置き換えてください。**パブリックアプリ**（シークレットなし）の場合、スクリプトはそのまま動作します。**シークレット付きのアプリ**の場合、デバイスリクエストとトークンリクエストの両方に`Authorization: Basic`ヘッダー（`client_id:client_secret`のBase64エンコード）を追加してください。

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

> [!NOTE]
> クライアントシークレットを持つ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](https://huggingface.co/docs/inference-providers/index) に対して推論リクエストを送信します。
- `read-endpoints`: ユーザーの[Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index)を表示し、ユーザーに代わってそれらに対して推論リクエストを送信します。
- `write-endpoints`: ユーザーの Inference Endpoints を管理します。作成と削除を含みます。`read-endpoints` アクセスが含まれます。
- `jobs`: [jobs](https://huggingface.co/docs/huggingface_hub/main/en/guides/jobs)を実行
- `webhooks`: [webhooks](https://huggingface.co/docs/huggingface_hub/main/en/guides/webhooks)の管理
- `write-discussions`: ユーザーに代わってディスカッションや Pull Request を作成し、ディスカッションとのやり取り（リアクション、コメントの投稿/編集、ディスカッションのクローズなど）を行います。プライベートリポジトリで Pull Request を作成するには、`read-repos` スコープもリクエストする必要があります。

その他のすべての情報は、[OpenID メタデータ](https://huggingface.co/.well-known/openid-configuration)で利用可能です。

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

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

デフォルトでは、oauth アプリは組織リソースにアクセスする必要はありません。

ただし、`read-repos` や `read-billing` などのスコープは、組織にも適用されます。

ユーザーは、アプリを認可する際にアクセスを許可する組織を選択できます。特定の組織へのアクセスを必須とする場合は、OAuth 認可 URL にクエリパラメータとして`orgIds=ORG_ID`を追加できます。組織 ID は、userinfo レスポンスの`orgs[].sub`フィールドで確認できます。

## 組織のメンバーシップをグループとして同期する

userinfo レスポンス（`https://huggingface.co/oauth/userinfo`）には、`groups` クレームが含まれます。これは、ユーザーが所属する組織の名前を文字列の配列として表したものです。

```json
{
  "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に統合するための説明付きの[バッジ](https://huggingface.co/datasets/huggingface/badges#sign-in-with-hugging-face)をご覧ください。

[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-sm.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)
[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-sm-dark.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)

[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-md.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)
[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-md-dark.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)

[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-lg.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)
[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-lg-dark.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)

[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-xl.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)
[![Sign in with Hugging Face](https://huggingface.co/datasets/huggingface/badges/resolve/main/sign-in-with-huggingface-xl-dark.svg)](https://huggingface.co/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=openid%20profile&state=STATE)

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

> [!WARNING]
> この機能はEnterpriseプランの一部です。

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

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

この機能は、トークン交換シナリオのための標準プロトコルである[RFC 8693 - OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html)を実装しています。

### ユースケース

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**（これを安全に保管してください！）

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

### 認証

Token Exchange は、OAuth アプリの認証情報を使用して HTTP Basic Authentication を使用します。`client_id:client_secret` を Base64 エンコードして、認可ヘッダーを作成します。

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

### メールによるトークンの発行

メールアドレスを使用して、組織メンバーのアクセストークンを発行するには:

```bash
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"
```

### 応答

正常にリクエストが完了すると、アクセストークンが返されます:

```json
{
  "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リクエストを行うことができます。

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

### スコープの制御

デフォルトでは、発行されたトークンはOAuthアプリに設定されたすべてのスコープを継承します。`scope`パラメータを追加することで、特定のスコープをリクエストできます。利用可能な値については、[現在サポートされているスコープ](#currently-supported-scopes)を参照してください。

トークンの有効な権限は、要求されたスコープと、組織内でのユーザーのロールの両方によって制限されます。

```bash
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"
```

> [!TIP]
> 最小権限の原則に従い、アプリケーションが実際に必要とするスコープのみを要求してください。

### セキュリティに関する考慮事項

Token Exchange によって発行されたトークンには、組み込みのセキュリティ制限があります:

- **組織スコープ**: トークンは、その組織内のリソース（組織が所有するモデル、データセット、Spaces、コレクション）にのみアクセスできます。組織外では、アクセスは読み取り専用となり、以下の範囲に限定されます。すべてのユーザーまたは組織の公開コレクション、およびユーザーに個別にアクセス権が付与された公開ゲート付きリポジトリ。
- **個人アクセスなし**: トークンは、ユーザーの個人用プライベートリポジトリや、他の組織のプライベートリポジトリにアクセスできません。
- **短期間**: トークンはデフォルトで8時間後に期限切れになります。組織管理者は、OAuthアプリの設定でトークンの有効期間（最大30日）を設定できます。リフレッシュトークンは提供されません。
- **監査可能**: すべてのトークン交換は記録され、組織の[監査ログ](./audit-logs)で確認できます。

> [!WARNING]
> 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` | アクセストークンが発行されたことを示します |

**関連ドキュメント:**
- [RFC 8693 - OAuth 2.0 トークン交換](https://www.rfc-editor.org/rfc/rfc8693.html)
- [監査ログ](./audit-logs)