🔑 技術調査 - AIエージェントの認可: Device Flowで実行主体と承認主体を分離

OAuth 2.0 Device Authorization Grant(Device Flow、RFC 8628)を、ブラウザを持たない AI エージェントや CLI へ適用し、実行主体(エージェント)と承認主体(人間)を構造的に分離する認可アーキテクチャの調査です。起点はエムスリーの社内レポート配信システムへの実装事例(2026-07-15 公開)です。

本記事は 2026-07-16 時点の RFC 8628・MCP Authorization 仕様と、エムスリーの実装事例(2026-07-15 公開)に基づく技術調査です。RFC が規定しない実装選択には「実装案」と明記しています。

概要

目的・位置づけ

この認可パターンは、ブラウザを持たない AI エージェントに、社内データへのアクセス権を安全に与えるための仕組みです。

OAuth 2.0 Device Authorization Grant(Device Flow、RFC 8628)を応用します。RFC 8628 は本来、スマート TV やプリンタなど「ブラウザがない、または入力が制限されたデバイス」向けの拡張です。この特性が、Claude Code のような CLI/エージェント実行環境にも当てはまります。

起点はエムスリーの社内レポート配信システムへの実装事例です。既存の認可システム自身を Authorization Server 化し、インフラを追加せずに導入しています。

解決する課題

既存の「人間 + ブラウザ」前提の認可システムには、次の課題がありました。

これらに共通する本質は、「誰が実行したか」と「誰が承認したか」を区別できないことです。Device Flow は、この 2 つを別チャネルに分離します。なお本記事の「実行主体」は OAuth client のロールを指し、エージェント実体そのものの認証・identity ではありません(この限界は後述の attribution で扱います)。

関連技術との関係

他方式との比較

特徴

• 実行主体と承認主体の分離: エージェントは device_code を保持するだけで、セッション Cookie など人間の権限そのものは受け取らない。人間はブラウザで「このエージェントを承認する」行為を明示的に行う
• opaque token による即時失効: トークンを自己完結型の JWT にせず不透明な文字列にする。DB の該当行に失効時刻を打つだけで、次のリクエストから確実に拒否できる
• 既存 RBAC(Role-Based Access Control)の無改修: Bearer 認証をミドルウェアとして追加するだけで済む。トークンからユーザーを解決した後は、既存のセッション認証と同じ認可判定(ユーザー・グループ・ロールとリソースの紐付け)をそのまま流用できる
• PAT 先行のインクリメンタル導入: いきなり Device Flow を作るのではなく、Phase 1 で PAT(Web UI 発行・手動コピー)を先行導入し、トークン保存形式・Bearer 認証ミドルウェア・失効管理という基盤を検証する。Phase 2 で Device Flow を同じ基盤の上に載せることでリスクを抑える
• インフラ追加ゼロ: 既存の認可システム自身が Authorization Server を兼ねる設計により、新規サービスや API Gateway の追加が不要。既存 nginx 設定の変更も最小限で済む
• 認証と認可の責務分離: 人間の認証(誰であるか)は既存 SSO(OIDC IdP)に任せ、認可システムは CLI 向けトークンの発行・検証のみを担当する。IdP 側への改修を避けられる
• secret として扱いやすい設計: トークンにプレフィックスを付与し、平文はユーザーに発行時一度だけ表示する。secret scanning 等の既存ツールとも相性がよい

構造

AI エージェント向け Device Flow 認可システムの内部アーキテクチャを、C4 model の 3 段階(システムコンテキスト図・コンテナ図・コンポーネント図)で示します。あわせて Device Flow の認可シーケンスを図解します。

システムコンテキスト図

本パターンの主体を RFC 8628 のロールへ対応づけると、次のとおりです。

コンテナ図

認可システムをドリルダウンし、内部コンテナ構成を示します。

コンポーネント図

コンテナごとの実装コンポーネントをドリルダウンします。

CLI 実行主体

Device 認可エンドポイント

Token エンドポイント

Bearer 認証ミドルウェア

Token ストア

リバースプロキシ

Device Flow 認可シーケンス図

RFC 8628 の device authorization endpoint・token endpoint・ポーリング制御を反映した認可シーケンスです。

