OAuth 2.0 메커니즘

이 문서에서는 IMAP AUTHENTICATE, POP AUTH, SMTP AUTH 명령어와 함께 사용할 SASL XOAUTH2 메커니즘을 정의합니다. 이 메커니즘을 사용하면 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 도메인 전체 위임을 통해 IMAP을 통해 사용자의 메일함에 액세스하려는 경우 Google Workspace 범위 https://www.googleapis.com/auth/gmail.imap_admin를 사용하여 클라이언트를 승인할 수 있습니다.

이 범위로 승인되면 IMAP 연결이 다르게 작동합니다.

  • 사용자가 Gmail 설정에서 라벨의 'IMAP에 표시'를 사용 중지한 경우에도 모든 라벨이 IMAP을 통해 표시됩니다.
  • 사용자가 Gmail 설정의 '폴더 크기 제한'에서 설정한 내용과 관계없이 모든 메일이 IMAP을 통해 표시됩니다.

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\')을 전송합니다.

참조