Çok adımlı doğrulama¶

Çok adımlı doğrulama (MFA), hesap parolasından sonra kimliğin ikinci bir kanıtını ister. TEBHOS bir TOTP doğrulayıcı uygulamasını ve geçiş anahtarları (passkey) gibi WebAuthn kimlik bilgilerini kabul eder. Tek kullanımlık bir yedek kod TOTP kodunun yerine geçer; sudo modu ise API genelinde güvenlik açısından hassas işlemleri korumak için bu faktörleri yeniden kullanır.

Bu sayfadaki tüm yollar yalnızca kullanıcılara açıktır. Bir kullanıcı oturum token'ı (Authorization: Bearer <token>) gerektirir. Geçerli bir Bot <token> kimlik bilgisi 403 ACCESS_DENIED ile reddedilir.

Girişi ikinci bir faktörle tamamlama HTTP kimlik doğrulama sayfasında anlatılır. SMS kodları Telefon doğrulama sayfasında ele alınır ve TEBHOS'ta kullanılamaz.

Doğrulayıcı türleri¶

Kullanıcı nesnesi, hesabın ikinci faktörlerini authenticator_types alanında bildirir (bkz. doğrulayıcı türleri) ve liste boş değilse mfa_enabled alanını ayarlar.

Parolayla giriş, hesapta TOTP etkinse veya en az bir kayıtlı WebAuthn kimlik bilgisi varsa ikinci bir faktör ister. Dolayısıyla kayıtlı bir geçiş anahtarı her zaman ikinci faktördür. Ayrı bir anahtar (switch) yoktur.

TOTP parametreleri¶

TEBHOS bir TOTP kodunu, 30 saniyelik zaman adımı üzerinden altı haneli HMAC-SHA-1 tek kullanımlık parola olarak doğrular ve her iki yönde bir zaman adımı kadar saat kaymasını kabul eder.

Gizli anahtarı TEBHOS üretir. TOTP'yi kurma, yeni bir 160 bitlik Base32 gizli anahtar ve QR kodu için bir otpauth:// URL'si döndürür; gizli anahtarı, TOTP'yi etkinleştirme bir kodla onaylayana kadar şifreli olarak saklar. İstemcinin gönderdiği herhangi bir gizli anahtar yok sayılır.

Yedek kod sözleşmesi¶

Bir hesap en fazla bir adet 10 yedek koddan oluşan küme tutar. Her kod, küçük harfli Latin alfabesi ve ondalık rakamlardan oluşan, kısa çizgiyle ayrılmış dörder karakterlik iki gruptur; örneğin a3f2-9kd7. TEBHOS kodları, küme daha sonra hangi kodların kullanıldığı bilgisiyle birlikte yeniden gösterilebilecek şekilde saklar.

• TOTP'yi etkinleştirmek yeni bir küme üretir ve döndürür. Önceki küme varsa değiştirilir.
• Yeniden oluşturma, kümenin tamamını 10 yeni kodla değiştirir; böylece kaydedilmiş her kod çalışmaz hale gelir.
• TOTP'yi devre dışı bırakmak, hesap geçiş anahtarlarını korusa bile tüm yedek kodları siler.
• Bir kodun kullanılması geri alınamaz.

Yedek kod; sudo doğrulama nesnesinin mfa_code alanında, TOTP'yi devre dışı bırakma işleminin code alanında ve HTTP kimlik doğrulama sayfasında anlatılan yedek kodla giriş yolunda kabul edilir.

Sudo modu¶

Sudo modu, oturumun başındaki kişinin hâlâ hesap sahibi olduğunu gösteren kısa süreli bir kanıttır. TEBHOS bunu sağlamanın birbirinden bağımsız iki yolunu sunar ve sudo korumalı her yol bunlardan yalnızca birini kabul eder.

Bir yetki satır içi bir yolu karşılamaz; satır içi alanlar da yetki gerektiren bir yolu karşılamaz.

