03 — Uygulama Kaydı ve Ortamlar

Kimin için: Uygulama mimarları ve entegrasyonu başlatan geliştiriciler.
Ön koşul: TALOST ID hesabı ve Temel Kavramlar.
Tahmini süre: 10 dakika.

Ne Öğreneceksiniz

• TALOST ID üzerinde yeni bir uygulama oluşturmayı ve temel ayarlarını yapılandırmayı,
• DEV, STAGING ve PRODUCTION ortamlarının izolasyon kurallarını,
• Geçerli Redirect URI, Allowed Origins ve Post-Logout kurallarını,
• İstemci anahtarı rotasyonunu (rotate-secret).

Ortam Mimarisi ve İzolasyon Kuralları

TALOST ID, geliştirme ve canlı sistemlerin birbirini etkilememesi için katı bir 3'lü ortam mimarisine sahiptir:

Redirect URI ve Güvenlik Kuralları

Giriş tamamlandıktan sonra kullanıcının yönlendirileceği adresler için aşağıdaki güvenlik standartları uygulanır:

1. Tam Eşleşme (Exact Match):
   Authorize isteğinde gönderilen redirect_uri ile portalde kayıtlı adres karakteri karakterine aynı olmalıdır.
   • Örnek: https://app.com/callback/ (sonda slash var) ile https://app.com/callback (sonda slash yok) eşleşmez.
2. Joker Karakter (Wildcard) Yasaktır:
   https://*.example.com/callback gibi wildcard tanımlamalar OAuth 2.0 güvenlik açığı oluşturduğu için kabul edilmez.
3. Parça / Fragment (#) Yasaktır:
   URI içinde hash (#) işareti bulunamaz.
4. Yerel Ağ ve IP Kısıtlamaları:
   http://localhost veya http://127.0.0.1 adresleri yalnızca DEVELOPMENT ortamında geçerlidir; STAGING veya PRODUCTION istemcilerine kaydedilemez.
5. Özel Şemalar (Custom URI Schemes):
   Mobil ve masaüstü uygulamalar için özel şemalar desteklenir (örn: talostapp://oauth/callback).

Adım Adım Yapılandırma

1. Yeni Uygulama Başvurusu

• TALOST ID Yöneticiniz tarafından oluşturulmuş bir uygulamanız varsa Geliştirici Portalı üzerinden doğrudan erişebilirsiniz.
• Uygulamanızın slug değeri benzersizdir (örn: talost-flow).

2. İstemcileri Yapılandırma

Geliştirici Portalında uygulamanızı seçip Ortamlar sekmesine gelin:

1. İstemci Türü:
   • Confidential (Gizli İstemci): Sunucu taraflı web uygulamaları (Next.js, Node, Python, .NET, PHP). client_secret güvenli şekilde sunucuda tutulur.
   • Public (Açık İstemci): SPA (React, Vue) ve mobil/masaüstü istemciler. client_secret barındırmaz; yalnızca PKCE ile çalışır.
2. Yönlendirme Adresleri (Redirect URIs): Uygulamanızın geri dönüş rotalarını her satıra bir adet gelecek şekilde girin.
3. Çıkış Sonrası Adresler (Post Logout Redirect URIs): Kullanıcı oturumu kapattığında yönlendirilebileceği izinli adresler.
4. İzin Verilen Kaynaklar (Allowed Origins): SPA uygulamaları için CORS izinli domainler (örn: https://app.example.com).

İstemci Gizli Anahtarı (Client Secret) Rotasyonu

İstemci gizli anahtarınızın sızdığından şüphelenirseniz veya periyodik güvenlik gereği yenilemek isterseniz:

1. Geliştirici Portalında ilgili istemci kartındaki Gizli Anahtarı Yenile (Rotate Secret) butonuna tıklayın.
2. Açılan onay modalında onaylayın.
3. Dikkat: Eski gizli anahtar anında geçersiz kılınır ve eski anahtarla çalışan servisler yeni anahtar güncellenene kadar token alamaz.
4. Yeni üretilen anahtar ekranda yalnızca bir kez gösterilir. Hemen kopyalayıp güvenli ortam değişkenlerinize kaydedin.

Sık Yapılan Hatalar

• Port Uyuşmazlığı: Yerel sunucunuz http://localhost:3001 üzerinde çalışırken portalde http://localhost:3000 kayıtlı olması durumunda invalid_request hatası döner.
• HTTPS İhlali: STAGING veya PRODUCTION ortamına http:// protokolüyle başlayan bir adres kaydedilemez.
• Ekip Üyesi Olmayan Hesap: DEV istemcisinde test yaparken "Bu ortama erişim yetkiniz yok" uyarısı alırsanız, hesabınızı uygulamanın Ekip sekmesinden ekleyin.

Güvenlik Notları

• Canlı ortam (PRODUCTION) anahtarlarını asla test sunucularına veya yerel ortama kopyalamayın.
• İstemci kimliklerini (client_id, client_secret) doğrudan git reposuna git commit yapmayın; daima .env veya gizli anahtar kasaları (Vault vb.) kullanın.

İlgili Sayfalar

• 04.1. Web Sunucu Taraflı Giriş
• 16. Test ve Teşhis Araçları
• 17. Canlıya Alma Kontrol Listesi

Son doğrulama: 2026-10-04 · Kaynak: _envanter.md, src/lib/apps/redirect-uri.ts