> 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/maiagent-user-guide-ja/org/sso/sso-keycloak.md).
# Keycloak 連携
Keycloak は広く利用されているオープンソースの ID 認証およびアクセス管理プラットフォームです。MaiAgent は OpenID Connect プロトコルを通じた Keycloak との統合に対応しています。
**対象ユーザー**：Keycloak で統一的な ID 管理を行っている企業、または Realm 単位でユーザーを管理する必要がある組織
**主なメリット**：
* Keycloak Realm の分離に対応
* Email を持たないアカウント向けに、仮想 Email ID を自動生成
* サーバーサイドでの Token 失効（ログアウト）に対応
* Keycloak エコシステムの各種機能との統合
## 設定手順
### 1. Keycloak で Client を作成する
1. Keycloak Admin Console にログインします
2. 対象の Realm を選択します
3. Clients で Client を新規追加します
4. Client Protocol を `openid-connect` に設定します
5. Access Type を `public` に設定します（またはセキュリティ要件に応じて `confidential` を選択します）
6. Valid Redirect URIs を MaiAgent のフロントエンドドメインに設定します
7. Client ID を控えておきます
### 2. MaiAgent 管理画面で Keycloak 設定を入力する
Keycloak 認証設定：認証ソース名、Email Domain、サーバー URL を入力します
Keycloak 認証タイプを選択した後、以下の項目を入力する必要があります：
| 項目 | 必須 | 説明 |
| ------------ | -- | ------------------------------------------------------- |
| 認証ソース名 | はい | Realm 名との対応に使用します。Keycloak の Realm 名を使用することを推奨します |
| Email Domain | はい | 仮想 Email を生成するためのドメインです。例：`company.com` |
| Server URL | はい | Keycloak サーバーの URL です。例：`https://keycloak.company.com/` |
入力が完了すると、システムが自動的に **Login URL** を生成します。形式は以下のとおりです：
```
https://{フロントエンドドメイン}/auth/keycloak?url={Server URL}&clientId={Client ID}&realm={Realm}
```
### 3. 保存してテストする
MaiAgent 管理画面で 保存 をクリックし、生成された Login URL を使用してログインフローをテストします。
## Keycloak の仮想 Email の仕組み
Keycloak のユーザーは必ずしも Email アドレスを持っているとは限らないため、MaiAgent は一意の識別子として仮想 Email を自動的に生成します：
```
仮想 Email = {preferred_username}@{email_domain}
```
例：Email Domain が `company.com` に設定されている場合、ユーザー `john.doe` には MaiAgent のユーザー Email として `john.doe@company.com` が生成されます。
{% hint style="info" %}
この仮想 Email はシステム内部での識別のみを目的としており、実際の Email 送信には使用されません。
{% endhint %}
## Keycloak のログアウト
MaiAgent の Keycloak 統合はサーバーサイドでのログアウトに対応しています。ユーザーが MaiAgent からログアウトすると、システムは同時に Keycloak サーバーへ Token 失効リクエストを送信し、Token が Keycloak 側でも無効になることを保証します。
## 設定項目クイックリファレンス
| 項目 | 必須 | 形式 | 例 |
| ------------ | -- | ---------------------- | ------------------------------- |
| 認証ソース名 | はい | 小文字英数字 + ハイフン、最大 31 文字 | `company-kc` |
| Email Domain | はい | ドメイン形式 | `company.com` |
| Server URL | はい | HTTPS URL | `https://keycloak.company.com/` |
---
# 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/maiagent-user-guide-ja/org/sso/sso-keycloak.md?ask=&goal=
```
`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.