データ

概念モデル

情報モデル

トークンの状態遷移

opaque token の発行から失効までのライフサイクルを状態遷移で示します。

構築方法

本セクションでは、AI エージェント/CLI 向け Device Flow 認可基盤の初回構築手順をまとめます。

全体構成

• 認可システム自身が Authorization Server の役割を兼ねます。
• 既存の OIDC IdP は認証(誰であるか)を担当します。
• 認可システムは CLI 用トークンの発行・検証だけを担当します。
• この責務分離により、IdP が Device Flow 未対応でも認可層で補完できます。

Authorization Server のエンドポイント構成

エムスリー実装事例では、認可システムに次のエンドポイントを新設しています。

• 検証 URL は https://reports.example.com/device のように、既存サービスのドメイン配下に置きます。
• 認証は SSO に委譲します。未ログインの場合は OIDC ログインへ流入させます。

opaque token の生成と DB 保存スキーマ

• トークン形式は JWT ではなく、ランダム値による opaque token を採用します。
• 用途別に prefix を付与します。GitHub の ghp_ のような形式です。
• prefix により、トークン種別の識別と secret scanning への対応がしやすくなります。
• DB には生トークンを保存せず、SHA-256 ハッシュのみを保存します。
• 十分なエントロピーを持つランダムトークンであれば、DB が漏洩してもハッシュから元のトークン文字列を求めることは計算上困難です(低エントロピー値なら辞書・総当たり攻撃が成立し得ます)。

DB スキーマ例(実装案):

CREATE TABLE access_tokens (
  id            BIGSERIAL PRIMARY KEY,
  token_hash    CHAR(64) NOT NULL UNIQUE,  -- SHA-256(secret) の16進文字列
  prefix        VARCHAR(16) NOT NULL,      -- 例: 'rpt_at_' (access) / 'rpt_rt_' (refresh)
  user_id       BIGINT NOT NULL REFERENCES users(id),
  client_id     TEXT,                      -- 実行した OAuth client
  device_authorization_id BIGINT,          -- 監査逆引き用。承認者(approved_by)への JOIN キー
  scope         TEXT,
  issued_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
  expires_at    TIMESTAMPTZ NOT NULL,
  revoked_at    TIMESTAMPTZ,               -- NULL = 有効、非NULL = 失効済み
  last_used_at  TIMESTAMPTZ
);

CREATE INDEX idx_access_tokens_user_id ON access_tokens(user_id);

• 失効は revoked_at に時刻を打つだけで、次のリクエストから確実に拒否できます。
• refresh_token も同じテーブル構造で prefix のみ変えて管理できます。

トークン検証の擬似コード(実装案):

import hashlib

def verify_token(raw_token: str) -> User | None:
    token_hash = hashlib.sha256(raw_token.encode()).hexdigest()
    row = db.query(
        "SELECT * FROM access_tokens WHERE token_hash = %s "
        "AND revoked_at IS NULL AND expires_at > now()",
        [token_hash],
    )
    if row is None:
        return None
    return get_user(row.user_id)

Bearer 認証ミドルウェアの追加

• Bearer 認証はミドルウェアとして追加します。
• ミドルウェアはトークンからユーザーを解決するだけの役割です。
• ユーザー解決後は、既存のセッション認証と同じ認可判定(ユーザー / グループ / ロールとリソースの紐付け)をそのまま適用します。
• 認可システム本体の「担当者ごとの権限判定」ロジックには一切手を入れません。
• この無改修設計により、「CLI 経由だと見えるはずのないレポートが見える」という事故が構造的に起きません。

ミドルウェア擬似コード(実装案):

def bearer_auth_middleware(request):
    auth_header = request.headers.get("Authorization", "")
    if not auth_header.startswith("Bearer "):
        return  # 従来のセッション認証にフォールスルー
    raw_token = auth_header.removeprefix("Bearer ")
    user = verify_token(raw_token)
    if user is None:
        raise Unauthorized()
    request.current_user = user
    # 以降は既存の認可判定 (RBAC) をそのまま利用

nginx リバースプロキシ設定

• 既存の auth_request 構成に、Authorization ヘッダーをサブリクエストへ転送する設定を 1 行追加します。
• 追加行は proxy_set_header Authorization $http_authorization; のみです。

