KeycloakのClientとは？Webアプリ連携で必ず理解したい基本

この記事の最終更新日: 2026年5月30日

Keycloakを使ってWebアプリにログイン機能を追加しようとすると、必ず出てくるのが Client です。

Keycloakの管理画面でRealmを作ったあと、多くの場合はClientを作成します。

しかし初心者のうちは、

Clientって何？
Realmとは何が違うの？
ReactやLaravelのアプリはClientなの？
APIサーバーもClientなの？
Valid Redirect URIsって何を設定すればいいの？
Public clientとConfidential clientはどう違うの？

と混乱しやすいです。

Keycloak公式ドキュメントでは、Clientは「Keycloakにユーザー認証を要求できるエンティティ」であり、多くの場合はKeycloakで保護したいアプリケーションやサービスを指すと説明されています。つまり、Keycloakと連携するWebアプリ、SPA、API、モバイルアプリなどがClientになります。(Keycloak)

この記事では、KeycloakのClientとは何か、Webアプリ連携でどの設定を理解すべきかを、初心者向けにわかりやすく解説します。

KeycloakのClientとは？
RealmとClientの違い
Clientは「ログインする人」ではない
Webアプリ連携でClientが必要な理由
Clientを使ったログインの流れ
Client IDとは？
Root URLとは？
Valid Redirect URIsとは？
Valid Redirect URIsでワイルドカードを雑に使わない
Web Originsとは？
Public Clientとは？
Confidential Clientとは？
Client Secretとは？
Standard Flowとは？
Direct Access Grantsとは？
Service Accountsとは？
Client Scopeとは？
Webアプリ連携の基本構成
1. サーバーサイドWebアプリ
2. SPA + API
3. BFF構成
Client設定で初心者が見るべき項目
ローカル開発でのClient設定例
LaravelなどのサーバーサイドWebアプリでの設定例
APIサーバーはClientなのか？
Client Roleとは？
Client設定でよくあるエラー
1. invalid redirect_uri
2. CORSエラー
3. Client Secretが間違っている
4. Public ClientなのにSecretを使おうとしている
5. Roleがトークンに入っていない
Client設定のおすすめ設計
Client IDの命名例
Webアプリ連携で最初に作るべきClient構成
実務ではClient設定をコード管理したくなる
Clientを理解するとKeycloak連携が一気にわかりやすくなる
まとめ

KeycloakのClientとは？

Client とは、Keycloakを使って認証・認可を行うアプリケーションやサービスのことです。

たとえば、次のようなものがClientになります。

Reactのフロントエンドアプリ
Vue.jsのSPA
LaravelのWebアプリ
RailsのWebアプリ
Spring BootのWebアプリ
FastAPIのAPIサーバー
管理画面
スマホアプリ

Keycloak側にClientを登録することで、「このアプリはKeycloakを使ってログインします」と設定できます。

イメージとしては、次のような関係です。

Keycloak
└── Realm
    ├── Client: frontend-app
    ├── Client: admin-app
    └── Client: backend-api

Realmが「認証管理の箱」だとすると、Clientはその箱の中に登録される「アプリケーション」です。

RealmとClientの違い

Keycloak初心者が最初につまずくのが、RealmとClientの違いです。

簡単に整理すると、こうです。

Realm：
ユーザー、Client、Role、Groupなどを管理する認証管理の箱

Client：
Keycloakを使ってログイン・認可したいアプリケーション

たとえば、社内システム用のRealmを1つ作り、その中に複数のClientを作ることがあります。

internal Realm
├── attendance-app
├── expense-app
├── admin-console
└── backend-api

この場合、internal がRealmです。

attendance-app や expense-app がClientです。

同じRealm内に複数のClientを作ることで、同じユーザー基盤を使って複数アプリをログイン連携できます。

Clientは「ログインする人」ではない

Clientという名前から、初心者は「ユーザーのこと？」と勘違いすることがあります。

しかし、KeycloakのClientはユーザーではありません。

User：
ログインする人

Client：
Keycloakを使うアプリケーション

たとえば、田中さんがReactアプリにログインする場合を考えます。

User: tanaka@example.com
Client: react-web-app
Realm: myapp

