CLOVER🍀

That was when it all began.

KeycloakのAdmin CLIを使う

これは、なにをしたくて書いたもの?

Keycloakを使う時はWeb UIから操作しているのですが、管理のCLI(Admin CLI)があるようなので、こちらでの操作を
覚えてみようかな、と思いまして。

Server Administration Guide / The Admin CLI

こちらを使うことで、RealmやClient、User、RoleといったところをCLIで操作できるようになります。

環境

今回の環境は、こちらです。

$ java -version
openjdk version "1.8.0_262"
OpenJDK Runtime Environment (AdoptOpenJDK)(build 1.8.0_262-b10)
OpenJDK 64-Bit Server VM (AdoptOpenJDK)(build 25.262-b10, mixed mode)

Keycloakのバージョンは、11.0.0.です。

2020-07-29 11:59:32,910 INFO  [org.jboss.as] (MSC service thread 1-2) WFLYSRV0049: Keycloak 11.0.0 (WildFly Core 12.0.3.Final) starting

Keycloakの管理ユーザーを作成する

まずは、Keycloakを操作するための管理ユーザーを作成します。

Server Initialization

$ bin/add-user-keycloak.sh -u keycloak-admin -p password
$ bin/jboss-cli.sh -c --command=reload

「keycloak-admin / password」で作成して、Keycloakを再起動。

ヘルプを見る

Admin CLIの実体は、kcadm.shというスクリプトになります。

ヘルプを確認。

$ bin/kcadm.sh --help

kcadm.shはコマンドを指定して実行するので、こちらに対してヘルプを確認。

$ bin/kcadm.sh get --help

サブコマンドを取るものについては、サブコマンドを指定した上でヘルプを確認。

 bin/kcadm.sh config credentials --help

ログインする

まずは、Keycloakにログインします。

Authenticating

先ほど作成した、「keycloak-admin」ユーザーでログインしてみましょう。「config credentials」コマンドでログインします。

$ bin/kcadm.sh config credentials --server http://localhost:8080/auth --realm master --client admin-cli --user keycloak-admin --password password
Logging into http://localhost:8080/auth as user keycloak-admin of realm master

「--realm」でレルムを、「--user」でログインするユーザー名を指定します。「--client」はクライアント名ですが、デフォルトで
「admin-cli」であり、今回は明示的に指定しています。

「--password」オプションでパスワードを指定しない場合は、対話形式でパスワードを聞かれます。
※この例では、「--client」は省略しています

$ bin/kcadm.sh config credentials --server http://localhost:8080/auth --realm master --user keycloak-admin
Logging into http://localhost:8080/auth as user keycloak-admin of realm master
Enter password: ********

ログインに成功すると、デフォルトで「$HOME/.keycloak/kcadm.config」のログイン時の情報が出力されます。

Working with alternative configurations

https://github.com/keycloak/keycloak/blob/11.0.0/integration/client-cli/admin-cli/src/main/java/org/keycloak/client/admin/cli/commands/ConfigCredentialsCmd.java#L193

https://github.com/keycloak/keycloak/blob/11.0.0/integration/client-cli/admin-cli/src/main/java/org/keycloak/client/admin/cli/util/ConfigUtil.java#L35

中身は、こんな感じですね。