Kabul edilebilir bir kanıt sunmayan istek 403 SUDO_MODE_REQUIRED ile başarısız olur:

{
  "error": "SUDO_REQUIRED",
  "code": "SUDO_MODE_REQUIRED",
  "message": "Bu işlem güvenlik onayı gerektirir."
}

Gövde kullanılabilir yöntemleri listelemez. Kullanıcıdan hangi kanıtın isteneceğine karar vermek için Sudo MFA yöntemlerini alma çağrısını yapın.

Sunulmuş ama yanlış olan bir kanıt 401 UNAUTHORIZED ile başarısız olur. Bu 401 oturumun geçersiz olduğu anlamına gelmez; bu nedenle istemci buna dayanarak kullanıcının oturumunu kapatmamalıdır.

Kabul edilen kanıt¶

TEBHOS mevcut olan ilk alanı şu sırayla okur: sudo_proof, ardından boş olmayan bir mfa_code, ardından boş olmayan bir password.

mfa_code önce TOTP kodu, ardından yedek kod olarak denetlenir ve eşleşen yedek kod kullanılmış sayılır. sudo_proof, Geçiş anahtarı doğrulamasını denetleme işleminden gelmelidir.

mfa_code yolu, hesap başına 15 dakikada 10 denemelik bir izin miktarından (auth:sudo_mfa) düşer; bu miktar kod denetlenmeden önce harcanır. password yolu 5 dakikada 10 denemeden (auth:sudo_pwd) düşer. Her ikisi de sudo korumalı tüm yollar tarafından paylaşılır.

Sudo doğrulama nesnesi¶

Satır içi sudo yolları bu alanları kendi JSON gövdeleriyle birleştirir.

Yapı¶

Sudo yetkisi nesnesi¶

Yapı¶

Sudo MFA yöntemleri nesnesi¶

Yapı¶

MFA yedek kodları nesnesi¶

Yapı¶

Örnek¶

{
  "backup_codes": [
    {"code": "a3f2-9kd7", "consumed": false},
    {"code": "b81c-4nq0", "consumed": true}
  ]
}

MFA yedek kodu nesnesi¶

Yapı¶

TOTP kurulum nesnesi¶

Yapı¶

WebAuthn kimlik bilgisi nesnesi¶

Bir hesap en fazla 10 WebAuthn kimlik bilgisi tutar.

Yapı¶

TEBHOS kimlik bilgisinin açık anahtarını veya imza sayacını hiçbir zaman döndürmez.

WebAuthn kayıt seçenekleri nesnesi¶

TEBHOS, bir istemcinin PublicKeyCredentialCreationOptions nesnesini kendisi oluşturması için gereken değerleri döndürür. TEBHOS web istemcisi, TEBHOS'un doğrulayabildiği tek anahtar türleri olan ES256 (-7) ve RS256 (-257) algoritmalarını ister.

Yapı¶

WebAuthn doğrulama seçenekleri nesnesi¶

Yapı¶

Geçiş anahtarı sudo kanıtı nesnesi¶

Yapı¶

Sudo MFA yöntemlerini alma¶

GET /auth/sudo/mfa-methods

Hesabın hangi kanıtları sunabileceğini açıklayan bir sudo MFA yöntemleri nesnesi döndürür. Sudo modu gerekmez.

Yanıt¶

Hız sınırı¶

sudo:mfa:methods kovasında kimliği doğrulanmış her kullanıcı için dakikada 20 istek.

Sudo yetkisi oluşturma¶

POST /auth/sudo

Sudo modunu kanıtlar ve çağıran oturuma 5 dakikalığına verir. Başarılı olursa bir sudo yetkisi nesnesi döndürür.

Yetki, isteği yapan oturum token'ına aittir. Aynı hesabın diğer oturumlarını yükseltmez. Aynı oturumdan yeniden çağırmak yeni bir 5 dakikalık yetki yazar.

JSON gövdesi¶

Bir sudo doğrulama nesnesi. Kabul edilen kanıt kuralları geçerlidir.

