API 利用準備ガイド
マーケットプレイス版の API を使うための準備の手順です。社員が外部ツールから自分のアカウントで使う「アプリケーション」と、会社のシステムが使う「システム連携」で、準備する所が違います。
概要
| アプリケーション | システム連携 | |
|---|---|---|
| だれが使うか | 社員(Claude Code などの外部ツールから、自分のアカウントで) | 会社のシステム |
| 認証 | 外部ツールでログイン(認可コード+PKCE) | サービスアカウント(Client Credentials) |
| 準備する所 | 認証サーバーのコンソール | 管理画面(Admin) |
| 呼べる API | ユーザー API(会話・組織・プロジェクト)・MCP | システム連携 API・MCP |
- 外部ツールでのログインは、管理者が認証サーバーの外の入口を開けた環境でだけ使えます。既定では閉じています。開け方・閉じ方は、構築の節の ドメイン設定ガイド を参照してください
- 開け閉めのたびに認証サーバーが入れ替わり、その間はメイン画面のログインとトークンの更新もできません。利用者の少ない時間に行ってください
- MCP も使うときは、MCP の受け口も開けます(構築の節の Helm Values リファレンス)
認証サーバーのコンソールを開く
アプリケーションの準備は、認証サーバーのコンソールで行います。コンソールは外に出していないので、クラスタに kubectl でつなげる端末から、中の道で開きます。
-
MP の realm の名前を確かめます。インストーラーの
config.yamlのkeycloak.realm_nameです(例:agenticstar)。入れた後の環境では、次のコマンドでも分かりますcurlkubectl get configmap librechat-auth-env -n librechat-auth -o jsonpath='{.data.KEYCLOAK_REALM}' -
認証サーバーへの道をつなぎます(
8080が使われていれば、手元の別のポートにします)curlkubectl port-forward -n librechat-auth svc/keycloak-extensions-keycloakx-http 8080:8080 -
ブラウザで
http://localhost:8080/admin/を開き、master realm の管理者でログインします。最初の管理者のユーザー名とパスワードは、インストーラーのconfig.yamlのkeycloak.admin_email・keycloak.admin_passwordです -
左上の realm の選び先で、MP の realm(1 の名前)を選びます
人用の管理者を作る
最初の管理者は、すべての realm を変えられます。ふだんの作業には、MP の realm のクライアントだけを扱える管理者を、master realm に作って使うことを勧めます。
- master realm で「ユーザー(Users)」→「ユーザーの追加(Add user)」から作り、「クレデンシャル(Credentials)」タブの「パスワードを設定(Set password)」でパスワードを決めます
- 「ロールマッピング(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)) - 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 は、製品が配るログインの流れのサンプルです。メイン画面のログインと同じく、承認済みでメールを確かめた利用者だけを通します。この流れを付けないクライアントでは、承認待ち・メール未確認の利用者もログインできてしまいます。流れを変えたいときは、サンプルの流れを写して使う を参照してください。
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 リファレンス — 外部ツールでのログイン にあります。
システム連携の作成手順(管理画面)
会社のシステムが使うサービスアカウントを、管理画面(Admin)で作ります。
- 管理画面の「ユーザー管理」→「サービスアカウント」で「サービスアカウント作成」を押します
- 「Client ID」(英数字・
.・_・-)と「名前」「説明」を入れ、「有効化」をオンにして作ります - 作ったサービスアカウントの詳細画面で、Client ID と Client Secret を確かめます
トークンの取り方は 認証ガイド — トークンの取得 を参照してください。
認証情報の確認
社員とシステムの担当者に、次を伝えます。
| 伝えるもの | アプリケーション | システム連携 |
|---|---|---|
| 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>(認証サービスのドメイン)は、構築の時に管理者が決めたものです(ドメイン設定ガイド)。
資格情報が漏れたとき
| 漏れたもの | 止め方 |
|---|---|
| サービスアカウントの 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 は版上げで製品の形に戻るので、直接変えないでください。変えたいときは写して使います。
- 「認証(Authentication)」の「フロー(Flows)」で
agentic-star browserの行の操作から「重複(Duplicate)」を選び、新しい名前を付けます - 写した流れの中の、承認の確かめとメールの確かめの段(写す前の名前は
agentic-star browser approval・agentic-star browser email)は、消さずに残します - 自分のクライアントの「認証フローの上書き(Authentication flow overrides)」の「ブラウザーフロー(Browser Flow)」に、写した流れを選びます
写した流れは購入者のもので、版上げでは触りません。製品のサンプルが版上げで変わったときは、もう一度写し直して、自分の変更を当て直してください。
次のステップ
- AI クライアント接続ガイド(MCP) — 外部ツールの設定とログイン
- 認証ガイド — トークンの取り方
- API を呼び出す — システム連携でチャット API を呼ぶ最短の手順