Bu dokümanda, IMAPAUTHENTICATE
, POP AUTH
ve SMTP AUTH
komutlarıyla birlikte kullanılmak üzere SASL XOAUTH2 mekanizması tanımlanmaktadır. Bu mekanizma, kullanıcının Gmail hesabında kimlik doğrulaması yapmak için OAuth 2.0 erişim jetonlarının kullanılmasına olanak tanır.
OAuth 2.0'ı kullanma
Google API'lerine Erişmek için OAuth 2.0'ı Kullanma başlıklı makaleyi inceleyerek başlayın. Bu dokümanda, OAuth 2.0'un işleyiş şekli ve istemci yazmak için gereken adımlar açıklanmaktadır.
Çalışan örnekler için örnek XOAUTH2 koduna da göz atabilirsiniz.
OAuth 2.0 Kapsamları
IMAP, POP ve SMTP erişiminin kapsamı https://mail.google.com/
'tür. IMAP, POP veya SMTP uygulamanız için tam posta kapsamına erişim isteğinde bulunuyorsanız uygulamanız Google API Hizmetleri: Kullanıcı Verileri Politikamıza uygun olmalıdır.
- Uygulamanızın onaylanması için
https://mail.google.com/
'ün tam olarak kullanıldığını göstermesi gerekir. - Uygulamanız
https://mail.google.com/
gerektirmiyorsa Gmail API'ye geçin ve daha ayrıntılı kısıtlanmış kapsamlar kullanın.
için alan genelinde yetki
IMAP üzerinden kullanıcılarının posta kutularına erişmek için hizmet hesaplarını kullanarak alan genelinde yetkilendirme kullanmayı planlıyorsanız bunun yerine https://www.googleapis.com/auth/gmail.imap_admin
kapsamını kullanarak istemcinizi yetkilendirebilirsiniz.
Bu kapsamda yetkilendirildiğinde IMAP bağlantıları farklı şekilde davranır:
- Kullanıcılar Gmail ayarlarında etiket için "IMAP'te göster" seçeneğini devre dışı bıraksa bile tüm etiketler IMAP üzerinden gösterilir.
- Kullanıcının Gmail ayarlarındaki "Klasör Boyutu Sınırları" bölümünde ne belirlediğine bakılmaksızın tüm iletiler IMAP üzerinden gösterilir.
SASL XOAUTH2 Mekanizması
XOAUTH2 mekanizması, istemcilerin sunucuya OAuth 2.0 erişim jetonları göndermesine olanak tanır. Protokol, aşağıdaki bölümlerde gösterilen kodlanmış değerleri kullanır.
İlk Müşteri Yanıtı
SASL XOAUTH2 ilk istemci yanıtı aşağıdaki biçime sahiptir:
base64("user=" {User} "^Aauth=Bearer " {Access Token} "^A^A")
RFC 4648'de tanımlanan base64 kodlama mekanizmasını kullanın. ^A
, Ctrl+A (\001) tuş kombinasyonunu temsil eder.
Örneğin, base64 kodlamadan önce istemcinin ilk yanıtı şu şekilde görünebilir:
user=someuser@example.com^Aauth=Bearer ya29.vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg^A^A
Base64 kodlamasından sonra bu şu şekilde olur (anlaşılırlık için satır sonları eklenmiştir):
dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
Hata Yanıtı
Hataya neden olan ilk istemci yanıtı, sunucunun aşağıdaki biçimde bir hata mesajı içeren bir istek göndermesine neden olur:
base64({JSON-Body})
JSON-Body, status
, schemes
ve scope
olmak üzere üç değer içerir. Örneğin:
eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K
Base64 ile kod çözme işleminin ardından bu değer şu şekilde görünür (anlaşılır olması için biçimlendirilmiştir):
{
"status":"401",
"schemes":"bearer",
"scope":"https://mail.google.com/"
}
SASL protokolü, istemcilerin bu istem için boş bir yanıt göndermesini gerektirir.
IMAP Protokolü Değişimi
Bu bölümde, SASL XOAUTH2'nin Gmail IMAP sunucusuyla nasıl kullanılacağı açıklanmaktadır.
İlk Müşteri Yanıtı
SASL XOAUTH2 mekanizmasıyla giriş yapmak için istemci, XOAUTH2
mekanizma parametresi ve yukarıda oluşturulan ilk istemci yanıtıyla AUTHENTICATE
komutunu çağırır. Örneğin:
[connection begins]
C: C01 CAPABILITY
S: * CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA XLIST
CHILDREN XYZZY SASL-IR AUTH=XOAUTH2 AUTH=XOAUTH
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvb
QFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG
1semRHRXVZMjl0Q2cBAQ==
S: A01 OK Success
[connection continues...]
IMAP protokolü değişimiyle ilgili dikkat edilmesi gereken noktalar:
- IMAP
AUTHENTICATE
komutu RFC 3501'de açıklanmıştır. - SASL-IR özelliği, ilk istemci yanıtının
AUTHENTICATE
komutunun ilk satırında gönderilmesine olanak tanır. Böylece kimlik doğrulama için yalnızca bir gidiş dönüş işlemi gerekir. SASL-IR, RFC 4959'da açıklanmıştır. - AUTH=XOAUTH2 özelliği, sunucunun bu doküman tarafından tanımlanan SASL mekanizmasını desteklediğini belirtir ve bu mekanizma,
AUTHENTICATE
komutunun ilk bağımsız değişkeni olarak XOAUTH2 belirtilerek etkinleştirilir. AUTHENTICATE
veCAPABILITY
komutlarındaki satır sonları, anlaşılması kolay olması içindir ve gerçek komut verilerinde bulunmaz. Base64 bağımsız değişkeninin tamamı, yerleştirilmiş boşluk içermeyen tek bir kesintisiz dize olmalıdır. BöyleceAUTHENTICATE
komutunun tamamı tek bir metin satırından oluşur.
Hata Yanıtı
Kimlik doğrulama hataları, IMAP AUTHENTICATE
komutu aracılığıyla da döndürülür:
[connection begins]
S: * CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA XLIST
CHILDREN XYZZY SASL-IR AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQ
FhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1s
emRHRXVZMjl0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb
3BlIjoiaHR0cHM6Ly9tYWlsLmdvb2dsZS5jb20vIn0K
C:
S: A01 NO SASL authentication failed
IMAP protokolü değişimiyle ilgili dikkat edilmesi gereken noktalar:
- İstemci, hata mesajını içeren istem için boş bir yanıt ("\r\n") gönderir.
POP Protokol Değişimi
Bu bölümde, SASL XOAUTH2'nin Gmail POP sunucusuyla nasıl kullanılacağı açıklanmaktadır.
İlk Müşteri Yanıtı
SASL XOAUTH2 mekanizmasıyla giriş yapmak için istemci, XOAUTH2
mekanizma parametresi ve yukarıda oluşturulan ilk istemci yanıtıyla AUTH
komutunu çağırır. Örneğin:
[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0
Q2cBAQ==
S: +OK Welcome.
[connection continues...]
POP protokolü değişimiyle ilgili dikkat edilmesi gerekenler:
- POP
AUTH
komutu RFC 1734'te açıklanmıştır. AUTH
komutundaki satır sonları, anlaşılması kolay olması içindir ve gerçek komut verilerinde bulunmaz. Base64 bağımsız değişkeninin tamamı, yerleştirilmiş boşluk içermeyen tek bir kesintisiz dize olmalıdır. BöyleceAUTH
komutunun tamamı tek bir metin satırından oluşacaktır.
Hata Yanıtı
Kimlik doğrulama hataları, POP AUTH
komutu aracılığıyla da döndürülür:
[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDAiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUi
OiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ==
SMTP Protokolü Değişimi
Bu bölümde, SASL XOAUTH2'nin Gmail SMTP sunucusunda nasıl kullanılacağı açıklanmaktadır.
İlk Müşteri Yanıtı
XOAUTH2 mekanizmasıyla giriş yapmak için istemci, XOAUTH2
mekanizma parametresi ve yukarıda oluşturulan ilk istemci yanıtıyla AUTH
komutunu çağırır. Örneğin:
[connection begins]
S: 220 mx.google.com ESMTP 12sm2095603fks.9
C: EHLO sender.example.com
S: 250-mx.google.com at your service, [172.31.135.47]
S: 250-SIZE 35651584
S: 250-8BITMIME
S: 250-AUTH LOGIN PLAIN XOAUTH XOAUTH2
S: 250-ENHANCEDSTATUSCODES
S: 250 PIPELINING
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 235 2.7.0 Accepted
[connection continues...]
SMTP protokolü değişimiyle ilgili dikkat edilmesi gereken noktalar:
- SMTP
AUTH
komutu RFC 4954'te açıklanmıştır. AUTH
komutundaki satır sonları, anlaşılması kolay olması içindir ve gerçek komut verilerinde bulunmaz. Base64 bağımsız değişkeninin tamamı, yerleştirilmiş boşluk içermeyen tek bir kesintisiz dize olmalıdır. BöyleceAUTH
komutunun tamamı tek bir metin satırından oluşur.
Hata Yanıtı
Kimlik doğrulama hataları, SMTP AUTH
komutu aracılığıyla da döndürülür:
[connection begins]
S: 220 mx.google.com ESMTP 12sm2095603fks.9
C: EHLO sender.example.com
S: 250-mx.google.com at your service, [172.31.135.47]
S: 250-SIZE 35651584
S: 250-8BITMIME
S: 250-AUTH LOGIN PLAIN XOAUTH XOAUTH2
S: 250-ENHANCEDSTATUSCODES
S: 250 PIPELINING
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJl
ciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cB
AQ==
S: 334 eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb
3BlIjoiaHR0cHM6Ly9tYWlsLmdvb2dsZS5jb20vIn0K
C:
S: 535-5.7.1 Username and Password not accepted. Learn more at
S: 535 5.7.1 https://support.google.com/mail/?p=BadCredentials hx9sm5317360pbc.68
[connection continues...]
SMTP protokolü değişimiyle ilgili dikkat edilmesi gereken noktalar:
- İstemci, hata mesajını içeren istem için boş bir yanıt ("\r\n") gönderir.
Referanslar
- OAUTH2: Google API'lerine Erişmek için OAuth 2.0'ı Kullanma
- SMTP: RFC 2821: Basit Posta Aktarım Protokolü
- IMAP: RFC 3501: INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1
- POP: RFC 1081: Post Office Protocol - Version 3
- SASL: RFC 4422: Basit Kimlik Doğrulama ve Güvenlik Katmanı (SASL)
- JSON: RFC 4627: JavaScript Nesne Gösterimi için application/json Medya Türü
- BASE64: RFC 4648: Base16, Base32 ve Base64 Veri Kodlamaları
- SASL-IR: RFC 4959: Basit Kimlik Doğrulama ve Güvenlik Katmanı (SASL) İlk İstemci Yanıtı için IMAP Uzantısı
- SMTP-AUTH: RFC 4954: Kimlik Doğrulama İçin SMTP Hizmeti Uzantısı