Nylas Hosted OAuth ile Kullanıcı Posta Kutularını Kolayca Bağlayın

Modern web uygulamalarında kullanıcı adına e-posta göndermek, takvim olaylarını yönetmek veya kişiler listesini okumak için OAuth yetkilendirmesi şart. Ancak Google, Microsoft veya diğer sağlayıcıların her birine ayrı ayrı kayıt olmak, farklı konsent ekranlarını yönetmek ve token yenileme işlemlerini elle gerçekleştirmek zaman alıcı ve karmaşık olabilir. Nylas Hosted OAuth çözümü, bu süreci tek bir akışa indirgeyerek tüm sağlayıcıları destekleyen standart bir yöntem sunuyor.

Bu rehberde, Nylas Hosted OAuth akışını hem üretim ortamında kullanabileceğiniz HTTP API yöntemiyle hem de geliştirme aşamasında tercih edebileceğiniz komut satırı aracıyla nasıl uygulayacağınızı adım adım açıklıyoruz. Bu sayede kullanıcıların posta kutularına güvenli bir şekilde erişebilir ve uygulamanızın tüm özelliklerini sorunsuzca entegre edebilirsiniz.

Nylas'ta Yetkilendirme Nedir?

Nylas sisteminde "grant" adı verilen yetkilendirme birimi, bir kullanıcının e-posta, takvim veya kişiler verilerine erişim sağlamak için uygulamanıza verdiği izindir. Kullanıcı yetkilendirmeyi tamamladığında Nylas, size kalıcı bir grant_id tanımlayıcısı verir. Bu tanımlayıcıyı her API çağrısında kullanarak kullanıcının verilerine erişebilirsiniz.

Yetkilendirme sürecinde iki farklı kimlik bilgisi önem taşıyor:

• API anahtarınız: Uygulamanızın Nylas'a kimlik doğrulaması için kullandığı gizli anahtar. Bu anahtar her API isteğinde Authorization başlığında gönderilir ve uygulamaya ait kalıcı bir kimlik görevi görür.
• grant_id: Kullanıcı tarafından yetkilendirilen ve her API isteğinde hangi kullanıcının verilerine erişileceğini belirleyen tanımlayıcı. Bu kimlik yalnızca ilgili kullanıcı için oluşturulur ve uygulamada saklanır.

Hosted OAuth sayesinde Google, Microsoft, Yahoo, iCloud, IMAP ve Exchange gibi farklı posta sağlayıcıları arasındaki farklar ortadan kalkıyor. Her sağlayıcı için ayrı ayrı OAuth akışı uygulamaya gerek kalmadan, tek bir standart süreçle tüm bağlantılar yönetilebiliyor.

Hosted OAuth Akışının Üç Temel Adımı

Nylas Hosted OAuth, standart bir yetkilendirme kodu akışını takip eder ve üç temel aşamadan oluşur:

1. Yönlendirme aşaması: Uygulamanız kullanıcıyı, Nylas tarafından barındırılan yetkilendirme URL'sine yönlendirir. Bu URL'de uygulamanızın client_id, kullanıcının yönlendirileceği redirect_uri ve yetkilendirme türü (response_type=code) gibi gerekli parametreler yer alır.

1. Kullanıcı onayı aşaması: Kullanıcı, sağlayıcısının giriş ekranında kimlik doğrulaması yapar ve uygulamanıza gerekli izinleri verir. Yetkilendirme başarılı olduktan sonra kullanıcı, belirlediğiniz redirect_uri adresine otomatik olarak yönlendirilir ve URL'ye ?code= parametresiyle bir yetkilendirme kodu eklenir.

1. Token değişimi aşaması: Uygulamanızın arka uç sistemi, bu yetkilendirme kodunu Nylas sunucularına göndererek kalıcı bir grant_id alır. Bu değişim sırasında uygulamanızın gizli anahtarı kullanıldığı için işlem yalnızca sunucu tarafında gerçekleştirilmelidir.

Bu akışın en önemli avantajı, sağlayıcıya özel farklılıkların tamamen soyutlanmasıdır. Google, Microsoft veya diğer sağlayıcılar için farklı OAuth akışları uygulamaya gerek kalmadan, tüm bağlantılar standart bir şekilde yönetilebilir.

Yetkilendirme URL'sinin Oluşturulması

Uygulamanızın kullanıcıları yetkilendirme sürecine başlatmak için aşağıdaki adımları izleyin:

