Limit Admin CLI windows support to upstream

Closes #23946

Co-authored-by: Alexander Schwartz <aschwart@redhat.com>
This commit is contained in:
andymunro 2023-10-13 06:08:11 -04:00 committed by GitHub
parent 2df2aed044
commit 6074cbf311
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -7,29 +7,45 @@ With {project_name}, you can perform administration tasks from the command-line
{project_name} packages the Admin CLI server distribution with the execution scripts in the `bin` directory. {project_name} packages the Admin CLI server distribution with the execution scripts in the `bin` directory.
The Linux script is called `kcadm.sh`, and the script for Windows is called `kcadm.bat`. Add the {project_name} server directory to your `PATH` to use the client from any location on your file system. ifeval::[{project_product}==true]
The script is called `kcadm.sh`.
endif::[]
ifeval::[{project_product}!=true]
The Linux script is called `kcadm.sh`, and the script for Windows is called `kcadm.bat`.
endif::[]
Add the {project_name} server directory to your `PATH` to use the client from any location on your file system.
For example: For example:
ifeval::[{project_product}!=true]
* Linux: * Linux:
+
endif::[]
[options="nowrap"] [options="nowrap"]
---- ----
$ export PATH=$PATH:$KEYCLOAK_HOME/bin $ export PATH=$PATH:$KEYCLOAK_HOME/bin
$ kcadm.sh $ kcadm.sh
---- ----
ifeval::[{project_product}!=true]
* Windows: * Windows:
+
[options="nowrap"] [options="nowrap"]
---- ----
c:\> set PATH=%PATH%;%KEYCLOAK_HOME%\bin c:\> set PATH=%PATH%;%KEYCLOAK_HOME%\bin
c:\> kcadm c:\> kcadm
---- ----
endif::[]
[NOTE] [NOTE]
==== ====
You must set the `KEYCLOAK_HOME` environment variable to the path where you extracted the {project_name} Server distribution. You must set the `KEYCLOAK_HOME` environment variable to the path where you extracted the {project_name} Server distribution.
ifeval::[{project_product}!=true]
To avoid repetition, the rest of this document only uses Windows examples in places where the CLI differences are more than just in the `kcadm` command name. To avoid repetition, the rest of this document only uses Windows examples in places where the CLI differences are more than just in the `kcadm` command name.
endif::[]
==== ====
@ -45,9 +61,11 @@ Consult the Admin REST API documentation for details about JSON attributes for s
. Start an authenticated session by logging in. You can now perform create, read, update, and delete (CRUD) operations. . Start an authenticated session by logging in. You can now perform create, read, update, and delete (CRUD) operations.
+ +
For example: For example:
+
ifeval::[{project_product}!=true]
* Linux: * Linux:
+ +
endif::[]
[options="nowrap",subs="attributes+"] [options="nowrap",subs="attributes+"]
---- ----
$ kcadm.sh config credentials --server http://localhost:8080{kc_base_path} --realm demo --user admin --client admin $ kcadm.sh config credentials --server http://localhost:8080{kc_base_path} --realm demo --user admin --client admin
@ -55,6 +73,7 @@ $ kcadm.sh create realms -s realm=demorealm -s enabled=true -o
$ CID=$(kcadm.sh create clients -r demorealm -s clientId=my_client -s 'redirectUris=["http://localhost:8980/myapp/*"]' -i) $ CID=$(kcadm.sh create clients -r demorealm -s clientId=my_client -s 'redirectUris=["http://localhost:8980/myapp/*"]' -i)
$ kcadm.sh get clients/$CID/installation/providers/keycloak-oidc-keycloak-json $ kcadm.sh get clients/$CID/installation/providers/keycloak-oidc-keycloak-json
---- ----
ifeval::[{project_product}!=true]
+ +
* Windows: * Windows:
+ +
@ -66,17 +85,21 @@ c:\> kcadm create clients -r demorealm -s clientId=my_client -s "redirectUris=[\
c:\> set /p CID=<clientid.txt c:\> set /p CID=<clientid.txt
c:\> kcadm get clients/%CID%/installation/providers/keycloak-oidc-keycloak-json c:\> kcadm get clients/%CID%/installation/providers/keycloak-oidc-keycloak-json
---- ----
endif::[]
. In a production environment, access {project_name} by using `https:` to avoid exposing tokens. If a trusted certificate authority, included in Java's default certificate truststore, has not issued a server's certificate, prepare a `truststore.jks` file and instruct the Admin CLI to use it. . In a production environment, access {project_name} by using `https:` to avoid exposing tokens. If a trusted certificate authority, included in Java's default certificate truststore, has not issued a server's certificate, prepare a `truststore.jks` file and instruct the Admin CLI to use it.
+ +
For example: For example:
+
ifeval::[{project_product}!=true]
* Linux: * Linux:
+ +
endif::[]
[options="nowrap"] [options="nowrap"]
---- ----
$ kcadm.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks $ kcadm.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks
---- ----
ifeval::[{project_product}!=true]
+ +
* Windows: * Windows:
+ +
@ -84,7 +107,7 @@ $ kcadm.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks
---- ----
c:\> kcadm config truststore --trustpass %PASSWORD% %HOMEPATH%\.keycloak\truststore.jks c:\> kcadm config truststore --trustpass %PASSWORD% %HOMEPATH%\.keycloak\truststore.jks
---- ----
endif::[]
=== Authenticating === Authenticating
@ -126,8 +149,10 @@ Run the `kcadm.sh config credentials --help` command for more information about
=== Working with alternative configurations === Working with alternative configurations
By default, the Admin CLI maintains a configuration file named `kcadm.config`. {project_name} places this file in the user's home directory. By default, the Admin CLI maintains a configuration file named `kcadm.config`. {project_name} places this file in the user's home directory.
In Linux-based systems, the full pathname is `$HOME/.keycloak/kcadm.config`. In Linux-based systems, the full pathname is `$HOME/.keycloak/kcadm.config`.
In Windows, the full pathname is `%HOMEPATH%\.keycloak\kcadm.config`. ifeval::[{project_product}!=true]
In Windows, the full pathname is `%HOMEPATH%\.keycloak\kcadm.config`.
endif::[]
You can use the `--config` option to point to a different file or location so you can maintain multiple authenticated sessions in parallel. You can use the `--config` option to point to a different file or location so you can maintain multiple authenticated sessions in parallel.
@ -239,7 +264,10 @@ You can send a JSON document with realm attributes directly from a file or pipe
For example: For example:
ifeval::[{project_product}!=true]
* Linux: * Linux:
+
endif::[]
[options="nowrap"] [options="nowrap"]
---- ----
$ kcadm.sh create realms -f - << EOF $ kcadm.sh create realms -f - << EOF
@ -247,11 +275,14 @@ $ kcadm.sh create realms -f - << EOF
EOF EOF
---- ----
ifeval::[{project_product}!=true]
* Windows: * Windows:
+
[options="nowrap"] [options="nowrap"]
---- ----
c:\> echo { "realm": "demorealm", "enabled": true } | kcadm create realms -f - c:\> echo { "realm": "demorealm", "enabled": true } | kcadm create realms -f -
---- ----
endif::[]
[discrete] [discrete]
==== Listing existing realms ==== Listing existing realms
@ -358,18 +389,22 @@ $ kcadm.sh get realms/demorealm --fields id --format csv --noquotes
+ +
For example: For example:
+ +
ifeval::[{project_product}!=true]
* Linux: * Linux:
+ +
endif::[]
[options="nowrap"] [options="nowrap"]
---- ----
$ kcadm.sh create components -r demorealm -s name=rsa-generated -s providerId=rsa-generated -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s 'config.priority=["101"]' -s 'config.enabled=["true"]' -s 'config.active=["true"]' -s 'config.keySize=["2048"]' $ kcadm.sh create components -r demorealm -s name=rsa-generated -s providerId=rsa-generated -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s 'config.priority=["101"]' -s 'config.enabled=["true"]' -s 'config.active=["true"]' -s 'config.keySize=["2048"]'
---- ----
ifeval::[{project_product}!=true]
* Windows: * Windows:
+ +
[options="nowrap"] [options="nowrap"]
---- ----
c:\> kcadm create components -r demorealm -s name=rsa-generated -s providerId=rsa-generated -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s "config.priority=[\"101\"]" -s "config.enabled=[\"true\"]" -s "config.active=[\"true\"]" -s "config.keySize=[\"2048\"]" c:\> kcadm create components -r demorealm -s name=rsa-generated -s providerId=rsa-generated -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s "config.priority=[\"101\"]" -s "config.enabled=[\"true\"]" -s "config.active=[\"true\"]" -s "config.keySize=[\"2048\"]"
---- ----
endif::[]
. Set the `parentId` attribute to the value of the target realm's ID. . Set the `parentId` attribute to the value of the target realm's ID.
+ +
The newly added key is now the active key, as revealed by `kcadm.sh get keys -r demorealm`. The newly added key is now the active key, as revealed by `kcadm.sh get keys -r demorealm`.
@ -381,18 +416,22 @@ The newly added key is now the active key, as revealed by `kcadm.sh get keys -r
+ +
For example, on: For example, on:
+ +
ifeval::[{project_product}!=true]
* Linux: * Linux:
+ +
endif::[]
[options="nowrap"] [options="nowrap"]
---- ----
$ kcadm.sh create components -r demorealm -s name=java-keystore -s providerId=java-keystore -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s 'config.priority=["101"]' -s 'config.enabled=["true"]' -s 'config.active=["true"]' -s 'config.keystore=["/opt/keycloak/keystore.jks"]' -s 'config.keystorePassword=["secret"]' -s 'config.keyPassword=["secret"]' -s 'config.keyAlias=["localhost"]' $ kcadm.sh create components -r demorealm -s name=java-keystore -s providerId=java-keystore -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s 'config.priority=["101"]' -s 'config.enabled=["true"]' -s 'config.active=["true"]' -s 'config.keystore=["/opt/keycloak/keystore.jks"]' -s 'config.keystorePassword=["secret"]' -s 'config.keyPassword=["secret"]' -s 'config.keyAlias=["localhost"]'
---- ----
ifeval::[{project_product}!=true]
* Windows: * Windows:
+ +
[options="nowrap"] [options="nowrap"]
---- ----
c:\> kcadm create components -r demorealm -s name=java-keystore -s providerId=java-keystore -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s "config.priority=[\"101\"]" -s "config.enabled=[\"true\"]" -s "config.active=[\"true\"]" -s "config.keystore=[\"/opt/keycloak/keystore.jks\"]" -s "config.keystorePassword=[\"secret\"]" -s "config.keyPassword=[\"secret\"]" -s "config.keyAlias=[\"localhost\"]" c:\> kcadm create components -r demorealm -s name=java-keystore -s providerId=java-keystore -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s "config.priority=[\"101\"]" -s "config.enabled=[\"true\"]" -s "config.active=[\"true\"]" -s "config.keystore=[\"/opt/keycloak/keystore.jks\"]" -s "config.keystorePassword=[\"secret\"]" -s "config.keyPassword=[\"secret\"]" -s "config.keyAlias=[\"localhost\"]"
---- ----
endif::[]
. Ensure you change the attribute values for `keystore`, `keystorePassword`, `keyPassword`, and `alias` to match your specific keystore. . Ensure you change the attribute values for `keystore`, `keystorePassword`, `keyPassword`, and `alias` to match your specific keystore.
. Set the `parentId` attribute to the value of the target realm's ID. . Set the `parentId` attribute to the value of the target realm's ID.
@ -409,23 +448,28 @@ $ kcadm.sh get keys -r demorealm
. Perform an `update`. . Perform an `update`.
+ +
For example: For example:
+
ifeval::[{project_product}!=true]
* Linux: * Linux:
+ +
endif::[]
[options="nowrap"] [options="nowrap"]
---- ----
$ kcadm.sh update components/PROVIDER_ID -r demorealm -s 'config.active=["false"]' $ kcadm.sh update components/PROVIDER_ID -r demorealm -s 'config.active=["false"]'
---- ----
ifeval::[{project_product}!=true]
* Windows: * Windows:
+ +
[options="nowrap"] [options="nowrap"]
---- ----
c:\> kcadm update components/PROVIDER_ID -r demorealm -s "config.active=[\"false\"]" c:\> kcadm update components/PROVIDER_ID -r demorealm -s "config.active=[\"false\"]"
---- ----
endif::[]
+ +
You can update other key attributes: You can update other key attributes:
. Set a new `enabled` value to disable the key, for example, `config.enabled=["false"]`.
. Set a new `priority` value to change the key's priority, for example, `config.priority=["110"]`. * Set a new `enabled` value to disable the key, for example, `config.enabled=["false"]`.
* Set a new `priority` value to change the key's priority, for example, `config.priority=["110"]`.
[discrete] [discrete]
==== Deleting an old key ==== Deleting an old key
@ -455,31 +499,44 @@ You can set up a built-in event listener that receives all events and logs the e
For example: For example:
ifeval::[{project_product}!=true]
* Linux: * Linux:
+
[options="nowrap"] [options="nowrap"]
+
endif::[]
---- ----
$ kcadm.sh update events/config -r demorealm -s 'eventsListeners=["jboss-logging"]' $ kcadm.sh update events/config -r demorealm -s 'eventsListeners=["jboss-logging"]'
---- ----
ifeval::[{project_product}!=true]
* Windows: * Windows:
+
[options="nowrap"] [options="nowrap"]
---- ----
c:\> kcadm update events/config -r demorealm -s "eventsListeners=[\"jboss-logging\"]" c:\> kcadm update events/config -r demorealm -s "eventsListeners=[\"jboss-logging\"]"
---- ----
endif::[]
For example: For example:
You can turn on storage for all available ERROR events, not including auditing events, for two days so you can retrieve the events through Admin REST. You can turn on storage for all available ERROR events, not including auditing events, for two days so you can retrieve the events through Admin REST.
ifeval::[{project_product}!=true]
* Linux: * Linux:
+
endif::[]
[options="nowrap"] [options="nowrap"]
---- ----
$ kcadm.sh update events/config -r demorealm -s eventsEnabled=true -s 'enabledEventTypes=["LOGIN_ERROR","REGISTER_ERROR","LOGOUT_ERROR","CODE_TO_TOKEN_ERROR","CLIENT_LOGIN_ERROR","FEDERATED_IDENTITY_LINK_ERROR","REMOVE_FEDERATED_IDENTITY_ERROR","UPDATE_EMAIL_ERROR","UPDATE_PROFILE_ERROR","UPDATE_PASSWORD_ERROR","UPDATE_TOTP_ERROR","VERIFY_EMAIL_ERROR","REMOVE_TOTP_ERROR","SEND_VERIFY_EMAIL_ERROR","SEND_RESET_PASSWORD_ERROR","SEND_IDENTITY_PROVIDER_LINK_ERROR","RESET_PASSWORD_ERROR","IDENTITY_PROVIDER_FIRST_LOGIN_ERROR","IDENTITY_PROVIDER_POST_LOGIN_ERROR","CUSTOM_REQUIRED_ACTION_ERROR","EXECUTE_ACTIONS_ERROR","CLIENT_REGISTER_ERROR","CLIENT_UPDATE_ERROR","CLIENT_DELETE_ERROR"]' -s eventsExpiration=172800 $ kcadm.sh update events/config -r demorealm -s eventsEnabled=true -s 'enabledEventTypes=["LOGIN_ERROR","REGISTER_ERROR","LOGOUT_ERROR","CODE_TO_TOKEN_ERROR","CLIENT_LOGIN_ERROR","FEDERATED_IDENTITY_LINK_ERROR","REMOVE_FEDERATED_IDENTITY_ERROR","UPDATE_EMAIL_ERROR","UPDATE_PROFILE_ERROR","UPDATE_PASSWORD_ERROR","UPDATE_TOTP_ERROR","VERIFY_EMAIL_ERROR","REMOVE_TOTP_ERROR","SEND_VERIFY_EMAIL_ERROR","SEND_RESET_PASSWORD_ERROR","SEND_IDENTITY_PROVIDER_LINK_ERROR","RESET_PASSWORD_ERROR","IDENTITY_PROVIDER_FIRST_LOGIN_ERROR","IDENTITY_PROVIDER_POST_LOGIN_ERROR","CUSTOM_REQUIRED_ACTION_ERROR","EXECUTE_ACTIONS_ERROR","CLIENT_REGISTER_ERROR","CLIENT_UPDATE_ERROR","CLIENT_DELETE_ERROR"]' -s eventsExpiration=172800
---- ----
ifeval::[{project_product}!=true]
* Windows: * Windows:
+
[options="nowrap"] [options="nowrap"]
---- ----
c:\> kcadm update events/config -r demorealm -s eventsEnabled=true -s "enabledEventTypes=[\"LOGIN_ERROR\",\"REGISTER_ERROR\",\"LOGOUT_ERROR\",\"CODE_TO_TOKEN_ERROR\",\"CLIENT_LOGIN_ERROR\",\"FEDERATED_IDENTITY_LINK_ERROR\",\"REMOVE_FEDERATED_IDENTITY_ERROR\",\"UPDATE_EMAIL_ERROR\",\"UPDATE_PROFILE_ERROR\",\"UPDATE_PASSWORD_ERROR\",\"UPDATE_TOTP_ERROR\",\"VERIFY_EMAIL_ERROR\",\"REMOVE_TOTP_ERROR\",\"SEND_VERIFY_EMAIL_ERROR\",\"SEND_RESET_PASSWORD_ERROR\",\"SEND_IDENTITY_PROVIDER_LINK_ERROR\",\"RESET_PASSWORD_ERROR\",\"IDENTITY_PROVIDER_FIRST_LOGIN_ERROR\",\"IDENTITY_PROVIDER_POST_LOGIN_ERROR\",\"CUSTOM_REQUIRED_ACTION_ERROR\",\"EXECUTE_ACTIONS_ERROR\",\"CLIENT_REGISTER_ERROR\",\"CLIENT_UPDATE_ERROR\",\"CLIENT_DELETE_ERROR\"]" -s eventsExpiration=172800 c:\> kcadm update events/config -r demorealm -s eventsEnabled=true -s "enabledEventTypes=[\"LOGIN_ERROR\",\"REGISTER_ERROR\",\"LOGOUT_ERROR\",\"CODE_TO_TOKEN_ERROR\",\"CLIENT_LOGIN_ERROR\",\"FEDERATED_IDENTITY_LINK_ERROR\",\"REMOVE_FEDERATED_IDENTITY_ERROR\",\"UPDATE_EMAIL_ERROR\",\"UPDATE_PROFILE_ERROR\",\"UPDATE_PASSWORD_ERROR\",\"UPDATE_TOTP_ERROR\",\"VERIFY_EMAIL_ERROR\",\"REMOVE_TOTP_ERROR\",\"SEND_VERIFY_EMAIL_ERROR\",\"SEND_RESET_PASSWORD_ERROR\",\"SEND_IDENTITY_PROVIDER_LINK_ERROR\",\"RESET_PASSWORD_ERROR\",\"IDENTITY_PROVIDER_FIRST_LOGIN_ERROR\",\"IDENTITY_PROVIDER_POST_LOGIN_ERROR\",\"CUSTOM_REQUIRED_ACTION_ERROR\",\"EXECUTE_ACTIONS_ERROR\",\"CLIENT_REGISTER_ERROR\",\"CLIENT_UPDATE_ERROR\",\"CLIENT_DELETE_ERROR\"]" -s eventsExpiration=172800
---- ----
endif::[]
You can reset stored event types to *all available event types*. Setting the value to an empty list is the same as enumerating all. You can reset stored event types to *all available event types*. Setting the value to an empty list is the same as enumerating all.
[options="nowrap"] [options="nowrap"]
@ -958,16 +1015,23 @@ Use the `update` command with the same endpoint URI that you use to get a specif
For example: For example:
ifeval::[{project_product}!=true]
* Linux: * Linux:
+
endif::[]
[options="nowrap"] [options="nowrap"]
---- ----
$ kcadm.sh update clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm -s enabled=false -s publicClient=true -s 'redirectUris=["http://localhost:8080/myapp/*"]' -s baseUrl=http://localhost:8080/myapp -s adminUrl=http://localhost:8080/myapp $ kcadm.sh update clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm -s enabled=false -s publicClient=true -s 'redirectUris=["http://localhost:8080/myapp/*"]' -s baseUrl=http://localhost:8080/myapp -s adminUrl=http://localhost:8080/myapp
---- ----
ifeval::[{project_product}!=true]
* Windows: * Windows:
+
[options="nowrap"] [options="nowrap"]
---- ----
c:\> kcadm update clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm -s enabled=false -s publicClient=true -s "redirectUris=[\"http://localhost:8080/myapp/*\"]" -s baseUrl=http://localhost:8080/myapp -s adminUrl=http://localhost:8080/myapp c:\> kcadm update clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm -s enabled=false -s publicClient=true -s "redirectUris=[\"http://localhost:8080/myapp/*\"]" -s baseUrl=http://localhost:8080/myapp -s adminUrl=http://localhost:8080/myapp
---- ----
endif::[]
[discrete] [discrete]
==== Deleting a client ==== Deleting a client
@ -1042,16 +1106,22 @@ Use the `update` command with the same endpoint URI that you use to get a specif
For example: For example:
ifeval::[{project_product}!=true]
* Linux: * Linux:
+
endif::[]
[options="nowrap"] [options="nowrap"]
---- ----
$ kcadm.sh update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm -s 'requiredActions=["VERIFY_EMAIL","UPDATE_PROFILE","CONFIGURE_TOTP","UPDATE_PASSWORD"]' $ kcadm.sh update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm -s 'requiredActions=["VERIFY_EMAIL","UPDATE_PROFILE","CONFIGURE_TOTP","UPDATE_PASSWORD"]'
---- ----
ifeval::[{project_product}!=true]
* Windows: * Windows:
+
[options="nowrap"] [options="nowrap"]
---- ----
c:\> kcadm update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm -s "requiredActions=[\"VERIFY_EMAIL\",\"UPDATE_PROFILE\",\"CONFIGURE_TOTP\",\"UPDATE_PASSWORD\"]" c:\> kcadm update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm -s "requiredActions=[\"VERIFY_EMAIL\",\"UPDATE_PROFILE\",\"CONFIGURE_TOTP\",\"UPDATE_PASSWORD\"]"
---- ----
endif::[]
[discrete] [discrete]
==== Deleting a user ==== Deleting a user