OAuth 2.0 Sistemi

Bu dokümanda, IMAP AUTHENTICATE, POP AUTH ve SMTP AUTH komutlarıyla kullanılmak üzere SASL XOAUTH2 mekanizması açıklanmaktadır. Bu mekanizma, bir kullanıcının Gmail hesabının kimliğinin doğrulanması için OAuth 2.0 Erişim Jetonlarının kullanılmasına izin verir.

OAuth 2.0'ı kullanma

Google API'lerine Erişmek için OAuth 2.0'ı Kullanma hakkında bilgi edinerek başlayın. Bu dokümanda, 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 göz atmak da isteyebilirsiniz.

OAuth 2.0 Kapsamları

IMAP, POP ve SMTP erişimi https://mail.google.com/ ile sınırlıdır. IMAP, POP veya SMTP uygulamanız için tam posta kapsamına erişim talep ediyorsanız uygulamanız Google API Hizmetleri: Kullanıcı Verileri Politikamıza uygun olmalıdır.

  • Onaylanması için uygulamanızın https://mail.google.com/ ürününün tam kullanımı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 Workspaceiçin alan genelinde yetki

IMAP erişimi üzerinden Google Workspace kullanıcıların posta kutularına erişmek için Hizmet Hesapları ile Google Workspace alan genelinde yetki kullanmayı düşünüyorsanız Google Workspace https://www.googleapis.com/auth/gmail.imap_admin kapsamı kullanarak istemcinizi yetkilendirebilirsiniz.

Bu kapsamla yetkilendirildiğinde IMAP bağlantıları farklı davranır:

  • Kullanıcılar Gmail ayarlarında etiket için "IMAP'te göster"i devre dışı bırakmış olsa bile tüm etiketler IMAP yoluyla gösterilir.
  • Kullanıcının Gmail ayarlarındaki "Klasör Boyutu Sınırları"nda belirlediğinden bağımsız olarak tüm iletiler IMAP yoluyla gösterilir.

SASL XOAUTH2 Sistemi

XOAUTH2 mekanizması, istemcilerin sunucuya OAuth 2.0 erişim jetonları göndermesine izin verir. 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ı şu 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) işaretini temsil eder.

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

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

Base64 kodlamasından sonra şu hale gelir (netlik için satır sonları eklenir):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Hata Yanıtı

Hataya neden olan ilk istemci yanıtı, sunucunun aşağıdaki biçimde bir hata mesajı içeren bir sorgulama 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 öğe şu şekilde olur (netlik için biçimlendirilir):

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

SASL protokolü için istemcilerin bu sorgulamaya boş yanıt göndermeleri gerekir.

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ı

İstemci SASL XOAUTH2 mekanizmasıyla giriş yapmak için AUTHENTICATE komutunu XOAUTH2 mekanizma parametresi ve yukarıda yapılandırıldığı gibi ilk istemci yanıtı ile ç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 ile ilgili göz önünde bulundurulması gerekenler:

  • IMAP AUTHENTICATE komutu, RFC 3501'de belgelenmiştir.
  • SASL-IR özelliği, AUTHENTICATE komutunun ilk satırında ilk istemci yanıtının gönderilmesine olanak tanır. Böylece, kimlik doğrulama için tek bir gidiş dönüş yapılması gerekir. SASL-IR, RFC 4959'da belgelenmiştir.
  • AUTH=XOAUTH2 özelliği, sunucunun bu belge ile tanımlanan SASL mekanizmasını desteklediğini bildirir ve bu mekanizma, AUTHENTICATE komutunun ilk bağımsız değişkeni olarak XOAUTH2 belirtilerek etkinleştirilir.
  • AUTHENTICATE ve CAPABILITY komutlarındaki satır sonları netleştirme amaçlıdır ve gerçek komut verilerinde yer almaz. Base64 bağımsız değişkeninin tamamı, yerleştirilmiş boşluk içermeyen tek bir sürekli dize olmalıdır. Böylece, AUTHENTICATE komutunun tamamı tek bir metin satırından oluşur.

Hata Yanıtı

Kimlik doğrulama hataları da IMAP AUTHENTICATE komutu aracılığıyla 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 ile ilgili göz önünde bulundurulması gerekenler:

  • İstemci, hata mesajını içeren sorgulamaya 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ı

İstemci SASL XOAUTH2 mekanizmasıyla giriş yapmak için AUTH komutunu XOAUTH2 mekanizma parametresi ve yukarıda yapılandırıldığı gibi ilk istemci yanıtı ile çağırır. Örneğin:

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0
Q2cBAQ==
S: +OK Welcome.
[connection continues...]

POP protokol değişimi ile ilgili göz önünde bulundurulması gereken noktalar:

  • POP AUTH komutu, RFC 1734'te belgelenmiştir.
  • AUTH komutundaki satır sonları netlik sağlamak içindir ve gerçek komut verilerinde yer almaz. Base64 bağımsız değişkeninin tamamı, yerleştirilmiş boşluk içermeyen tek bir sürekli dize olmalıdır. Böylece, AUTH komutunun tamamı tek bir metin satırından oluşur.

Hata Yanıtı

Kimlik doğrulama hataları da POP AUTH komutu aracılığıyla 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 sunucusuyla nasıl kullanılacağı açıklanmaktadır.

İlk Müşteri Yanıtı

İstemci XOAUTH2 mekanizmasıyla giriş yapmak için AUTH komutunu XOAUTH2 mekanizma parametresiyle ve yukarıda yapılandırıldığı gibi ilk istemci yanıtıyla ç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şimi ile ilgili göz önünde bulundurulması gereken noktalar:

  • SMTP AUTH komutu, RFC 4954'te belgelenmiştir.
  • AUTH komutundaki satır sonları netlik sağlamak içindir ve gerçek komut verilerinde yer almaz. Base64 bağımsız değişkeninin tamamı, yerleştirilmiş boşluk içermeyen tek bir sürekli dize olmalıdır. Böylece, AUTH komutunun tamamı tek bir metin satırından oluşur.

Hata Yanıtı

Kimlik doğrulama hataları da SMTP AUTH komutu aracılığıyla 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şimi ile ilgili göz önünde bulundurulması gereken noktalar:

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

Referanslar