> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/ja/conversations/web-chat/source-id-access.md).

# 連絡先の Source ID によるログイン不要の対話

Web サイトにログイン済みのユーザーが、自分のユーザー番号（Source ID）を使用して再ログインせずに直接対話できます。プラットフォームはこの番号を連絡先に対応付け、バックエンドの署名がないリクエストによるなりすましを防ぎます。

Web Chat を自社の Web サイトに埋め込む場合、ユーザーはすでにそのサイトにログインしていることが一般的です。この設定を使用すると、自社システムのユーザー番号を渡してすぐに対話を開始でき、再度ログイン画面を通る必要がありません。同時に、公開対話 URL からの匿名アクセスは引き続きブロックされます。

MaiAgent ではこの番号を **Source ID** と呼び、管理画面と埋め込みスクリプトでも同じ名称を使用します。Source ID を受信すると、プラットフォームはそれを一人の**連絡先**に対応付けるか、新しい連絡先を作成し、そのユーザーの対話履歴を連絡先に紐付けます。

## <mark style="color:blue;">一、この設定で解決できる課題</mark> <a href="#what-it-solves" id="what-it-solves"></a>

これまでは、ログイン設定で次のいずれかを選ぶ必要がありました。

* ログイン設定を有効にする：埋め込み元ですでに本人確認済みでも、ユーザーは再度ログインを求められます。
* ログイン設定を無効にする：公開対話 URL を誰でも匿名で利用できます。

この設定を有効にすると、Source ID と有効な署名を持つユーザーは直接対話でき、それらを持たないアクセスはすべてログインページへ転送されます。

{% hint style="info" %}
この設定はデフォルトで無効です。無効の場合、既存の動作は一切変わりません。
{% endhint %}

## <mark style="color:blue;">二、設定を有効にする</mark> <a href="#enable" id="enable"></a>

左側のメニューで「<mark style="color:blue;">カスタマーサポート対話 > 対話プラットフォーム</mark>」を開き、Web サイトタイプの対話プラットフォームを選択して、「<mark style="color:blue;">ログイン設定</mark>」タブを開きます。

### 1. 最初にログインソースを選択する <a href="#prerequisite" id="prerequisite"></a>

このスイッチはログイン設定に付随するため、まず「<mark style="color:blue;">ログインソース</mark>」でいずれかのソース（MaiAgent／AD／Keycloak／LINE）を選択する必要があります。未選択の場合はスイッチを操作できず、「<mark style="color:blue;">先にログインソースを選択してください</mark>」と表示されます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-0bed4d025474ad42bf838b7e9e00e78f90693425%2Fsourceid-01-default.png?alt=media" alt=""><figcaption><p>ログイン設定タブでは、このスイッチはデフォルトで無効です</p></figcaption></figure>

### 2. スイッチを有効にする <a href="#toggle" id="toggle"></a>

「<mark style="color:blue;">埋め込み側で Source ID を使用したログイン不要の対話を許可</mark>」を有効にします。有効にすると、検証方式、署名シークレット、連携例が表示されます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-95e715c203b5b89846e419419586baad4076301b%2Fsourceid-02-enabled-signature.png?alt=media" alt=""><figcaption><p>展開された設定欄では、「署名検証を必須にする」がデフォルトです</p></figcaption></figure>

### 3. 検証方式を選択する <a href="#verify-mode" id="verify-mode"></a>

| 検証方式                                            | 説明                                                                                   | 適した環境             |
| ----------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------- |
| <mark style="color:blue;">署名検証を必須にする</mark>（推奨） | 埋め込み側は、バックエンドで計算した署名を添付する必要があります。検証に成功した場合のみ許可され、シークレットを持つサーバーだけがユーザーに代わって対話を開始できます。 | 本番環境              |
| <mark style="color:blue;">Source ID のみ</mark>   | 署名を検証せず、Source ID があれば許可します。                                                         | テスト環境または閉域イントラネット |

