Kendi sisteminize Touchque 2FA ekleyin (Google Authenticator yerine)

Müşterileriniz Google Authenticator'daki 6 haneli kodlar yerine Touchque Authenticator uygulamasıyla giriş onaylasın. Şifre adımınız aynı kalır; ikinci adım telefona gelen bir onay olur. Bu rehber bütün yolu anlatır: API anahtarı, SDK kurulumu, telefonu bağlama, giriş isteği, sonuç (webhook ya da durum sorgusu) ve kısa kod.

Kısaca: 1) Panelde API anahtarı oluşturun. 2) SDK'yı kurun. 3) Kullanıcı ayarlar sayfanızdaki QR'ı Touchque Authenticator ile bir kez okutur. 4) Her girişte şifreden sonra login.request çağırın, telefona push gider. 5) Sonucu webhook ile ya da login.status ile alın ve oturumu açın.

Kullanıcılarınız için ne değişir?

Konu	Google Authenticator	Touchque Authenticator
İkinci adım	Kullanıcı uygulamayı açar, 6 haneli kodu okur ve yazar.	Telefona bir push gelir. Kullanıcı bakar ve Onayla'ya dokunur (Face ID ya da parmak izi).
Kullanıcının gördüğü	Bir kod ve adınız. Bu girişle ilgili hiçbir şey.	Markanız, neyin onaylandığı (giriş ya da ayrıntılarıyla bir ödeme), şehir ve tarayıcı.
Başkası denerse	Oltalama sayfası kodu ister ve hemen kullanır.	Push başka bir şehir ya da tarayıcı gösterir; kullanıcı "Bu ben değilim"e dokunur. Riskli istekler sayı eşleştirme ister ya da engellenir.
Telefonda internet yoksa	Kodlar çevrimdışı çalışır.	Açarsanız çevrimdışı QR kodu ya da çevrimdışı zaman tabanlı kod.
Telefon kaybolursa	2FA'yı elle sıfırlarsınız.	Kurtarma kodları, iş arkadaşlarının onayıyla yeni telefona taşıma ya da sizin yaptığınız sıfırlama.

Kullanıcılarınız Touchque Authenticator'ı telefonlarına (iPhone ya da Android) kurar ve bir kez bağlar. Kayıt olma ve şifre yazma şekilleri değişmez.

Başlamadan önce

