> 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/org/sso/sso-keycloak.md).

# Keycloak 連携

OpenID Connect プロトコルを通じて、オープンソースの認証基盤 Keycloak と連携します

Keycloak は広く利用されているオープンソースの認証・アクセス管理基盤です。MaiAgent は OpenID Connect プロトコルによる Keycloak との連携に対応しています。

**対象ユーザー**：Keycloak で統合的な ID 管理を行っている企業、または Realm 単位でユーザーを管理する必要がある組織

**主なメリット**：

* Keycloak の Realm による分離に対応します
* Email を持たないアカウント向けに、仮想 Email の識別情報を自動的に合成します
* サーバー側での Token 失効（Logout）に対応します
* Keycloak エコシステムの各種機能と連携できます

## 設定手順 <a href="#setup-steps" id="setup-steps"></a>

### 1. Keycloak で Client を作成する <a href="#step-1-create-client" id="step-1-create-client"></a>

1. Keycloak Admin Console にログインします
2. 対象の Realm を選択します
3. <mark style="color:blue;">Clients</mark> で新しい Client を追加します
4. Client Protocol を `openid-connect` に設定します
5. Access Type を `public` に設定します（セキュリティ要件に応じて `confidential` を選択することもできます）
6. Valid Redirect URIs を MaiAgent のフロントエンドドメインに設定します
7. Client ID を控えておきます

### 2. MaiAgent 管理画面で Keycloak の設定を入力する <a href="#step-2-fill-keycloak-settings" id="step-2-fill-keycloak-settings"></a>

認証タイプとして <mark style="color:blue;">Keycloak</mark> を選択した後、次の項目を入力します。

| 項目                                         | 必須 | 説明                                                                                 |
| ------------------------------------------ | -- | ---------------------------------------------------------------------------------- |
| <mark style="color:blue;">認証ソース名</mark>    | はい | この認証ソースを識別する英字の名前です。ログインリンクの一部になります。例：`company-kc`                                 |
| <mark style="color:blue;">仮想メールドメイン</mark> | はい | 仮想 Email を合成するためのドメインです。システムは「アカウント名@このドメイン」の形式でユーザーのメールアドレスを生成します。例：`company.com` |
| <mark style="color:blue;">サーバー URL</mark>  | はい | Keycloak サーバーの URL です。例：`https://keycloak.company.com/`                            |
| <mark style="color:blue;">Realm 名</mark>   | はい | 貴組織が Keycloak で使用している Realm の名前です。ログインリンクの `realm` パラメータに組み込まれます                   |
| <mark style="color:blue;">Client ID</mark> | はい | 手順 1 でその Realm に作成した OIDC Client の Client ID です。ログインリンクの `clientId` パラメータに組み込まれます  |

入力が完了すると、システムが次の形式で **Login URL** を自動生成します。

```
https://{フロントエンドドメイン}/auth/keycloak?url={Server URL}&clientId={Client ID}&realm={Realm}
```

### 3. 保存してテストする <a href="#step-3-save-and-test" id="step-3-save-and-test"></a>

MaiAgent 管理画面で <mark style="color:blue;">保存</mark> をクリックし、生成された Login URL を使ってログインフローをテストします。

## Keycloak の仮想 Email の仕組み <a href="#keycloak-virtual-email-mechanism" id="keycloak-virtual-email-mechanism"></a>

Keycloak のユーザーは必ずしも Email アドレスを持っているとは限らないため、MaiAgent は一意の識別子として仮想 Email を自動的に合成します。

```
仮想 Email = {preferred_username}@{email_domain}
```

たとえば、仮想メールドメインが `company.com` の設定でユーザー `john.doe` がログインすると、MaiAgent のユーザー Email として `john.doe@company.com` が生成されます。

{% hint style="info" %}
この仮想 Email はシステム内部の識別用途にのみ使用され、実際のメール送信には使用されません。
{% endhint %}

## ログイン失敗時のメッセージ <a href="#error-messages" id="error-messages"></a>

ユーザーが Keycloak のログインリンクを開くと、画面にはまず「Keycloak ログイン中...」と表示されます。失敗した場合は、下に赤字で原因が表示されます。

| 画面のメッセージ                                                              | よくある原因                                                                                               | 対処方法                                                                                                      |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| 缺少必要的參數 (url, clientId, realm)（必須パラメータ (url, clientId, realm) がありません） | 開いた URL に Keycloak サーバー、Client ID、Realm のいずれかのパラメータがありません。多くの場合、リンクが途中で切れているか、手動で書き換えられています          | 設定ページのログインリンクカードからコピーした完全な URL を使用してください                                                                  |
| 認證過程發生錯誤，請重試（…）（認証処理中にエラーが発生しました。もう一度お試しください（…））                      | ブラウザーから Keycloak サーバーに接続できないか、Client の設定（Valid redirect URIs、Web origins）で MaiAgent の URL が許可されていません | ユーザーのネットワークから Keycloak に到達できることを確認し、Client の redirect URI と Web origins の設定を確認してください                      |
| API 登入失敗（API ログインに失敗しました）                                             | Keycloak での認証は成功しましたが、MaiAgent がログイン結果を返しませんでした                                                      | 管理画面でこの認証ソースのログインが有効になっていることを確認してから、もう一度お試しください                                                           |
| API 登入過程發生錯誤（…）（API ログイン処理中にエラーが発生しました（…））                            | MaiAgent が Keycloak の Token を検証する際にエラーが発生しました。括弧内はサーバーが返した原因です                                       | 括弧内のメッセージに従って対処してください。よくある原因は、リンク内のサーバー URL、Realm 名、Client ID が管理画面の設定と一致していないこと、または認証ソースがこの組織に属していないことです |

## Keycloak のログアウト <a href="#keycloak-logout" id="keycloak-logout"></a>

MaiAgent の Keycloak 連携は、サーバー側でのログアウトに対応しています。ユーザーが MaiAgent からログアウトすると、システムは Keycloak サーバーにも Token の失効リクエストを送信し、Keycloak 側でも Token が無効になることを保証します。

## 設定項目クイックリファレンス <a href="#settings-quick-reference" id="settings-quick-reference"></a>

| 項目        | 必須 | 形式                               | 例                               |
| --------- | -- | -------------------------------- | ------------------------------- |
| 認証ソース名    | はい | 小文字英数字 + ハイフン、最大 31 文字           | `company-kc`                    |
| 仮想メールドメイン | はい | ドメイン形式                           | `company.com`                   |
| サーバー URL  | はい | HTTPS URL                        | `https://keycloak.company.com/` |
| Realm 名   | はい | Keycloak の Realm 名               | `company-sso`                   |
| Client ID | はい | Keycloak OIDC Client の Client ID | `maiagent-portal`               |


---

# 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/org/sso/sso-keycloak.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.