田中さんはUserです。

ReactアプリはClientです。

Keycloakは、ClientであるReactアプリからの認証要求を受けて、Userである田中さんをログインさせます。

Webアプリ連携でClientが必要な理由

WebアプリがKeycloakを使うには、Keycloak側にそのアプリを登録する必要があります。

なぜなら、Keycloakは次のようなことを確認する必要があるからです。

どのアプリからログイン要求が来たのか
ログイン後にどのURLへ戻してよいのか
このアプリにトークンを発行してよいのか
このアプリはClient Secretを持てるのか
どの認証フローを許可するのか
どのスコープやロールを渡すのか

たとえば、ログイン後の戻り先URLを自由にしてしまうと、悪意あるURLへリダイレクトされる危険があります。

そのため、KeycloakではClientごとにValid Redirect URIsなどを設定し、「このアプリにはこのURLだけ許可する」と制御します。

Red HatのKeycloak系ドキュメントでも、Valid Redirect URIsは必須項目として説明されており、ワイルドカードはURIの末尾でのみ許可されるという注意も記載されています。(Red Hat Documentation)

Clientを使ったログインの流れ

WebアプリとKeycloakの基本的なログインの流れは、次のようになります。

ユーザーがWebアプリにアクセスする
↓
WebアプリがKeycloakのログイン画面へリダイレクトする
↓
ユーザーがKeycloakでログインする
↓
KeycloakがWebアプリへリダイレクトする
↓
Webアプリがトークンを受け取る
↓
Webアプリはログイン済みとして扱う

このとき、Keycloakは「どのClientに対するログインなのか」を見ています。

つまり、WebアプリがKeycloakにログインを依頼するとき、Client IDやRedirect URIなどの情報を使います。

KeycloakはOpenID Connect Providerとして、アプリケーションやサービスがユーザーを認証・認可するためのエンドポイントを提供しています。(Keycloak)

Client IDとは？

Client ID は、Keycloak上でClientを識別するための名前です。

たとえば、次のようなClient IDを設定します。

frontend-app
admin-app
backend-api
myapp-web

アプリ側の設定でも、このClient IDを指定します。

たとえば、ReactアプリでKeycloak連携する場合、設定ファイルに次のような値を書くことがあります。

const keycloakConfig = {
  url: 'https://auth.example.com',
  realm: 'myapp',
  clientId: 'frontend-app',
};

この clientId が、Keycloak側で作成したClient IDと一致している必要があります。

Client IDが間違っていると、アプリはKeycloakと正しく連携できません。

Root URLとは？

Root URL は、そのClientの基本URLを表す設定です。

たとえば、Webアプリが次のURLで動いているとします。


https://app.example.com
app.example.com

この場合、Root URLにこのURLを設定することがあります。

Root URLを設定しておくと、Keycloak内の他のURL設定で相対パスを使いやすくなる場合があります。

ただし、初心者が最初に重要視すべきなのはRoot URLよりも、次に説明する Valid Redirect URIs です。

Valid Redirect URIsとは？

Valid Redirect URIs は、ログイン後にKeycloakがリダイレクトしてよいURLの一覧です。

これは非常に重要です。

たとえば、Reactアプリが次のURLで動いているとします。


http://localhost:5173
localhost

開発環境では、Valid Redirect URIsに次のように設定することがあります。


http://localhost:5173/*
localhost

本番環境なら、たとえば次のように設定します。


https://app.example.com/*
app.example.com

ログイン後、Keycloakはこの設定に合うURLにだけリダイレクトします。

もしアプリ側が指定したRedirect URIがValid Redirect URIsに一致しない場合、invalid redirect_uri のようなエラーになります。

初心者がKeycloak連携でかなり高確率でハマるのが、このRedirect URIの設定ミスです。

Valid Redirect URIsでワイルドカードを雑に使わない

開発中は、つい次のように設定したくなることがあります。

しかし、本番環境でこのように雑な設定をするのは危険です。

Redirect URIを広く許可しすぎると、オープンリダイレクトのようなセキュリティリスクにつながる可能性があります。

古いKeycloak関連ドキュメントでも、Redirect URIはできるだけ具体的にすべきであり、特にPublic clientでは注意が必要だと説明されています。(wjw465150.gitbooks.io)

