このドキュメントでは、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 経由で表示されます。Gmail の設定でラベルの適切な名前を指定します。
- ユーザーが [フォルダサイズの制限] で設定した内容に関係なく、すべてのメールが 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
の 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 行目で最初のクライアント レスポンスを送信できるため、認証に必要なラウンド トリップは 1 回だけです。SASL-IR は RFC 4959 に記載されています。 - AUTH=XOAUTH2 機能は、このドキュメントで定義されている SASL メカニズムがサーバーがサポートしていることを宣言します。このメカニズムは、XOAUTH2 を
AUTHENTICATE
コマンドの最初の引数として指定することで有効になります。 AUTHENTICATE
コマンドとCAPABILITY
コマンドの改行は、わかりやすくするためのもので、実際のコマンドデータには存在しません。base64 引数全体は、空白を埋めずに連続した 1 つの文字列にする必要があります。これにより、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 引数全体は、空白を埋めずに連続した 1 つの文字列にする必要があります。これにより、AUTH
コマンド全体が 1 行のテキストで構成されます。
エラー レスポンス
認証失敗は、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 引数全体は、空白を埋めずに連続した 1 つの文字列にする必要があります。これにより、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」)を送信します。
参照
- OAUTH2: OAuth 2.0 を使用した Google API へのアクセス
- SMTP: RFC 2821: Simple Mail Transfer Protocol
- IMAP: RFC 3501: インターネット メッセージ アクセス プロトコル - バージョン 4rev1
- POP: RFC 1081: ポスト オフィス プロトコル - バージョン 3
- SASL: RFC 4422: Simple Authentication and Security Layer(SASL)
- JSON: RFC 4627: The application/json Media Type for JavaScript Object Notation
- BASE64: RFC 4648: Base16、Base32、Base64 データのエンコード
- SASL-IR: RFC 4959: IMAP Extension for Simple Authentication and Security Layer(SASL)Initial Client Response(簡易認証とセキュリティ レイヤ(SASL)初期クライアント応答の IMAP 拡張)
- SMTP-AUTH: RFC 4954: SMTP Service Extension for Authentication