# Takumi Guard の組織ユーザートークン発行ポータルの参考実装を GitHub で公開

組織内の開発者が、自社の IdP でサインインしたうえで自身の Takumi Guard **組織ユーザートークン**（`tg_org_`）を払い出せるオープンソースの参考実装ポータルを、[`flatt-security/takumi-guard-portal-example`](https://github.com/flatt-security/takumi-guard-portal-example) として公開しました。Bot のクレデンシャル自体を各開発者の端末に配布する必要のない構成です。

## 概要

本ポータルは、開発者と Guard の組織ユーザートークン API の間に立つ小さな Web アプリケーションです。各開発者は、自社の IdP でポータルにサインインし、自身の `user_identifier` に紐づく `tg_org_` トークンをポータル上で発行します。発行直後に画面に表示される平文を、その場で `.npmrc` や CI ランナーのシークレットなど必要な箇所に貼り付ければ、以降はその設定から Guard と直接通信できるようになります。

この構成では、Bot のクレデンシャル自体はポータル側にのみ保持されます。これにより、各開発者は自身が利用するトークンだけを各自で扱えばよく、Takumi Guard の契約を担当する管理者側も、Shisho Cloud の Bot のクレデンシャルを開発者一人ひとりの端末や CI 環境に配布する必要がありません。

全体の流れを次の図に示します。

```mermaid
flowchart LR
    Dev([開発者のブラウザ])

    subgraph CustomerSide[利用側 顧客環境]
        Portal["guard-token-portal<br/>bot id と API キーを保持<br/>認証アダプター: IAP・Basic・独自実装"]
    end

    subgraph ShishoSide[Shisho Cloud]
        API["Takumi API<br/>/o/orgID/guard/org-user-tokens"]
    end

    Dev ==>|"① IdP でサインインし、自身のトークンを発行・一覧・取り消し"| Portal
    Portal ==>|"② Bot 認証で API を呼び出し、呼び出し元の user_identifier に限定"| API
    API -.->|"③ 発行されたトークン・一覧・取り消し結果"| Portal
    Portal -.->|"④ 平文は一度だけ表示し、一覧は完全一致で再フィルタ"| Dev
```

本ポータルは、[管理者向けセットアップスクリプト](/docs/ja/t/guard/features/admin-deployment)（Bot のクレデンシャル込みのセットアップを MDM 経由で管理対象端末に一斉配信する用途）と、[Takumi API](/docs/ja/r/202605-takumi-api-guard-tokens)（CI/CD や入退社処理からトークン操作を完全に自動化する用途）のちょうど中間にあたる選択肢として位置づけられます。開発者自身がトークンを払い出す運用にしたい一方で、Bot のクレデンシャルを MDM で全端末に配るのは難しい、あるいは望ましくないという環境に適しています。

ポータルに表示される機能は、ポータル側の設定値ではなく、紐づけた Bot に付与されている Guard ロールから自動的に決まります。Bot が **`organization/takumi_guard_token_issuer`** ロールを持つ場合は発行ボタンのみの画面となり、**`organization/takumi_manager`** ロールを持つ場合は、各開発者が自身のトークン一覧と取り消し操作も併せて利用できる画面となります。ロールの切り替えは Guard 側だけで完結し、次回のページ読み込みから挙動に反映されるため、ポータル本体の再デプロイは必要ありません。

![自身のトークン一覧と、各行の取り消しボタンが並ぶ管理画面](/docs/ja/_md-assets/81d64ae42b-tokens-list.png)

トークンを発行すると、平文のトークンがメタデータと併せて **一度だけ** 表示されます。ページを閉じたあとはポータル側でも復元できないため、開発者はその場で必要なツールの設定に貼り付けるか、改めて取り消したうえで再発行する必要があります。

![発行直後の画面 平文のトークンが一度だけ表示され、token id・prefix・user_identifier・発行日時などのメタデータが併記される](/docs/ja/_md-assets/2a548aeb0b-token-minted.png)

一覧・取り消しを有効にした場合も、各開発者が画面から確認・取り消しできるのは **自身のトークンに限られます**。組織オーナーであっても、他者のトークンを操作するための画面は用意していません。一覧・取り消しのどちらでも `user_identifier` を二重にフィルタしており、まず Guard API 側にプレフィックスを渡して呼び出し元のトークンに絞り込み、さらにポータル側でも完全一致を確認しています。リクエストに `token_id` を改ざんしても、呼び出し元が所有していないトークンへは到達できない設計です。

## 利用方法

:::info 有料機能
組織ユーザートークンを利用するには、Guard を有効化した Takumi サブスクリプションが必要です。詳しくは[料金と請求](/docs/ja/t/guard/billing)を参照してください。
:::

リポジトリには、**Google Cloud Run + Identity-Aware Proxy + Secret Manager** 構成での[デプロイ例](https://github.com/flatt-security/takumi-guard-portal-example/tree/main/examples/cloudrun)が同梱されています。この構成を採用する場合は、以下の手順でデプロイできます。

1. Shisho Cloud のコンソールで Bot を作成し、用途に応じて **`organization/takumi_guard_token_issuer`** ロール（発行のみ）または **`organization/takumi_manager`** ロール（発行・一覧・取り消し）を付与する。発行された Bot ID（`BT01…`）と API キーを控えておく。
2. リポジトリをクローンし、`examples/cloudrun/` 配下の README に従ってデプロイする。
3. 公開された URL を開発者に共有する。各開発者は IdP でサインインしたあと、数クリックで自身のトークンを払い出し、一度だけ表示される平文をその場で必要なツールの設定に貼り付ければよい。

:::warning
同梱の `basic` 認証モードは、ローカル開発や動作確認を目的としたデバッグ用のアダプターです。本番環境では使用しないでください。実際に開発者が利用するポータルとして公開する場合は、`iap` モード（Google Cloud Identity-Aware Proxy）または独自に実装した認証アダプターをご利用ください。
:::

Google Cloud IAP 以外の IdP と連携させたい場合や、Cloud Run 以外の環境にデプロイしたい場合は、`internal/auth/` 配下に 4 メソッドの `Authenticator` インターフェースを実装した認証アダプターを各自で追加したうえで、ご利用の環境に合わせてデプロイしてください。同梱の IAP / Basic アダプターをそのまま実装例として参考にできます。

## 補足: 位置づけ

本リポジトリは「参考実装」としての公開であり、マネージドプロダクトではありません。社内で最低限のレビューは経ていますが、本番環境で運用する前には、貴組織のセキュリティ要件と照らし合わせたうえで必ず検証し、必要に応じて改変してからご利用ください。ソースコードは MIT ライセンスのもと、[github.com/flatt-security/takumi-guard-portal-example](https://github.com/flatt-security/takumi-guard-portal-example) で公開しています。