# 認証ガイド

マーケットプレイス版のアクセストークン取得手順を解説します。

## 概要

用途に応じて、2 つの認証フローを使い分けます。

|                | アプリケーション                     | システム連携              |
| -------------- | ---------------------------- | ------------------- |
| **認証フロー**      | Authorization Code（PKCE）     | Client Credentials  |
| **用途**         | 社員が外部ツールから、自分のアカウントでログインして使う | 会社のシステムがサーバー間で使う    |
| **トークン取得**     | ブラウザでログインし、認可コードを経由して取得      | サービスアカウントの認証情報で直接取得 |
| **リフレッシュトークン** | あり                           | なし（期限切れ後に再取得）       |
| **準備する所**      | 認証サーバーのコンソール                 | 管理コンソール             |

準備の手順は [API 利用準備ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/setup-guide.md) を、詳細仕様は [認証 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/auth-mp-ref.md) を参照してください。

## 前提条件

- マーケットプレイスで購入した AGENTIC STAR 環境のセットアップが完了していること
- アプリケーション: 管理者が外部ツールでのログインの入口を開け、認証サーバーのコンソールで外部ツールのクライアントを作成済みであること（[API 利用準備ガイド — アプリケーションの作成手順](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/setup-guide.md#external-tool-client)）
- システム連携: 管理コンソールでサービスアカウントを作成済みで、`Client ID` と `Client Secret` を取得済みであること（[API 利用準備ガイド — システム連携の作成手順](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/setup-guide.md#service-account)）

トークンを取る所と API は、ドメインが違います。トークンは認証サービス（または認証サーバーの外の入口）のドメイン、API は外部 API のドメインです。どちらも構築の時に管理者が決めたものです。

## Authorization Code フロー

社員が外部ツールでログインし、認可コードを経由してアクセストークンとリフレッシュトークンを取得する認証フローです。MCP 対応の AI クライアント（Claude Code・Codex など）は、この手順を自分で行います（[AI クライアント接続ガイド（MCP）](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/ai-client-guide.md)）。自社のアプリでログインするときは、次の手順で行います。

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

ユーザーをブラウザで、認証サーバーの外の入口の認可エンドポイントにリダイレクトします。PKCE（S256）が必須です。

```text
GET https://<認証サーバーの外の入口のドメイン>/realms/<realm>/protocol/openid-connect/auth?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=http://localhost:8765/callback
  &scope=openid
  &state=STATE_VALUE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
```

| パラメータ                   | 必須 | 説明                                          |
| ----------------------- | -- | ------------------------------------------- |
| `response_type`         | 必須 | `code` 固定                                   |
| `client_id`             | 必須 | 認証サーバーのコンソールで作ったクライアントの ID                  |
| `redirect_uri`          | 必須 | クライアントに登録した戻り先                              |
| `scope`                 | 必須 | `openid` を含めます                              |
| `state`                 | 推奨 | CSRF 対策のランダム値。戻ってきた値がリクエストの値と同じかを必ず確かめてください |
| `code_challenge`        | 必須 | `code_verifier` の SHA-256 を base64url にした値  |
| `code_challenge_method` | 必須 | `S256` 固定                                   |

### 2. ユーザー認証

認証サーバーのログインの画面で、メイン画面と同じメールアドレスとパスワードでログインします。承認済みで、メールアドレスを確かめた利用者だけがログインできます（API 利用準備ガイドの手順どおりに作ったクライアントのとき）。

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

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

### 4. トークンの交換

認可コードを、トークンエンドポイントでアクセストークンに換えます。公開のクライアントなので、`client_secret` は送りません。

```bash
curl -X POST https://<認証サーバーの外の入口のドメイン>/realms/<realm>/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=http://localhost:8765/callback" \
  -d "code_verifier=CODE_VERIFIER"
```

応答の `access_token` を API の呼び出しに、`refresh_token` を次の取り直しに使います。

### 5. トークンの更新

アクセストークンの期限が切れたら、リフレッシュトークンで取り直します。

```bash
curl -X POST https://<認証サーバーの外の入口のドメイン>/realms/<realm>/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "refresh_token=REFRESH_TOKEN"
```

## Client Credentials フロー

管理コンソールで作成したサービスアカウントの認証情報で、アクセストークンを取得します。ユーザーの介在はありません。サーバー側で次のリクエストを実行してください。

```bash
curl -X POST https://<auth-domain>/api/v1/oauth/token \
  -u "<your-client-id>:<your-client-secret>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"
```

- クライアントの認証は、`Authorization` ヘッダーの Basic 認証か、本文の `client_id`・`client_secret` のどちらか一方で送ります
- `<auth-domain>` は、ご利用環境の認証サービスのドメインです（例: `auth.example.com`）

**レスポンス例**

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "openid profile email"
}
```

認証情報が誤っているときは `401 Unauthorized`（`{"error": "invalid_client", ...}`）が返ります。

> **これまでのトークンの口**
>
> これまでの `POST https://<auth-domain>/api/v1/auth/external-service-token`（本文は JSON の `client_id`・`client_secret`）も、引き続き使えます。応答は `success`・`access_token`・`token_type`・`expires_in`・`scope` です。

### トークンの再取得

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

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

## スコープ

マーケットプレイス版ではスコープによる制限はありません。どちらのフローのトークンでも、スコープで API を絞りません。

- アプリケーションのトークンでは、その利用者に許された操作ができます。プロジェクトの操作は、プロジェクトへの参加状況と組織の運用の役割で決まります（[ユーザー API リファレンス（プロジェクト）](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md)）
- システム連携のトークンで呼べる API は、[システム連携 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/api-reference.md) にあるものです

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

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

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

すべての API エンドポイントで同じ形式を使用します。API の住所は `https://<your-domain>/api`（`<your-domain>` は外部 API のドメイン）です。
