# 認証ガイド

AGENTIC STAR の認証フロー（OIDC 準拠）によるアクセストークン取得手順を解説します。

## 概要

AGENTIC STAR は OIDC（OpenID Connect）標準に準拠した認証を提供します。用途に応じて、適切な認証フローを選択してください。

|                | アプリケーション                                | システム連携                                      |
| -------------- | --------------------------------------- | ------------------------------------------- |
| **認証フロー**      | Authorization Code                      | Client Credentials                          |
| **用途**         | ユーザーがブラウザ経由でログイン                        | サーバー間の連携（システム連携 API 等）                      |
| **呼べる API**    | ユーザー API（チャット・会話・ファイル・プロジェクトほか）・MCP・A2A | システム連携 API（プロジェクトの一部を含む）・MCP の一部。チャットは使えません |
| **トークン取得**     | 認可コードを経由して取得                            | クライアント認証情報で直接取得                             |
| **リフレッシュトークン** | あり                                      | なし（期限切れ後に再取得）                               |
| **前提となる画面**    | Console                                 | Console                                     |

詳細仕様は [認証 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/auth-saas-ref.md) を参照してください。マーケットプレイス版は [認証ガイド（マーケットプレイス版）](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/auth-guide.md) を参照してください。

## Authorization Code フロー

ユーザーがブラウザ経由でログインし、認可画面を経由してアクセストークンとリフレッシュトークンを取得する認証フローです。

### 前提条件

- Console でアプリケーション（クライアント）を登録済みであること（[Consoleガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md)）
- `client_id` と `client_secret` を取得済みであること
- リダイレクト URI（`redirect_uri`）を登録済みであること

### 1. 認可リクエスト

ユーザーをブラウザで認可エンドポイントにリダイレクトします。

```text
GET https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &state=STATE_VALUE
```

**パラメータ**

| パラメータ           | 必須 | 説明                                                                                                               |
| --------------- | -- | ---------------------------------------------------------------------------------------------------------------- |
| `response_type` | 必須 | `code` 固定                                                                                                        |
| `client_id`     | 必須 | Console で取得したクライアント ID                                                                                           |
| `redirect_uri`  | 必須 | Console に登録済みのリダイレクト URI                                                                                         |
| `state`         | 推奨 | CSRF 攻撃対策用のランダム値。指定した場合はレスポンスで返却されるため、リクエスト時の値と一致を必ず検証してください                                                     |
| `nonce`         | —  | ID Token のリプレイ攻撃対策用ランダム値（推奨）。指定すると ID Token の `nonce` クレームに同じ値が挿入されるため、検証して一致を確認してください                           |
| `ui_locales`    | —  | ログイン画面・同意画面の表示言語。`ja`（デフォルト）、`en`、`fr`、`es`、`th`、`id`、`ar`、`zh-CN`、`zh-TW`、`pt-BR`、`de-DE`、`it-IT`、`ko`、`vi` に対応 |

### 2. ユーザー認証

認可エンドポイントにアクセスすると、ログイン画面が表示されます。普段ご利用のアカウントと同じ認証方法でログインしてください。

