KeycloakのAPI機能調査 – テクノロジーが世界を未来へと導く

🔲 KeycloakのAPI機能調査

Keycloakのアプリケーションを開発する前にKeycloakにサポートされているAPIのエンドポイントについて、調査してみましょう。KeycloakのRest APIについては、公式ドキュメントを読み、理解することから始めることが必要です。ところが公式ドキュメントを見てみると文書量が多く、非常に難解なため理解することが困難です。

そこで、用意したのが、PostmanによるAPIコールです。必要最小限のエリア（OpenID Connect）に絞って調査することで、KeycloakのAPIを素早く理解することができます。

Postmanのget methodで下記のコマンドを実行してみてください。

http://localhost:8080/realms/demo/.well-known/openid-configuration

「openid-configuration」のエンドポイントは、パラメータ無しで実行できます。パラメータの「demo」はサーバの設定で定義したRealm名です。

リクエスト実行後、下記のJSONデータが返ってきます。

JOSNデータは以下の通りです。

    "issuer": "http://localhost:8080/realms/demo",
    "authorization_endpoint": "http://localhost:8080/realms/demo/protocol/openid-connect/auth",
    "token_endpoint": "http://localhost:8080/realms/demo/protocol/openid-connect/token",
    "introspection_endpoint": "http://localhost:8080/realms/demo/protocol/openid-connect/token/introspect",
    "userinfo_endpoint": "http://localhost:8080/realms/demo/protocol/openid-connect/userinfo",
    "end_session_endpoint": "http://localhost:8080/realms/demo/protocol/openid-connect/logout",
    "frontchannel_logout_session_supported": true,
    "frontchannel_logout_supported": true,
    "jwks_uri": "http://localhost:8080/realms/demo/protocol/openid-connect/certs",
    "check_session_iframe": "http://localhost:8080/realms/demo/protocol/openid-connect/login-status-iframe.html",
    "grant_types_supported": [..........以下省略......

Keycloakのopenid-configurationエンドポイントは、OpenID Connect Discovery 1.0仕様に基づいて、OpenID Providerの設定情報を提供します。このエンドポイントから得られる主な情報は以下の通りです。
- authorization_endpoint
  - クライアントアプリケーションがKeycloakと対話を開始する最初のステップであり、ユーザー認証とアクセス許可のプロセスを制御する重要な役割を果たします。
- token_endpoint
  - OAuth 2.0およびOpenID Connectプロトコルにおいて重要な役割を果たすエンドポイントです。クライアントアプリケーションが認可コードやリフレッシュトークンを使用して、新しいアクセストークンを取得するために使用します。
- introspection_endpoint
  - トークンベースの認証システムにおいて、トークンの有効性と内容を確認するための重要な機能を提供します。これにより、セキュリティを強化し、不正なアクセスを防ぐことができます。
- userinfo_endpoint
  - 認証されたユーザーに関する追加の情報（クレーム）を提供します。また、IDトークンに含まれていない詳細な情報を取得できます。
- end_session_endpoint
  - ユーザーのKeycloakセッションを終了し、関連するトークンを無効化します。
- jwks_uri
  - JWTの署名を検証するために必要な公開鍵を提供します。公開鍵はJSON Web Key Set (JWKS) フォーマットで提供されます。
- grant_types_supported: サポートされる認可タイプのリスト。
- response_types_supported: サポートされるレスポンスタイプのリスト。
- subject_types_supported: サポートされるサブジェクトタイプのリスト。
- id_token_signing_alg_values_supported: IDトークンの署名に使用可能なアルゴリズムのリスト。
- scopes_supported: サポートされるスコープのリスト。などの情報が取得できます。

上記APIの詳細な情報はOpenID Connect Coreの仕様書を参照してください。

上記のendpointから調査を開始することで、keycloakのAPI機能を効率よく理解することが可能になります。

コマンドの実行例として、JWTの署名検証に必要な公開鍵を取得してみましょう。get methodでパラメータ無しでリクエストできます。

http://localhost:8080/realms/demo/protocol/openid-connect/certs

下図の通り、Realm「demo」の公開鍵を取得することができました。

KeycloakのAPI仕様については、OpenID Connectを中心にnode-redを使って、順次認証と認可について、説明を加えていきたいと思います。

node-redによる「openid-configuration」のエンドポイント実行例です。

node-redによるget methodによる「certs」のリクエスト実行結果です。

※OpenID Connect Discoveryとは
OpenID Connect 1.0 は、OAuth 2.0 プロトコルの上にあるシンプルな ID レイヤーです。これにより、クライアントは、認可サーバーによって実行される認証に基づいてエンドユーザーの ID を検証できるほか、相互運用可能な REST のような方法でエンドユーザーに関する基本的なプロファイル情報を取得できます。
この仕様では、OpenID Connect の依存当事者がエンドユーザーの OpenID プロバイダーを検出し、OAuth 2.0 エンドポイントの場所など、プロバイダーとのやり取りに必要な情報を取得するためのメカニズムを定義しています。

※OpenID Connect Coreとは
OpenID Connect 1.0 は、OAuth 2.0 プロトコルの上にあるシンプルな ID レイヤーです。これにより、クライアントは、認可サーバーによって実行される認証に基づいてエンドユーザーの ID を検証できるほか、相互運用可能で REST のような方法でエンドユーザーに関する基本的なプロファイル情報を取得できます。
この仕様では、OAuth 2.0 上に構築された認証と、エンドユーザーに関する情報を通信するためのクレームの使用という、OpenID Connect のコア機能が定義されています。