Yanıt¶

Hız sınırı¶

auth:sudo kovasında her istemci IP'si için 10 saniyede 5 istek; buna ek olarak sudo modu altında açıklanan hesap başına izin miktarları.

Sudo yetkisini iptal etme¶

DELETE /auth/sudo

Çağıran oturumun varsa sudo yetkisini kaldırır. Boş gövdeyle 204 döndürür.

TOTP'yi kurma¶

POST /auth/2fa/totp/setup

Yeni bir TOTP gizli anahtarı üretir ve bekleyen olarak saklar. Bir TOTP kurulum nesnesi döndürür. TOTP'yi etkinleştirme gizli anahtarı onaylayana kadar hesapta hiçbir şey değişmez.

Bu işlemi yeniden çağırmak bekleyen gizli anahtarı değiştirir. Gizli anahtar etkinleştirilene kadar hiçbir etkisi olmadığından sudo modu gerekmez.

Yanıt¶

TOTP'yi etkinleştirme¶

POST /auth/2fa/totp/verify

TOTP'yi kurma işleminden gelen bekleyen gizli anahtarı geçerli bir kodla onaylar ve TOTP'yi etkinleştirir. Satır içi sudo modu gerektirir. Bir User Update Gateway olayı yayar.

Yanıt ayrıca 10 yedek koddan oluşan ilk kümeyi taşır. Önceki küme varsa değiştirilir.

JSON gövdesi¶

Gövde, sudo doğrulama nesnesini şu alanla genişletir:

Yanıt¶

TOTP adımından gelen hatalar, code üyesi olmayan {"error": "<CODE>", "message": "..."} gövdesini kullanır.

Hız sınırı¶

user:mfa:totp:enable kovasında kimliği doğrulanmış her kullanıcı için dakikada 10 istek.

Örnek¶

curl -X POST https://tebhos.com/api/v1/auth/2fa/totp/verify \
  -H "Authorization: Bearer $TEBHOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "492039", "password": "correct horse battery staple"}'

TOTP'yi etkinleştirme (alternatif yol)¶

POST /users/@me/mfa/totp/enable

TOTP'yi etkinleştirme ile aynı işi yapar, ancak sudo modunu satır içi alanlar yerine bir sudo yetkisi ile kanıtlar ve yalnızca MFA yedek kodları nesnesini döndürür.

JSON gövdesi¶

Yanıt¶

Diğer hatalar TOTP'yi etkinleştirme ile aynıdır.

Hız sınırı¶

user:mfa:totp:enable kovasında kimliği doğrulanmış her kullanıcı için dakikada 10 istek.

TOTP'yi devre dışı bırakma¶

POST /users/@me/mfa/totp/disable

TOTP'yi devre dışı bırakır ve tüm yedek kodları siler. Boş gövdeyle 204 döndürür. Bir User Update Gateway olayı yayar.

code alanı kimlik kanıtıdır: geçerli bir TOTP kodu veya kullanılmamış bir yedek kod. Başka hiçbir sudo alanı okunmaz.

JSON gövdesi¶

Yanıt¶

Hız sınırı¶

user:mfa:totp:disable kovasında kimliği doğrulanmış her kullanıcı için dakikada 10 istek.

MFA yedek kodlarını listeleme¶

POST /users/@me/mfa/backup-codes

Bir MFA yedek kodları nesnesi döndürür; regenerate true ise önce kümeyi değiştirir. Satır içi sudo modu gerektirir.

Ne TOTP ne de doğrulanmış bir e-posta gerekir; bu nedenle ikinci faktörü olmayan bir hesap sudo modunu parolasıyla kanıtlayıp bir küme oluşturabilir.

Sudo modunu kanıtlamak için mfa_code olarak gönderilen yedek kod kullanılmış sayılır. regenerate false iken bu kod consumed değeri true olarak geri gelir.

JSON gövdesi¶

Gövde, sudo doğrulama nesnesini şu alanla genişletir:

Yanıt¶

Hız sınırı¶