実務では、次のように環境ごとに具体的なURLを設定する方が安全です。

開発環境：

http://localhost:5173/*
localhost

検証環境：

https://stg.example.com/*
stg.example.com

本番環境：

https://app.example.com/*
app.example.com

開発中だけ広めに許可し、本番ではできるだけ絞るのが基本です。

Web Originsとは？

Web Origins は、ブラウザからKeycloakへアクセスする際のCORSに関係する設定です。

SPAやフロントエンドアプリでは、Keycloakに対してブラウザから直接通信することがあります。

その場合、Web Originsが適切に設定されていないとCORSエラーになることがあります。

たとえば、Reactアプリが次のURLで動いている場合です。


http://localhost:5173
localhost

Web Originsには次のように設定します。


http://localhost:5173
localhost

または、Keycloakの設定によっては + を使ってRedirect URIから推測させる運用もあります。

ただし、初心者は最初のうちは明示的に設定して、挙動を理解するのがおすすめです。

Public Clientとは？

KeycloakのClient設定では、Client authenticationを無効にしたClientを使うことがあります。

これが、いわゆる Public Client です。

Public Clientは、Client Secretを安全に保持できないアプリケーションで使います。

代表例は次の通りです。

ReactのSPA
Vue.jsのSPA
ブラウザ上で動くフロントエンドアプリ
モバイルアプリ

ブラウザ上で動くJavaScriptアプリにClient Secretを埋め込んでも、ユーザーから見えてしまいます。

そのため、SPAではClient Secretを使わないPublic Clientとして設定するのが一般的です。

Confidential Clientとは？

Confidential Client は、Client Secretを安全に保持できるアプリケーション向けのClientです。

代表例は次の通りです。

LaravelのサーバーサイドWebアプリ
RailsのWebアプリ
Spring BootのWebアプリ
バックエンドサーバー
BFF

サーバーサイドで動くアプリケーションなら、Client Secretをサーバー環境変数などで安全に保持できます。

そのため、Confidential Clientとして設定できます。

簡単に整理すると、こうです。

Public Client：
Client Secretを安全に持てないアプリ向け

Confidential Client：
Client Secretを安全に持てるサーバーサイドアプリ向け

初心者は、ReactやVueなどのフロントエンドSPAならPublic、LaravelやSpring BootなどのサーバーサイドWebアプリならConfidentialと考えると理解しやすいです。

Client Secretとは？

Client Secret は、Clientを認証するための秘密情報です。

Confidential Clientでは、アプリがKeycloakと通信するときにClient Secretを使います。

イメージとしては、Keycloakとアプリの間の合言葉に近いです。

Client ID：
アプリの名前

Client Secret：
そのアプリ本人であることを示す秘密情報

ただし、Client Secretは外部に漏らしてはいけません。

GitHubにコミットしたり、フロントエンドのJavaScriptに埋め込んだりしてはいけません。

サーバーサイドアプリで使う場合は、環境変数やシークレット管理サービスで安全に扱う必要があります。

Standard Flowとは？

KeycloakのClient設定では、認証フローを選ぶ項目があります。

Webアプリ連携でよく使うのが Standard Flow です。

これは、OpenID ConnectのAuthorization Code Flowに相当するものです。

ざっくりした流れはこうです。

アプリがKeycloakへリダイレクトする
↓
ユーザーがログインする
↓
Keycloakが認可コードをアプリへ返す
↓
アプリが認可コードを使ってトークンを取得する

WebアプリやSPAでは、このStandard Flowを理解することが重要です。

現在のSPAでは、Authorization Code Flow + PKCEを使う構成が一般的です。

Direct Access Grantsとは？

Direct Access Grants は、ユーザー名とパスワードを直接アプリ側で受け取り、Keycloakへ送ってトークンを取得するようなフローです。

初心者は便利そうに見えるかもしれません。

しかし、Webアプリの通常ログインでは、基本的にはKeycloakのログイン画面へリダイレクトする方式を使う方が自然です。

なぜなら、アプリ側でユーザーのパスワードを直接扱うと、セキュリティ責任が重くなるからです。

