Red Hat Single Sign-On Administration

Red Hat recommends to add the RH-SSO bin directory to your PATH environment variable so you can use the RH-SSO Admin CLI from any location on your file system.

[rhsso@sso ~]$ export PATH=$PATH:/opt/rh-sso-7.6/bin

If you run the kcadm.sh script without any parameter, then it shows the basic information about the Admin CLI.

[rhsso@sso ~]$ kcadm.sh
Keycloak Admin CLI

Use 'kcadm.sh config credentials' command with username and password to start a
 session against a specific server and realm.

For example:

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

Any configured username can be used for login, but to perform admin operations
the user needs proper roles, otherwise operations will fail.
...output omitted...

You can also use kcadm.sh help command to show specific help for a command.

The RH-SSO Admin CLI makes HTTP requests to the Admin REST endpoints. You need to start an authenticated session with the proper permissions to access to the Admin REST endpoints. Thus, the first step to start using the Admin CLI is to start a session against the RH-SSO server, and a realm by using the config credentials command. To do it, you must provide the server URL, the realm name, and the username parameters.

[rhsso@sso ~]$ kcadm.sh config credentials \
  --server rhsso_server_url --realm realm_name --user username

Then, the RH-SSO Admin CLI prompts for the user password in the realm. You can also provide the password as plain text when starting a session against the RH-SSO server by using the --password option. However, Red Hat recommends not to use that option due to security reasons.

Note that for production environments, you must access RH-SSO by using HTTPS to avoid exposing tokens. If the server's certificate is not issued by a trusted certificate authority included in the Java's default certificate truststore, then you need to prepare a truststore.jks file and use it in your Admin CLI. You can perform this task by using the config truststore command like the following example.

[rhsso@sso ~]$ kcadm.sh config truststore \
  --trustpass truststore_password truststore_file_path

Use the get command to retrieve information about existing resources from the server. For example, you can retrieve the RH-SSO realms information by using the get realms command.

[rhsso@sso ~]$ kcadm.sh get realms
[ {
  "id" : "d0a4c96a-25de-4ab4-9610-b5df1cc25e04",
  "realm" : "master",
  "displayName" : "rh-sso",
  "displayNameHtml" : "<strong>Red Hat</strong><sup>®</sup> Single Sign On",
  "notBefore" : 0,
  "defaultSignatureAlgorithm" : "RS256",
  "revokeRefreshToken" : false,
  "refreshTokenMaxReuse" : 0,
  "accessTokenLifespan" : 60,
  "accessTokenLifespanForImplicitFlow" : 900,
...output omitted...

Use the --fields option to provide a filter pattern to specify which fields you want to show at the output. The following example lists the RH-SSO realms showing only the realm name.

[rhsso@sso ~]$ kcadm.sh get realms --fields realm
[ {
  "realm" : "master"
}, {
  "realm" : "demo"
} ]

Use the -r option to provide the target realm to issue your requests. If you do not use this option, then RH-SSO issues your request to the realm you provided when configuring the credentials. The following example lists the users, first in the realm configured in your credentials and then in the demo realm.

[rhsso@sso ~]$ kcadm.sh get users --fields username
[ {
  "username" : "admin"
}, {
  "username" : "johndoe"
} ]
[rhsso@sso ~]$ kcadm.sh get users --fields username -r demo
[ {
  "username" : "alice"
}, {
  "username" : "bob"
} ]

Use the -q option to filter the results by attribute. The following example lists all the users in the demo realm with a Red Hat email.

[rhsso@sso ~]$ kcadm.sh get users -r demo -q email=@redhat.com
[ {
  "id" : "7fe813bc-1cb7-4cad-99ec-4aed882f8cec",
  "createdTimestamp" : 1672833216011,
  "username" : "bob",
  "enabled" : true,
  "totp" : false,
  "emailVerified" : false,
  "email" : "bob@redhat.com",
...output omitted...

Note that filtering does not use exact matching. The previous example matches the value of the email attribute against the *@redhat.com* pattern.

Use the create command to create resources on the server. For example, you can create a RH-SSO realm by using the create realms command. Use the -s option to set an attribute to a specified value.

The following example creates a new realm called demo and enables it.

[rhsso@sso ~]$ kcadm.sh create realms -s realm=demo -s enabled=true
Created new realm with id 'demo'

Use the update command to update existing resources on the server. For example, you can update the first name for the bob user in the demo realm by using the update command with the -s option.

[rhsso@sso ~]$ kcadm.sh get users -r demo --fields id,firstName \
  -q username=bob
[ {
  "id" : "7fe813bc-1cb7-4cad-99ec-4aed882f8cec"
} ]
[rhsso@sso ~]$ kcadm.sh update users/7fe813bc-1cb7-4cad-99ec-4aed882f8cec \
  -r demo -s firstName=Bob
[rhsso@sso ~]$ kcadm.sh get users -r demo --fields id,firstName \
  -q username=bob
[ {
  "id" : "7fe813bc-1cb7-4cad-99ec-4aed882f8cec"
  "firstName" : "Bob"
} ]

Note that you must provide the user ID to update its attributes.

Use the delete command to delete resources from the server. The following example deletes the bob user from the demo realm.

[rhsso@sso ~]$ kcadm.sh delete users/7fe813bc-1cb7-4cad-99ec-4aed882f8cec \
  -r demo

Note that you must provide the user ID to delete it.

Use the set-password command to set a user's password. For example, the following command sets the bob user password to redhat.

[rhsso@sso ~]$ kcadm.sh set-password -r demo --username bob \
  --new-password redhat

If you want to set a temporary password that the user must change the next time they log in, then use the --temporary option.