ログイン中のユーザー情報を使う

Keelson がログインと、アプリを開ける人の確認を行います。アプリでは、そのユーザー情報を使って、作成者を記録したり、本人のデータだけを表示したりできます。

「誰がどの申請を承認できるか」など、アプリ内の業務ルールはアプリ側で実装します。用途に応じて、次の 3 つの方法を使い分けます。

やりたいこと	使うもの	追加設定
誰がアクセスしているか知りたい（作成者の記録、自分のデータだけ表示）	ヘッダー `X-Keelson-User-Id` / `-Email` / `-Name`	不要
アプリの運用者（デプロイ・設定変更ができる人）だけに見せる画面を作りたい	ヘッダー `X-Keelson-User-App-Perms`	不要（権限はコンソールで設定）
部署ごと・役職ごとの分岐、承認者の判定	Identity SDK の `attributes.groups`	`keelson apps directory enable`

「上司だけが承認できる」のような業務上の権限は、アプリ管理用の manage ではなく、所属グループ、またはアプリ自身のデータ（担当者テーブルなど）で判断します。manage を持つのはアプリをデプロイ・設定できる人であり、業務上の承認者と一致するとは限りません。

1. 誰がアクセスしているか

Keelson は、ログイン済みユーザーからのリクエストに、ユーザー情報をヘッダー（リクエストに付く付加情報）として渡します。アプリのサーバー側で読み取れます。

ヘッダー	内容
`X-Keelson-User-Id`	ユーザー ID（安定した識別子。DB に保存するならこれ）
`X-Keelson-User-Email`	メールアドレス（Keelson に値がなければ空文字）
`X-Keelson-User-Name`	表示名（Keelson に値がなければ空文字）

作成者を記録するなら、データの保存時にユーザー ID も記録します。本人のデータだけを表示するなら、DB の検索条件にその ID を使います。ヘッダーを読み取るだけで、データの絞り込みが自動で行われるわけではありません。

# FastAPI / Flask
user_id = request.headers.get("X-Keelson-User-Id")
email = request.headers.get("X-Keelson-User-Email")

// Express
const userId = req.headers["x-keelson-user-id"];
const email = req.headers["x-keelson-user-email"];

これらのユーザー情報は、Keelson がログインを確認したうえで付けます。呼び出し元が同名のヘッダーを送っても、Keelson が確認したユーザー情報に置き換えられます。アプリ側で Keelson のログインセッションを管理する必要はありません。

SDK で読み取る

Identity SDK を使うと、ユーザー情報を id、email、name としてまとめて取得できます。getCurrentUser はヘッダーを読むだけで、外部への通信や Directory API の有効化は不要です。JavaScript では await を付けて呼びます。ヘッダーがない場合は例外（IdentityError）になります。

import { getCurrentUser } from "@keelsonhq/identity";

app.get("/", async (req, res) => {
  const user = await getCurrentUser({ headers: req.headers });   // { id, email, name }
  res.type("text").send(`こんにちは、${user.name ?? "ゲスト"} さん`);
});

2. 運用者だけの画面

アプリの権限は「閲覧（view）」と「管理（manage）」の 2 種類で、コンソールまたは CLI でグループに割り当てます（グループとアプリ権限）。manage はデプロイ・設定変更・シークレット編集ができる運用者の権限で、既定では Owner / Admin / Developer が持ちます。Keelson はその結果をヘッダーで渡します。

`X-Keelson-User-App-Perms`	意味
`view`	閲覧できる
`view,manage`	閲覧と管理ができる

アプリは manage が含まれるかだけを見ます。グループ名はコードに書きません。

// Express — ヘッダーはリクエストごとに違うので、ハンドラの中で読む
function canManage(req) {
  const perms = (req.headers["x-keelson-user-app-perms"] ?? "").split(",");
  return perms.includes("manage");
}

app.get("/admin", (req, res) => {
  if (!canManage(req)) return res.status(403).end();
  res.send("運用者向けの画面");
});