• Nylas API'sinin /v3/connect/auth uç noktasına bir GET isteği gönderin.
• İsteğinize client_id, redirect_uri, response_type=code ve isteğe bağlı olarak provider parametrelerini ekleyin.
• Oluşturulan URL'yi kullanıcıyı yönlendirmek için kullanın.

Aşağıda örnek bir URL yapısı görülüyor. Uygulamanızda bu URL'nin parametrelerini dinamik olarak oluşturmanız gerekecek:

access_type parametresi, uygulamanızın ihtiyaçlarına göre online veya offline olarak ayarlanabilir:

• online: Kullanıcı oturumdayken geçerli olan ve sürekli erişim gerektirmeyen durumlar için uygundur. Bu seçenek, token yenileme işlemlerini devre dışı bırakır.
• offline: Uygulamanızın kullanıcı oturumundan bağımsız olarak arka planda veri okuma veya gönderme işlemleri gerçekleştirmesi gerektiğinde kullanılır.

Yetkilendirme tamamlandığında kullanıcı, belirlediğiniz redirect_uri adresine yönlendirilir ve URL'ye ?code= parametresiyle birlikte bir yetkilendirme kodu eklenir. Bu kod, bir sonraki adıma geçmek için kullanılacaktır.

Yetkilendirme Kodunun grant_id'ye Dönüştürülmesi

Kullanıcı yetkilendirmeyi tamamladıktan sonra uygulamanızın arka uç sistemi, aldığınız yetkilendirme kodunu Nylas sunucularına göndererek kalıcı bir grant_id elde etmelidir. Bu işlem yalnızca sunucu tarafında yapılmalıdır, çünkü API gizli anahtarını içerir.

İşte örnek bir token değişim isteği:

curl --request POST \
  --url " \
  --header "Content-Type: application/json" \
  --data '{
    "client_id": "NYLAS_CLIENT_ID",
    "client_secret": "NYLAS_API_KEY",
    "code": "AUTH_CODE",
    "redirect_uri": "
    "grant_type": "authorization_code"
  }'

Başarılı bir yanıt aldığınızda, yanıt içinde yer alan grant_id değerini kullanıcı kayıtlarınıza kaydedin. Artık kullanıcının verilerine erişmek için bu tanımlayıcıyı kullanabilirsiniz. Yetkilendirme kodu tek kullanımlıktır; aynı kod ikinci kez gönderildiğinde hata alırsınız.

Geliştirme Ortamında CLI ile Test Hesabı Bağlama

Üretim ortamında OAuth akışı, uygulamanızın hem ön yüzünde hem de arka yüzünde gerçekleşirken, geliştirme aşamasında tüm sistemi kurmak zahmetli olabilir. Nylas komut satırı aracı (CLI), bu süreci basitleştirerek terminal üzerinden tam yetkilendirme akışını yönetmenizi sağlar.

CLI kullanarak bir test hesabı bağlamak için aşağıdaki komutları kullanabilirsiniz:

• Google hesabı bağlamak (varsayılan):

nylas auth login

• Farklı bir sağlayıcı seçmek için:

nylas auth login --provider microsoft
nylas auth login --provider imap

Desteklenen sağlayıcılar arasında google, microsoft, ews, icloud, yahoo ve imap bulunuyor. CLI aracı, yetkilendirme akışını tamamladıktan sonra elde edilen grant_id'yi otomatik olarak kaydeder ve bu hesabı varsayılan olarak ayarlar. Bu sayede geliştirme sürecinde hızlıca test ortamı oluşturabilirsiniz.

Sonuç: Basitlik ve Standartlaşma için Tek Yol

Nylas Hosted OAuth, farklı posta sağlayıcıları arasındaki karmaşıklığı ortadan kaldırarak geliştiricilere tek bir standart akış sunuyor. Bu sayede uygulamanızın kullanıcı adına gerçekleştireceği tüm e-posta, takvim ve kişiler işlemlerinde gerekli yetkilendirme süreci basitleşiyor.

Geliştirme sırasında CLI aracını kullanarak hızlıca test hesapları oluşturabilir, üretim ortamında ise standart HTTP API yöntemini uygulayarak kullanıcıların verilerine güvenli bir şekilde erişebilirsiniz. Bu yaklaşım, hem geliştirme sürecini hızlandırıyor hem de uygulamanızın farklı sağlayıcılarla uyumluluğunu garanti altına alıyor. Gelecekte OAuth akışlarının daha da standartlaşmasıyla birlikte, geliştiricilerin bu tür karmaşıklıklardan kurtulması ve asıl ürün geliştirmeye odaklanması mümkün olacak.