Touchque panelinde Developers → API keys altında bir anahtar oluşturun. tq_ ile başlayan API anahtarını ve API secret'ı alırsınız; secret yalnız bir kez gösterilir.
İkisini de yalnız sunucunuzda tutun (TQ_API_KEY, TQ_API_SECRET). Tarayıcıya ya da mobil uygulamaya koymayın: her istek bu secret ile HMAC imzalanır.
Her kullanıcı için sabit bir kimlik seçin: externalUsername (e-posta, kullanıcı id'si). Touchque bunu yalnız referans olarak saklar.

1. SDK'yı kurun ve anahtarlarınızı tanımlayın

Sunucu dilinizi seçin. Node.js 5.2.0, Python 5.2.0, PHP 5.2.0, Go 5.2.0, .NET 5.2.0, Ruby 5.2.0 ve Java 5.2.0 yayımlandı. SDK olmadan REST API her dilde çalışır: istek imzası için Kimlik doğrulama sayfasına bakın.

# Node.js
npm install @touchque/node
# Python
pip install touchque-authenticator
# PHP
composer require touchque-authenticator/php-sdk:^5.0
# Go
go get github.com/Touchque/touchque-go/v5
# .NET
dotnet add package Touchque.AspNetCore
# Ruby
bundle add touchque
# Java
implementation("com.touchque:touchque-spring-boot-starter:5.2.0")
# : henüz yayımlanmadı

# .env sunucunuzda (asla tarayıcıda ya da uygulamada değil)
TQ_API_KEY=tq_...
TQ_API_SECRET=...

2. Kullanıcının telefonunu bağlayın (bir kez)

Ayarlar sayfanızda ("2FA'yı aç") kullanıcı için bir secret oluşturun ve birlikte gelen QR görselini gösterin. Kullanıcı Touchque Authenticator'ı açar ve QR'ı okutur; Google Authenticator'a hesap eklemek gibi. Secret 5 dakika geçerlidir; sonra yenisini oluşturun. 10 kurtarma kodunu bir kez gösterin ve saklamasını isteyin: telefon yoksa giriş yolu bunlardır.

const { Touchque } = require('@touchque/node');
const tq = new Touchque(); // TQ_API_KEY / TQ_API_SECRET from the environment

// Ayarlar sayfası → "2FA'yı aç"
app.post('/2fa/enroll', requireSession, async (req, res) => {
  const { qrCodeDataUrl, recoveryCodes, expiresAt } = await tq.auth.generateSecret({
    externalUsername: req.user.email,
  });
  // QR'ı gösterin (<img src=qrCodeDataUrl>), kurtarma kodlarını bir kez gösterin
  res.json({ qrCodeDataUrl, recoveryCodes, expiresAt });
});

// Telefon bağlanana kadar sayfa bunu sorar
app.get('/2fa/enroll/status', requireSession, async (req, res) => {
  const user = await tq.auth.getUser({ externalUsername: req.user.email });
  res.json({ linked: Boolean(user.used && user.deviceId) });
});

using Touchque;

var tq = new TouchqueClient(); // TQ_API_KEY / TQ_API_SECRET from the environment

var secret = await tq.Auth.GenerateSecretAsync(user.Email);
// secret.QrCodeDataUrl → <img>, secret.RecoveryCodes → bir kez gösterin

var u = await tq.Auth.GetUserAsync(user.Email);
var linked = u.Used && u.DeviceId is not null;

tq = Touchque::Client.new # TQ_API_KEY / TQ_API_SECRET from the environment

secret = tq.auth.generate_secret(current_user.email)
# secret["qrCodeDataUrl"] → <img>, secret["recoveryCodes"] → bir kez gösterin

u = tq.auth.get_user(current_user.email)
linked = u["used"] && !u["deviceId"].nil?

var tq = new TouchqueClient(); // TQ_API_KEY / TQ_API_SECRET from the environment

JsonNode secret = tq.auth().generateSecret(user.getEmail());
// secret.path("qrCodeDataUrl") → <img>, secret.path("recoveryCodes") → bir kez gösterin

JsonNode u = tq.auth().getUser(user.getEmail());
boolean linked = u.path("used").asBoolean() && u.hasNonNull("deviceId");

from touchque import Touchque
tq = Touchque()  # TQ_API_KEY / TQ_API_SECRET from the environment

secret = tq.auth.generate_secret(current_user.email)
# secret['qrCodeDataUrl'] → <img>, secret['recoveryCodes'] → bir kez gösterin

user = tq.auth.get_user(current_user.email)
linked = bool(user.get('used') and user.get('deviceId'))

$tq = new \Touchque\Touchque(); // TQ_API_KEY / TQ_API_SECRET from the environment

$secret = $tq->auth->generateSecret($user->email);
// $secret['qrCodeDataUrl'] → <img>, $secret['recoveryCodes'] → bir kez gösterin

$u = $tq->auth->getUser($user->email);
$linked = !empty($u['used']) && !empty($u['deviceId']);

tq, err := touchque.New() // TQ_API_KEY / TQ_API_SECRET from the environment
if err != nil {
    log.Fatal(err)
}

secret, err := tq.Auth.GenerateSecret(user.Email)
// secret.QRCodeDataURL → <img>, secret.RecoveryCodes → bir kez gösterin

u, err := tq.Auth.GetUser(user.Email)
linked := u.Used && u.DeviceID != ""

Kullanıcı bağlandığında getUser yanıtında used: true ve bir deviceId olur. Panelde 2FA users sayfası da bağlı telefonları gösterir.

Şifre doğruysa oturumu henüz açmayın. Sunucunuzdan login.request çağırın: Touchque kullanıcının telefonuna push gönderir. Telefon girişin nereden geldiğini gösterebilsin diye kullanıcının IP adresini ve tarayıcı bilgisini (user agent) iletin. İstek 30 saniye geçerlidir.

// Şifre kontrolü geçtikten sonra:
const r = await tq.login.request({
  externalUsername: user.email,
  type: 'LOGIN',
  clientIp: req.ip,                 // telefonda şehir, ülke olarak görünür
  userAgent: req.get('user-agent'), // tarayıcı ve cihaz olarak görünür
});
// r = { requestId, expiresAt, challengeCode?, caseCode }
req.session.pending2fa = { requestId: r.requestId, user: user.email };
res.json({ waiting: true, number: r.challengeCode }); // sayı varsa gösterin

// Şifre kontrolü geçtikten sonra:
var r = await tq.Login.RequestAsync(new LoginRequestOptions
{
    ExternalUsername = user.Email,
    Type = "LOGIN",
    ClientIp = HttpContext.Connection.RemoteIpAddress?.ToString(),
    UserAgent = Request.Headers.UserAgent.ToString(),
});
HttpContext.Session.SetString("pending2fa", r.RequestId);
// r.ChallengeCode (varsa gösterin), r.CaseCode

r = tq.login.request(current_user.email, type: "LOGIN",
                     client_ip: request.remote_ip, user_agent: request.user_agent)
session[:pending_2fa] = { "request_id" => r["requestId"], "user" => current_user.email }
# r["challengeCode"] varsa gösterin

Login.RequestResult r = tq.login().request(new LoginRequestOptions(user.getEmail())
        .type("LOGIN")
        .clientIp(request.getRemoteAddr())
        .userAgent(request.getHeader("User-Agent")));
session.setAttribute("pending2fa", r.requestId());
// r.challengeCode() (varsa gösterin), r.caseCode()

r = tq.login.request(
    external_username=user.email,
    type='LOGIN',
    client_ip=request.remote_addr,
    user_agent=request.headers.get('User-Agent'),
)
session['pending_2fa'] = {'request_id': r['requestId'], 'user': user.email}
# r.get('challengeCode') varsa gösterin: telefon kullanıcıdan onu seçmesini ister

$r = $tq->login->request(
    externalUsername: $user->email,
    type: 'LOGIN',
    clientIp: $_SERVER['REMOTE_ADDR'],
    userAgent: $_SERVER['HTTP_USER_AGENT'] ?? null,
);
$_SESSION['pending_2fa'] = ['request_id' => $r['requestId'], 'user' => $user->email];
// $r['challengeCode'] varsa gösterin

r, err := tq.Login.RequestWithOptions(touchque.LoginRequestOptions{
    ExternalUsername: user.Email,
    Type:             "LOGIN",
    ClientIP:         clientIP(req),
    UserAgent:        req.UserAgent(),
})
// r.RequestID, r.ChallengeCode (varsa gösterin), r.CaseCode

Yanıtta challengeCode varsa (risk yüksek ya da siz requireNumberMatch istediniz) sayıyı sayfanızda gösterin: telefon kullanıcıdan aynı sayıyı seçmesini ister. Bu, kullanıcının yalnız kendi başlattığı girişi onaylamasını sağlar.

4. Sonucu alın: webhook ya da durum sorgusu

İki yol var, birini kullanın. Webhook (önerilen): Developers → Webhooks altında Callback URL'nizi girin; kullanıcı onaylayınca ya da reddedince Touchque sonucu API secret'ınızla imzalayıp oraya POST eder (o sayfadaki Signing secret aynı değerdir). Güvenmeden önce x-signature başlığını ham gövde üzerinde mutlaka doğrulayın. Durum sorgusu: 30 saniyeye kadar 2 saniyede bir login.status sorun. Oturumu yalnız CONFIRMED (durum) ya da SUCCESS (webhook) için ve yalnız 3. adımda sakladığınız requestId ve kullanıcı için açın.

// Webhook: Developers → Webhooks → Callback URL = https://uygulamaniz/webhooks/touchque
app.post('/webhooks/touchque', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = tq.webhook.verify({ rawBody: req.body.toString('utf8'), signature: req.get('x-signature') });
  } catch {
    return res.sendStatus(403); // Touchque'dan değil, değiştirilmiş ya da eski
  }
  // event.status: 'SUCCESS' | 'REJECTED', event.requestId, event.externalUsername
  saveDecision(event.requestId, event.status); // bekleyen tarayıcı bunu okur
  res.sendStatus(200);
});