user:mfa:backup_codes kovasında kimliği doğrulanmış her kullanıcı için dakikada 6 istek; MFA yedek kodlarını yeniden oluşturma ve MFA yedek kodlarını sayma ile paylaşılır.

MFA yedek kodlarını yeniden oluşturma¶

POST /auth/2fa/backup-codes/regenerate

Yedek kod kümesini 10 yeni kodla değiştirir ve bunları düz string olarak döndürür. Satır içi sudo modu gerektirir. Gövdesiz bir istek, kanıt sunmamış sayılır.

JSON gövdesi¶

Bir sudo doğrulama nesnesi.

Yanıt¶

Hız sınırı¶

user:mfa:backup_codes kovasında kimliği doğrulanmış her kullanıcı için dakikada 6 istek.

MFA yedek kodlarını sayma¶

GET /auth/2fa/backup-codes/list

Kaç yedek kodun henüz kullanılmadığını, kodları açığa çıkarmadan döndürür. Sudo modu gerekmez.

Yanıt¶

Hız sınırı¶

user:mfa:backup_codes kovasında kimliği doğrulanmış her kullanıcı için dakikada 6 istek.

WebAuthn kimlik bilgilerini listeleme¶

GET /auth/passkeys

Hesabın kimlik bilgilerini en eskiden başlayarak, WebAuthn kimlik bilgisi nesneleriyle {"passkeys": [...]} biçiminde döndürür. Sudo modu gerekmez.

GET /users/@me/mfa/webauthn/credentials aynı kimlik bilgilerini çıplak bir dizi olarak döndürür.

Yanıt¶

Hız sınırı¶

mfa:webauthn:list kovasında kimliği doğrulanmış her kullanıcı için 10 saniyede 40 istek. Her iki yol da bu kovayı paylaşır.

WebAuthn kayıt seçeneklerini oluşturma¶

POST /auth/passkeys/register-options

Tek kullanımlık bir kayıt sınaması oluşturur ve bir WebAuthn kayıt seçenekleri nesnesi döndürür. Satır içi sudo modu gerektirir. Gövdesiz bir istek, kanıt sunmamış sayılır.

Yeni bir sınama, hesabın önceki kayıt sınamasının yerini alır.

JSON gövdesi¶

Bir sudo doğrulama nesnesi.

Yanıt¶

Hız sınırı¶

mfa:webauthn:registration_options kovasında kimliği doğrulanmış her kullanıcı için 10 saniyede 20 istek.

WebAuthn kimlik bilgisi kaydetme¶

POST /auth/passkeys/register

Tarayıcının kayıt sınaması için oluşturduğu kimlik bilgisini saklar. Yeni WebAuthn kimlik bilgisi nesnesini last_used_at olmadan döndürür. Tam kimlik bilgisi listesiyle bir WebAuthn Credentials Update Gateway olayı ve bir User Update olayı yayar.

Bu yol hiçbir sudo alanını okumaz. Sınama yalnızca sudo modu gerektiren WebAuthn kayıt seçeneklerini oluşturma işleminden gelebilir.