推奨しやすい流れ：
アプリ → Keycloakログイン画面 → アプリへ戻る

避けたい流れ：
アプリが直接ユーザーのパスワードを受け取る

Direct Access Grantsは使いどころを選ぶ設定です。

初心者は、まずStandard Flowを理解するのがおすすめです。

Service Accountsとは？

Service Accounts は、ユーザーではなくシステム同士の通信で使う仕組みです。

たとえば、バックエンドバッチやサーバー間API通信などで使います。

バッチサーバー
↓
Keycloakでトークン取得
↓
APIサーバーを呼び出す

この場合、ログインする人間のユーザーはいません。

システム自身がClientとしてトークンを取得します。

人間のログインとは別の用途なので、Webアプリの通常ログインとは分けて考えましょう。

Client Scopeとは？

Client Scope は、Clientが要求できる情報やトークンに含める情報を管理するための仕組みです。

たとえば、OpenID Connectでは次のようなScopeが出てきます。

openid
profile
email
roles

Scopeによって、ID TokenやAccess Tokenにどの情報を含めるかが変わります。

初心者がよくハマるのは、「Roleを作ったのにトークンに入っていない」というケースです。

その場合、Client ScopeやMapperの設定を確認する必要があります。

最初は難しく感じますが、Client Scopeは「トークンに何を含めるかを調整する設定」と考えると理解しやすいです。

Webアプリ連携の基本構成

WebアプリとKeycloakを連携する場合、よくある構成は次の3つです。

1. サーバーサイドWebアプリ

Laravel、Rails、Spring BootなどのサーバーサイドWebアプリです。

ブラウザ
↓
Laravel / Rails / Spring Boot
↓
Keycloak

この場合、アプリサーバーがKeycloakと通信します。

Client Secretをサーバー側で安全に持てるため、Confidential Clientにしやすいです。

2. SPA + API

ReactやVueのSPAと、バックエンドAPIを分ける構成です。

ブラウザ
↓
React / Vue
↓ Access Token
APIサーバー
↓
Keycloakでトークン検証

この場合、フロントエンドアプリはPublic Clientとして扱うことが多いです。

APIサーバーは、Access Tokenを検証して、ユーザーがアクセスしてよいか判断します。

3. BFF構成

BFF、つまりBackend for Frontendを使う構成です。

ブラウザ
↓
BFF
↓
Keycloak
↓
APIサーバー

この構成では、ブラウザ側にトークンを直接持たせない設計にしやすくなります。

セキュリティ設計としては有力ですが、実装は少し複雑になります。

初心者はまず、サーバーサイドWebアプリかSPA + APIの基本構成を理解するとよいです。

Client設定で初心者が見るべき項目

KeycloakのClient設定には多くの項目があります。

初心者が最初に見るべきなのは、次の項目です。

Client ID
Client authentication
Valid Redirect URIs
Web Origins
Standard Flow
Direct Access Grants
Service Accounts
Client Scopes
Roles

すべてを一度に理解する必要はありません。

まずは、Webアプリがログインして戻ってくるために必要な項目から理解しましょう。

特に重要なのは次の3つです。

Client ID
Valid Redirect URIs
Client authentication

この3つを間違えると、ログイン連携が動かないことが多いです。

ローカル開発でのClient設定例

たとえば、Reactアプリをローカルで動かす場合を考えます。

Reactアプリ：

http://localhost:5173
localhost

Keycloak Realm：
myapp

Client ID：
frontend-app

この場合、Client設定はざっくり次のようになります。

Client ID:
frontend-app

Client authentication:
Off

Valid Redirect URIs:

http://localhost:5173/*
localhost

Web Origins:

http://localhost:5173
localhost

ReactやVueのようなSPAでは、Client authenticationはOff、つまりPublic Clientにすることが多いです。

LaravelなどのサーバーサイドWebアプリでの設定例

LaravelアプリをKeycloakと連携する場合を考えます。

Laravelアプリ：

https://app.example.com
app.example.com

Realm：
myapp

Client ID：
laravel-app

この場合は、サーバー側でClient Secretを持てるため、Confidential Clientにすることがあります。

Client ID:
laravel-app