// Ya da tarayıcı beklerken 2 saniyede bir sorun:
const s = await tq.login.status(pending.requestId); // PENDING | CONFIRMED | REJECTED | EXPIRED
if (s.status === 'CONFIRMED' && s.externalUsername === pending.user) startSession(pending.user);

app.MapPost("/webhooks/touchque", async (HttpRequest request, TouchqueClient tq) =>
{
    using var reader = new StreamReader(request.Body);
    var rawBody = await reader.ReadToEndAsync();
    try
    {
        var e = tq.Webhook.Verify(rawBody, request.Headers["X-Signature"]);
        SaveDecision((string?)e["requestId"], (string?)e["status"]); // SUCCESS | REJECTED
        return Results.Ok();
    }
    catch (TouchqueWebhookSignatureException)
    {
        return Results.StatusCode(403);
    }
});

// ya da sorgulayın:
var s = await tq.Login.StatusAsync(pendingRequestId); // PENDING | CONFIRMED | REJECTED | EXPIRED

class TouchqueWebhooksController < ApplicationController
  skip_forgery_protection

  def create
    event = Touchque.client.webhook.verify(request.raw_post, request.headers["X-Signature"])
    save_decision(event["requestId"], event["status"]) # SUCCESS | REJECTED
    head :ok
  rescue Touchque::WebhookSignatureError
    head :forbidden
  end