TEBHOS, istemci verisi türünün webauthn.create olduğunu, sınamasının hesabın geçerli kayıt sınaması olduğunu ve kökeninin TEBHOS web uygulaması (https://tebhos.com) olduğunu denetler. Onay (attestation) beyanı doğrulanmaz. İlk kimlik bilgisi, WebAuthn doğrulayıcı türünü ekler.

JSON gövdesi¶

Yanıt¶

Başarısız bir kayıt, sınamayı süresi dolana kadar yerinde bırakır. Herhangi bir hesaba zaten kayıtlı olan bir kimlik bilgisi kimliği yeniden saklanmaz ve istek yine de 200 döndürür.

Hız sınırı¶

mfa:webauthn:register kovasında kimliği doğrulanmış her kullanıcı için dakikada 10 istek.

WebAuthn kimlik bilgisini yeniden adlandırma¶

PATCH /auth/passkeys/{credential_id}

Bir kimlik bilgisinin adını değiştirir. Satır içi sudo modu gerektirir. Bir WebAuthn Credentials Update Gateway olayı yayar.

Yol parametreleri¶

JSON gövdesi¶

Gövde, sudo doğrulama nesnesini şu alanla genişletir:

Yanıt¶

Hız sınırı¶

mfa:webauthn:update kovasında kimliği doğrulanmış her kullanıcı için 10 saniyede 20 istek.

WebAuthn kimlik bilgisini silme¶

DELETE /auth/passkeys/{credential_id}

Bir kimlik bilgisini siler. DELETE isteğinin JSON gövdesinde gönderilen satır içi sudo modu gerektirir. Bir WebAuthn Credentials Update Gateway olayı ve bir User Update olayı yayar.

Sudo modu, TEBHOS kimlik bilgisini aramadan önce denetlenir; böylece kanıtsız bir istek kimlik bilgisi hakkında hiçbir şey öğrenemez.

Yol parametreleri¶

JSON gövdesi¶

Bir sudo doğrulama nesnesi.

Yanıt¶

Hız sınırı¶

mfa:webauthn:delete kovasında kimliği doğrulanmış her kullanıcı için dakikada 10 istek.

Geçiş anahtarı doğrulama seçeneklerini oluşturma¶

POST /auth/passkeys/assert-options

Oturum açmış bir hesap için tek kullanımlık bir doğrulama sınaması oluşturur ve bir WebAuthn doğrulama seçenekleri nesnesi döndürür. Bir geçiş anahtarını Geçiş anahtarı doğrulamasını denetleme ile sudo kanıtına dönüştürmek için kullanın. Boş bir gövde gönderin.

Yanıt¶

Geçiş anahtarı doğrulamasını denetleme¶

POST /auth/passkeys/assert

Geçiş anahtarı doğrulama seçeneklerini oluşturma işleminden gelen sınama için bir WebAuthn doğrulamasını denetler ve bir geçiş anahtarı sudo kanıtı nesnesi döndürür.

TEBHOS; istemci verisi türünün webauthn.get olduğunu, sınama ve kökenin eşleştiğini, kimlik bilgisinin hesaba ait olduğunu ve imzayı denetler. Desteklenen anahtarlar ES256 ve RS256'dır. İmza sayacı saklanan sayaçtan büyük olmalıdır; her ikisinin de sıfır olduğu durum hariçtir, çünkü sayacı olmayan bir doğrulayıcı bu şekilde bildirir. Başarılı olursa sayaç ve last_used_at güncellenir ve sınama tüketilir.

JSON gövdesi¶

Yanıt¶

Hız sınırı¶

auth:pk_assert kovasında kimliği doğrulanmış her kullanıcı için 5 dakikada 10 istek.

Örnek¶

const base = "https://tebhos.com/api/v1";
const headers = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
const b64u = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf)))
  .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
const fromB64u = (s) => Uint8Array.from(atob(s.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0));

const opts = await fetch(`${base}/auth/passkeys/assert-options`, { method: "POST", headers })
  .then((r) => r.json());

const cred = await navigator.credentials.get({
  publicKey: {
    challenge: fromB64u(opts.challenge),
    rpId: opts.rp_id,
    allowCredentials: opts.allow_credential_ids.map((id) => ({ type: "public-key", id: fromB64u(id) })),
    userVerification: "preferred",
  },
});

const { sudo_proof } = await fetch(`${base}/auth/passkeys/assert`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    credential_id: cred.id,
    client_data_json: b64u(cred.response.clientDataJSON),
    authenticator_data: b64u(cred.response.authenticatorData),
    signature: b64u(cred.response.signature),
  }),
}).then((r) => r.json());

// Use it once, within 5 minutes, on an inline sudo route.
await fetch(`${base}/users/@me/mfa/backup-codes`, {
  method: "POST",
  headers,
  body: JSON.stringify({ regenerate: false, sudo_proof }),
});