# API 利用準備ガイド

マーケットプレイス版の API を使うための準備の手順です。社員が外部ツールから自分のアカウントで使う「アプリケーション」と、会社のシステムが使う「システム連携」で、準備する所が違います。

## 概要

|         | アプリケーション                             | システム連携                        |
| ------- | ------------------------------------ | ----------------------------- |
| だれが使うか  | 社員（Claude Code などの外部ツールから、自分のアカウントで） | 会社のシステム                       |
| 認証      | 外部ツールでログイン（認可コード＋PKCE）               | サービスアカウント（Client Credentials） |
| 準備する所   | 認証サーバーのコンソール                         | 管理画面（Admin）                   |
| 呼べる API | ユーザー API（会話・組織・プロジェクト）・MCP           | システム連携 API・MCP                |

> **外部ツールでのログインを使う前に**
>
> - 外部ツールでのログインは、管理者が認証サーバーの外の入口を開けた環境でだけ使えます。既定では閉じています。開け方・閉じ方は、構築の節の [ドメイン設定ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/guide/domain-guide.md) を参照してください
> - 開け閉めのたびに認証サーバーが入れ替わり、その間はメイン画面のログインとトークンの更新もできません。利用者の少ない時間に行ってください
> - MCP も使うときは、MCP の受け口も開けます（構築の節の [Helm Values リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/reference/helm-values-ref.md)）

## 認証サーバーのコンソールを開く

アプリケーションの準備は、認証サーバーのコンソールで行います。コンソールは外に出していないので、クラスタに `kubectl` でつなげる端末から、中の道で開きます。

1. MP の realm の名前を確かめます。インストーラーの `config.yaml` の `keycloak.realm_name` です（例: `agenticstar`）。入れた後の環境では、次のコマンドでも分かります

   ```bash
   kubectl get configmap librechat-auth-env -n librechat-auth -o jsonpath='{.data.KEYCLOAK_REALM}'
   ```

2. 認証サーバーへの道をつなぎます（`8080` が使われていれば、手元の別のポートにします）

   ```bash
   kubectl port-forward -n librechat-auth svc/keycloak-extensions-keycloakx-http 8080:8080
   ```

3. ブラウザで `http://localhost:8080/admin/` を開き、master realm の管理者でログインします。最初の管理者のユーザー名とパスワードは、インストーラーの `config.yaml` の `keycloak.admin_email`・`keycloak.admin_password` です

4. 左上の realm の選び先で、MP の realm（1 の名前）を選びます

### 人用の管理者を作る

最初の管理者は、すべての realm を変えられます。ふだんの作業には、MP の realm のクライアントだけを扱える管理者を、master realm に作って使うことを勧めます。

1. master realm で「ユーザー（Users）」→「ユーザーの追加（Add user）」から作り、「クレデンシャル（Credentials）」タブの「パスワードを設定（Set password）」でパスワードを決めます
2. 「ロールマッピング（Role mapping）」タブの「ロールの割り当て（Assign role）」で「クライアントによるフィルター（Filter by clients）」を選び、`<MP の realm の名前>-realm` の `view-realm`・`view-clients`・`manage-clients` を割り当てます。この 3 つだけなら、クライアントの作成と停止はでき、realm の設定は変えられません

- クライアントを管理できる人は、ほかの人になりすましたトークンを作れます。この権限は、最初の管理者と同じくらい信頼できる人にだけ付けてください
- MP の realm の利用者（メイン画面にログインするアカウント）には、コンソールの権限を付けないでください

## アプリケーションの作成手順（認証サーバーのコンソール）

外部ツールのクライアントを、MP の realm に作ります。社員は、ここで作ったクライアントの ID を外部ツールに設定してログインします。

### 1. クライアントを作る

「クライアント（Clients）」→「クライアントの作成（Create client）」で、次のとおり入れます。

| 段                        | 項目                                                                                   | 値                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| 一般的な設定（General settings） | クライアントタイプ（Client type）                                                               | OpenID Connect                                                                               |
|                          | クライアント ID（Client ID）                                                                 | 外部ツールに設定する ID（例: claude-code）                                                                |
| 機能設定（Capability config）  | クライアント認証（Client authentication）                                                      | オフ（公開のクライアント）                                                                                |
|                          | スタンダードフロー（Standard flow）                                                             | オン                                                                                           |
|                          | ダイレクトアクセスグラント（Direct access grants）                                                  | オフ                                                                                           |
|                          | インプリシットフロー（Implicit flow）・OAuth 2.0 デバイス認可グラント（OAuth 2.0 Device Authorization Grant） | オフ                                                                                           |
|                          | PKCE の方式（PKCE Method）                                                                | S256                                                                                         |
| ログイン設定（Login settings）   | 有効なリダイレクト URI（Valid redirect URIs）                                                   | http\://localhost/callback と http\://127.0.0.1/callback（VS Code を使うときは http\://127.0.0.1/ も） |

