Masuk dengan Hugging Face

Anda dapat menggunakan alur HF OAuth / OpenID connect untuk membuat alur “Sign in with HF” di situs web atau Aplikasi mana pun.

Hal ini akan memungkinkan pengguna untuk masuk ke situs web atau aplikasi Anda menggunakan akun HF mereka, dengan mengklik tombol yang mirip dengan ini:

Setelah mengklik tombol ini, pengguna Anda akan ditampilkan modal izin untuk mengotorisasi aplikasi Anda:

Membuat aplikasi oauth

Anda dapat membuat aplikasi Anda di pengaturan Anda:

Aplikasi OAuth yang dimiliki organisasi

Fitur ini merupakan bagian dari paket Team & Enterprise.

Aplikasi OAuth juga dapat dimiliki oleh organisasi, bukan akun individu. Hal ini berguna untuk aplikasi yang dipelihara bersama oleh tim Anda, karena aplikasi tersebut tetap berada di bawah organisasi alih-alih bergantung pada akun satu anggota.

Admin organisasi dapat membuat dan mengelola aplikasi yang dimiliki organisasi dari bagian OAuth Apps pada pengaturan organisasi (https://huggingface.co/organizations/<your-org>/settings/applications). Semua admin organisasi dapat mengedit aplikasi, memutar ulang client secret-nya, atau menghapusnya. Daftar aplikasi menunjukkan anggota mana yang membuat setiap aplikasi, dan perubahan pada aplikasi dicatat dalam audit logs organisasi.

Halaman yang sama juga mencantumkan Token Exchange app organisasi, jika sudah diatur.

Anda juga dapat memindahkan aplikasi OAuth yang sudah ada dan Anda miliki ke organisasi tempat Anda menjadi admin, melalui bagian Transfer to an organization di halaman pengaturan aplikasi. Organisasi tersebut harus menggunakan paket Team atau Enterprise. Setelah pemindahan, aplikasi dikelola oleh semua admin organisasi. Client ID, client secret, serta otorisasi dan token yang sudah ada tetap sama, sehingga situs web atau aplikasi Anda tetap berfungsi tanpa perubahan. Pemindahan tidak dapat dibatalkan dari halaman pengaturan.

Aplikasi OAuth publik (tanpa rahasia)

Anda dapat membuat atau menggunakan aplikasi OAuth tanpa client secret. Hal ini berguna untuk aplikasi native, CLI, atau konteks lain di mana menjaga kerahasiaan secret tidak praktis.

• Saat pembuatan aplikasi: Saat membuat aplikasi OAuth baru, Anda dapat memilih untuk membuatnya tanpa secret.
• Setelah dibuat: Untuk aplikasi yang sudah ada, Anda dapat menghapus rahasia klien di pengaturan aplikasi. Aplikasi tersebut kemudian akan berfungsi sebagai aplikasi publik.

Aplikasi publik melakukan autentikasi hanya menggunakan client ID (misalnya dalam alur kode perangkat atau alur kode otorisasi dengan PKCE). Aplikasi yang memiliki secret masih dapat menggunakan secret tersebut saat diperlukan (misalnya Authorization: Basic untuk permintaan token).

URI pengalihan

redirect_uri yang dikirim dalam permintaan otorisasi harus persis cocok dengan salah satu URI redirect yang terdaftar di aplikasi Anda.

URI redirect loopback adalah satu-satunya pengecualian: untuk URI yang menggunakan skema http pada host loopback (localhost, 127.0.0.1 atau [::1]), port apa pun diterima saat permintaan, selama setiap komponen lainnya cocok dengan URI yang terdaftar. Hal ini mengikuti RFC 8252 §7.3 / OAuth 2.1, dan memungkinkan aplikasi native, CLI, dan klien MCP untuk mendaftarkan URI tanpa port seperti http://localhost/callback dan kemudian mendengarkan pada port ephemeral apa pun yang ditetapkan oleh sistem operasi (misalnya http://localhost:49282/callback).

Beberapa hal yang perlu diperhatikan:

• Pengecualian ini hanya berlaku untuk skema http. URI redirect dengan skema https dan skema kustom (misalnya myapp://callback) selalu memerlukan kecocokan persis, termasuk port.
• Host loopback dicocokkan secara individual: permintaan untuk http://localhost:49282/callback tidak cocok dengan http://127.0.0.1/callback yang terdaftar. Daftarkan keduanya jika aplikasi Anda mungkin menggunakan salah satunya.
• Hanya port yang mungkin berbeda. Path, query, dan userinfo harus tetap cocok secara persis.

Jika Anda meng-hosting di Spaces

Jika Anda meng-hosting aplikasi Anda di Spaces, alurnya akan lebih mudah diimplementasikan (dan sudah dibangun langsung di Gradio); lihat panduan OAuth Spaces kami.

Pembuatan aplikasi oauth otomatis

Hugging Face mendukung CIMD alias Client ID Metadata Documents, yang memungkinkan Anda membuat aplikasi oauth untuk situs web Anda secara otomatis:

• Tambahkan endpoint ke situs web Anda di /.well-known/oauth-cimd yang mengembalikan JSON berikut:

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

• Gunakan "[your website url]/.well-known/oauth-cimd" sebagai client ID, dan PCKE sebagai mekanisme autentikasi

Aplikasi native dan klien MCP yang menerima kode otorisasi pada port lokal dapat mencantumkan URI loopback tanpa port di redirect_uris, misalnya ["http://localhost/callback", "http://127.0.0.1/callback"] — lihat Redirect URIs.

Hal ini sangat berguna untuk lingkungan sementara atau klien MCP. Lihat contoh implementasi di Hugging Chat.

OAuth kode perangkat

Device code flow memungkinkan pengguna mengotorisasi aplikasi di satu perangkat (misalnya CLI) dengan memasukkan kode pendek di perangkat lain (misalnya ponsel atau browser). Tidak diperlukan redirect URI atau browser di perangkat yang menjalankan aplikasi.

Menguji dengan skrip sampel

Anda dapat menguji aplikasi OAuth device-code dengan skrip berikut. Ganti <Client ID> dengan client ID aplikasi Anda. Untuk aplikasi publik (tanpa secret), skrip ini berfungsi apa adanya. Untuk aplikasi dengan secret, tambahkan header Authorization: Basic (Base64 dari client_id:client_secret) ke kedua permintaan device dan token.

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

Untuk aplikasi OAuth yang memiliki client secret, sertakan header Authorization: Basic (dengan client_id:client_secret yang di-encode Base64) pada permintaan kode perangkat dan permintaan token.

Cakupan yang saat ini didukung

Scope yang didukung saat ini adalah:

• openid: Menerima token ID di samping token akses.
• profile: Membaca informasi profil pengguna (nama pengguna, avatar, dll.)
• email: Membaca alamat email pengguna.
• read-billing: Mengetahui apakah pengguna telah mengatur metode pembayaran.
• read-memberships: Membaca organisasi mana yang menjadi anggota pengguna, serta peran mereka di masing-masing organisasi. Ini tidak memberikan akses ke pengaturan atau sumber daya organisasi.
• read-repos: Membaca repositori pribadi pengguna.
• gated-repos: Membaca konten repositori publik yang terkunci (gated) yang aksesnya telah diberikan kepada pengguna. Berbeda dengan read-repos, ini tidak memberikan akses ke repositori privat.
• contribute-repos: Membuat repositori dan mengakses repositori yang dibuat oleh aplikasi ini. Tidak dapat mengakses repositori lain kecuali izin tambahan diberikan.
• write-repos: Membaca dan menulis repositori pribadi pengguna.
• manage-repos: Kelola sepenuhnya repositori pribadi pengguna, termasuk membuat dan menghapusnya.
• read-collections: Membaca koleksi pribadi pengguna.
• write-collections: Membaca dan menulis koleksi pribadi pengguna, termasuk membuat dan menghapusnya.
• inference-api: Membuat permintaan inferensi ke Inference Providers atas nama pengguna.
• read-endpoints: Menampilkan Inference Endpoints pengguna dan membuat permintaan inferensi ke endpoint tersebut atas nama pengguna.
• write-endpoints: Mengelola Inference Endpoints pengguna, termasuk membuat dan menghapusnya. Termasuk akses read-endpoints.
• jobs: Jalankan jobs
• webhooks: Kelola webhooks
• write-discussions: Membuka diskusi dan Pull Requests atas nama pengguna serta berinteraksi dengan diskusi (termasuk reaksi, memposting/mengedit komentar, menutup diskusi, …). Untuk membuka Pull Requests pada repositori privat, Anda juga perlu meminta scope read-repos.

Semua informasi lainnya tersedia di metadata OpenID.

Hubungi kami jika Anda memerlukan cakupan tambahan.

Mengakses sumber daya organisasi

Secara default, aplikasi oauth tidak perlu mengakses sumber daya organisasi.

Namun beberapa scope seperti read-repos atau read-billing juga berlaku untuk organisasi.

Pengguna dapat memilih organisasi mana yang akan diberikan akses saat mengotorisasi aplikasi. Jika Anda memerlukan akses ke organisasi tertentu, Anda dapat menambahkan orgIds=ORG_ID sebagai parameter kueri ke URL otorisasi OAuth. ID organisasi tersedia di field orgs[].sub dari respons userinfo.

Sinkronisasi keanggotaan organisasi sebagai grup

Respons userinfo (https://huggingface.co/oauth/userinfo) mencakup klaim groups: nama-nama organisasi yang menjadi keanggotaan pengguna, sebagai array string.

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

Banyak klien OIDC (misalnya Discourse, Grafana, Argo CD, Vault, Kubernetes) dapat menyinkronkan keanggotaan grup dari klaim yang berisi array string, dan sering dikonfigurasi dengan klaim groups. Anda dapat menggunakannya untuk memetakan organisasi Hugging Face ke peran atau grup di aplikasi Anda. Untuk detail lebih lanjut tentang setiap organisasi (ID, peran, dll.), gunakan field orgs sebagai gantinya.

Beberapa hal yang perlu diperhatikan:

• Klaim groups hanya dikembalikan oleh endpoint userinfo, bukan di dalam ID token.
• Isi di dalamnya adalah nama organisasi, bukan ID. Jika sebuah organisasi diubah namanya, pemetaan yang menggunakan nama lamanya akan berhenti cocok.
• Grup sumber daya tidak disertakan. Untuk organisasi dengan paket berbayar, grup sumber daya dan peran pengguna terdaftar di orgs[].resourceGroups.

Branding

Anda bebas menggunakan desain sendiri untuk tombol. Di bawah ini adalah beberapa gambar SVG yang disediakan dengan senang hati.

Lihat badge kami beserta penjelasan untuk mengintegrasikannya dalam markdown atau HTML.

Token Exchange untuk Organisasi (RFC 8693)

Fitur ini merupakan bagian dari paket Enterprise.

Token Exchange memungkinkan organisasi untuk menerbitkan token akses secara programatik bagi anggotanya tanpa memerlukan persetujuan pengguna interaktif. Hal ini sangat berguna untuk membangun alat internal, pipeline otomasi, dan integrasi perusahaan yang perlu mengakses sumber daya Hugging Face atas nama anggota organisasi.

Jika Anda hanya memerlukan autentikasi tanpa kunci dari alur kerja CI/CD (GitHub Actions, GitLab CI, CircleCI, …) — tanpa penerbitan token per anggota — lihat Trusted Publishers, yang juga menggunakan /oauth/token tetapi mengambil id_token OIDC yang diterbitkan oleh penyedia CI Anda sebagai token subjek (tidak memerlukan paket Enterprise, tidak memerlukan kredensial klien).

Fitur ini mengimplementasikan RFC 8693 - OAuth 2.0 Token Exchange, sebuah protokol standar untuk skenario pertukaran token.

Kasus penggunaan

Token Exchange dirancang untuk skenario di mana organisasi Anda perlu:

• Membangun platform internal: Buat dasbor atau portal yang mengakses sumber daya Hugging Face atas nama anggota tim Anda, tanpa mengharuskan setiap pengguna untuk melakukan autentikasi secara manual.
• Otomatiskan pipeline CI/CD: Terbitkan token jangka pendek dengan cakupan terbatas untuk alur kerja otomatis yang perlu mendorong model atau dataset ke repositori organisasi.
• Integrasi dengan sistem identitas perusahaan: Hubungkan penyedia identitas Anda yang ada dengan Hugging Face dengan menerbitkan token berdasarkan direktori pengguna internal Anda.
• Implement kontrol akses kustom: Bangun middleware yang menerbitkan token dengan cakupan spesifik berdasarkan kebijakan internal organisasi Anda.

Cara kerjanya

1. Organisasi Anda memiliki aplikasi OAuth yang terikat ke organisasi Anda dengan hak istimewa token-exchange.
2. Layanan backend Anda melakukan autentikasi dengan aplikasi OAuth ini menggunakan kredensial klien.
3. Layanan Anda meminta token akses untuk anggota organisasi tertentu (diidentifikasi melalui email).
4. Hugging Face memverifikasi bahwa pengguna adalah anggota organisasi Anda dan menerbitkan token berscope.
5. Token yang diterbitkan hanya dapat mengakses sumber daya dalam cakupan organisasi Anda.

Prasyarat

Untuk menggunakan Token Exchange, Anda memerlukan aplikasi OAuth yang terikat pada organisasi dengan hak istimewa token-exchange. Hubungi dukungan Hugging Face untuk mengatur aplikasi OAuth yang memenuhi syarat untuk organisasi Anda.

Setelah dikonfigurasi, Anda akan menerima:

• ID Klien (misalnya, a1b2c3d4-e5f6-7890-abcd-ef1234567890)
• Rahasia Klien (jaga kerahasiaannya!)

Administrator organisasi dapat mengelola aplikasi OAuth setelah dibuat, termasuk memperbarui rahasia klien dan mengatur durasi token. Aplikasi tersebut terdaftar di bagian OAuth Apps dalam pengaturan organisasi Anda, dan perubahan padanya dicatat dalam audit logs organisasi.

Autentikasi

Token Exchange menggunakan HTTP Basic Authentication dengan kredensial aplikasi OAuth Anda. Buat header otorisasi dengan meng-encode Base64 client_id:client_secret Anda:

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

Menerbitkan token melalui email

Untuk menerbitkan token akses untuk anggota organisasi menggunakan alamat email mereka:

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"

Respons

Permintaan yang berhasil mengembalikan token akses:

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

Bidang id_token disertakan ketika cakupan openid diminta.

Anda kemudian dapat menggunakan token ini untuk membuat permintaan API atas nama pengguna:

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

Kontrol cakupan

Secara default, token yang diterbitkan mewarisi semua scope yang dikonfigurasi pada aplikasi OAuth. Anda dapat meminta scope tertentu dengan menambahkan parameter scope. Lihat Scope yang didukung saat ini untuk nilai yang tersedia.

Izin efektif token dibatasi baik oleh cakupan yang diminta maupun oleh peran pengguna dalam organisasi.

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"

Ikuti prinsip hak akses minimum: minta hanya scope yang benar-benar dibutuhkan oleh aplikasi Anda.

Pertimbangan keamanan

Token yang diterbitkan melalui Token Exchange memiliki pembatasan keamanan bawaan:

• Berjangkauan organisasi: Token hanya dapat mengakses sumber daya di dalam organisasi Anda (model, dataset, Spaces, dan koleksi yang dimiliki oleh organisasi). Di luar organisasi, akses bersifat hanya-baca dan terbatas pada: koleksi publik dari pengguna atau organisasi mana pun, dan repositori gated publik yang aksesnya diberikan secara individual kepada pengguna.
• Tanpa akses pribadi: Token tidak dapat mengakses repositori pribadi milik pengguna atau repositori pribadi dari organisasi lain.
• Berumur pendek: Token kedaluwarsa setelah 8 jam secara default. Administrator organisasi dapat mengatur durasi token (hingga 30 hari) di pengaturan aplikasi OAuth. Tidak ada refresh token yang disediakan.
• Dapat diaudit: Semua pertukaran token dicatat dan terlihat di log audit organisasi Anda.

Lindungi kredensial aplikasi OAuth Anda dengan cermat. Siapa pun yang memiliki akses ke rahasia klien Anda dapat menerbitkan token untuk anggota organisasi Anda mana pun.

Respons error

Referensi

Jenis izin:

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

Parameter permintaan (subject_token_type):

Field respons (issued_token_type):

Dokumentasi terkait:

• RFC 8693 - Pertukaran Token OAuth 2.0
• Log Audit