OAuth 2.0 메커니즘

이 문서에서는 IMAP 액세스와 함께 사용하기 위한 SASL XOAUTH2 메커니즘을 정의합니다. AUTHENTICATE, POP AUTH, SMTP AUTH 명령어. 이 메커니즘을 사용하면 OAuth 2.0 액세스 토큰을 사용하여 사용자의 Gmail 계정에 인증

OAuth 2.0 사용

먼저 OAuth 2.0을 사용하여 Google API에 액세스하기를 숙지합니다. 해당 문서에서는 OAuth 2.0의 작동 방식과 클라이언트를 작성하는 데 필요한 단계를 설명합니다.

샘플 XOAUTH2 코드의 작업 예를 찾아볼 수도 있습니다.

OAuth 2.0 범위

IMAP, POP, SMTP 액세스의 범위는 https://mail.google.com/입니다. 만약 IMAP, POP 또는 SMTP 앱의 전체 메일 범위에 대한 액세스를 요청할 수 있습니다. Google API 서비스: 사용자 데이터 정책을 준수해야 합니다.

  • 승인되려면 앱에서 https://mail.google.com/을(를) 모두 사용하는 것으로 표시되어야 합니다.
  • 앱에 https://mail.google.com/가 필요하지 않은 경우 Gmail로 이전하세요. API 및 보다 세분화된 제한된 범위를 사용합니다.

Google Workspace의 도메인 전체 위임

Google Workspace 도메인 전체 위임 사용 서비스 계정 액세스 Google Workspace 권한을 가진 메일함, 범위를 사용하여 클라이언트를 https://www.googleapis.com/auth/gmail.imap_admin를 사용하세요.

이 범위로 승인하면 IMAP 연결이 다음과 같이 다르게 작동합니다.

  • 사용자가 'IMAP에 표시'를 사용 중지해도 모든 라벨은 IMAP을 통해 표시됩니다. 을 사용 중지할 수 있습니다.
  • 사용자가 '폴더 크기 제한'에 설정한 설정과 관계없이 모든 메일은 IMAP을 통해 표시됩니다. Gmail 환경설정에서 확인할 수 있습니다.
를 통해 개인정보처리방침을 정의할 수 있습니다.

SASL XOAUTH2 메커니즘

XOAUTH2 메커니즘을 사용하면 클라이언트가 OAuth 2.0 액세스 토큰을 서버로 보낼 수 있습니다. 이 프로토콜은 다음 섹션에 나와 있는 인코딩된 값을 사용합니다.

초기 고객 응답

SASL XOAUTH2 초기 클라이언트 응답의 형식은 다음과 같습니다.

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

RFC 4648에 정의된 base64 인코딩 메커니즘을 사용합니다. ^A는 Control+A (\001)를 나타냅니다.

예를 들어 base64 인코딩 전에 초기 클라이언트 응답은 다음과 같을 수 있습니다.

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

base64 인코딩 후에는 다음과 같이 됩니다 (명확하게 하기 위해 줄바꿈이 삽입됨).

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

오류 응답

오류를 일으키는 초기 클라이언트 응답으로 인해 서버는 챌린지에 도전해도 됩니다.

base64({JSON-Body})

JSON-Body에는 status, schemes, scope의 세 가지 값이 포함됩니다. 예를 들면 다음과 같습니다.

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

base64 디코딩 후에는 다음과 같이 됩니다 (명확히 하기 위한 형식).

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

SASL 프로토콜은 클라이언트가 이 챌린지에 대해 빈 응답을 보내도록 요구합니다.

IMAP 프로토콜 교환

이 섹션에서는 Gmail IMAP 서버에서 SASL XOAUTH2를 사용하는 방법을 설명합니다.

초기 고객 응답

SASL XOAUTH2 메커니즘으로 로그인하기 위해 클라이언트는 XOAUTH2의 메커니즘 매개변수와 위에 구성된 초기 클라이언트 응답을 사용하여 AUTHENTICATE 명령어를 호출합니다. 예를 들면 다음과 같습니다.

[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 프로토콜 교환 관련 참고사항

  • IMAP AUTHENTICATE 명령어는 RFC 3501에 설명되어 있습니다.
  • SASL-IR 기능을 사용하면 AUTHENTICATE 명령어의 첫 번째 줄에 초기 클라이언트 응답을 보낼 수 있으므로 인증에 한 번의 왕복만 필요합니다. SASL-IR은 RFC 4959에 문서화되어 있습니다.
  • AUTH=XOAUTH2 기능은 서버가 이 문서에 정의된 SASL 메커니즘을 지원함을 선언하며, 이 메커니즘은 XOAUTH2를 AUTHENTICATE 명령어의 첫 번째 인수로 지정하여 활성화됩니다.
  • AUTHENTICATE 명령어와 CAPABILITY 명령어의 줄바꿈은 명확성을 위한 것으로 실제 명령어 데이터에는 표시되지 않습니다. 전체 base64 인수는 공백이 포함되지 않은 하나의 연속된 문자열이어야 하므로 전체 AUTHENTICATE 명령어가 한 줄의 텍스트로 구성되어야 합니다.

오류 응답

인증 실패는 IMAP AUTHENTICATE 명령어를 통해서도 반환됩니다.

[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 프로토콜 교환 관련 참고사항

  • 클라이언트는 오류 메시지가 포함된 챌린지로 빈 응답("\r\n")을 보냅니다.

POP 프로토콜 교환

이 섹션에서는 Gmail POP 서버와 함께 SASL XOAUTH2를 사용하는 방법을 설명합니다.

초기 고객 응답

SASL XOAUTH2 메커니즘으로 로그인하기 위해 클라이언트는 XOAUTH2의 메커니즘 매개변수와 위에 구성된 초기 클라이언트 응답을 사용하여 AUTH 명령어를 호출합니다. 예를 들면 다음과 같습니다.

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

POP 프로토콜 교환 관련 참고사항:

  • POP AUTH 명령어는 RFC 1734에 설명되어 있습니다.
  • AUTH 명령어의 줄바꿈은 명확성을 위한 것으로 실제 명령어 데이터에는 표시되지 않습니다. 전체 base64 인수는 공백이 포함되지 않은 하나의 연속된 문자열이어야 하므로 전체 AUTH 명령어가 한 줄의 텍스트로 구성되어야 합니다.

오류 응답

인증 실패는 POP AUTH 명령어를 통해서도 반환됩니다.

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDAiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUi
OiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ==

SMTP 프로토콜 교환

이 섹션에서는 Gmail SMTP 서버에서 SASL XOAUTH2를 사용하는 방법을 설명합니다.

초기 고객 응답

XOAUTH2 메커니즘으로 로그인하기 위해 클라이언트는 XOAUTH2의 메커니즘 매개변수와 위에 구성된 초기 클라이언트 응답을 사용하여 AUTH 명령어를 호출합니다. 예를 들면 다음과 같습니다.

[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 프로토콜 교환 관련 참고사항:

  • SMTP AUTH 명령어는 RFC 4954에 설명되어 있습니다.
  • AUTH 명령어의 줄바꿈은 명확성을 위한 것으로 실제 명령어 데이터에는 표시되지 않습니다. 전체 base64 인수는 공백이 포함되지 않은 하나의 연속된 문자열이어야 하므로 전체 AUTH 명령어가 한 줄의 텍스트로 구성되어야 합니다.

오류 응답

인증 실패는 SMTP AUTH 명령어를 통해서도 반환됩니다.

[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 프로토콜 교환 관련 참고사항:

  • 클라이언트는 오류 메시지가 포함된 챌린지로 빈 응답("\r\n")을 보냅니다.

참조