メインコンテンツまでスキップ

API 利用準備ガイド

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

概要​

アプリケーションシステム連携
だれが使うか社員(Claude Code などの外部ツールから、自分のアカウントで)会社のシステム
認証外部ツールでログイン(認可コード+PKCE)サービスアカウント(Client Credentials)
準備する所認証サーバーのコンソール管理画面(Admin)
呼べる APIユーザー API(会話・組織・プロジェクト)・MCPシステム連携 API・MCP
外部ツールでのログインを使う前に
  • 外部ツールでのログインは、管理者が認証サーバーの外の入口を開けた環境でだけ使えます。既定では閉じています。開け方・閉じ方は、構築の節の ドメイン設定ガイド を参照してください
  • 開け閉めのたびに認証サーバーが入れ替わり、その間はメイン画面のログインとトークンの更新もできません。利用者の少ない時間に行ってください
  • MCP も使うときは、MCP の受け口も開けます(構築の節の Helm Values リファレンス)

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

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

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

    curl
    kubectl get configmap librechat-auth-env -n librechat-auth -o jsonpath='{.data.KEYCLOAK_REALM}'
  2. 認証サーバーへの道をつなぎます(8080 が使われていれば、手元の別のポートにします)

    curl
    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))
  • 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)で作ります。

  1. 管理画面の「ユーザー管理」→「サービスアカウント」で「サービスアカウント作成」を押します
  2. 「Client ID」(英数字・.・_・-)と「名前」「説明」を入れ、「有効化」をオンにして作ります
  3. 作ったサービスアカウントの詳細画面で、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 は版上げで製品の形に戻るので、直接変えないでください。変えたいときは写して使います。

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

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

次のステップ​