# LINEWORKS User Account共通認証基盤 設計書

日付: 2026-08-24

## 背景・目的

LINEWORKS API、機能によりUser Account認証(OAuth Authorization Code)必須のものがある(例: Form API、[[project_lineworks_form_pleasanter_sync]]参照)。この認証方式、社内で複数システムが今後利用したい想定。

各システムがそれぞれ個別に認証UI・トークン管理・リフレッシュロジックを実装すると、重複実装・保守コスト増となる。共通の認証・トークン管理基盤として切り出し、消費側システムは認証を一切実装せずAPI経由でaccess tokenを取得できるようにする。

## 方針

- **LINEWORKS連携専用アカウントはシステムごとに別**(1アカウントを複数システムで共用しない)。共通化するのは**仕組み**(認証UI・トークン管理ロジック・テーブル構造)のみ
- 提供形態、**独立サービス**(新規Node.jsアプリ)。消費側システムはHTTP経由でaccess token取得のみ、リフレッシュロジック等の自前実装不要

## 全体アーキテクチャ

```
[消費側システムA]  [Form連携]  [将来のシステムC...]
      │              │                │
      └────── GET /token?key=<連携キー> (実行キー認証) ──────┘
                      │
                      ▼
        [lineworks-user-auth (独立Node.jsアプリ)]
         ├─ 認証UI(社内限定、連携キーごとに新規登録/再認可)
         └─ トークン提供API(有効期限チェック→自動リフレッシュ→返却)
                      │
                      ▼
        プリザンター「LINEWORKS連携トークン」テーブル
        (複数レコード、連携キーで一意識別)
```

## コンポーネント

### 1. 認証UI(社内限定アクセス)

- 登録済み連携キー一覧・各ステータス(有効/要再認可)を表示
- 「新規登録」: 連携キー・対象LINEWORKSアカウント名を入力→LINEWORKS Authorization Codeフローへリダイレクト→本人がLINEWORKS公式ログイン画面でID/PW入力・同意→コールバックで認可コード受領→token endpoint叩いてaccess/refresh token取得→暗号化してプリザンターへ保存
- 「再認可」: refresh_token失効時等、同じフローを連携キー指定で再実行(既存レコード更新)
- アクセス制御、認証基盤側で社内限定に絞る(対象者は情シス担当等、実装計画で確定)

### 2. トークン提供API

`GET /token?key=<連携キー>`(実行キー認証、呼び出し元ごとに別キー)

処理:
1. プリザンターの該当連携キーのレコード取得
2. アクセストークン有効期限確認
   - **期限内** → 保存済みaccess tokenをそのまま返却(LINEWORKS側への追加リクエストなし)。「最終使用日時」のみ更新
   - **期限切れ** → refresh_tokenでLINEWORKSへリフレッシュ要求→新access token取得→「アクセストークン有効期限」「最終使用日時」「リフレッシュトークン取得日時」を全て更新→新access token返却
3. レコードが存在しない/失効済みの場合、エラー返却(消費側で検知・通知)

**既知の注意点(軽微、実装計画で検討可):** 複数消費者が期限直前に同時アクセスした場合、二重リフレッシュが走る競合の可能性あるが、頻度・影響とも小さく許容範囲。

## プリザンター「LINEWORKS連携トークン」テーブル構造

複数システム分のレコードを1テーブルで保持。連携キーで一意識別。

| 列名 | 型(想定) | 内容 |
|---|---|---|
| 連携キー | 文字列(Class) | 検索用固定識別子。例: `lineworks-form-sync` |
| 対象LINEWORKSアカウント | 文字列(Class) | 連携専用アカウントのメールアドレス等(非機密) |
| アクセストークン(暗号化) | 複数行文字列(Body等) | AES暗号化済み。JWT相当の長さになるため単一行Class列は不可 |
| リフレッシュトークン(暗号化) | 複数行文字列(Body等) | 同上 |
| アクセストークン有効期限 | 日時 | 判定基準 |
| リフレッシュトークン取得日時 | 日時 | 直近リフレッシュ実施日時 |
| 最終使用日時 | 日時 | `/token`呼び出しの都度更新。未使用連携キーの検知・監視用 |
| スコープ | 文字列(Class) | 参考記録。例: `form form.read` |
| ステータス備考 | 文字列(Class)等 | 「失効・要再認可」等の運用メモ |

テーブル作成・列追加・アクセス権限設定、ユーザー側で実施。

暗号化鍵、`lineworks-user-auth`アプリの環境変数で管理(org-master-syncの秘密鍵管理方式踏襲)。

## 運用: 新規システム追加時

1. 対象システム用にLINEWORKS連携専用アカウント用意
2. 認証UIで新規連携キー登録→初回のみAuthorization Code認可(担当者がブラウザでログイン)
3. 消費側システムへ、その連携キー用の実行キーを払い出し
4. 消費側システムは`GET /token?key=<連携キー>`を呼ぶだけで利用開始

## 認証キー方針

`/token`エンドポイント、消費側システムごとに別々の実行キー付与。使い回し禁止(既存方針[[project_org_master_sync_webhook_auth_keys]]踏襲)。

## Node.jsアプリのエンドポイント一覧

| パス | 呼び出し元 | 認証 | 役割 |
|---|---|---|---|
| `/health` | dokploy-webapp規約 | なし | ヘルスチェック(必須) |
| `/token` | 各消費側システム | 実行キー(消費側ごとに別) | 有効なaccess token返却(自動リフレッシュ込み) |
| `/auth/*` | 人(ブラウザ) | 社内限定アクセス制御 | 新規登録・再認可UI |

## 補足: Refresh Tokenの有効期限(公式ドキュメント確認済み、2026-08-24)

Refresh Tokenの有効期限は**90日**([`auth-oauth`ドキュメント](https://developers.worksmobile.com/jp/docs/auth-oauth)明記)。Refresh Token Rotation(本アプリはOn)時は再発行の都度新しいRefresh Tokenが発行されるが、新規発行分の90日カウンタが都度リセットされるかは公式ドキュメントに明記なし(未確定、一般的なOAuth実装の慣習からは都度リセットが妥当な推測)。

**実務上の意味**: 消費側システム(Form連携アプリ等)が90日以内に最低1回`/token`経由でaccess tokenのリフレッシュを発生させ続ける限り、実質的に再認可なしで運用継続できる可能性が高い。[[project_lineworks_form_pleasanter_sync]]側の自動実行周期(15分〜1日の選択肢)は、この90日以内リフレッシュ前提を満たす設計にする。

## 未確定・今後の確認事項

- Rotation後のRefresh Tokenの90日カウンタが都度リセットされるか(実機の長期運用で検証要)
- 認証UIのアクセス制御方式(Keycloak SSO連携か、簡易Basic認証か等、実装計画で確定)
- 暗号化方式の具体的なアルゴリズム・鍵管理詳細(実装計画で確定) → AES-256-GCMで実装済み(2026-08-24)