これは、なにをしたくて書いたもの?
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を操作するための管理ユーザーを作成します。
$ 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にログインします。
先ほど作成した、「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
中身は、こんな感じですね。
$ 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の作成。
$ bin/kcadm.sh create realms -s realm=demo-realm -s enabled=true Created new realm with id 'demo-realm'
「-s(--set)」は、属性を「名前=値」の形式で指定するオプションです。
Realmの一覧を取得。
$ bin/kcadm.sh get realms
特定のRealmを取得する場合は、「realms/[Realm名]」を指定します。
$ bin/kcadm.sh get realms/demo-realm
その他、Realmの更新や削除。
Clientを操作する
Clientの操作について。
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を一覧で取得。
$ bin/kcadm.sh get clients -r demo-realm
特定のクライアントを取得する場合は、「clients/[ClientのID]」で指定します。「clientId」ではありません…。
$ 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の更新。
$ 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の削除。
Roleを操作する
Roleを操作します。
Roleの作成。
$ bin/kcadm.sh create roles -r demo-realm -s name=users Created new role with id 'users'
Role一覧の取得。
$ 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" } ]
更新や削除。
Roleは、簡単に終了…。
Userを操作する
Userの操作。
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の一覧を表示。
$ bin/kcadm.sh get users -r demo-realm
特定のUserを表示。指定する時は、「users/[Userのid]」になります。なので、やっぱりUUIDです。
$ 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 } }
更新。
$ bin/kcadm.sh update users/e83b1a53-37c9-4c9d-af06-caf0978f7bfd -r demo-realm -s firstName=user1 -s lastName=test1
こちらも、指定していない属性は、最初は属性自体がなかったりするので、Web UIで操作してから対象の属性を確認した方が
良いでしょう。
削除。
パスワードのリセット。
$ 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に追加。
$ 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
こんな感じで。
もちろん、ここに載せた以外にもいろいろできますが、それは使いつつ慣れていきましょう…。