end

# ya da sorgulayın:
s = tq.login.status(session[:pending_2fa]["request_id"]) # PENDING | CONFIRMED | REJECTED | EXPIRED

@PostMapping("/webhooks/touchque")
ResponseEntity<Void> webhook(@RequestBody String rawBody, @RequestHeader("X-Signature") String signature) {
    try {
        ObjectNode event = tq.webhook().verify(rawBody, signature);
        saveDecision(event.path("requestId").asText(), event.path("status").asText()); // SUCCESS | REJECTED
        return ResponseEntity.ok().build();
    } catch (TouchqueWebhookSignatureException e) {
        return ResponseEntity.status(403).build();
    }
}

// ya da sorgulayın:
Login.Status s = tq.login().status(pendingRequestId); // PENDING | CONFIRMED | REJECTED | EXPIRED

@app.post('/webhooks/touchque')
def touchque_webhook():
    try:
        event = tq.webhook.verify(raw_body=request.get_data(as_text=True),
                                  signature=request.headers.get('x-signature'))
    except TouchqueWebhookSignatureException:
        return '', 403
    save_decision(event['requestId'], event['status'])  # SUCCESS | REJECTED
    return '', 200

# ya da sorgulayın:
s = tq.login.status(pending['request_id'])  # PENDING | CONFIRMED | REJECTED | EXPIRED
if s['status'] == 'CONFIRMED' and s['externalUsername'] == pending['user']:
    start_session(pending['user'])

try {
    $event = $tq->webhook->verify(file_get_contents('php://input'), $_SERVER['HTTP_X_SIGNATURE'] ?? null);
} catch (\Touchque\Exceptions\TouchqueWebhookSignatureException $e) {
    http_response_code(403);
    exit;
}
saveDecision($event['requestId'], $event['status']); // SUCCESS | REJECTED

// ya da sorgulayın:
$s = $tq->login->status($pending['request_id']); // PENDING | CONFIRMED | REJECTED | EXPIRED

body, _ := io.ReadAll(r.Body)
event, err := tq.Webhook.Verify(string(body), r.Header.Get("x-signature"))
if err != nil {
    w.WriteHeader(http.StatusForbidden)
    return
}
saveDecision(event["requestId"].(string), event["status"].(string)) // SUCCESS | REJECTED

// ya da sorgulayın:
s, err := tq.Login.Status(pending.RequestID) // s.Status: PENDING | CONFIRMED | REJECTED | EXPIRED

Webhook adresiniz HTTPS olmalı (yerel testte localhost olabilir) ve 5 saniye içinde 2xx dönmeli; dönmezse Touchque birkaç kez yeniden dener. Aynı olay iki kez gelebilir: jti ya da requestId ile tekrarları ayıklayın.

5. Diğer yanıtları ele alın

Her yanıt K7P-2QX gibi bir caseCode taşır. İstek reddedilince kodu kullanıcıya gösterin; ekibiniz panelde Logs → Look up a case altında kodu açar ve nedenini görür.

Yanıt	Ne yapmalı
`challengeCode ile 200`	Sayı eşleştirme: sayıyı sayfanızda gösterin. Telefon kullanıcıdan bu sayıyı seçmesini ister.
`404`	Kullanıcının bağlı telefonu yok. 2. adıma yönlendirin ya da kurtarma kodu kabul edin.
`403 blocked`	Risk motoru isteği reddetti. caseCode'u gösterin: "Destek ekibinize söyleyin: K7P-2QX".
`403 device_keys_lost`	Telefon anahtarlarını kaybetti (uygulama yeniden kuruldu, telefon geri yüklendi). Kullanıcı telefonu yeniden bağlar.
`423 frozen`	Çok fazla reddedilen istek. Kullanıcının kim olduğunu doğrulayın, sonra secret'ı sıfırlayın (sıfırlama dondurmayı da kaldırır).
`429 rate_limited`	Bu kullanıcıya 10 dakikada 5'ten fazla push. retryAfter saniye bekleyin.
`requiresPasskey: true`	Politikanız bu işlem için passkey istiyor, push gönderilmedi. Passkey sayfasına bakın.
`REJECTED`	Kullanıcı Reddet'e dokundu. rejectReason bunu bildirip bildirmediğini söyler ("Bu ben değilim").
`EXPIRED`	30 saniye içinde yanıt gelmedi. Yeni bir istek göndermeyi önerin.