$ cat ~/.keycloak/kcadm.config 
{
  "serverUrl" : "http://localhost:8080/auth",
  "realm" : "master",
  "endpoints" : {
    "http://localhost:8080/auth" : {
      "master" : {
        "clientId" : "admin-cli",
        "token" : "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJfdGF0U0JEWkNVOGZIM19rZGJ6QU81dVZtN3NXeHV1WEw0c3ZzT3FJX2RzIn0.eyJleHAiOjE1OTYwMjUxODAsImlhdCI6MTU5NjAyNTEyMCwianRpIjoiNDc5NTA1ZjMtOGQ4Ni00NzkzLWI4MGUtOWJhYjE0MjM3ZDc1IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL21hc3RlciIsInN1YiI6IjI5ZDE2YzA4LWJlYjEtNGJiYS05NjE5LWQ4MmRmOTI4YzgwNSIsInR5cCI6IkJlYXJlciIsImF6cCI6ImFkbWluLWNsaSIsInNlc3Npb25fc3RhdGUiOiI2YTNhNmQ0Zi1iNmEzLTQ2NWYtOTk2OS05YjNmZWE2ZmFjZjgiLCJhY3IiOiIxIiwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJrZXljbG9hay1hZG1pbiJ9.Po9xUUo-itiBBxxM8wJlYFdLvLLij0LMa31EwPTm5fANMeRRcgDeK4hhGrSJdlr7tL37Dr3ebPPHH78_ytOWqzki_HNm8br38exQSjNSk6wJNZGQZVt7meRU--HB4BbjE1pI4D9f9PzPoyGVRtwi9-zFQ1_Ue81YY-l4P8DivnbPUowyEWBPd5-a_nWFpIvQjnWiFCezlQQNM--WLOGJCuM7nk8WZkbswFIeRpF4nF7iBtW3UmP7UuiUVD5uaCqEobqFQ2IQyYn24Jf4UR3x4q4-nsXnxOY5MK0UoqnrkR8FWa0JWTPdieSRYFVP-mpOiG46iKxaYNHMDSbMVbBHtA",
        "refreshToken" : "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1MDViOWNkMS02Zjk0LTQ4NDctYTBkZi03ZmVjMDdjMzg3N2YifQ.eyJleHAiOjE1OTYwMjY5MjAsImlhdCI6MTU5NjAyNTEyMCwianRpIjoiZDUwZGU4M2EtZmJmNS00ZDNlLTg4MjItNjNhOTY1MjA4OWYwIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL21hc3RlciIsImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC9hdXRoL3JlYWxtcy9tYXN0ZXIiLCJzdWIiOiIyOWQxNmMwOC1iZWIxLTRiYmEtOTYxOS1kODJkZjkyOGM4MDUiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoiYWRtaW4tY2xpIiwic2Vzc2lvbl9zdGF0ZSI6IjZhM2E2ZDRmLWI2YTMtNDY1Zi05OTY5LTliM2ZlYTZmYWNmOCIsInNjb3BlIjoicHJvZmlsZSBlbWFpbCJ9.F1VVAoyggCo1jdbjXx6GgoBVjKMHIoGI1C_19cTFdjE",
        "expiresAt" : 1596025180618,
        "refreshExpiresAt" : 1596026920618
      }
    }
  }
}

トークンの有効期限が切れたら、再度ログインし直してください。

エンドポイント

Admin CLIは、REST APIを使っています。エンドポイントの形式を確認しておくと、コマンドが理解しやすくなるでしょう。

Basic operations and resource URIs

Realmを操作する

Admin CLIから、Realmを操作してみましょう。

Realm operations

Realmの作成。

Creating a new realm

$ bin/kcadm.sh create realms -s realm=demo-realm -s enabled=true
Created new realm with id 'demo-realm'

「-s(--set)」は、属性を「名前=値」の形式で指定するオプションです。

Realmの一覧を取得。

Listing existing realms

$ bin/kcadm.sh get realms

特定のRealmを取得する場合は、「realms/[Realm名]」を指定します。

Getting a specific realm

$ bin/kcadm.sh get realms/demo-realm

その他、Realmの更新や削除。

Updating a realm

Deleting a realm

Clientを操作する

Clientの操作について。

Client operations

Clientの登録。

Creating a client

$ bin/kcadm.sh create clients -r demo-realm -s clientId=demo-client -s enabled=true
Created new client with id '97304682-ce11-4c35-b226-67d6d7b8753f'

「-s」の意味は、Realmの時と同じです。「-r(--target-realm)」は、対象のRealmの指定です。