Client authentication:
On

Valid Redirect URIs:

https://app.example.com/*
app.example.com

Web Origins:

https://app.example.com
app.example.com

Client authenticationをOnにすると、Client Secretが発行されます。

Laravel側では、そのClient Secretを .env などに設定します。

KEYCLOAK_CLIENT_ID=laravel-app
KEYCLOAK_CLIENT_SECRET=xxxxxxxx
KEYCLOAK_REALM=myapp
KEYCLOAK_BASE_URL=https://auth.example.com

Client SecretはGit管理しないように注意しましょう。

APIサーバーはClientなのか？

APIサーバーも、Keycloak上でClientとして登録することがあります。

ただし、APIサーバーの役割はフロントエンドとは少し違います。

フロントエンドアプリは、ユーザーをログインさせるためにKeycloakを使います。

一方、APIサーバーは、受け取ったAccess Tokenを検証して、アクセスを許可するか判断します。

フロントエンド：
ログインしてトークンを取得する

APIサーバー：
トークンを検証して保護する

APIサーバーをClientとして登録する場合、API向けのRoleやScopeを管理しやすくなります。

たとえば、次のようなClient Roleを作れます。

backend-api:view
backend-api:write
backend-api:admin

これにより、APIごとの権限をKeycloak側で管理しやすくなります。

Client Roleとは？

Keycloakには、Realm RoleとClient Roleがあります。

Client Roleは、特定のClientに紐づくRoleです。

たとえば、backend-api Clientに次のRoleを作ることがあります。

viewer
editor
admin

この場合、backend-api に対する権限としてRoleを管理できます。

Client: backend-api
├── Role: viewer
├── Role: editor
└── Role: admin

一方で、Realm全体で使うRoleはRealm Roleにします。

Realm Role:
admin
user
staff

初心者は、まず次のように考えるとよいです。

Realm Role：
システム全体で使う役割

Client Role：
特定アプリ・API向けの役割

Client設定でよくあるエラー

1. invalid redirect_uri

最もよくあるのがこれです。

invalid redirect_uri

原因は、アプリが指定したRedirect URIが、KeycloakのValid Redirect URIsに一致していないことです。

確認するポイントは次の通りです。

httpとhttpsが一致しているか
localhostのポート番号が一致しているか
パスが一致しているか
末尾のスラッシュが違っていないか
Valid Redirect URIsに対象URLが含まれているか

たとえば、アプリが http://localhost:5173/callback に戻ろうとしているのに、Keycloak側が http://localhost:3000/* になっていたら失敗します。

2. CORSエラー

SPAでよくあるのがCORSエラーです。

この場合は、Web Originsを確認します。

ReactアプリのURL：

http://localhost:5173
localhost

Web Origins：

http://localhost:5173
localhost

開発環境と本番環境でURLが違う場合、それぞれ正しく設定する必要があります。

3. Client Secretが間違っている

Confidential Clientの場合、Client Secretが間違っているとトークン取得に失敗します。

確認ポイントは次の通りです。

Client authenticationがOnになっているか
アプリ側のClient Secretが正しいか
古いSecretを使っていないか
環境変数に反映されているか

Client Secretを再生成した場合は、アプリ側の環境変数も更新する必要があります。

4. Public ClientなのにSecretを使おうとしている

SPAなどのPublic Clientでは、Client Secretを使いません。

しかし、ライブラリ設定やサンプルコードをそのまま使って、Secretを要求する構成にしてしまうことがあります。

ReactやVueのようなブラウザアプリでは、Secretを埋め込まない設計にしましょう。

5. Roleがトークンに入っていない

KeycloakでRoleを設定したのに、アプリ側でRoleが見えないことがあります。

この場合、次を確認します。

ユーザーにRoleが割り当てられているか
Group経由でRoleが付いているか
Client Scopeの設定は正しいか
MapperでRoleがトークンに含まれる設定になっているか
Access Tokenの中身を確認したか

Roleを作っただけでは、アプリが期待する形で必ずトークンに入るとは限りません。

トークンの中身をデコードして確認することが重要です。

Client設定のおすすめ設計

初心者向けに、Client設計の基本方針をまとめると次の通りです。

