> 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/serve/choose-channel/web-chat/source-id-access.md).

# 連絡先の Source ID を使ったログイン不要のチャット

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

Web Chat を自社サイトに埋め込む場合、ユーザーはすでにサイトにログインしていることがよくあります。この設定により、自社システムのユーザー識別子を使って、再度ログイン画面を経由せずに会話を開始できます。同時に、公開の会話 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 自体がアクセス許可証になります。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> 」セクションには、この会話プラットフォームの識別子が反映されるため、そのままコピーして使用できます。パラメーターの詳細、検証ルール、トラブルシューティングについては、エンジニアに [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(シークレット, "{会話プラットフォーム識別子}.{Source ID}.{タイムスタンプ}")` を計算し、hex 文字列で渡します。タイムスタンプは 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 秒です。この範囲を超えるタイムスタンプは拒否されます。
* **正しい会話プラットフォーム識別子を使用してください**：署名には会話プラットフォーム識別子が含まれます。別の会話プラットフォームの識別子で計算した署名は検証に失敗します。

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

| 受信したリクエスト                         | 結果                     |
| --------------------------------- | ---------------------- |
| Source ID ＋ 有効な署名あり               | ログイン画面を表示せず、直接会話を開始します |
| Source ID あり、署名が不正または期限切れ         | 拒否します                  |
| 同じ署名を再利用                          | 初回は成功し、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>ユーザーが自社サイトからログアウトした後も、会話を続けられますか？</summary>

すでに認証済みのユーザーは、その会話を続けられます。制御できるのは署名の発行側です。ログアウト後に新しい署名を発行しなければ、ユーザーは再度認証できません。「ログアウト時に即座に無効化する」必要がある場合は、お問い合わせください。対応方法を別途検討します。

</details>

<details>

<summary>Source ID でアクセスしたユーザーのログイン認証情報は、AI がツールを呼び出す際に渡されますか？</summary>

いいえ。「[Keycloak のログイン ID を使用してツールを呼び出す](/maiagent-user-guide/ja/serve/choose-channel/web-chat.md#keycloak-token-passthrough)」は、実際に Keycloak でログインした訪問者にのみ適用されます。ID は会話の作成時に紐付けられた組織メンバーに基づき、埋め込み側から渡された Source ID は使用しません。そのため、Source ID を使って他人の認証情報を偽装することはできません。ツールでユーザーを識別する必要がある場合は、Keycloak ログインとこの機能を組み合わせるか、連絡先に [MCP 認証情報](/maiagent-user-guide/ja/build/tools/setup-contacts-mcp-credentials.md) を設定してください。

</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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.