{% hint style="danger" %}
「Source ID のみ」を選択すると、Source ID 自体がアクセス証明になります。メールアドレス、学籍番号、社員番号など推測可能な値の場合、第三者がそのユーザーになりすまして対話し、履歴を閲覧できる可能性があります。本人確認が必要な場合は署名モードを使用するか、AD／Keycloak／MaiAgent ログインを使用してください。
{% endhint %}

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-8fa84f2e4965e66f8872be1997424f02b47e77c5%2Fsourceid-03-raw-mode-warning.png?alt=media" alt=""><figcaption><p>「Source ID のみ」を選択すると、赤色のリスク警告が表示されます</p></figcaption></figure>

### 4. 署名シークレットを取得する <a href="#signing-secret" id="signing-secret"></a>

署名モードを選択して設定を保存すると、プラットフォームが署名シークレットを生成します。シークレット欄では次の操作ができます。

* 「<mark style="color:blue;">表示</mark>」をクリックして完全なシークレットを確認します（デフォルトではマスクされています）
* 「<mark style="color:blue;">コピー</mark>」をクリックしてエンジニアに渡します
* 「<mark style="color:blue;">再生成</mark>」をクリックして新しいシークレットを発行します

{% hint style="warning" %}
シークレットはサーバーの環境変数に保存し、フロントエンドのコードには絶対に記述しないでください。再生成すると古いシークレットは直ちに無効になります。バックエンドも同時に更新しないと、すべての署名検証に失敗します。
{% endhint %}

### 5. 署名の有効期限を設定する <a href="#signature-ttl" id="signature-ttl"></a>

1 分、5 分、15 分から選択でき、デフォルトは 5 分です。期限切れまたは使用済みの署名は拒否されます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-2e4eb936b04e8a0ffea6d1aa0dac6fa5b6ec0407%2Fsourceid-04-secret-ttl-snippets.png?alt=media" alt=""><figcaption><p>署名シークレット、有効期限、連携例、動作プレビュー</p></figcaption></figure>

{% hint style="info" %}
有効期限は「この署名を使用して対話を開始できる期間」を制限するもので、対話の継続時間ではありません。本人確認後の対話は通常どおり継続し、5 分後にログアウトすることはありません。
{% endhint %}

## <mark style="color:blue;">三、エンジニア向け連携方法</mark> <a href="#integration" id="integration"></a>

