2024/03/10 (更新日: 2024/03/11)

【Node.js】Keycloak Admin APIを操作するkeycloak-admin-clientを使ってみた

Node.js

こんにちは、Keycloak大好きエンジニアのやまだゆうです。

今回はKeycloak Admin REST APIを操作するNode.jsのライブラリkeycloak-admin-clientの使い方について解説します。

この記事の内容

1. Keycloak Admin REST APIとは？
2. keycloak-admin-clientとは
3. keycloak-admin-clientを使ってみる

Keycloak Admin REST APIとは？

Keycloakの管理コンソールで提供されるすべての機能をカバーしたAPIです。

このAPIを利用することで、自作のサーバーからKeycloak Admin REST APIにリクエストを送ってKeycloak上にレルムやユーザーなどを作成したり更新したりすることができます。

Keycloak comes with a fully functional Admin REST API with all features provided by the Admin Console.
To invoke the API you need to obtain an access token with the appropriate permissions. The required permissions are described in the Server Administration Guide.

Admin REST API – Server Developer Guide

このAPIを呼び出すためには適切な権限を持ったアクセストークンを取得する必要があります。のちほど紹介するサンプルコードで解説します。

Keycloak Admin REST APIで呼び出せるAPIは以下のドキュメントですべて公開されています。

Keycloak Admin REST API

keycloak-admin-clientとは？

Keycloak Admin REST APIを実行するためのNode.jsのライブラリです。

@keycloak/keycloak-admin-client – npm

axiosのようなHTTPクライアントライブラリを使ってKeycloak Admin REST APIのパスを直接書いて呼び出してもよいのですが、keycloak-admin-clientを使うことで以下のようなメリットが得られます。

• TypeScriptをサポートしている
• 最新バージョンのKeycloakに対応している
• リソース定義が網羅されている
• 十分にテストされたAPIを使用できる
• 直感的に何をリクエストしているかわかる＝可読性が向上する（以下のサンプルコードを読んでみてください）

const user = await kcAdminClient.users.create({
      username,
      email: "test@keycloak.org",
      enabled: true,
      attributes: {
        key: "value"
      },
    });

とても簡単な例ですが、「ユーザーを作るんだな」ということがわかりますよね。

keycloak-admin-clientを使ってみる

では実際にkeycloak-admin-clientを使ってみましょう。ちょっと項目が多いので、この章の中でも目次を入れます。

1. 前提
2. プロジェクト構成
3. keycloak-admin-clientをインストールする
4. 設定ファイルを定義する
5. レルムを作成するプログラムを実行
6. レルムとユーザーを作成するプログラムを実行

前提

• マシン：MacBook Air M2
• Node.jsバージョン：18.19.1
• Keycloakバージョン：22.0.3（Dockerで起動）

この記事で使用するKeycloakは以前の記事で紹介した、Dockerで起動したものを使用します。

Dockerで複数バージョンのKeycloakを開発する | yamaday0u Blog

プロジェクト構成

プロジェクトの構成は以下のようになっています。この記事で使用しているプログラムはぼくのGithubで公開しています。良かったらクローンして使ってみてください。

.
├── node_modules（中身は省略）
├── package-lock.json
├── package.json
└── src
    ├── connectionConfig.js
    ├── credentials.js
    └── index.js

keycloak-admin-clientをインストールする

keycloak-admin-clientをインストールしましょう。

npm install @keycloak/keycloak-admin-client

設定ファイルを定義する

baseUrlとreamlNameを設定するconnectionConfig.jsと、admin-cliを使うためのcredentials.jsを定義します。

export const config = {
  baseUrl: "http://localhost:4000/auth",
  realmName: "master"
};

デフォルトだと”http://127.0.0.1:8180″になっているので、自身が起動した環境に合わせて設定しましょう。

古いバージョンのKeycloakを使っていた影響で、パスにauthがついている方が個人的に安心するので今回起動したKeycloakのbaseUrlにはauthが入るようになっています。

export const credentials = {
  username: "admin",
  password: "password",
  grantType: "password",
  clientId: "admin-cli"
};

credentials.jsの設定により、先述の「適切な権限を持ったアクセストークンを取得する」ことができます。

レルムを作成するプログラムを実行

まずはレルムを作成する単純なプログラムを実行します。

import KcAdminClient from "@keycloak/keycloak-admin-client";
import { config } from "./connectionConfig.js";
import { credentials } from "./credentials.js";

const kcAdminClient = new KcAdminClient(config);
await kcAdminClient.auth(credentials); // ここでアクセストークンを取得している

const realm = await kcAdminClient.realms.create({
  realm: "demoRealm01",
  enabled: true
});
console.log(realm);

上記のプログラムのうちawait kcAdminClient.auth(credentials);の部分でadmin-cliを利用できるアクセストークンを取得しています。auth()の中の処理を見てみると、アクセストークンを取得していることがわかります。

では、このプログラムを実行します。

node src/index.js

# 実行結果
# { realmName: 'demoRealm01' }

Keycloakの管理コンソールを見ると、demoRealm01ができていることが確認できます。

注意：Node.jsのバージョンは18以上を使おう

Node.jsのバージョンが18未満の状態でプログラムを実行すると”ReferenceError: FormData is not defined”というエラーが出てしまいます。

keycloak-admin-clientが内部で呼び出している処理でformData型かチェックする箇所があります。

formDataはNode.js18からグローバルに定義されたものであるため、Node.jsのバージョン18以上でないとここでエラーします。

レルムとユーザーを作成するプログラムを実行

次にレルムとユーザーを作るプログラムを実行します。

import KcAdminClient from "@keycloak/keycloak-admin-client";
import { config } from "./connectionConfig.js";
import { credentials } from "./credentials.js";

const kcAdminClient = new KcAdminClient(config);
await kcAdminClient.auth(credentials);

const realm = await kcAdminClient.realms.create({
  realm: "demoRealm02",
  enabled: true
});
console.log(realm);

const user = await kcAdminClient.users.create({
  realm: realm.realmName, // demoRealm02レルムにユーザーを作るために一時的に上書きする
  username: "demoUser",
  enabled: true,
  attributes: {
    gender: "man"
  }
});
console.log(user);

上記のプログラムを実行します。

node src/index.js

# 実行結果
# { realmName: 'demoRealm02' }
# { id: '3d6d29d6-b299-45f6-96bd-86a8ca5174a8' }

yamaday0uを応援お願いします！あなたの１クリックが励みになります。
>> にほんブログ村

Keycloak Node.js プログラマー徹底基礎理解シリーズ

• facebook
• Tweet
• hatebu
• LINE
• Read Later