- 戻り先の `localhost`・`127.0.0.1` は、ポートを問われません。外部ツールで指定するポートは、空いているものを自由に選べます（[AI クライアント接続ガイド（MCP）](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/ai-client-guide.md)）
- VS Code は、戻り先の道が `/`（`http://127.0.0.1:<ポート>/`）です。VS Code を使うときは `http://127.0.0.1/` も登録してください
- ダイレクトアクセスグラント（パスワードを直に送る形）は使わないでください。承認とメールの確かめを通らずにトークンが出ます

### 2. ログインの流れを付ける

作ったクライアントの「高度（Advanced）」タブの「認証フローの上書き（Authentication flow overrides）」で、「ブラウザーフロー（Browser Flow）」に `agentic-star browser` を選んで保存します。

`agentic-star browser` は、製品が配るログインの流れのサンプルです。メイン画面のログインと同じく、承認済みでメールを確かめた利用者だけを通します。この流れを付けないクライアントでは、承認待ち・メール未確認の利用者もログインできてしまいます。流れを変えたいときは、[サンプルの流れを写して使う](#copy-sample-flow) を参照してください。

### 3. スコープと写し方を確かめる

- 「クライアントスコープ（Client scopes）」タブの `email` を外さないでください。外すとトークンにメールアドレスが入らず、外部 API の呼び出しが断られます
- 長く使えるトークン（`offline_access`）は、承認済みの間、無操作が最長 30 日になるまで更新できます。出させたくないときは、「クライアントスコープ（Client scopes）」タブで `offline_access` を外します（Claude Code は、ログインのときに `offline_access` を求めます）
- クライアントにマッパー（Mappers）を足して、トークンに `client_id` を入れないでください。`client_id` のあるトークンは、システム連携のトークンとして扱われます

### 4. 承認待ちのアカウントで断られることを確かめる

クライアントを作るたびに、承認待ちの試しのアカウントでログインし、断られることを確かめてください。断られずにログインできたときは、2 の流れが付いていません。

### ふつうの OIDC のアプリのクライアント

外部ツールではない自社のアプリ（OIDC のライブラリでログインするもの）のクライアントも、同じ形で作ります。違うのは次の 2 つです。

- 有効なリダイレクト URI（Valid redirect URIs）に、そのアプリの戻り先を入れます
- ブラウザで動くアプリ（ブラウザから直にトークンの口を呼ぶもの）は、Web オリジン（Web origins）にアプリの住所を入れます

ログインの流れ（2）・スコープ（3）・確かめ（4）は、外部ツールのクライアントと同じです。認証サーバーの口は [認証 API リファレンス — 外部ツールでのログイン](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/auth-mp-ref.md#external-login) にあります。

## システム連携の作成手順（管理画面）

会社のシステムが使うサービスアカウントを、管理画面（Admin）で作ります。

1. 管理画面の「ユーザー管理」→「サービスアカウント」で「サービスアカウント作成」を押します
2. 「Client ID」（英数字・`.`・`_`・`-`）と「名前」「説明」を入れ、「有効化」をオンにして作ります
3. 作ったサービスアカウントの詳細画面で、Client ID と Client Secret を確かめます

トークンの取り方は [認証ガイド — トークンの取得](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/auth-guide.md#%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3%E3%81%AE%E5%8F%96%E5%BE%97) を参照してください。

## 認証情報の確認

社員とシステムの担当者に、次を伝えます。

| 伝えるもの    | アプリケーション                                                              | システム連携                                     |
| -------- | --------------------------------------------------------------------- | ------------------------------------------ |
| ID       | 外部ツールのクライアントのクライアント ID                                                | サービスアカウントの Client ID                       |
| 秘密       | なし（公開のクライアント）                                                         | Client Secret                              |
| API の住所  | https\://\<your-domain>/api（MCP は https\://\<your-domain>/api/v1/mcp） | 同じ                                         |
| トークンを取る所 | 外部ツールが見つけます（MCP）。自社のアプリは、認証サーバーの外の入口の住所                               | https\://\<auth-domain>/api/v1/oauth/token |

`<your-domain>`（外部 API のドメイン）と `<auth-domain>`（認証サービスのドメイン）は、構築の時に管理者が決めたものです（[ドメイン設定ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/guide/domain-guide.md)）。

### 資格情報が漏れたとき

| 漏れたもの                    | 止め方                                                                                 |
| ------------------------ | ----------------------------------------------------------------------------------- |
| サービスアカウントの Client Secret | 管理画面で、サービスアカウントの「シークレット再生成」を押すか、「有効化」をオフにします。再生成すると、前の Secret でのトークンの取得はすぐにできなくなります |
| 社員のアカウント（外部ツールでのログイン）    | 下の「外部ツールを止める」の手順で止めます                                                               |

- すでに出たアクセストークンは、止めた後も期限まで使えます（初期の設定では 24 時間）
- 漏れた資格情報でできるのは、その社員・サービスアカウントに許された操作です。すでに読まれたデータは取り戻せません

### 外部ツールを止める

ログインした外部ツールは、メイン画面からのログアウト・パスワードの変更や再設定・端末のログアウトでは止まりません。トークンを更新しながら、最長 30 日使えます。止めるときは、認証サーバーのコンソールで、MP の realm の「ユーザー（Users）」からその利用者を開き、「セッション（Sessions）」タブの「すべてのセッションのログアウト（Logout all sessions）」を押します。

- これで、外部ツールはトークンを更新できなくなります。すでに出たアクセストークンは、期限（初期の設定では 24 時間）まで使えます
- 承認を外した利用者は、新しくログインできません。ただし、すでにログインしている外部ツールは、セッションをログアウトさせるまで止まりません

## アプリケーションの注意

### 外部ツールでできること

- 外部ツールは、マーケットプレイス版で公開している API・MCP の範囲で、その利用者に許された操作を全部できます。トークンのスコープでは絞りません（スコープによる制限はありません）
- 承認済みの利用者は、管理者が作ったクライアントでなくても、認証サーバーに最初からある利用者の画面用のクライアントでトークンを取れます。作ったクライアントだけに、使える外部ツールを限る仕組みではありません
- MCP の仕様の「トークンの宛先の確かめ」は行いません

### ログインの画面と守り

- 外部ツールのログインの画面は、認証サーバーの標準の画面です。メイン画面と見た目が違い、メイン画面の追加の守り（ワンタイムパスワードなど）とプロフィールの設定への誘導は効きません。要るときは、認証サーバーで設定します
- 外の入口には、IP ごとの回数の制限はありません（メイン画面のほかの入口と同じ）。認証サーバーは利用者ごとにログインの失敗で締め出します。IP で止めたいときは、外の入口の前に WAF などを置いてください
- 認証サーバーの外の入口も、ドメインの無い環境では出荷時の自前の証明書です。外部ツールはそのままでは信頼しません。公開の前に、独自ドメインと正規の証明書にしてください

### 製品が認証サーバーに作るもの

次は製品が作るものです。MP の realm の設定はメイン画面と共有なので、変えるとメイン画面にも効きます。「版上げのとき」の欄が「戻す」のものは、コンソールで変えても、次の GUI の版上げで製品の形に戻ります。

| もの                                                                 | 版上げのとき                                       |
| ------------------------------------------------------------------ | -------------------------------------------- |
| MP の realm（表示名・ログインの画面・言語・アクセストークンとログインのセッションの期限など）                | 作るときだけ入れる（変えた値は残る）                           |
| realm の設定（パスワードの決まり・締め出し・クライアントのセッションの期限・ユーザー名の扱い・SSL の要求）         | 戻す                                           |
| 利用者のプロフィール（姓・名を必須にしない・決まっていない属性を許す）                                | 違えば戻す（ほかのプロフィールの設定は残る）                       |
| ロール（admin・user・developer・pending）                                  | 無ければ作る                                       |
| グループ（pending-approval・approved-users・rejected-users）とロールの対応        | 無ければ作る・対応を足す                                 |
| メイン画面のログインに使うクライアントと、製品のサービスアカウント                                  | 無ければ作る。あれば秘密などをそろえる                          |
| メイン画面のログインに使うクライアントの写し方                                            | 無ければ足す                                       |
| 最初の管理者                                                             | 無ければ作る。あればロールとグループを付け直す                      |
| 記録（イベント）の設定と、要る種類                                                  | 違えば戻す。要る種類が足りなければ足す（購入者が足した種類は残る）            |
| パスキーの決まりと、パスキーの 2 つの必要な操作                                          | 違えば戻す                                        |
| ログインの流れのサンプル agentic-star browser                                  | 製品の形に戻す                                      |
| 最初からある account・account-console・security-admin-console の「認証フローの上書き」 | 何も付いていないか、無い流れを指すときだけ、サンプルを付ける（購入者が付けた流れは残る） |
| 最初からある admin-cli                                                   | 止める                                          |

製品が新しく作るもの（ログインの流れのサンプルと、その中の条件）は、名前の頭が `agentic-star` で、説明の欄に製品のものと書いてあります。

### サンプルの流れを写して使う

`agentic-star browser` は版上げで製品の形に戻るので、直接変えないでください。変えたいときは写して使います。

1. 「認証（Authentication）」の「フロー（Flows）」で `agentic-star browser` の行の操作から「重複（Duplicate）」を選び、新しい名前を付けます
2. 写した流れの中の、承認の確かめとメールの確かめの段（写す前の名前は `agentic-star browser approval`・`agentic-star browser email`）は、消さずに残します
3. 自分のクライアントの「認証フローの上書き（Authentication flow overrides）」の「ブラウザーフロー（Browser Flow）」に、写した流れを選びます

写した流れは購入者のもので、版上げでは触りません。製品のサンプルが版上げで変わったときは、もう一度写し直して、自分の変更を当て直してください。

## 次のステップ

- [AI クライアント接続ガイド（MCP）](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/ai-client-guide.md) — 外部ツールの設定とログイン
- [認証ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/auth-guide.md) — トークンの取り方
- [API を呼び出す](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/quickstart/call-api.md) — システム連携でチャット API を呼ぶ最短の手順
