OAuth2 対応の Outlook アカウントを扱っていると、「メールアドレス｜パスワード｜refresh_token｜client_id」のような形式でアカウント情報を受け取ることがあります。メールアドレスとパスワードはわかっても、残りの長い文字列が何に使うものなのか、どう扱えばいいのかは見ただけではわかりません。
この2つは、プログラムやメールソフトが「ユーザーが毎回ログインしなくてもメールボックスにアクセスし続ける」ための部品です。役割を理解しておくと、接続エラーの原因もかなり絞り込めるようになります。
この記事でわかること
- アクセストークン・リフレッシュトークン・client_id の関係
- リフレッシュトークンの有効期限と、更新のたびに入れ替わる仕組み
- トークンを更新する具体的なリクエスト
- よくあるエラーの原因と、安全な保管方法
3つの値の関係を整理する
OAuth2 では、役割の違う3つの値が登場します。まずは全体像を押さえておきましょう。
| 値 | 役割 | おおよその寿命 |
|---|---|---|
| アクセストークン | メールボックスに実際にアクセスするための鍵。IMAP や Graph API に送る | 約1時間 |
| refresh_token | 期限切れのアクセストークンを新しく発行してもらうための引換券 | 最後に使ってから最大90日程度 |
| client_id | トークンを取得した「アプリ」を識別する ID。秘密の値ではない | アプリが削除されるまで |
例えると、アクセストークンは「1時間だけ使える入館証」です。refresh_token は「入館証を再発行してもらうための会員証」で、client_id は「その会員証を発行した窓口の番号」にあたります。会員証は、発行した窓口でしか使えません。この点が、後で説明するエラーの理解に直結します。
client_id とは何か
client_id は、Microsoft Entra ID（旧 Azure AD）に登録されたアプリの「アプリケーション (クライアント) ID」です。1a2b3c4d-5e6f-4a8b-9c0d-1e2f3a4b5c6d のような GUID 形式をしています。
ポイントは次の2つです。
- refresh_token は、発行したときの client_id とセットでしか使えません。別のアプリの ID で更新しようとすると拒否されます。
- デスクトップアプリやスクリプト（パブリック クライアント）の場合、client_id 自体は秘密情報ではありません。ただし、refresh_token と組み合わさると強い権限を持つため、セットで厳重に管理します。
自分でアプリを登録した場合は、Microsoft Entra 管理センターの「アプリの登録」→ 対象アプリの「概要」で確認できます。2026年10月時点の画面では、「アプリケーション (クライアント) ID」という表記です。
refresh_token の有効期限と「ローテーション」
個人用 Microsoft アカウントの refresh_token は、一般的に最後に使ってから90日ほど有効です。定期的に使っていれば、期限はその都度延びていきます。逆に、長期間まったく使わないと失効します。
もう一つ大事なのが「ローテーション」です。refresh_token を使ってアクセストークンを更新すると、レスポンスに新しい refresh_token が含まれることがあります。その場合は新しい値で保存し直してください。古い値を使い続ける作りだと、ある日突然更新できなくなる原因になります。
有効期限内でも、次のような場合には refresh_token が取り消されることがあります。
- アカウントのパスワードが変更・リセットされた
- ユーザーがアプリへのアクセス許可を取り消した
- Microsoft がセキュリティ上の理由でサインインのやり直しを求めた
スコープも「最初の同意」に縛られる
refresh_token で取得できるアクセストークンの権限は、最初にユーザーが同意したスコープの範囲内に限られます。例えば Graph の Mail.Read だけに同意したトークンからは、IMAP 用の IMAP.AccessAsUser.All のトークンは取れません。商品説明に「Graph」「IMAP/POP3/Graph」と書き分けられているのは、この同意済みスコープの違いを表しています。
トークンを更新するリクエスト
更新には、トークンエンドポイントへ HTTPS で POST します。パブリック クライアントの場合、client_secret は不要です。
POST https://login.microsoftonline.com/consumers/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id=＜client_id＞
&grant_type=refresh_token
&refresh_token=＜refresh_token＞
&scope=https://outlook.office.com/IMAP.AccessAsUser.All offline_access成功すると、JSON で access_token、expires_in（秒）、そして多くの場合は新しい refresh_token が返ってきます。IMAP で使う場合は、Outlook IMAP OAuth2 接続方法で紹介した XOAUTH2 の形式にして送ります。Graph API で使う場合は、スコープを https://graph.microsoft.com/Mail.Read offline_access にします。Python で実装する場合の具体例はMicrosoft Graph API でメールを取得する方法で紹介しています。
更新に失敗するときの原因
| レスポンス | 考えられる原因 | 確認すること |
|---|---|---|
invalid_grant | refresh_token の失効・取り消し、別の client_id での更新 | 発行時と同じ client_id か。最新の refresh_token を使っているか |
AADSTS70000 | 要求したスコープに同意していない、または期限切れ | スコープの指定が最初の同意の範囲内か |
AADSTS50173 | パスワード変更などで付与が取り消された | 再度サインインして同意し直す |
AADSTS700016 | client_id が見つからない | ID の転記ミス、アプリ削除、テナント指定の誤り |
invalid_request | パラメーターの欠落・形式の誤り | 改行や空白の混入、URL エンコード漏れ |
原因として意外に多いのが、コピー時の空白や改行の混入です。refresh_token は非常に長い文字列なので、前後の空白を除いてから使う処理を入れておくと安心です。
安全な保管方法
refresh_token は、メールボックスへのアクセスを長期間維持できる強力な資格情報です。パスワードと同等かそれ以上に慎重に扱ってください。
- ソースコードや設定ファイルに直接書かず、環境変数やシークレット管理サービスに保存する
- データベースに保存する場合は暗号化して保存する
- ログやエラーメッセージに出力しない（例外の詳細に含まれていないかも確認する）
- ローテーションで受け取った新しい値で確実に上書きする
- 不要になったら、Microsoft アカウントの「アプリとサービス」からアクセス許可を取り消す
他人のアカウントのトークンを、本人の許可なく取得・利用することは不正アクセスにあたります。各サービスの利用規約と法令を守ってご利用ください。
よくある質問
refresh_token に期限が表示されていませんが、いつまで使えますか？
refresh_token 自体に有効期限の情報は含まれていません。目安は最後に使ってから90日程度です。定期的に更新処理を行っていれば、継続して使えることが多いです。
client_id を自分のアプリの ID に置き換えても使えますか？
使えません。refresh_token は発行時の client_id と結びついています。自分のアプリで使いたい場合は、そのアプリでユーザーにサインインと同意をしてもらい、新しいトークンを取得します。
パスワードを変更したらトークンはどうなりますか？
セキュリティ上の理由から、既存の refresh_token が無効になることがあります。その場合は再度サインインして、トークンを取得し直してください。
アクセストークンをデコードして中身を見ても大丈夫ですか？
Microsoft はアクセストークンの中身をアプリ側で解析しないよう案内しています。形式が予告なく変わることがあるためです。有効期限はレスポンスの expires_in で管理するのが確実です。
まとめ
- アクセストークンは約1時間、refresh_token はそれを再発行するための引換券
- refresh_token は発行時の client_id とセットでしか使えない
- 使うたびに新しい refresh_token が返ることがあるので、必ず上書き保存する
- 取得できる権限は、最初に同意したスコープの範囲内に限られる
Graph や IMAP のスコープ別に用意した OAuth2 対応アカウントは、Hotmail・Outlook（OAuth2対応）でご確認いただけます。