フロントエンドSPAはPublic Clientにする
サーバーサイドWebアプリはConfidential Clientにする
APIサーバーは別ClientとしてRole管理を検討する
Redirect URIはできるだけ具体的にする
本番環境でワイルドカードを広く使いすぎない
Client IDはアプリ名・用途がわかる名前にする
開発・検証・本番でURLを混同しない
Client Secretは絶対にフロントエンドに置かない

特に重要なのは、アプリの種類によってClient設定を変えることです。

React / Vue：
Public Client

Laravel / Rails / Spring Boot：
Confidential Client

API：
Token検証・Role管理用Clientとして設計

Client IDの命名例

Client IDは、あとから見て用途がわかる名前にしましょう。

悪い例です。

test
app
client1
sample
new-client

よい例です。

myapp-frontend
myapp-admin
myapp-api
medical-records-web
medical-records-api

開発・検証・本番でRealmを分けているなら、Client ID自体には環境名を入れない運用もあります。

dev Realm:
  Client: web

stg Realm:
  Client: web

prod Realm:
  Client: web

一方、同じRealm内で環境違いのClientを持つなら、環境名を入れることもあります。

web-dev
web-stg
web-prod

どちらにせよ、チームで命名ルールを決めておくことが大切です。

Webアプリ連携で最初に作るべきClient構成

初心者が学習するなら、まずは次のような構成で十分です。

Realm:
demo

Client:
demo-web

User:
test-user

Role:
user

ローカル開発なら、Client設定は次のようにします。

Client ID:
demo-web

Client authentication:
Off

Valid Redirect URIs:

http://localhost:3000/*
localhost

http://localhost:5173/*
localhost

Web Origins:

http://localhost:3000
localhost

http://localhost:5173
localhost

この構成で、まずはログインできることを確認します。

その後、Roleを追加したり、API連携したり、Client Scopeを調整したりすると理解しやすいです。

実務ではClient設定をコード管理したくなる

KeycloakのClient設定は、管理画面から手で設定できます。

しかし、実務では次のような課題が出てきます。

開発環境と本番環境で設定差分が出る
誰がどの設定を変えたかわからない
再構築時に同じ設定を再現しにくい
Clientが増えると手管理がつらい

そのため、本格運用ではRealmやClient設定をエクスポートしたり、設定管理ツールでコード化したりすることを検討します。

最初は管理画面で理解し、慣れてきたら設定のIaC化を考えるとよいです。

Clientを理解するとKeycloak連携が一気にわかりやすくなる

KeycloakのClientを理解すると、Webアプリ連携の全体像が見えやすくなります。

Realm：
認証管理の箱

Client：
Keycloakを使うアプリ

User：
ログインする人

Role：
ユーザーに与える権限

Token：
ログイン後に発行される情報

Keycloak連携でログインできない場合、原因はClient設定にあることが多いです。

特に確認すべきなのは次の項目です。

Client ID
Valid Redirect URIs
Web Origins
Client authentication
Client Secret
Standard Flow
Client Scopes
Role設定

このあたりを理解できると、Keycloakのデバッグがかなり楽になります。

まとめ

KeycloakのClientとは、Keycloakを使って認証・認可したいアプリケーションやサービスのことです。

公式ドキュメントでも、ClientはKeycloakにユーザー認証を要求できるエンティティであり、多くの場合はKeycloakで保護したいアプリケーションやサービスだと説明されています。(Keycloak)

初心者が押さえるべきポイントは次の通りです。

Realm：
認証管理の箱

Client：
Keycloakを使うアプリケーション

Client ID：
Clientを識別する名前

Valid Redirect URIs：
ログイン後に戻ってよいURL

Web Origins：
ブラウザからのアクセス元

Public Client：
Secretを安全に持てないアプリ向け

Confidential Client：
Secretを安全に持てるサーバーサイドアプリ向け

KeycloakでWebアプリ連携をするなら、Clientの理解は必須です。

特に、Valid Redirect URIs、Web Origins、Client authentication、Client Secretの設定は、ログイン可否に直結します。

まずはローカル環境でシンプルなClientを作り、ログインできるところまで試してみるのがおすすめです。