管理画面の「<mark style="color:blue;">連携例</mark>」には、この対話プラットフォームの ID が反映されており、そのままコピーできます。パラメータ、検証ルール、トラブルシューティングの詳細は、[Web Chat 埋め込みと SDK · 署名検証](https://docs.maiagent.ai/tech/api-integration/web-chat-sdk#source-id-signature)を参照してください。

### 1. バックエンドで署名を計算する <a href="#backend-signature" id="backend-signature"></a>

署名は `HMAC-SHA256(シークレット, "{対話プラットフォーム ID}.{Source ID}.{タイムスタンプ}")` で、16 進文字列として渡します。タイムスタンプはバックエンドが生成する Unix 秒（UTC）です。

{% tabs %}
{% tab title="PHP" %}
{% code overflow="wrap" %}

```php
$ts  = time();
$sig = hash_hmac('sha256', "{$webChatId}.{$sourceId}.{$ts}", $SIGNING_SECRET);
```

{% endcode %}
{% endtab %}

{% tab title="Node" %}
{% code overflow="wrap" %}

```javascript
const ts = Math.floor(Date.now() / 1000);
const sig = crypto.createHmac('sha256', SIGNING_SECRET)
  .update(`${webChatId}.${sourceId}.${ts}`).digest('hex');
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code overflow="wrap" %}

```python
ts = int(time.time())
sig = hmac.new(SIGNING_SECRET.encode(),
  f"{web_chat_id}.{source_id}.{ts}".encode(), hashlib.sha256).hexdigest()
```

{% endcode %}
{% endtab %}
{% endtabs %}

### 2. フロントエンドの埋め込みスクリプトに渡す <a href="#frontend-setup-auth" id="frontend-setup-auth"></a>

{% code overflow="wrap" %}

```javascript
window.MaiAgent.setupAuth({ sourceId, name, ts, sig });
```

{% endcode %}

### 3. 連携時の注意事項 <a href="#integration-notes" id="integration-notes"></a>

* **アクセスのたびに再署名します**：同じ署名を正常に使用できるのは一度だけです。埋め込み側で署名をキャッシュしないでください。
* **署名はバックエンドで計算します**：シークレットがフロントエンドのコードに含まれると公開情報になります。
* **時刻を正確に保ちます**：システムは 60 秒の時刻ずれを許容します。範囲外のタイムスタンプは拒否されます。
* **正しい対話プラットフォーム ID を使用します**：別のプラットフォーム ID で計算した署名は検証に失敗します。

## <mark style="color:blue;">四、動作一覧</mark> <a href="#behavior" id="behavior"></a>

| リクエスト                              | 結果                   |
| ---------------------------------- | -------------------- |
| Source ID ＋ 有効な署名                  | ログイン画面を表示せず、直接対話します  |
| Source ID があり、署名が不正または期限切れ         | 拒否されます               |
| 同じ署名を再利用                           | 1 回目は成功し、2 回目は拒否されます |
| Source ID がない（公開 URL を直接開いた場合を含む）  | ログインページへ転送されます       |
| 検証方式が「Source ID のみ」で Source ID がある | 署名を検証せず、直接対話します      |
| このスイッチが無効                          | 従来のログイン設定の動作を維持します   |

{% hint style="info" %}
すべての拒否ケースで外部へのレスポンスは同じです。失敗理由や Source ID の存在は開示されません。理由は管理画面の署名検証失敗ログにのみ表示されます。
{% endhint %}

## <mark style="color:blue;">五、署名検証失敗ログ</mark> <a href="#verification-failures" id="verification-failures"></a>

連携がうまくいかない場合は、設定欄の「<mark style="color:blue;">署名検証失敗ログを表示</mark>」をクリックすると、最近の失敗イベントを確認できます。ログにシークレットや完全な署名は含まれません。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-97836892fb059355c1a832478e76d6795a3a1719%2Fsourceid-05-verification-failures.png?alt=media" alt=""><figcaption><p>展開された署名検証失敗ログ</p></figcaption></figure>

| 理由                      | 主な原因                                    |
| ----------------------- | --------------------------------------- |
| 署名の期限切れ                 | サーバー時刻のずれ、または埋め込み側による署名のキャッシュ           |
| タイムスタンプが未来の許容範囲を超過      | サーバー時刻が 60 秒を超えて進んでいます                  |
| 署名が一致しない（シークレットが異なる可能性） | バックエンドのシークレットが管理画面と異なるか、署名文字列の組み立てが不正です |
| タイムスタンプまたは署名がない         | 埋め込み側が `ts` または `sig` を渡していません          |
| 署名が使用済み                 | 同じ署名が 2 回送信されました                        |
| リプレイ防止キャッシュを利用できない      | プラットフォームの一時的な問題により、安全のため許可せず拒否します       |
| Source ID が複数の連絡先に対応    | この対話プラットフォームに同じ Source ID の連絡先が重複しています  |

## <mark style="color:blue;">六、よくある質問</mark> <a href="#faq" id="faq"></a>

<details>

<summary>署名の有効期限が切れると、ユーザーの対話は中断されますか？</summary>

いいえ。有効期限は、署名で本人確認できる期間のみを制限します。本人確認後の対話の継続時間は既存の Web Chat の仕組みに従い、署名の期限には影響されません。

</details>

<details>

<summary>同じ Source ID が複数の連絡先に対応することはありますか？</summary>

同じ対話プラットフォーム内では、一つの Source ID は一人の連絡先にのみ対応します。複数の対話プラットフォームで同じ Source ID を使用した場合は、各プラットフォームに個別の連絡先が作成され、対話履歴も分離されます。

</details>

<details>

<summary>この設定を有効にすると、既存の埋め込みに影響しますか？</summary>

この設定はデフォルトで無効のため、既存の動作は変わりません。署名モードを有効にすると、`ts` と `sig` のないリクエストはログインページへ転送されます。埋め込み側が更新済みであることをエンジニアに確認してから有効にしてください。

</details>

<details>

<summary>ユーザーが自社の Web サイトからログアウトした後も、対話を続けられますか？</summary>

すでに本人確認済みのユーザーは、その対話を継続できます。発行側では、ログアウト後に新しい署名を発行しないことで、再度本人確認できないように制御できます。「ログアウト時に即時無効化」が必要な場合は、対応方法を検討しますのでお問い合わせください。

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/ja/conversations/web-chat/source-id-access.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.