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 は Ctrl+A（\001）を表します。

たとえば、base64 エンコード前の初期クライアント レスポンスは次のようになります。

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

base64 エンコード後、次のようになります（明確にするために記すと、改行を挿入しています）。

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

エラー レスポンス

初期クライアント レスポンスでエラーが発生すると、サーバーは次の形式でエラー メッセージを含むチャレンジを送信します。

base64({JSON-Body})

JSON-Body には、status、schemes、scope の 3 つの値が含まれます。次に例を示します。

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 コマンドの最初の行で初期クライアント レスポンスを送信できるため、認証に必要な往復は 1 回のみです。SASL-IR については、RFC 4959 をご覧ください。
  • AUTH=XOAUTH2 機能は、サーバーがこのドキュメントで定義されている SASL メカニズムをサポートしていることを宣言します。このメカニズムは、AUTHENTICATE コマンドの最初の引数として XOAUTH2 を指定することで有効になります。
  • AUTHENTICATE コマンドと CAPABILITY コマンドの改行は明確にするために記すと、実際のコマンドデータには含まれません。base64 引数全体は、埋め込みの空白文字を含まない連続した文字列にする必要があります。これにより、AUTHENTICATE コマンド全体が 1 行のテキストで構成されます。

エラー レスポンス

認証の失敗も、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 コマンド全体が 1 行のテキストで構成されます。

エラー レスポンス

認証の失敗も、POP AUTH コマンドを介して返されます。

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

SMTP プロトコル交換

このセクションでは、Gmail SMTP サーバーで SASL XOAUTH2 を使用する方法について説明します。

初期クライアント レスポンス

XOAUTH2 メカニズムでログインするには、クライアントは AUTH コマンドと、メカニズム パラメータが XOAUTH2 の上記で作成した初期クライアント レスポンスを呼び出します。次に例を示します。

[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 コマンド全体が 1 行のテキストで構成されます。

エラー レスポンス

認証の失敗も、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」）を送信します。

参照