Hugging Face ile oturum aç

Herhangi bir web sitesinde veya uygulamada “HF ile Giriş Yap” akışı oluşturmak için HF OAuth / OpenID connect akışını kullanabilirsiniz.

Bu, kullanıcıların bu benzeri bir düğmeye tıklayarak HF hesaplarıyla web sitenize veya uygulamanıza giriş yapmasını sağlayacaktır:

Bu düğmeye tıkladıktan sonra kullanıcılarınıza, uygulamanızı yetkilendirmek için bir izin penceresi gösterilir:

Bir oauth uygulaması oluşturma

Uygulamanızı ayarlar bölümünüzde oluşturabilirsiniz:

Organizasyona ait OAuth uygulamaları

Bu özellik, Team & Enterprise planlarının bir parçasıdır.

OAuth uygulamaları, bireysel bir hesap yerine bir organizasyon tarafından da sahip tutulabilir. Ekip olarak birlikte sürdürdüğünüz uygulamalar için bu faydalıdır, çünkü uygulamalar tek bir üyenin hesabına bağımlı kalmak yerine organizasyonla birlikte kalır.

Organizasyon yöneticileri, organizasyon ayarlarındaki OAuth Apps bölümünden (https://huggingface.co/organizations/<your-org>/settings/applications) organizasyona ait uygulamaları oluşturabilir ve yönetebilir. Organizasyonun tüm yöneticileri uygulamayı düzenleyebilir, client secret değerini döndürebilir veya silebilir. Uygulama listesi, her uygulamanın hangi üye tarafından oluşturulduğunu gösterir ve uygulamalardaki değişiklikler organizasyonun audit logs kaydına işlenir.

Aynı sayfa, yapılandırılmışsa, organizasyonun Token Exchange uygulamasını da listeler.

Kendi sahibi olduğunuz mevcut bir OAuth uygulamasını, yöneticisi olduğunuz bir organizasyona, uygulamanın ayarlar sayfasındaki Organizasyona aktar bölümünden de aktarabilirsiniz. Organizasyonun bir Team veya Enterprise planında olması gerekir. Aktarımın ardından uygulama, organizasyonun tüm yöneticileri tarafından yönetilir. Uygulamanın istemci kimliği, istemci gizli anahtarı ve mevcut yetkilendirmeleri ile jetonları aynı kaldığından, web siteniz veya uygulamanız değişiklik yapılmadan çalışmaya devam eder. Ayarlar sayfasından aktarım işlemi geri alınamaz.

Herkese açık OAuth uygulamaları (gizli anahtar yok)

Müşteri gizli anahtarı olmadan OAuth uygulamaları oluşturabilir veya kullanabilirsiniz. Bu, bir gizli anahtarı saklamanın pratik olmadığı yerel uygulamalar, CLI'lar veya diğer bağlamlar için faydalıdır.

• Uygulama oluşturulurken: Yeni bir OAuth uygulaması oluştururken, gizli anahtar olmadan oluşturmayı seçebilirsiniz.
• Oluşturma sonrası: Mevcut bir uygulama için uygulama ayarlarında istemci gizli anahtarını silebilirsiniz. Uygulama bu durumda herkese açık bir uygulama olarak çalışır.

Herkese açık uygulamalar yalnızca istemci kimliğiyle kimlik doğrulama yapar (ör. PKCE ile cihaz kodu veya yetkilendirme kodu akışlarında). Bir sırra sahip olan uygulamalar, gerektiğinde hâlâ sırrı kullanabilir (ör. jeton istekleri için Authorization: Basic).

Yönlendirme URİ'leri

Bir yetkilendirme isteğinde gönderilen redirect_uri, uygulamanızda kayıtlı yönlendirme URI'lerinden biriyle birebir eşleşmelidir.

Loopback yönlendirme URI'leri tek istisnadır: http şemasını kullanan ve bir loopback ana makineyi (localhost, 127.0.0.1 veya [::1]) içeren URI'ler için, istek anında her diğer bileşen kayıtlı bir URI ile eşleştiği sürece herhangi bir port kabul edilir. Bu, RFC 8252 §7.3 / OAuth 2.1'e uygun olarak, yerel uygulamaların, CLI'ların ve MCP istemcilerinin http://localhost/callback gibi port içermeyen bir URI kaydedip ardından işletim sisteminin atadığı herhangi bir geçici portta (ör. http://localhost:49282/callback) dinlemesini sağlar.

Dikkat edilmesi gereken birkaç nokta:

• İstisna yalnızca http şeması için geçerlidir. https ve özel şemalı (ör. myapp://callback) yönlendirme URI'leri her zaman, port dahil olmak üzere, tam bir eşleşme gerektirir.
• Loopback ana bilgisayarları bireysel olarak eşleştirilir: http://localhost:49282/callback için yapılan bir istek, kayıtlı http://127.0.0.1/callback ile eşleşmez. Uygulamanız her ikisini de kullanabilirse her ikisini de kaydedin.
• Yalnızca port farklı olabilir. Yol, sorgu ve kullanıcı bilgileri yine de tam olarak eşleşmelidir.

Spaces'te barındırıyorsanız

Uygulamanızı Spaces üzerinde barındırıyorsanız, akışı uygulamak çok daha kolay olacaktır (ve Gradio'ya doğrudan yerleşiktir); Spaces OAuth kılavuzumuza göz atın.

Otomatik oauth uygulaması oluşturma

Hugging Face, web siteniz için bir oauth uygulamasını otomatik bir şekilde oluşturmanıza olanak tanıyan CIMD yani Client ID Metadata Documents özelliğini destekler:

• Web sitenize aşağıdaki JSON'u döndüren bir uç nokta ekleyin: /.well-known/oauth-cimd

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

• Müşteri kimliği olarak "[your website url]/.well-known/oauth-cimd" adresini ve kimlik doğrulama mekanizması olarak PCKE'yi kullanın

Yerel bir portta yetkilendirme kodunu alan yerel uygulamalar ve MCP istemcileri, redirect_uris içinde port içermeyen döngüsel geri (loopback) URI'lerini listeleyebilir, örneğin ["http://localhost/callback", "http://127.0.0.1/callback"] — bkz. Yönlendirme URI'leri.

Bu, geçici ortamlar veya MCP istemcileri için özellikle faydalıdır. Hugging Chat'te bir uygulama örneği bulun.

Cihaz kodu OAuth

Device code flow, kullanıcıların uygulamayı bir cihazda (ör. bir CLI) onaylamasına, kısa bir kodu başka bir cihazda (ör. bir telefon veya tarayıcı) girerek izin vermesine olanak tanır. Uygulamanın çalıştığı cihazda yönlendirme URI'si veya tarayıcı gerekmez.

Örnek bir betikle test etme

Aşağıdaki betik ile bir cihaz kodu OAuth uygulamasını test edebilirsiniz. <Client ID> yerini uygulamanızın istemci kimliği ile değiştirin. halka açık uygulamalar (gizli anahtar yok) için betik olduğu gibi çalışır. gizli anahtarı olan uygulamalar için hem cihaz hem de token isteklerine Authorization: Basic başlığı ekleyin (client_id:client_secret değerinin Base64 kodu).

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

Müşteri sırrı (client secret) olan OAuth uygulamaları için, hem cihaz kodu isteğinde hem de jeton isteğinde Authorization: Basic başlığı (Base64 kodlu client_id:client_secret ile) ekleyin.

Şu anda desteklenen kapsamlar

Şu anda desteklenen kapsamlar şunlardır:

• openid: Erişim belirtecinin yanı sıra bir kimlik belirtecini alın.
• profile: Kullanıcının profil bilgilerini (kullanıcı adı, avatar vb.) okur
• email: Kullanıcının e-posta adresini okur.
• read-billing: Kullanıcının bir ödeme yöntemi tanımlayıp tanımlamadığını öğrenin.
• read-memberships: Kullanıcının hangi kuruluşlara üye olduğunu ve her birindeki rolünü okur. Bu, kuruluşların ayarlarına veya kaynaklarına erişim yetkisi vermez.
• read-repos: Kullanıcının kişisel depolarını okur.
• gated-repos: Kullanıcının erişim izni verilen herkese açık gated depolarının içeriğini okur. read-repos'un aksine, bu özel depolara erişim sağlamaz.
• contribute-repos: Depolar oluşturur ve bu uygulama tarafından oluşturulanlara erişir. Ek izinler verilmedikçe başka depolara erişemez.
• write-repos: Kullanıcının kişisel depolarını okur ve yazar.
• manage-repos: Kullanıcının kişisel depolarını, bunları oluşturma ve silme dahil olmak üzere, tamamen yönetir.
• read-collections: Kullanıcının kişisel koleksiyonlarını oku.
• write-collections: Kullanıcının kişisel koleksiyonlarını okuma ve yazma, bunları oluşturma ve silme.
• inference-api: Kullanıcı adına Inference Providers üzerinden çıkarım istekleri yapın.
• read-endpoints: Kullanıcının Inference Endpoints bileşenlerini görüntüler ve kullanıcının adına bu bileşenlere çıkarım istekleri gönderir.
• write-endpoints: Kullanıcının Inference Endpoints'lerini, bunların oluşturulması ve silinmesi dahil olmak üzere yönetir. read-endpoints erişimini içerir.
• jobs: jobs çalıştır
• webhooks: webhook yönetimi
• write-discussions: Kullanıcı adına tartışma ve Pull Request açma ve tartışmalarla etkileşim kurma (reaksiyonlar, yorum gönderme/düzenleme, tartışmaları kapatma, …). Özel depolarda Pull Request açmak için ayrıca read-repos kapsamını da istemeniz gerekir.

Diğer tüm bilgiler OpenID metadata içinde mevcuttur.

Ek kapsamlara ihtiyacınız olursa lütfen bizimle iletişime geçin.

Organizasyon kaynaklarına erişim

Varsayılan olarak, oauth uygulamasının organizasyon kaynaklarına erişmesi gerekmez.

Ancak read-repos veya read-billing gibi bazı kapsamlar, kuruluşlara da uygulanır.

Kullanıcı, uygulamayı yetkilendirirken erişim izni vereceği kuruluşları seçebilir. Belirli bir kuruluşa erişim gerekiyorsa, OAuth yetkilendirme URL'sine orgIds=ORG_ID sorgu parametresi olarak ekleyebilirsiniz. Kuruluş kimliği, userinfo yanıtındaki orgs[].sub alanında bulunur.

Organizasyon üyeliğini gruplar olarak senkronize etme

userinfo yanıtı (https://huggingface.co/oauth/userinfo) bir groups iddiası içerir: kullanıcının üye olduğu kuruluşların adları, bir dizi dize olarak.

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

Birçok OIDC istemcisi (ör. Discourse, Grafana, Argo CD, Vault, Kubernetes), dizel bir dize dizisi içeren bir iddiadan (claim) grup üyeliğini senkronize edebilir ve genellikle groups iddiasıyla yapılandırılır. Hugging Face kuruluşlarını uygulamanızdaki roller veya gruplara eşlemek için bunu kullanabilirsiniz. Her kuruluşun ayrıntıları (ID, rol vb.) için bunun yerine orgs alanını kullanın.

Dikkat edilmesi gereken birkaç nokta:

• groups iddiası yalnızca userinfo uç noktası tarafından döndürülür, ID belirtecinde yer almaz.
• Organizasyon adlarını, kimlik numaralarını değil içerir. Bir organizasyon yeniden adlandırılırsa, eski adını kullanan eşlemeler eşleşmeyi durdurur.
• Kaynak grupları dahil değildir. Ücretli plandaki organizasyonlar için kullanıcının kaynak grupları ve rolleri orgs[].resourceGroups içinde listelenir.

Marka

Düğme için kendi tasarımınızı kullanmak serbestsiniz. Aşağıda, nazikçe sağlanan bazı SVG görselleri bulunmaktadır.

Markdown veya HTML'de entegre etmek için açıklamalı rozetlerimizi inceleyin.

Kuruluşlar için Token Değişimi (RFC 8693)

Bu özellik, Enterprise planının bir parçasıdır.

Token Exchange, kuruluşların üyeleri için etkileşimli kullanıcı onayı gerektirmeden programatik olarak erişim belirteçleri (access token) oluşturmasına olanak tanır. Bu özellik, kuruluş üyeleri adına Hugging Face kaynaklarına erişmesi gereken dahili araçlar, otomasyon hatları ve kurumsal entegrasyonlar oluşturmak için özellikle faydalıdır.

Eğer yalnızca CI/CD iş akışından (GitHub Actions, GitLab CI, CircleCI, …) anahtarsız kimlik doğrulamasına ihtiyacınız varsa — üye başına token yayınlama olmadan — lütfen Trusted Publishers bölümüne bakın. Bu bölüm de /oauth/token kullanır ancak konu token olarak CI sağlayıcınız tarafından oluşturulan bir OIDC id_token alır (Enterprise planı gerekmez, istemci kimlik bilgileri gerekmez).

Bu özellik, token değişim senaryoları için standart bir protokol olan RFC 8693 - OAuth 2.0 Token Exchange'i uygular.

Kullanım senaryoları

Token Exchange, kuruluşunuzun aşağıdaki durumlarda ihtiyaç duyduğu senaryolar için tasarlanmıştır:

• İç platformlar oluşturun: Her kullanıcının manuel olarak kimlik doğrulaması yapmasını gerektirmeden, ekip üyeleriniz adına Hugging Face kaynaklarına erişen panolar veya portallar oluşturun.
• CI/CD hatlarını otomatikleştirin: Kuruluş depolarına modeller veya veri kümeleri göndermesi gereken otomatik iş akışları için kısa ömürlü, kapsamı daraltılmış jetonlar oluşturun.
• Kurumsal kimlik sistemleriyle entegre edin: Mevcut kimlik sağlayıcınızı, dahili kullanıcı dizininize dayalı olarak token yayımlayarak Hugging Face ile köprüleyin.
• Özel erişim kontrolleri uygulayın: Kurumunuzun iç politikalarına göre belirli kapsamlara sahip jetonlar veren bir ara katman (middleware) oluşturun.

Nasıl çalışır

1. Organizasyonunuz, token-exchange yetkisine sahip bir OAuth uygulamasına bağlıdır.
2. Arka uç hizmetiniz, bu OAuth uygulamasıyla kimlik doğrulamasını istemci kimlik bilgileri (client credentials) kullanarak gerçekleştirir.
3. Hizmetiniz, belirli bir organizasyon üyesi (e-posta ile tanımlanır) için bir erişim jetonu ister.
4. Hugging Face, kullanıcının organizasyonunuzun bir üyesi olduğunu doğrular ve kapsamlı bir token yayar.
5. Verilen jeton yalnızca kuruluşunuzun kapsamındaki kaynaklara erişebilir.

Ön koşullar

Token Exchange'i kullanmak için, token-exchange yetkisine sahip, organizasyonunuza bağlı bir OAuth uygulamasına ihtiyacınız vardır. Organizasyonunuz için uygun bir OAuth uygulaması oluşturmak üzere Hugging Face destek ekibiyle iletişime geçin.

Yapılandırıldıktan sonra şunları alacaksınız:

• Bir Client ID (ör. a1b2c3d4-e5f6-7890-abcd-ef1234567890)
• Bir Client Secret (bunu güvende tutun!)

Organizasyon yöneticileri, oluşturulduktan sonra OAuth uygulamasını yönetebilir; bu, istemci gizli anahtarını yenilemeyi ve belirteç süresini yapılandırmayı içerir. Uygulama, organizasyon ayarlarınızın OAuth Apps bölümünde listelenir ve bu uygulamada yapılan değişiklikler organizasyonun audit logs kaydına işlenir.

Kimlik Doğrulama

Token Exchange, OAuth uygulama kimlik bilgilerinizle HTTP Basic Authentication kullanır. Yetkilendirme başlığını oluşturmak için client_id:client_secret değerini Base64 kodlayın:

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

E-posta ile jeton yayınlama

Bir organizasyon üyesine e-posta adresi kullanarak bir erişim belirteci vermek için:

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"

Yanıt

Başarılı bir istek bir erişim belirteci döndürür:

{
  "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 kapsamı istendiğinde id_token alanı dahil edilir.

Daha sonra bu belirteci, kullanıcının adına API istekleri yapmak için kullanabilirsiniz:

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

Kapsam kontrolü

Varsayılan olarak, verilen jetonlar OAuth uygulamasında yapılandırılmış tüm kapsamları devralır. Belirli kapsamları istemek için scope parametresini ekleyebilirsiniz. Kullanılabilir değerler için Şu anda desteklenen kapsamlar bölümüne bakın.

Token'ın etkin izinleri, hem istenen kapsam hem de kullanıcının organizasyon içindeki rolü tarafından sınırlanır.

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"

En az yetki ilkesine uyun: Uygulamanızın gerçekten ihtiyaç duyduğu kapsamları isteyin.

Güvenlik hususları

Token Exchange üzerinden verilen jetonlar yerleşik güvenlik kısıtlamalarına sahiptir:

• Organizasyon kapsamındaki: Jetonlar yalnızca organizasyonunuz içindeki kaynaklara (organizasyona ait modeller, veri kümeleri, Spaces ve koleksiyonlar) erişebilir. Organizasyon dışında erişim salt okunurdur ve şunlarla sınırlıdır: herhangi bir kullanıcıdan veya organizasyondan herkese açık koleksiyonlar ve kullanıcıya bireysel olarak erişim izni verilmiş herkese açık gated depolar.
• Kişisel erişim yok: Jetonlar, kullanıcının kişisel özel depolarına veya diğer organizasyonların özel depolarına erişemez.
• Kısa ömürlü: Jetonlar varsayılan olarak 8 saat sonra sona erer. Organizasyon yöneticileri, jeton süresini (en fazla 30 gün) OAuth uygulama ayarlarında yapılandırabilir. Yenileme jetonu sağlanmaz.
• Denetlenebilir: Tüm token değişimleri, organizasyonunuzun denetim günlüklerinde kaydedilir ve görüntülenebilir.

OAuth uygulama kimlik bilgilerinizi dikkatli bir şekilde koruyun. İstemci gizli anahtarınıza erişimi olan herkes, organizasyonunuzdaki herhangi bir üye adına jeton çıkarabilir.

Hata yanıtları

Referans

Yetki türü:

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

İstek parametresi (subject_token_type):

Yanıt alanı (issued_token_type):

İlgili belgeler:

• RFC 8693 - OAuth 2.0 Belirteç Değişimi
• Denetim Kayıtları