location /private/ {
    auth_request /auth;
    proxy_pass http://backend;
}

location = /auth {
    internal;
    proxy_pass http://auth-service/verify;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
    # Bearer トークン対応のための追加 1 行
    proxy_set_header Authorization $http_authorization;
}

• auth_request サブリクエストが 2xx を返せばアクセスを許可します。
• 401 または 403 を返せばアクセスを拒否します。
• それ以外のコードはエラーとして扱われます(nginx ngx_http_auth_request_module 仕様)。

PAT 先行リリースからの段階導入

Device Flow をいきなり導入せず、PAT(Personal Access Token)を Phase 1 として先行リリースします。

• PAT と Device Flow はトークンの保存形式・Bearer 認証ミドルウェア・失効管理を共通の基盤として使います。
• Phase 1 で基盤を検証してから、Phase 2 で Device Flow を上乗せする進め方です。
• 基盤が共通のため、Phase 2 での追加実装は device_code/user_code の発行とポーリング処理に絞り込めます。

既存 OIDC IdP が Device Flow 未対応の場合の補完

• IdP 側の変更は不要です。
• 認可システムが「SSO でログイン済みのユーザーが、この user_code を承認した」という事実だけを扱います。
• パスワードやセッション情報は CLI 側に渡しません。
• 検証 URL 自体は既存 SSO のログインフローに乗るため、IdP 側の Device Flow 対応を待たずに導入できます。

利用方法

RFC 8628 の必須パラメータ

Device Authorization Request(RFC 8628 Section 3.1):

Device Authorization Response(RFC 8628 Section 3.2):

Device Access Token Request(RFC 8628 Section 3.4):

エラーコード(RFC 8628 Section 3.5):

CLI/エージェントからの Device Flow 実行例

エムスリー記事に掲載された利用イメージです(記事上の例示。reports.example.com も例示ドメインで、実出力は未確認)。

$ report login
以下のURLを開き、コードを入力してください:
  URL:  https://reports.example.com/device
  Code: WDJB-MJHT
承認待ち... (有効期限 10 分)
✓ ログインしました

• CLI が POST /device/code を呼び、device_code と user_code を受け取ります。
• CLI は検証 URL と user_code を画面表示します。
• CLI は POST /device/token を interval 秒間隔でポーリングします。
• ユーザーはブラウザで検証 URL を開き、user_code を入力して承認します(未ログインなら OIDC ログインを経由します)。
• サーバーは承認完了後、次のポーリング応答で access_token と refresh_token を返します。

以下は RFC 8628 の記述をもとに補った、動作イメージの実装案です(エムスリー記事には登場しないコマンド/コード例)。

Device Authorization Request の実装案:

curl -s -X POST https://reports.example.com/device/code \
  -d client_id=cli-tool \
  -d scope=report:read

レスポンス例(実装案。device_code/user_code のみ RFC 8628 §3.2 の例示値を流用。verification_uri と expires_in(RFC 例は 1800)は本書の実装案):

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://reports.example.com/device",
  "verification_uri_complete": "https://reports.example.com/device?user_code=WDJB-MJHT",
  "expires_in": 600,
  "interval": 5
}

ポーリング CLI 擬似コード(実装案):

import time
import requests

def poll_for_token(device_code: str, interval: int) -> dict:
    while True:
        time.sleep(interval)
        resp = requests.post(
            "https://reports.example.com/device/token",
            data={
                "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
                "device_code": device_code,
                "client_id": "cli-tool",
            },
        )
        body = resp.json()
        if resp.status_code == 200:
            return body  # access_token, refresh_token を含む
        error = body.get("error")
        if error == "authorization_pending":
            continue
        if error == "slow_down":
            interval += 5
            continue
        if error in ("access_denied", "expired_token"):
            raise RuntimeError(f"device flow failed: {error}")

access_token を Bearer で API に付ける利用例

エムスリー記事に掲載された利用イメージです(例示・実出力未確認)。

$ curl -H "Authorization: Bearer $(report token)" \
       https://reports.example.com/path/to/report.txt

