OAuth 2.0 Sistemi

Bu belgede, IMAP AUTHENTICATE, POP AUTH ve SMTP AUTH komutlarıyla kullanılacak 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

İlk olarak Google API'lerine Erişmek İçin OAuth 2.0'ı Kullanma başlıklı makaleyi inceleyin. Bu belgede, OAuth 2.0'ın 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/'dır. IMAP, POP veya SMTP uygulamanız için tam posta kapsamına erişim isteğinde bulunursanı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/ öğesinin 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.

Google Workspace için alan genelinde yetki

Google Workspace kullanıcılarının posta kutularına IMAP üzerinden erişmek için hizmet hesaplarını kullanarak Google Workspace alan genelinde yetkilendirmeyi kullanmayı planlıyorsanız istemcinizi https://www.googleapis.com/auth/gmail.imap_admin kapsamını kullanarak yetkilendirebilirsiniz.

Bu kapsamla 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 ayarladığına 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 İstemci Yanıtı

SASL XOAUTH2 ilk istemci yanıtı aşağıdaki biçimdedir:

base64("user=" {User} "^Aauth=Bearer " {Access Token} "^A^A")

RFC 4648'de tanımlanan base64 kodlama mekanizmasını kullanın. ^A, Control+A (\001) karakterini temsil eder.

Örneğin, base64 kodlamasından önce ilk istemci yanıtı şu şekilde görünebilir:

user=someuser@example.com^Aauth=Bearer ya29.vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg^A^A

Base64 kodlamasından sonra bu değer (netlik 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 sorgu göndermesine neden olur:

base64({JSON-Body})

JSON-Body üç değer içerir: status, schemes ve scope. Örneğin:

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

Base64 kod çözme işleminden sonra bu değer (netlik için biçimlendirilmiş olarak) şu şekilde olur:

{
  "status":"401",
  "schemes":"bearer",
  "scope":"https://mail.google.com/"
}

SASL protokolü, istemcilerin bu zorluğa boş bir yanıt göndermesini gerektirir.

IMAP Protokolü Exchange

Bu bölümde, Gmail IMAP sunucusuyla SASL XOAUTH2'nin nasıl kullanılacağı açıklanmaktadır.

İlk İstemci Yanıtı

SASL XOAUTH2 mekanizmasıyla oturum açmak için istemci, AUTHENTICATE komutunu XOAUTH2 mekanizma parametresiyle ve yukarıda oluşturulan ilk istemci yanıtıyla ç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şimi hakkında dikkat edilmesi gerekenler:

  • IMAP AUTHENTICATE komutu RFC 3501'de belgelenmiştir.
  • 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üş gerekir. SASL-IR, RFC 4959'da belgelenmiştir.
  • AUTH=XOAUTH2 özelliği, sunucunun bu belgede tanımlanan SASL mekanizmasını desteklediğini ve bu mekanizmanın AUTHENTICATE komutunun ilk bağımsız değişkeni olarak XOAUTH2 belirtilerek etkinleştirildiğini bildirir.
  • AUTHENTICATE ve CAPABILITY komutlarındaki satır sonları, anlaşılırlık için eklenmiştir ve gerçek komut verilerinde yer almaz. Base64 bağımsız değişkeninin tamamı, tek bir metin satırından oluşan AUTHENTICATE komutunun tamamı için boşluk içermeyen tek bir dize olmalıdır.

Hata Yanıtı

Kimlik doğrulama hataları, IMAP AUTHENTICATE komutuyla 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şimi hakkında dikkat edilmesi gerekenler:

  • İstemci, hata mesajını içeren sorguya boş bir yanıt ("\r\n") gönderir.

POP Protokolü Değişimi

Bu bölümde, Gmail POP sunucusuyla SASL XOAUTH2'nin nasıl kullanılacağı açıklanmaktadır.

İlk İstemci Yanıtı

SASL XOAUTH2 mekanizmasıyla oturum açmak için istemci, AUTH komutunu XOAUTH2 mekanizma parametresiyle ve yukarıda oluşturulan ilk istemci yanıtıyla ç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 belgelenmiştir.
  • AUTH komutundaki satır sonları, netlik için eklenmiştir ve gerçek komut verilerinde yer almaz. Base64 bağımsız değişkeninin tamamı, tek bir metin satırından oluşan AUTH komutunun tamamı için boşluk içermeyen tek bir dize olmalıdır.

Hata Yanıtı

Kimlik doğrulama hataları, POP AUTH komutuyla 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, Gmail SMTP sunucusuyla SASL XOAUTH2'nin nasıl kullanılacağı açıklanmaktadır.

İlk İstemci Yanıtı

XOAUTH2 mekanizmasıyla oturum açmak için istemci, AUTH komutunu XOAUTH2 mekanizma parametresi ve yukarıda oluşturulan ilk istemci yanıtıyla birlikte ç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 belgelenmiştir.
  • AUTH komutundaki satır sonları, netlik için eklenmiştir ve gerçek komut verilerinde yer almaz. Base64 bağımsız değişkeninin tamamı, tek bir metin satırından oluşan AUTH komutunun tamamı için boşluk içermeyen tek bir dize olmalıdır.

Hata Yanıtı

Kimlik doğrulama hataları, SMTP AUTH komutuyla 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 sorguya boş bir yanıt ("\r\n") gönderir.

Referanslar