[同意画面](#%E5%90%8C%E6%84%8F%E7%94%BB%E9%9D%A2)が有効になっているアプリケーションの場合、初回利用時やスコープ追加時に同意画面が表示されます。内容を確認し、許可してください。

認証が完了すると、認可コードが発行されリダイレクト URI に返されます。

> **ログインできるアカウント**
>
> ログインには、ご契約の AGENTIC STAR 環境のアカウントが必要です。

> **アプリケーションを使える人**
>
> Console の「テナントの全員が使える」のオン・オフで、アクセスできるユーザーが変わります。詳細は [Consoleガイド — 公開範囲](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md#5-%E5%85%AC%E9%96%8B%E8%A8%AD%E5%AE%9A) を参照してください。

### 3. 認可コード受け取り

ユーザーが認可を許可すると、ブラウザは `redirect_uri` にリダイレクトされます。URL に一時的な認可コード（`code`）が含まれます。

```text
https://yourapp.com/callback?
  code=AUTH_CODE_VALUE
  &state=STATE_VALUE
```

> **警告**
>
> - `state` を指定した場合は、返された値がリクエスト時の値と一致することを必ず検証してください（CSRF 対策）
> - `code` は有効期限が短いため、すぐに次の Step でトークンに交換してください

### 4. トークンの取得

認可コードをアクセストークンに交換します。サーバー側で以下のリクエストを実行してください。

```bash
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_VALUE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
```

**パラメータ**

- `grant_type`: `authorization_code` 固定
- `code`: 手順 3 で取得した認可コード
- `redirect_uri`: 手順 1 と同じ URI
- `client_id`: Console で取得したクライアント ID
- `client_secret`: Console で取得したクライアントシークレット（安全に保管してください）

**レスポンス例**

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 86400,
  "scope": "openid chat:exec chat:history chat:file mcp:all"
}
```

### トークンリフレッシュ

Authorization Code フローで取得したリフレッシュトークン（`refresh_token`）を使用して、新しいアクセストークンを取得できます。

```bash
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN_VALUE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
```

**レスポンス例**

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 86400,
  "scope": "openid chat:exec chat:history chat:file mcp:all"
}
```

> **ベストプラクティス**
>
> アクセストークンの有効期限が切れる直前（例: 残り 5 分以内）にリフレッシュすることをお勧めします。これにより、API 呼び出し中のトークン有効期限切れエラーを防げます。

> **リフレッシュトークンの取り扱い**
>
> - **最新のトークンを使用してください**：リフレッシュのたびに新しい `refresh_token` が発行されます。レスポンスに含まれる新しい `refresh_token` を保存し、次回以降はそれを使用してください。以前の `refresh_token` は使用しないでください。
> - **共有・並行使用を避けてください**：同一の `refresh_token` を複数のプロセスやインスタンスで共有したり、同時にリフレッシュしたりしないでください。クライアントごとに個別にトークンを取得・管理してください。

### 同意画面

Authorization Code フローでは、Console のアプリケーション設定で同意画面を有効にすると、ユーザーがアプリケーションにアクセス権限を許可するための同意画面が表示されます。

#### 同意画面に表示される情報

- アプリケーション名・ロゴ・説明
- アプリケーションに許可するアクセス権限の一覧
- サポート URL、プライバシーポリシー URL、利用規約 URL

> **アクセス権限について**
>
> アクセス権限は、アプリケーションが API で実行できる操作の範囲です。Console でアプリケーションに割り当てた[スコープ](#%E3%82%B9%E3%82%B3%E3%83%BC%E3%83%97)に基づき、権限の一覧が表示されます。基本的なユーザー情報（プロフィール、メールアドレス）へのアクセスは、OIDC 標準スコープとしてデフォルトで許可されます。

これらの情報は Console のアプリケーション設定で管理します。詳細は [Consoleガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md) を参照してください。

#### 同意画面が表示されるタイミング

- **初回利用時** — ユーザーがそのアプリケーションを初めて利用する際に表示されます。ユーザーが同意すると、承認したスコープが記録されます。
- **スコープ追加時** — アプリケーションのスコープを後から追加した場合、次回認証時に同意画面が再度表示されます。このとき、新たに追加されたスコープだけでなく、既に承認済みのスコープも含めてすべてのスコープが表示されます。

一度同意したスコープは記録されるため、同じスコープ構成であれば 2 回目以降のログインでは同意画面は表示されません。

## Client Credentials フロー

サーバー間のシステム認証に使用するフローです。ユーザーの介在なしに、クライアント認証情報のみでアクセストークンを取得します。

システム連携は、トークンを取る代わりに、Console で発行した API キーを `Authorization: Bearer` で送ることもできます（[Console ガイド — API キー](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md#api-key)）。

### 前提条件

- Console でシステム連携（クライアント）を登録済みであること（[Consoleガイド — システム連携](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md#%E3%82%B7%E3%82%B9%E3%83%86%E3%83%A0%E9%80%A3%E6%90%BA%E3%81%AE%E4%BD%9C%E6%88%90%E6%89%8B%E9%A0%86)）
- `Client ID`、`Client Secret`、`Token URL` を取得済みであること

### トークンの取得

サーバー側で以下のリクエストを実行してください。

```bash
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
```

**パラメータ**

- `grant_type`: `client_credentials` 固定
- `client_id`: Console で取得したクライアント ID
- `client_secret`: Console で取得したクライアントシークレット

**レスポンス例**

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid users:read logs:read"
}
```

### トークンの再取得

Client Credentials フローではリフレッシュトークンは発行されません。アクセストークンの有効期限（`expires_in` に指定された秒数）が切れた場合は、同じリクエストを再度実行して新しいトークンを取得してください。

> **ベストプラクティス**
>
> 有効期限を管理し、期限切れ前に新しいトークンを取得することで、API 呼び出しの中断を防げます。

## スコープ

スコープは、アクセストークンに含まれる権限を表します。アプリケーションが API で実行できる操作は、付与されたスコープによって決まります。

### スコープの割り当て

- Console でクライアント作成時にスコープを選択します。アプリケーション（AC フロー）では Chat API・MCP・A2A・プロジェクト・ライブラリ用のスコープを、システム連携（CC フロー）ではシステム連携 API・プロジェクト・MCP 用のスコープを選択します（[Consoleガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md)）。割り当てたスコープに応じて、利用可能な API が制限されます。

### スコープ一覧

AGENTIC STAR のエージェントには、Chat API（SSE）、MCP、A2A の 3 つの接続方式があります。利用する接続方式に応じたスコープが必要です。接続方式の詳細は[接続方式ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/connection-guide.md)を参照してください。

#### Chat API（SSE）で接続する場合

| スコープ           | 説明                                                                |
| -------------- | ----------------------------------------------------------------- |
| `chat:exec`    | チャットの開始・停止、ストリーミング応答の受信、成果物の取得。Chat API を利用する場合は必須です。             |
| `chat:history` | 会話一覧・メッセージ履歴の取得（アクティブ / アーカイブ）、会話の削除・タイトル更新・アーカイブ済み会話の復元、メッセージ検索。 |
| `chat:file`    | チャットで使用するファイルのアップロード・取得・削除。                                       |

#### MCP / A2A で接続する場合

| スコープ          | 説明                                                                                                                                                                                                                                                                                                                     |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mcp:connect` | MCP（Model Context Protocol）に接続する場合に必要です。使えるツールは、あわせて持つスコープで決まります（[MCP API リファレンス — 提供ツール](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/mcp-ref.md#%E6%8F%90%E4%BE%9B%E3%83%84%E3%83%BC%E3%83%AB)）。新しく作るアプリには、こちらと使うツールのスコープを選ぶことを勧めます。                                               |
| `mcp:all`     | MCP のすべてのツールを使えます。ほかのスコープは要りません。                                                                                                                                                                                                                                                                                       |
| `a2a:connect` | A2A（Agent-to-Agent）プロトコルでエージェントに接続する場合に必要です。使える操作は、あわせて持つスコープで決まります（送る・取る・止める・つなぎ直すは `chat:exec`、ファイルを添えるならさらに `chat:file`、一覧は `chat:history`。[A2A API リファレンス — 認証](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/a2a-ref.md#%E8%AA%8D%E8%A8%BC)）。新しく作るアプリには、こちらと使う操作のスコープを選ぶことを勧めます。 |
| `a2a:all`     | A2A のすべての操作を使えます。ほかのスコープは要りません。                                                                                                                                                                                                                                                                                        |

#### システム連携 API を利用する場合

| スコープ                 | 説明                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------- |
| `sharedmemory:query` | 共有メモリの検索。                                                                             |
| `users:read`         | ユーザー情報の読み取り（一覧・詳細）。                                                                   |
| `users:manage`       | ユーザーの管理操作（作成・承認・承認取り消し・削除・ロール変更・利用の停止と再開・ロックの解除・所属と職種の変更）。`users:read` の権限を含みます。      |
| `logs:read`          | ログの閲覧（監査ログ・操作監査ログ・利用者の操作の監査・LLMログ・LLM Gateway ログ・LLM Gateway 操作監査・アクセスログ・ガードレールアラート）。 |
| `master:manage`      | マスターデータの管理（組織・職種の作成・更新・削除）。                                                           |

#### プロジェクトを操作する場合

プロジェクトを API で操作する場合に必要です。仕様はアプリケーションの場合は[ユーザー API リファレンス — プロジェクト](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#projects)、システム連携の場合は[システム連携 API リファレンス — プロジェクト](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/admin-api-reference.md#projects)を参照してください。

| スコープ             | 説明                                                                                                                                                                                 |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project:read`   | プロジェクトの参照。アプリケーションでは、参加しているプロジェクトと、組織の運用の役割で読めるプロジェクトの、実行・記録・確認依頼・キュー・プロジェクトのライブラリの閲覧（組織の運用の役割では、プロジェクトのライブラリと確認依頼は読めません。確認依頼は、キューの行には出ます）。システム連携では、プロジェクト制限の範囲のプロジェクトの一覧と実行状況の参照。 |
| `project:run`    | プロジェクトの実行開始と、`cycle` 型プロジェクトのトリガー発火と、ワークフローの実行の中断。アプリケーションでは、失敗した巡回の再実行と、閉じたワークフローの実行の再開も。                                                                                         |
| `project:write`  | プロジェクトの作成と、オーナーのプロジェクトの変更（ワークフローの実行の締め切りと確認担当者の付け替え、プロジェクトの一時停止と再開は、運用担当として参加しているプロジェクトと、組織の運用の役割を持つ組織のプロジェクトでも）、プロジェクトのライブラリのファイルの登録・変更・削除。アプリケーションだけ。                            |
| `project:delete` | オーナーのプロジェクトの削除。アプリケーションだけ。                                                                                                                                                         |
| `project:decide` | 担当の確認依頼（期間中の代理人として決められる確認依頼を含む）の判断と、確認依頼の期限の延長（期限の延長は、オーナー・運用担当と組織の運用の役割の人もできます）。アプリケーションだけ。                                                                                       |

#### ライブラリを操作する場合

Agent・Playbook・Skill を API で操作する場合に必要です。アプリケーションだけで使えます。仕様は[ユーザー API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md)を参照してください。

| スコープ            | 説明                                                          |
| --------------- | ----------------------------------------------------------- |
| `assets:read`   | Agent・Playbook・Skill の閲覧。スキル・プレイブックの一覧は `chat:exec` でも呼べます。 |
| `assets:write`  | Agent・Playbook・Skill の作成・変更・コピー。                            |
| `assets:delete` | Agent・Playbook・Skill の削除。                                   |

> **プロジェクト・ライブラリのスコープの注意**
>
> - **ワイルドカードは使えません。** `project:*`・`project:all`・`assets:*`・`assets:all` を指定しても API は利用できません。必要なスコープを個別に選択してください。
> - **`project:write`・`project:delete`・`project:decide` と `assets:read`・`assets:write`・`assets:delete` は、アプリケーション（AC フロー）だけで使えます。** システム連携のトークンには付きません。
> - **書き込み・削除・判断のスコープは、同じ領域の閲覧のスコープと一緒に使います。** `project:write`・`project:delete`・`project:decide` には `project:read` が、`assets:write`・`assets:delete` には `assets:read` が要ります。Console で選ぶと、閲覧のスコープも選ばれます。
> - **スコープはプロジェクトを選ぶものではありません。** 操作できるプロジェクトの範囲は、システム連携では Console の**プロジェクト制限**、アプリケーションでは**利用者のプロジェクトへの参加状況と組織の運用の役割**で決まります。
> - アプリケーション（AC フロー）では、プロジェクトの一覧はメンバーが、個々のプロジェクトと実行状況はメンバーと組織の運用の役割の人が読めます（組織の運用の役割の人には Agent の出力などが出ません）。実行の開始・トリガーの発火は、メンバーと組織の運用の役割の人が行えます。ワークフローの実行の中断は、オーナー・運用担当（組織の運用の役割の人を含む）と、その実行を始めた本人が行えます。ワークフローの実行の締め切りと確認担当者の付け替え・失敗した巡回の再実行・閉じたワークフローの実行の再開（再開の選択肢の取得も）・プロジェクトの一時停止と再開はオーナーと運用担当（組織の運用の役割の人を含む）、ほかのプロジェクトの変更と削除はオーナーのみ、確認依頼の判断は確認担当者と期間中の代理人のみ、期限の延長はそれに加えてオーナー・運用担当と組織の運用の役割の人です。

### スコープの選択指針

#### アプリケーション（AC フロー）で選択可能なスコープ

- **Chat API でエージェントを利用する場合**: `chat:exec` は必須です。履歴管理やファイル操作が必要であれば `chat:history`、`chat:file` を追加してください。
- **MCP 対応 AI エージェントから接続する場合**: `mcp:connect` と、使うツールのスコープ（例: チャットなら `chat:exec`、プロジェクトの参照なら `project:read`）を選択してください。MCP のすべてのツールを使う場合は `mcp:all` も選べます。
- **A2A 対応 AI エージェントから接続する場合**: `a2a:connect` と、使う操作のスコープ（送る・取る・止める・つなぎ直すなら `chat:exec`、ファイルを添えるならさらに `chat:file`、一覧なら `chat:history`）を選択してください。A2A のすべての操作を使う場合は `a2a:all` も選べます。
- **プロジェクトを操作する場合**: `project:read`（参照）、`project:run`（実行の開始・発火・失敗した巡回の再実行・閉じたワークフローの実行の再開・ワークフローの実行の中断）、`project:write`（作成・変更）、`project:delete`（削除）、`project:decide`（確認依頼の判断・期限の延長）を必要に応じて選択してください。
- **ライブラリ（Agent・Playbook・Skill）を操作する場合**: `assets:read`（閲覧）、`assets:write`（作成・変更・コピー）、`assets:delete`（削除）を必要に応じて選択してください。
- 複数の接続方式を併用する場合は、それぞれのスコープを組み合わせて選択できます。

#### システム連携（CC フロー）で選択可能なスコープ

- **システム連携 API を利用する場合**: 必要な操作に応じて `users:read`、`users:manage`、`logs:read`、`master:manage`、`sharedmemory:query` 等を選択してください。
- **プロジェクトを操作する場合**: 参照だけなら `project:read`、実行の開始・発火・ワークフローの実行の中断まで行うなら `project:run` を追加してください。あわせて Console でプロジェクト制限を設定してください（[Consoleガイド — プロジェクト制限の設定](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md#project-restriction)）。
- **MCP から使う場合**: `mcp:connect` を追加してください。システム連携で使えるのは、MCP の project の組の 5 つの操作と `list_personas` です（[AI クライアント接続ガイド（MCP）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/ai-client-guide.md)）。

## アクセストークンの利用

取得したアクセストークンは、API リクエストの `Authorization` ヘッダーに Bearer トークンとして設定してください。

```text
Authorization: Bearer <access_token>
```

すべての API エンドポイントで同じ形式を使用します。詳細は [ユーザー API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md) を参照してください。

> **利用者の権限の変更が反映される時期**
>
> - アプリケーションのトークンで呼ぶ API のうち、システム管理者かどうかで扱いが変わる操作は、利用者が AGENTIC STAR の画面に最後にログインしたときのロールで判定されます。ロールを変えた後は、その利用者が画面にログインするまで反映されません。
> - 利用者を無効にしても、発行済みのアクセストークンは有効期限（1 時間）まで使える場合があります。