• report token は保存済み access_token をローカルから取り出すサブコマンドです。
• API 側は Bearer 認証ミドルウェアでトークンを検証し、既存の RBAC 判定をそのまま適用します。

リフレッシュトークンでの更新(実装案)

RFC 8628 は refresh_token の扱いを直接規定していません。OAuth 2.0 の一般的な Refresh Token 更新フローに沿った実装案です。

curl -s -X POST https://reports.example.com/device/token \
  -d grant_type=refresh_token \
  -d refresh_token="$(report refresh-token)" \
  -d client_id=cli-tool

トークン失効操作(実装案)

• 管理画面または API から、対象トークンの revoked_at に失効時刻を設定します。
• 失効後の最初のリクエストから確実に拒否されます。

UPDATE access_tokens SET revoked_at = now() WHERE token_hash = :token_hash;

運用

本セクションは、AI エージェント向け Device Flow(RFC 8628)を稼働させた後の運用設計に集中します。

トークンの失効運用

opaque token 方式を採用すると、失効はデータベースの 1 レコード更新だけで完結します。エムスリーの実装記事でも「不透明トークンなら DB の該当行に失効時刻を打つだけで、次のリクエストから確実に拒否できる」と説明されています。この設計を運用ルールとして具体化すると、次の 3 パターンに整理できます。

トークン検証ミドルウェアは、次の 3 条件を毎リクエスト評価します。

-- Bearer トークン検証時の判定クエリ例
SELECT user_id, scope
FROM access_tokens
WHERE token_hash = $1          -- SHA-256(受信トークン)
  AND revoked_at IS NULL       -- 失効していない
  AND expires_at > now();      -- 期限切れでない

• revoked_at の記録だけでキャッシュ層を持たない設計にすると、失効が次のリクエストから即時反映されます。
• 緊急失効はユーザー単位の一括更新(UPDATE access_tokens SET revoked_at = now() WHERE user_id = $1)で足りるようにしておくと、インシデント対応の初動が 1 クエリで完結します。
• 期限切れクリーンアップは日次バッチで十分です。放置しても失効判定には影響しませんが、テーブル肥大化を避けるために定期削除を推奨します。

トークンのローテーション・更新

Device Flow で発行される refresh_token は、access_token の有効期限切れを見越した更新導線です。ローテーションを設計する際は、単純な延命でなく「使い捨て」を前提にします。

• public client の refresh token に対する現行 BCP(RFC 9700 §2.2.2)は「sender-constrained(DPoP/mTLS)」または「rotation」のいずれかを求めます。本書ではこのうち rotation を採用し、refresh_token で新しい access_token を発行するたびに新しい refresh_token も同時に発行し、古い refresh_token は即座に無効化します(rotation のみが必須ではなく、sender-constraining も選択肢です)。
• 無効化済みの refresh_token が再度使われた場合は「盗用の疑い」と判定し、そのトークンファミリー(同一発行系列の access_token・refresh_token すべて)を一括失効させます。
• ネットワーク瞬断などでクライアントが新トークンを受け取れなかった場合に備え、旧 refresh_token を数秒〜数十秒だけ許容する猶予期間(grace period)を設けると、正規クライアントの取りこぼしを防げます。
• スコープの拡大は refresh_token の更新時に行いません。スコープ変更が必要な場合は、再度 Device Flow を最初から実行させます。

トークン種別ごとの寿命の目安です。標準はこの値を定めておらず(MCP は short-lived を SHOULD とするのみ)、以下は本書のリスクベース実装案です。組織のリスク・再認可コスト・インシデント対応時間から決めます。

監査ログ

Device Flow の価値は「実行主体(エージェント/CLI)」と「承認主体(人間)」が分離できる点にあります。この分離を意味あるものにするには、監査ログで両者を常に紐づけて記録する必要があります。

監査ログに最低限含めるべき項目です。

• 承認時点(user_code 承認)で approved_by を device_code のレコードに固定し、そこから発行される access_token・refresh_token すべてに approved_by を引き継がせます。
• アクセスログには approved_by を直接書かず、token_id 経由で device_code テーブルを JOIN すれば逆引きできる設計にすると、ログ書き込み時のコストを抑えられます。逆引きを成立させるには、トークンテーブルに device_authorization_id(または承認記録への外部キー)を持たせる必要があります(前掲の DB スキーマ例に含めています)。
• 「誰が承認し、どのトークンで、どのリソースにアクセスしたか」を 1 クエリで追えるようにしておくと、インシデント調査・棚卸しの両方で有効です。