登録されているClientを一覧で取得。

Listing clients

$ bin/kcadm.sh get clients -r demo-realm

特定のクライアントを取得する場合は、「clients/[ClientのID]」で指定します。「clientId」ではありません…。

Getting a specific client

$ bin/kcadm.sh get clients/97304682-ce11-4c35-b226-67d6d7b8753f -r demo-realm

なので、こういうUUIDな感じになります。

Clientの一覧を取得する際に、「-F(--fields)」を指定することで、出力するフィールドを絞り込むこともできます。

$ bin/kcadm.sh get clients -r demo-realm --fields id,clientId
[ {
  "id" : "63f60e05-5e0e-4d89-9690-d15e8c50b400",
  "clientId" : "account"
}, {
  "id" : "4446599f-19a8-4f98-b994-17b2e84ba3f2",
  "clientId" : "account-console"
}, {
  "id" : "23506524-6239-4366-91db-a1606e363bcb",
  "clientId" : "admin-cli"
}, {
  "id" : "de0e3989-3b89-4db8-a40b-ff47e47cc285",
  "clientId" : "broker"
}, {
  "id" : "97304682-ce11-4c35-b226-67d6d7b8753f",
  "clientId" : "demo-client"
}, {
  "id" : "c528429a-b1e5-4659-8213-259d8aa97f6a",
  "clientId" : "realm-management"
}, {
  "id" : "d8c332c7-0268-4018-a9be-79c4ce60a930",
  "clientId" : "security-admin-console"
} ]

さらに「-q(--query)」で検索条件を指定することもできます。

$ bin/kcadm.sh get clients -r demo-realm -F id -q clientId=demo-client
[ {
  "id" : "97304682-ce11-4c35-b226-67d6d7b8753f"
} ]

Client Secretの取得。「clients/[ClientのID]/client-secret」で取得します。

Getting the current secret for a specific client

$ bin/kcadm.sh get clients/97304682-ce11-4c35-b226-67d6d7b8753f/client-secret -r demo-realm
{
  "type" : "secret",
  "value" : "a0801b69-71ec-4158-a5f5-ef13548cb39c"
}

Clientの更新。

Updating a client

$ bin/kcadm.sh update clients/97304682-ce11-4c35-b226-67d6d7b8753f -r demo-realm -s publicClient=false -s bearerOnly=false
$ bin/kcadm.sh update clients/97304682-ce11-4c35-b226-67d6d7b8753f -r demo-realm -s rootUrl=http://localhost:8080 -s 'redirectUris=["http://localhost:8080/*"]'
$ bin/kcadm.sh update clients/97304682-ce11-4c35-b226-67d6d7b8753f -r demo-realm -s rootUrl=http://localhost:8080 -s baseUrl=http://localhost:8080 -s 'redirectUris=["http://localhost:8080/*"]'

「rootUrl」や「baseUrl」などは、指定していない場合はAdmin CLIでClientの情報を取得しても、属性自体が表示されません。
更新対象の属性がわからなかったら、1度Web UIで更新して情報を見るとよいでしょうね。

Client Secretの更新もできるようです。

Updating the current secret for a specific client

Clientの削除。

Deleting a client

Roleを操作する

Roleを操作します。

Role operations

Roleの作成。

Creating a realm role

$ bin/kcadm.sh create roles -r demo-realm -s name=users
Created new role with id 'users'

Role一覧の取得。

Listing realm roles

