SpaceにHFでのサインインボタンを追加する

Spaceで組み込みのサインインフローを有効にできます。OAuth/OpenID connectアプリをシームレスに作成して関連付けることで、ユーザーはHFアカウントでログインできます。

これにより、Space に新しいユースケースが実現可能になります。例えば、Storage Bucketsと組み合わせることで、生成 AI の Space では、ユーザーがログインして自分だけがアクセスできる過去の生成結果にアクセスできるようになります。

このガイドでは、Sign-In with HFボタンを任意のSpaceに統合する手順を説明します。GradioSpaceでこれを迅速かつ簡単に実装する方法をお探しの方は、その組み込み統合をご覧ください。

Spaces 以外のウェブサイトやアプリでも、HF OAuth フローを使用して「HF でサインイン」フローを作成できます。一般的な OAuth に関するページをご覧ください。

OAuthアプリを作成する

Spaceのメタデータにhf_oauth: trueを追加するだけです。これはREADME.mdファイル内で設定します。

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をターゲットとする限り、任意のリダイレクト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: ユーザーがアクセス権限を付与されたパブリックのゲート付きリポジトリの内容を読み取ります。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 トークンを取得します（client_id、code、grant_type=authorization_code、redirect_uri をフォームデータとして、Authorization: Basic {base64(client_id:client_secret)} をヘッダーとして含める POST リクエスト）。

スペースがiframeの外で実行されていない限り、サインインページを新しいタブで開くために、ボタンにtarget=_blankを使用する必要があります。そうしないと、一部のブラウザでクッキーに関する問題が発生する可能性があります。

例:

• Gradio テストアプリ
• HuggingChat (NodeJS/SvelteKit)
• Inference Widgets (Auth.js/SvelteKit)は、inference-apiスコープを使用して、ユーザーに代わって推論リクエストを行います。
• 静的スペースでのクライアントサイド (huggingface.js) - 非常にシンプルな JavaScript の例。

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