device_code / user_code の有効期限・ポーリング間隔の運用値

RFC 8628 が定義するパラメータと、実運用でよく使われる値です。

• expires_in は「ユーザーが承認操作を完了できる長さ」と「フィッシングに悪用される猶予」のトレードオフです。短すぎると正規ユーザーが承認前にタイムアウトし、長すぎるとフィッシングで奪取した user_code の有効期間が延びます。RFC は具体的な推奨寿命を定めておらず、エムスリー例は 600 秒・RFC の例示値は 1800 秒です。本書ではこの範囲を初期候補とする実装案として扱います(標準の推奨値ではありません)。
• ポーリング間隔はサーバー負荷保護のためのものです。クライアント側は interval を必ず尊重し、slow_down を受け取るたびに間隔を伸ばす実装にします。

ベストプラクティス

実行主体と承認主体の分離を監査ログで追跡する設計

Device Flow の本質的な価値は「誰が動かしたか(実行主体)」と「誰が許可したか(承認主体)」を構造的に分離し、その両方を記録できる点にあります。

• 実行主体 = device client(CLI・エージェントプロセス)
• 承認主体 = resource owner(user_code を承認した人間)
• authorization server = 認可システム自身(既存 SSO には手を入れない)

この 3 者関係を RFC 8628 のロール定義に対応づけておくと、「誰の権限で実行したか(承認主体の責任範囲)」を設計レベルで担保できます。承認主体の ID を token に紐づけたまま失効管理することで、「エージェントが起こした操作」を「承認した人間の責任範囲」として追跡可能にします。

ただし Device Flow が構造的に分離するのは「人間の承認コンテキスト」と「別チャネルで動くクライアント」までです。「どのエージェント実体が実行したか」の attribution は Device Flow 単独では保証できません。RFC 8628 §5.6 は device client を原則 public client として扱い、偽装可能性を明記しています。device_code は一時的な秘密値でありエージェント ID ではなく、監査ログの issued_to(ホスト名/エージェント名)は信頼できる登録・証明機構がなければ自己申告にとどまります。エージェント実体の識別まで必要なら、個別クライアント登録・workload identity・mTLS・DPoP・端末 attestation を別レイヤーとして重ね、Device Flow 単独の効果と区別します。

opaque token vs JWT の選択

「漏洩時にすぐ止められること」を最優先するなら opaque token が適切です。JWT はステートレス検証が魅力ですが、失効を即座に反映するには結局 denylist や短い有効期限との組み合わせが必要になり、opaque token の DB 参照モデルと同等以上の運用コストがかかります。

既存のユーザー/グループ/ロール認可を無改修で引き継ぐ

Device Flow 導入時に既存の RBAC 基盤を作り直すと移行リスクが増えます。無改修で引き継ぐ設計のポイントです。

• Bearer 認証はミドルウェアとして追加し、トークンからユーザーを解決した後は既存の認可判定ロジックにそのまま処理を委譲します。
• nginx 側の変更は auth_request へ Authorization ヘッダーを転送する 1 行で足ります。

# 既存の auth_request 構成に Authorization ヘッダーを転送するだけ
proxy_set_header Authorization $http_authorization;

• 認可システムが担うのは「トークン→ユーザー」の解決だけです。ユーザー/グループ/ロールとリソースの紐付け判定は既存ロジックを一切変更しません。
• この構造により、CLI 経由でアクセスしても、ブラウザセッション経由と同じ認可境界が適用されます。「実行主体≠承認主体」であっても、権限判定は常に承認主体(user_code を承認した人間)のロールに基づいて行われるため、権限逸脱が構造的に起きません。

最小権限スコープ・短期トークン・prefix によるトークン種別識別

• スコープは Device Flow 発行時に用途を絞り込み、CLI/エージェントが必要とする最小範囲のみ付与します。
• access_token は短期(用途に応じて 5〜60 分)、refresh_token で継続利用を担保します。
• トークンに prefix を付与すると、ログ・Slack 共有・secret scanning での識別性が上がります。GitHub のトークン形式が参考になります。

