Ana içeriğe atla
GOWA’da iki ayrı kimlik doğrulama türü vardır:
  1. API erişimi: GOWA’yı kimlerin çağırabileceğini belirler. HTTP Basic Auth kullanılır.
  2. WhatsApp eşleştirme: WhatsApp Web’i bağlarken olduğu gibi, bir WhatsApp hesabını cihaz yuvasına bağlamaktır.

API erişimi: Basic Auth

Basic Auth, API için tek kimlik doğrulama yöntemidir. REST çağrıları için API anahtarı veya JWT yoktur. Bir veya daha fazla user:password çiftini virgülle ayırarak ayarlayın:
Her girişte boş olmayan bir kullanıcı adı ve parola bulunmalıdır. Varsayılan dinleyici APP_HOST=0.0.0.0, eksiksiz kimlik bilgileri olmadan başlamayı reddeder. Kimlik doğrulamasız yerel geliştirme için APP_HOST=127.0.0.1 adresine bağlayın. Bir ters vekil her çağrıyı yapanın kimliğini doğruluyorsa APP_ALLOW_UNAUTHENTICATED=true veya --allow-unauthenticated=true, geri döngü dışı bir dinleyicinin Basic Auth olmadan çalışmasına açıkça izin verir. Bu dinleyiciye doğrudan erişimi kısıtlayın. Her istekte kimlik bilgilerini gönderin:
Eksik veya yanlış kimlik bilgileri 401 Unauthorized yanıtına yol açar.

Basic Auth ile korunmayanlar

/ yolundaki kontrol paneli, /mcp ve /ws dahil diğer her şey, yapılandırıldığında Basic Auth gerektirir.

WebSocket

Tarayıcılar WebSocket bağlantılarında başlık ayarlayamadığından /ws, kimlik bilgisini sorgu dizesinden alır:
authorization, base64(user:password) biçimindedir. TLS (wss://) kullanın ve vekil günlüklerinde sorgu dizesini gizleyin. WebSocket, tarayıcı kaynağını durum değiştiren HTTP isteklerinde kullanılan güvenilen kaynaklarla karşılaştırır. Mevcut WebSocket merkezi, olayları bağlı tüm soketlere yayınlar. device_id sorgusu bağlantının cihaz bağlamını seçer ancak olay iletimini yalıtmaz. Kontrol paneli görünümünü filtrelemek için olayın cihaz tanımlayıcılarını kullanın ve API erişimini yalnızca tüm cihazlara erişimine güvenilen çağrıcılara verin. Olay kodları, yükler ve bir istemci örneği için WebSocket başvurusuna bakın.

CORS

CORS varsayılan olarak tüm kaynaklara izin verir. APP_CORS_ALLOWED_ORIGINS=https://ui.example.com ile kısıtlayın (virgülle ayrılmış). İzin verilen istek başlıkları Origin, Content-Type, Accept, Authorization ve X-Device-Id şeklindedir. CORS ile tarayıcı kaynak denetimleri ayrıdır. Joker karakterli bir CORS kaynağı, durum değiştiren isteklere veya WebSocket bağlantılarına izin vermez. GOWA, isteğin kendi ana makinesine, belirli CORS kaynaklarına, APP_TRUSTED_ORIGINS değerlerine ve OAuth sağlayıcısı ile Chatwoot geri çağrı URL’si için yapılandırılan kaynaklara güvenir. Ayrı bir kontrol paneli için tam kaynağını yapılandırın:
Güvenilmeyen bir tarayıcı durum değişikliği isteği 403 CROSS_SITE_REQUEST_BLOCKED döndürür. Bu, oturum açan, oturumu kapatan, yeniden bağlanan veya davet bağlantısını sıfırlayan GET yollarını da kapsar. Tarayıcı kaynak başlıkları göndermeyen curl gibi istemciler çalışmaya devam eder. null kaynağına asla güvenilmez. gowa-ui.html dosyasını file:// URL’si olarak açmak yerine HTTP veya HTTPS üzerinden sunun. Bir ters vekilin arkasında Host başlığını koruyun, güvenilen vekilleri X-Forwarded-Host ile yapılandırın veya genel erişime açık kaynağı APP_TRUSTED_ORIGINS içinde listeleyin.

WhatsApp eşleştirme

Her WhatsApp hesabı bir cihaz yuvasında bulunur. Önce yuvayı oluşturun, ardından eşleştirin. /devices/{device_id} altındaki yollar, cihazı yoldan alır. Eşdeğer /app/* yolları X-Device-Id başlığını kullanır.

QR kodu

qr_link adresini açın ve telefondan tarayın: Ayarlar → Bağlı cihazlar → Cihaz bağla. qr_duration saniye sonra yeni bir kod isteyin. / yolundaki kontrol paneli QR kodunu doğrudan gösterir ve WebSocket üzerinden canlı güncellenir.

Eşleştirme kodu

Yanıtta 8 karakterli results.pair_code kodu bulunur. Telefonda Bunun yerine telefon numarasıyla bağla seçeneğini seçip kodu yazın. phone, bağlanan hesabın ülke kodunu içeren numarası olmalıdır.

Geçiş anahtarı

QR ile oturum açarken telefon geçiş anahtarı doğrulaması isterse GOWA bir WebAuthn doğrulama isteği saklar ve WebSocket üzerinden PASSKEY_REQUEST yayınlar. Kontrol paneli bu akışı yönetir. Kendiniz yönetmek için:
  1. GET /app/passkey, bekleyen doğrulama isteğini döndürür.
  2. POST /app/passkey/response, WebAuthn doğrulama beyanını gönderir (PublicKeyCredential.toJSON() biçiminde).
  3. PASSKEY_CONFIRMATION olayını bekleyin. result.skip_handoff_ux doğru olduğunda etkin QR akışı onayı otomatik gönderir. Aksi halde result.code değerini telefondaki kodla karşılaştırın, ardından POST /app/passkey/confirm çağrısı yapın.
Üç çağrının tamamında X-Device-Id gönderin.

Sonucu kontrol edin

Hesap bağlandığında results.is_connected ve results.is_logged_in değerlerinin ikisi de true olur. Oturumlar storages/ içinde kalıcı olarak saklanır; bu nedenle yeniden başlatmalarda tekrar eşleştirme gerekmez.

Oturumu kapatma ve kaldırma

Telefondan bağlantısı kaldırılan bir hesabın (Bağlı cihazlar → Çıkış yap) oturumu da aynı şekilde kapatılır: yuva kalır ve yeniden eşleştirilmesi gerekir.

Güvenlik kontrol listesi

  • Ağdan erişilebilen her kurulumda APP_BASIC_AUTH değerini güçlü parolalarla ayarlayın.
  • TLS’i bir ters vekilde sonlandırın; Basic Auth kimlik bilgileri yalnızca base64 ile kodlanır.
  • Bir tarayıcı arayüzü API’yi çağırdığında APP_CORS_ALLOWED_ORIGINS değerini kısıtlayın.
  • Kalıcı bir WHATSAPP_WEBHOOK_SECRET anahtarını openssl rand -hex 32 ile oluşturun. Boş veya yayımlanmış örnek gizli anahtarlar, her süreç için rastgele üretilen ve yeniden başlatıldığında değişen bir anahtarla değiştirilir.
  • storages/ dizinini hassas veri olarak değerlendirin. Bağlı her hesabın oturum anahtarlarını içerir. Yeni SQLite dosyaları yalnızca sahibine erişim veren izinler kullanır; bunlar için oluşturulan dizinlerde 0700 kullanılır. Yedekleri de aynı özenle koruyun.