$ bin/kcadm.sh get-roles -r demo-realm
[ {
  "id" : "c783e283-3083-40e5-b6ca-2f1883bdef6d",
  "name" : "uma_authorization",
  "description" : "${role_uma_authorization}",
  "composite" : false,
  "clientRole" : false,
  "containerId" : "61723d6f-e27e-4365-99ff-c61c3cf8283f"
}, {
  "id" : "bbcb149f-b9f6-4d36-a7a8-294fdd34bad8",
  "name" : "users",
  "composite" : false,
  "clientRole" : false,
  "containerId" : "61723d6f-e27e-4365-99ff-c61c3cf8283f"
}, {
  "id" : "b2a2cd9b-4a95-457c-ae3d-dad42c293449",
  "name" : "offline_access",
  "description" : "${role_offline-access}",
  "composite" : false,
  "clientRole" : false,
  "containerId" : "61723d6f-e27e-4365-99ff-c61c3cf8283f"
} ]

更新や削除。

Updating a realm role

Deleting a realm role

Roleは、簡単に終了…。

Userを操作する

Userの操作。

User operations

Userの作成。

Creating a user

$ bin/kcadm.sh create users -r demo-realm -s username=user001 -s enabled=true
Created new user with id 'e83b1a53-37c9-4c9d-af06-caf0978f7bfd'

Userの一覧を表示。

Listing users

$ bin/kcadm.sh get users -r demo-realm

特定のUserを表示。指定する時は、「users/[Userのid]」になります。なので、やっぱりUUIDです。

Getting a specific user

$ bin/kcadm.sh get users/e83b1a53-37c9-4c9d-af06-caf0978f7bfd -r demo-realm
{
  "id" : "e83b1a53-37c9-4c9d-af06-caf0978f7bfd",
  "createdTimestamp" : 1596027970167,
  "username" : "user001",
  "enabled" : true,
  "totp" : false,
  "emailVerified" : false,
  "disableableCredentialTypes" : [ ],
  "requiredActions" : [ ],
  "notBefore" : 0,
  "access" : {
    "manageGroupMembership" : true,
    "view" : true,
    "mapRoles" : true,
    "impersonate" : true,
    "manage" : true
  }
}

更新。

Updating a user

$ bin/kcadm.sh update users/e83b1a53-37c9-4c9d-af06-caf0978f7bfd -r demo-realm -s firstName=user1 -s lastName=test1

こちらも、指定していない属性は、最初は属性自体がなかったりするので、Web UIで操作してから対象の属性を確認した方が
良いでしょう。

削除。

Deleting a user

パスワードのリセット。

Resetting a user’s password

$ bin/kcadm.sh set-password -r demo-realm --username user001 --new-password password

「--temporary」を付与すると、ログイン時にパスワード変更を求められる一時パスワードになります。

$ bin/kcadm.sh set-password -r demo-realm --username user001 --new-password password --temporary

UserをRoleに追加。

Adding realm roles to a user

$ bin/kcadm.sh add-roles -r demo-realm --username user001 --rolename users

Userが属するRoleを表示。

Listing assigned, available, and effective realm roles for a user

$ bin/kcadm.sh get-roles -r demo-realm --username user001 
[ {
  "id" : "c783e283-3083-40e5-b6ca-2f1883bdef6d",
  "name" : "uma_authorization",
  "description" : "${role_uma_authorization}",
  "composite" : false,
  "clientRole" : false,
  "containerId" : "61723d6f-e27e-4365-99ff-c61c3cf8283f"
}, {
  "id" : "bbcb149f-b9f6-4d36-a7a8-294fdd34bad8",
  "name" : "users",
  "composite" : false,
  "clientRole" : false,
  "containerId" : "61723d6f-e27e-4365-99ff-c61c3cf8283f"
}, {
  "id" : "b2a2cd9b-4a95-457c-ae3d-dad42c293449",
  "name" : "offline_access",
  "description" : "${role_offline-access}",
  "composite" : false,
  "clientRole" : false,
  "containerId" : "61723d6f-e27e-4365-99ff-c61c3cf8283f"
} ]

UserからRoleを削除。

Removing realm roles from a user

$ bin/kcadm.sh remove-roles -r demo-realm --username user001 --rolename users

こんな感じで。

もちろん、ここに載せた以外にもいろいろできますが、それは使いつつ慣れていきましょう…。