GitHub が 2021 年に導入したトークン形式では、prefix に加えて 32-bit CRC32 を Base62 化してトークン末尾 6 文字に埋め込むことで、DB へ問い合わせなくても形式に合わないランダム文字列・secret scanning の誤検知候補をオフラインで除外できるようにしています(以下の表はこの形式の代表例です)。CRC32 は非暗号学的チェックサムで攻撃者も再計算できるため、真正性検証・偽造耐性の用途には使えません。自社実装でも「種別 prefix + チェックサム + 高エントロピー」の組み合わせは、漏洩トークンの種別特定と誤検知除外を安価に実現する手段として応用できます。

MCP 認可・エージェント ID・非人間 ID(NHI) の文脈での位置づけ

Device Flow(RFC 8628)と MCP Authorization spec は、扱う層が異なります。両者の関係を整理します。

• MCP Authorization は仕様上 OPTIONAL であり、「MCP client がどう token を得るか」の grant type も限定していません。STDIO トランスポートでは認可仕様自体を適用せず、環境変数からの資格情報取得を推奨しています。HTTP トランスポートで、かつブラウザを起動できないエージェント実行環境(サーバー内バッチ・踏み台サーバー等)では、Device Flow が現実的な選択肢になります。
• MCP server(resource server)は token の audience 検証を必須とし、他 API 向けに発行された token を受け取らない設計が要求されています(token passthrough の禁止)。これは Device Flow で発行した token を MCP 以外のリソースへ使い回さない設計とも整合します。
• エージェント ID・非人間 ID(NHI)の文脈では、2 つのアプローチがあります。1 つは「承認した人間の権限を、短命な token を介してエージェントに委譲する」設計(本パターンが該当)、もう 1 つは「エージェントに明示的な workload identity を与えて consumer → credential → identity → resource を対応づける」設計です。NHI 管理の実務では、Provision → Rotate → Monitor → Decommission のライフサイクルを回すことが求められており、Device Flow の revoked_at 運用・refresh rotation はこのライフサイクルの Rotate/Decommission 部分に対応します。両アプローチは排他でなく、監査要件に応じて重ねられます。
• 監査上は「AI エージェントが自律的に行動を起こした場合、どのエージェントが・なぜ・誰の権限で行ったか」を追跡できることが、業界のガバナンス上推奨されます。承認主体を token に紐づけて記録する設計は、この要求のうち「誰の権限で」の部分に直接応えます(「どのエージェント実体が」は前述の attribution レイヤーで補完します)。

RFC 8628 セキュリティ考慮のベストプラクティス

トラブルシューティング

device_code/token エンドポイントのエラー

運用フェーズの症状別対処

まとめ

Device Flow(RFC 8628)は、ブラウザを持たない AI エージェントへ「実行主体(エージェント)」と「承認主体(人間)」を分離したまま社内データへのアクセスを与える手段になります。opaque token のハッシュ保存と即時失効、既存 RBAC の無改修引き継ぎ、PAT 先行の段階導入を組み合わせると、インフラ追加を抑えつつ安全に導入できます。ただし「どのエージェント実体が実行したか」の attribution は Device Flow 単独では保証できないため、必要なら workload identity や mTLS/DPoP を別レイヤーで重ねます。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• 公式ドキュメント・仕様
  • RFC 8628: OAuth 2.0 Device Authorization Grant
  • OAuth 2.0 Device Authorization Grant - OAuth.net
  • Authorization (2025-06-18) - Model Context Protocol
  • Authorization (2025-11-25, 最新版) - Model Context Protocol
  • nginx: ngx_http_auth_request_module
• 実装事例・技術記事
  • AIエージェント×OAuth 2.0:Device Flowで社内データの安全な認可を実装した話 - エムスリーテックブログ
  • Behind GitHub's new authentication token formats - The GitHub Blog
  • Refresh Token Rotation - Auth0 Docs
  • Non-Human Identity Management Guide - Oasis Security
  • Why do long-lived user tokens create governance risk for AI agents? - NHI Mgmt Group