const { TouchqueAPIError } = require('@touchque/node');

try {
  await tq.login.request({ externalUsername: user.email, type: 'LOGIN', clientIp: req.ip });
} catch (err) {
  if (!(err instanceof TouchqueAPIError)) throw err;
  if (err.status === 404) return res.json({ enroll: true });            // bağlı telefon yok
  if (err.caseCode) return res.status(err.status).json({                 // blocked, frozen, rate_limited
    message: `Destek ekibinize söyleyin: ${err.caseCode}`,
  });
  throw err;
}

try
{
    await tq.Login.RequestAsync(new LoginRequestOptions { ExternalUsername = user.Email, ClientIp = ip });
}
catch (TouchqueApiException e) when (e.Status == 404)
{
    return Results.Json(new { enroll = true }); // bağlı telefon yok
}
catch (TouchqueApiException e) when (e.CaseCode is not null) // blocked, frozen, rate_limited
{
    return Results.Json(new { message = $"Destek ekibinize söyleyin: {e.CaseCode}" }, statusCode: e.Status);
}

begin
  tq.login.request(current_user.email, type: "LOGIN", client_ip: request.remote_ip)
rescue Touchque::APIError => e
  return render json: { enroll: true } if e.status == 404 # bağlı telefon yok
  raise unless e.case_code # blocked, frozen, rate_limited
  render json: { message: "Destek ekibinize söyleyin: #{e.case_code}" }, status: e.status
end

try {
    tq.login().request(new LoginRequestOptions(user.getEmail()).clientIp(request.getRemoteAddr()));
} catch (TouchqueApiException e) {
    if (e.status() == 404) return ResponseEntity.ok(Map.of("enroll", true)); // bağlı telefon yok
    if (e.caseCode() == null) throw e; // blocked, frozen, rate_limited
    return ResponseEntity.status(e.status()).body(Map.of("message", "Destek ekibinize söyleyin: " + e.caseCode()));
}

_, err := tq.Login.RequestWithOptions(touchque.LoginRequestOptions{ExternalUsername: user.Email, Type: "LOGIN", ClientIP: ip})
var apiErr *touchque.APIError
if errors.As(err, &apiErr) {
    if apiErr.StatusCode == http.StatusNotFound {
        json.NewEncoder(w).Encode(map[string]bool{"enroll": true}) // bağlı telefon yok
        return
    }
    if apiErr.CaseCode != "" { // blocked, frozen, rate_limited
        w.WriteHeader(apiErr.StatusCode)
        json.NewEncoder(w).Encode(map[string]string{"message": "Destek ekibinize söyleyin: " + apiErr.CaseCode})
        return
    }
}

Google Authenticator kullanıcılarını taşıma

Google Authenticator secret'ları Touchque'ya aktarılamaz: her kullanıcı telefonunu 2. adımdaki QR ile bir kez bağlar.
Geçiş süresince iki yöntemi birlikte tutun: telefonu bağlı olana push, olmayana eski kod. Bir sonraki girişte "Touchque ile onayla"yı önerin.
Kullanıcının telefonu bağlanınca (used: true) onun eski TOTP secret'ını silin; böylece oltalanabilecek kod kalmaz.
Telefonu internetsiz kalabilen kullanıcılar için panelde App user policy altında çevrimdışı onayı açın.

Kısayollar: tek satırlık middleware ve hazır ekranlar

Yukarıdaki adımlar çıplak çağrılardır. SDK'lar bunları sarar: requireTouchque('LOGIN') (Express), @require_touchque (Flask, Django, FastAPI), ->middleware('touchque:LOGIN') (Laravel) ve touchque.Require (Go) telefon onaylayana kadar 202 döner. Sayfada @touchque/web ve @touchque/react bağlama QR'ını, sayılı bekleme ekranını ve passkey adımını hazır verir. Bu rehberler için kenar çubuğunu SDKs'e çevirin.

Canlıya almadan önce

API anahtarı ve secret yalnız sunucuda; istekler HTTPS üzerinden.
Webhook imzası doğrulanıyor; oturum yalnız sizin başlattığınız requestId için açılıyor.
Kurtarma kodları kayıt sırasında gösteriliyor ve telefon kaybı için bir yolunuz var (Sorun giderme sayfasına bakın).
Reddedilen isteklerde caseCode kullanıcıya gösteriliyor.
Gerçek bir telefonla bağlama, onay, ret ve süre dolması denendi.