# FastAPI / Flask — 同じくリクエストごとに読む
def can_manage(request) -> bool:
    perms = request.headers.get("X-Keelson-User-App-Perms", "").split(",")
    return "manage" in perms

「経理チームだけが使えるアプリ」は権限の割り当てだけで実現でき、アプリ側のコードは要りません（チームにアプリを共有する）。「運用者だけが設定画面を開ける」は manage の確認で実現できます。誰が manage を持つかは、コードを変えずにコンソールで変えられます。

3. グループごとの分岐

部署ごと・役職ごとの分岐や、「承認者だけが承認できる」のような業務上の権限が必要なら、Identity SDK でユーザーの所属グループを取得します。

画面の出し分けだけでは不十分です。「本人の申請だけ見える」を実装するときは、一覧の絞り込みに加えて、API で他人の申請 ID を指定しても取得・更新できないことをサーバー側で確認してください。判定に使うのは、ブラウザから送られた値ではなく、Keelson が付けたヘッダーや SDK の戻り値です。

準備

アプリに Directory API の読み取りを許可し、再デプロイします。

Directory アクセスを有効にするとトークンが保存されますが、再デプロイするまでアプリには注入されません。

keelson apps directory enable
keelson deploy

これでアプリに KEELSON_DIRECTORY_TOKEN が注入され、SDK が自動で使います。トークンはサーバー側だけで使い、ブラウザに渡さないでください。

使い方

import { getCurrentIdentity } from "@keelsonhq/identity";

// リクエストを処理する関数の中で取得します。
const me = await getCurrentIdentity({ headers: req.headers });
const groups = me.attributes?.groups ?? []; // 例: ["everyone", "developers", "経理"]
const isAccountingMember = groups.includes("経理");
// この結果を使って、経理向けの操作を許可するか判断します。

from keelson_identity import get_current_identity

me = get_current_identity(headers=request.headers)
groups = me.attributes.groups if me.attributes else []
is_accounting_member = "経理" in groups
# この結果を使って、経理向けの操作を許可するか判断します。

attributes.groups に入るのはグループのキーです。

ロールに応じたシステムグループ: Owner は owners developers everyone、Admin は admins developers everyone、Developer は developers everyone、App User は everyone
そのアプリに権限が割り当てられているカスタムグループのうち、ユーザーが属するもの。アプリに割り当てていないグループは出ません
キーは変わらないので、コードに書いて判定に使えます。日本語のキー（経理）も使えます

getCurrentIdentity の戻り値には、ユーザー（id email name）、ワークスペースでのロール（workspace.role）、このアプリでの権限（app.permissions）も含まれます。

担当者の選択肢にメンバー一覧を使う

担当者の選択肢を出すなど、他のメンバーの情報が必要なときは listMembers / list_members（検索、ロール・グループで絞り込み）、getUser、listGroups が使えます。

ローカル開発

Identity SDK は KEELSON_LOCAL_MODE=1 で、開発用のダミーユーザーを返します。ユーザー ID やメールアドレスは KEELSON_LOCAL_USER_ID / KEELSON_LOCAL_USER_EMAIL で変更できます。

ただし、ダミーユーザーは本番の権限を完全には再現しません。一般利用者には管理画面を開かせない、といった動作は、実際の権限を設定したテスト用アプリでも確認してください。

ローカルで権限を確認するときの注意点

ヘッダーを直接読むコードには、SDK のダミーは適用されません。テスト用のリクエストにヘッダーを付けるなどして確認します。
ダミーの app.permissions は常に manage,view です。KEELSON_LOCAL_WORKSPACE_ROLE=APP_USER にしても、管理権限のないユーザーの動作にはなりません。
カスタムグループは含まれません。ダミーの Owner は admins にも含まれますが、本番の Owner は admins には含まれません。

Webhook などログインなしのリクエスト

外部システムから呼ばれるパス（auth.endpoints）には X-Keelson-User-Id が付きません。そこでは Webhook の署名やアプリトークンで認証します。外部システムとの連携を参照してください。