1396 lines
56 KiB
Text
1396 lines
56 KiB
Text
|
|
== The Admin CLI
|
|
|
|
In previous chapters, we described how to use the {project_name} Admin Console to perform administrative tasks. You can also perform those tasks from the command-line interface (CLI) by using the Admin CLI command-line tool.
|
|
|
|
|
|
=== Installing the Admin CLI
|
|
|
|
The Admin CLI is packaged inside {project_name} Server distribution. You can find execution scripts inside the [filename]`bin` directory.
|
|
|
|
The Linux script is called [filename]`kcadm.sh`, and the script for Windows is called [filename]`kcadm.bat`.
|
|
|
|
You can add the {project_name} server directory to your [filename]`PATH` to use the client from any location on your file system.
|
|
|
|
For example, on:
|
|
|
|
* Linux:
|
|
[options="nowrap"]
|
|
----
|
|
$ export PATH=$PATH:$KEYCLOAK_HOME/bin
|
|
$ kcadm.sh
|
|
----
|
|
|
|
* Windows:
|
|
[options="nowrap"]
|
|
----
|
|
c:\> set PATH=%PATH%;%KEYCLOAK_HOME%\bin
|
|
c:\> kcadm
|
|
----
|
|
|
|
We assume the `KEYCLOAK_HOME` environment (env) variable is set to the path where you extracted the {project_name} Server distribution.
|
|
|
|
[NOTE]
|
|
====
|
|
To avoid repetition, the rest of this document only gives Windows examples in places where the difference in the CLI is more than just in the [command]`kcadm` command name.
|
|
====
|
|
|
|
|
|
=== Using the Admin CLI
|
|
|
|
The Admin CLI works by making HTTP requests to Admin REST endpoints. Access to them is protected and requires authentication.
|
|
|
|
//Should there be a link for the REST API documentation?
|
|
[NOTE]
|
|
====
|
|
Consult the Admin REST API documentation for details about JSON attributes for specific endpoints.
|
|
====
|
|
|
|
. Start an authenticated session by providing credentials, that is, logging in. You are ready to perform create, read, update, and delete (CRUD) operations.
|
|
+
|
|
For example, on
|
|
|
|
* Linux:
|
|
+
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh config credentials --server http://localhost:8080/auth --realm demo --user admin --client admin
|
|
$ 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)
|
|
$ kcadm.sh get clients/$CID/installation/providers/keycloak-oidc-keycloak-json
|
|
----
|
|
+
|
|
* Windows:
|
|
+
|
|
[options="nowrap"]
|
|
----
|
|
c:\> kcadm config credentials --server http://localhost:8080/auth --realm demo --user admin --client admin
|
|
c:\> kcadm create realms -s realm=demorealm -s enabled=true -o
|
|
c:\> kcadm create clients -r demorealm -s clientId=my_client -s "redirectUris=[\"http://localhost:8980/myapp/*\"]" -i > clientid.txt
|
|
c:\> set /p CID=<clientid.txt
|
|
c:\> kcadm get clients/%CID%/installation/providers/keycloak-oidc-keycloak-json
|
|
----
|
|
|
|
. In a production environment, you access {project_name} with `https:` to avoid exposing tokens to network sniffers. If a server's certificate is not issued by one of the trusted certificate authorities (CAs) that are included in Java's default certificate truststore, prepare a [filename]`truststore.jks` file and instruct the Admin CLI to use it.
|
|
+
|
|
For example, on:
|
|
|
|
* Linux:
|
|
+
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks
|
|
----
|
|
+
|
|
* Windows:
|
|
+
|
|
[options="nowrap"]
|
|
----
|
|
c:\> kcadm config truststore --trustpass %PASSWORD% %HOMEPATH%\.keycloak\truststore.jks
|
|
----
|
|
|
|
|
|
=== Authenticating
|
|
|
|
When you log in with the Admin CLI, you specify a server endpoint URL and a realm, and then you specify a username. Another option is to specify only a client ID, which results in using a special "service account". When you log in using a username, you must use a password for the specified user. When you log in using a client ID, you only need the client secret, not the user password. You could also use [command]`Signed JWT` instead of the client secret.
|
|
|
|
Make sure the account used for the session has the proper permissions to invoke Admin REST API operations. For example, the `realm-admin` role of the `realm-management` client allows the user to administer the realm within which the user is defined.
|
|
|
|
There are two primary mechanisms for authentication. One mechanism uses [command]`kcadm config credentials` to start an authenticated session.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh config credentials --server http://localhost:8080/auth --realm master --user admin --password admin
|
|
----
|
|
|
|
This approach maintains an authenticated session between the [command]`kcadm` command invocations by saving the obtained access token and the associated refresh token. It may also maintain other secrets in a private configuration file. See <<_working_with_alternative_configurations, next chapter>> for more information on the configuration file.
|
|
|
|
The second approach only authenticates each command invocation for the duration of that invocation. This approach increases the load on the server and the time spent with roundtrips obtaining tokens. The benefit of this approach is not needing to save any tokens between invocations, which means nothing is saved to disk. This mode is used when the [command]`--no-config` argument is specified.
|
|
|
|
For example, when performing an operation, we specify all the information required for authentication.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh get realms --no-config --server http://localhost:8080/auth --realm master --user admin --password admin
|
|
----
|
|
|
|
Run the [command]`kcadm.sh help` command for more information on using the Admin CLI.
|
|
|
|
Run the [command]`kcadm.sh config credentials --help` command for more information about starting an authenticated session.
|
|
|
|
|
|
[[_working_with_alternative_configurations]]
|
|
=== Working with alternative configurations
|
|
|
|
By default, the Admin CLI automatically maintains a configuration file called [filename]`kcadm.config` located under the user's home directory, which is the full path name [filename]`$HOME/.keycloak/kcadm.config`. On Windows, the full path name is [filename]`%HOMEPATH%\.keycloak\kcadm.config`.
|
|
|
|
You can use the [command]`--config` option to point to a different file or location so you can maintain multiple authenticated sessions in parallel.
|
|
|
|
[NOTE]
|
|
====
|
|
It is best to perform operations tied to a single configuration file from a single thread.
|
|
====
|
|
|
|
Make sure you do not make the configuration file visible to other users on the system. It contains access tokens and secrets that should be kept private. By default, the [filename]`~/.keycloak` directory and its content are created automatically with proper access limits. If the directory already exists with non-default permissions, those access tokens and secrets will not be updated.
|
|
|
|
Consider avoiding storing secrets inside a configuration file, even though it is less convenient and you have to make more token requests. If you choose to not store secrets, you can use the [command]`--no-config` option with all your commands and specify all the authentication information needed by the [command]`config credentials` command with each [command]`kcadm` invocation.
|
|
|
|
|
|
=== Basic operations and resource URIs
|
|
|
|
The Admin CLI allows you to generically perform CRUD operations against Admin REST API endpoints in with additional commands that simplify performing certain tasks.
|
|
|
|
The main usage pattern is listed below, where the operations [command]`create`, [command]`get`, [command]`update`, and [command]`delete` are mapped to the HTTP verbs POST, GET, PUT, and DELETE, respectively.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh create ENDPOINT [ARGUMENTS]
|
|
$ kcadm.sh get ENDPOINT [ARGUMENTS]
|
|
$ kcadm.sh update ENDPOINT [ARGUMENTS]
|
|
$ kcadm.sh delete ENDPOINT [ARGUMENTS]
|
|
----
|
|
|
|
ENDPOINT is a target resource URI and can either be absolute (starting with `http:` or `https:`) or relative, used to compose an absolute URL of the following format.
|
|
[options="nowrap"]
|
|
----
|
|
SERVER_URI/admin/realms/REALM/ENDPOINT
|
|
----
|
|
|
|
For example, if you authenticate against the server http://localhost:8080/auth and realm is [filename]`master`, then using [filename]`users` as ENDPOINT results in the resource URL http://localhost:8080/auth/admin/realms/master/users.
|
|
|
|
If you set ENDPOINT to [filename]`clients`, the effective resource URI would be http://localhost:8080/auth/admin/realms/master/clients.
|
|
|
|
There is a [filename]`realms` endpoint that is treated slightly differently because it is the container for realms. It resolves to:
|
|
[options="nowrap"]
|
|
----
|
|
SERVER_URI/admin/realms
|
|
----
|
|
|
|
There is also a [filename]`serverinfo` endpoint, which is treated the same way because it is independent of realms.
|
|
|
|
When you authenticate as a user with realm-admin powers, you might need to perform operations on multiple realms. In that case, specify the [command]`-r` option to tell explicitly which realm the operation should be executed against. Instead of using REALM as specified via the [command]`--realm` option of [command]`kcadm.sh config credentials`, the TARGET_REALM is used.
|
|
|
|
[options="nowrap"]
|
|
----
|
|
SERVER_URI/admin/realms/TARGET_REALM/ENDPOINT
|
|
----
|
|
|
|
For example,
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh config credentials --server http://localhost:8080/auth --realm master --user admin --password admin
|
|
$ kcadm.sh create users -s username=testuser -s enabled=true -r demorealm
|
|
----
|
|
|
|
In this example, you start a session authenticated as the [filename]`admin` user in the [filename]`master` realm. You then perform a POST call against the resource URL [filename]`http://localhost:8080/auth/admin/realms/demorealm/users`.
|
|
|
|
The [command]`create` and [command]`update` commands send a JSON body to the server by default. You can use [filename]`-f FILENAME` to read a premade document from a file. When you can use [command]`-f -` option, the message body is read from standard input. You can also specify individual attributes and their values as seen in the previous [command]`create users` example. They are composed into a JSON body and sent to the server.
|
|
|
|
There are several ways to update a resource using the [command]`update` command. You can first determine the current state of a resource and save it to a file, and then edit that file and send it to the server for updating.
|
|
|
|
For example:
|
|
[options="nowraps"]
|
|
----
|
|
$ kcadm.sh get realms/demorealm > demorealm.json
|
|
$ vi demorealm.json
|
|
$ kcadm.sh update realms/demorealm -f demorealm.json
|
|
----
|
|
|
|
This method updates the resource on the server with all the attributes in the sent JSON document.
|
|
|
|
Another option is to perform an on-the-fly update using the [command]`-s, --set` options to set new values.
|
|
|
|
For example:
|
|
[options="nowraps"]
|
|
----
|
|
$ kcadm.sh update realms/demorealm -s enabled=false
|
|
----
|
|
|
|
That method only updates the [command]`enabled` attribute to `false`.
|
|
|
|
By default, the [commamd]`update` operation first performs a [command]`get` and then merges the new attribute values with existing values. This is the preferred behavior. In some cases, the endpoint may support [command]`PUT` but not [command]`GET`. You can use [command]`-n` option to perform a "no-merge" update, which performs a [command]`PUT` without first doing a [command]`GET`.
|
|
|
|
|
|
=== Realm operations
|
|
|
|
==== Creating a new realm
|
|
|
|
Use the [command]`create` operation on the `realms` endpoint to create a new enabled realm, and set the attributes to `realm` and `enabled`.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh create realms -s realm=demorealm -s enabled=true
|
|
----
|
|
|
|
A realm is not enabled by default. By enabling it, you can use a realm immediately for authentication.
|
|
|
|
A description for a new object can also be in a JSON format.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh create realms -f demorealm.json
|
|
----
|
|
|
|
You can send a JSON document with realm attributes directly from a file or piped to a standard input.
|
|
|
|
For example, on:
|
|
|
|
* Linux:
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh create realms -f - << EOF
|
|
{ "realm": "demorealm", "enabled": true }
|
|
EOF
|
|
----
|
|
|
|
* Windows:
|
|
[options="nowrap"]
|
|
----
|
|
c:\> echo { "realm": "demorealm", "enabled": true } | kcadm create realms -f -
|
|
----
|
|
|
|
|
|
==== Listing existing realms
|
|
|
|
The following command returns a list of all realms.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh get realms
|
|
----
|
|
|
|
[NOTE]
|
|
====
|
|
A list of realms is additionally filtered on the server to return only realms a user can see.
|
|
====
|
|
|
|
Returning the entire realm description often provides too much information. Most users are interested only in a subset of attributes, such as realm name and whether the realm is enabled. You can specify which attributes to return by using the [command]`--fields` option.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh get realms --fields realm,enabled
|
|
----
|
|
|
|
You can also display the result as comma separated values.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh get realms --fields realm --format csv --noquotes
|
|
----
|
|
|
|
==== Getting a specific realm
|
|
|
|
You append an ID to a collection URI to get an individual item of a collection, as is common for REST web services.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh get realms/master
|
|
----
|
|
|
|
|
|
==== Updating a realm
|
|
|
|
. Use the [command]`-s` option to set new values for the attributes when you want to change only some of the realm's attributes.
|
|
+
|
|
For example:
|
|
+
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh update realms/demorealm -s enabled=false
|
|
----
|
|
. If you want to set all writable attributes with new values, perform a [command]`get`, edit the current values in the JSON file, and resubmit.
|
|
+
|
|
For example:
|
|
+
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh get realms/demorealm > demorealm.json
|
|
$ vi demorealm.json
|
|
$ kcadm.sh update realms/demorealm -f demorealm.json
|
|
----
|
|
|
|
|
|
==== Deleting a realm
|
|
|
|
Run the following command to delete a realm.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh delete realms/demorealm
|
|
----
|
|
|
|
|
|
==== Turning on all login page options for the realm
|
|
|
|
Set the attributes controlling specific capabilities to `true`.
|
|
|
|
For example:
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh update realms/demorealm -s registrationAllowed=true -s registrationEmailAsUsername=true -s rememberMe=true -s verifyEmail=true -s resetPasswordAllowed=true -s editUsernameAllowed=true
|
|
----
|
|
|
|
|
|
==== Listing the realm keys
|
|
|
|
Use the [command] `get` operation on the [filename]`keys` endpoint of the target realm.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh get keys -r demorealm
|
|
----
|
|
|
|
|
|
==== Generating new realm keys
|
|
|
|
. Get the `ID` of the target realm before adding a new RSA-generated key pair.
|
|
+
|
|
For example:
|
|
+
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh get realms/demorealm --fields id --format csv --noquotes
|
|
----
|
|
. Add a new key provider with a higher priority than the existing providers as revealed by [command]`kcadm.sh get keys -r demorealm`.
|
|
+
|
|
For example, on:
|
|
+
|
|
* Linux:
|
|
+
|
|
[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"]'
|
|
----
|
|
* Windows:
|
|
+
|
|
[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\"]"
|
|
----
|
|
. Set the `parentId` attribute to the value of target realm's `ID`.
|
|
+
|
|
The newly added key should now become the active key as revealed by [command]`kcadm.sh get keys -r demorealm`.
|
|
|
|
|
|
==== Adding new realm keys from a Java Key Store file
|
|
|
|
. Add a new key provider to add a new key pair already prepared as a JKS file on the server.
|
|
+
|
|
For example, on:
|
|
+
|
|
* Linux:
|
|
+
|
|
[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.alias=["localhost"]'
|
|
----
|
|
* Windows:
|
|
+
|
|
[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.alias=[\"localhost\"]"
|
|
----
|
|
. Make sure to change the attribute values for `keystore`, `keystorePassword`, `keyPassword`, and `alias` to match your specific keystore.
|
|
. Set the `parentId` attribute to the value of target realm's `ID`.
|
|
|
|
|
|
==== Making the key passive or disabling the key
|
|
|
|
. Identify the key you want to make passive
|
|
+
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh get keys -r demorealm
|
|
----
|
|
. Use the key's `providerId` attribute to construct an endpoint URI: [filename]`components/PROVIDER_ID`.
|
|
. Perform an [command]`update`.
|
|
+
|
|
For example, on:
|
|
|
|
* Linux:
|
|
+
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh update components/PROVIDER_ID -r demorealm -s 'config.active=["false"]'
|
|
----
|
|
* Windows:
|
|
+
|
|
[options="nowrap"]
|
|
----
|
|
c:\> kcadm update components/PROVIDER_ID -r demorealm -s "config.active=[\"false\"]"
|
|
----
|
|
+
|
|
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"]`.
|
|
|
|
|
|
==== Deleting an old key
|
|
|
|
. Make sure the key you are deleting has been passive and disabled to prevent any existing tokens held by applications and users from abruptly failing to work.
|
|
. Identify the key you want to make passive.
|
|
+
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh get keys -r demorealm
|
|
----
|
|
. Use the `providerId` of that key to perform a delete.
|
|
+
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh delete components/PROVIDER_ID -r demorealm
|
|
----
|
|
|
|
|
|
==== Configuring event logging for a realm
|
|
|
|
Use the [command]`update` command on the [filename]`events/config` endpoint.
|
|
|
|
The `eventsListeners` attribute contains a list of EventListenerProviderFactory IDs that specify all event listeners receiving events. Separately, there are attributes that control a built-in event storage, which allows querying past events via the Admin REST API. There is separate control over logging of service calls (`eventsEnabled`) and auditing events triggered during Admin Console or Admin REST API (`adminEventsEnabled`). You may want to set up expiry of old events so that your database does not fill up; `eventsExpiration` is set to time-to-live expressed in seconds.
|
|
|
|
Here is an example of setting up a built-in event listener that receives all the events and logs them through jboss-logging. (Using a logger called `org.keycloak.events`, error events are logged as `WARN`, and others are logged as `DEBUG`.)
|
|
|
|
For example, on:
|
|
|
|
* Linux:
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh update events/config -r demorealm -s 'eventsListeners=["jboss-logging"]'
|
|
----
|
|
* Windows:
|
|
[options="nowrap"]
|
|
----
|
|
c:\> kcadm update events/config -r demorealm -s "eventsListeners=[\"jboss-logging\"]"
|
|
----
|
|
|
|
Here is an example of turning on storage of all available ERROR events—not including auditing events—for 2 days so they can be retrieved via Admin REST.
|
|
|
|
For example, on:
|
|
|
|
* Linux:
|
|
[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
|
|
----
|
|
* Windows:
|
|
[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
|
|
----
|
|
|
|
Here is an example of how to reset stored event types to *all available event types*; setting to empty list is the same as enumerating all.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh update events/config -r demorealm -s enabledEventTypes=[]
|
|
----
|
|
|
|
Here is an example of how to enable storage of auditing events.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh update events/config -r demorealm -s adminEventsEnabled=true -s adminEventsDetailsEnabled=true
|
|
----
|
|
|
|
Here is an example of how to get the last 100 events; they are ordered from newest to oldest.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh get events --offset 0 --limit 100
|
|
----
|
|
|
|
Here is an example of how to delete all saved events.
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm delete events
|
|
----
|
|
|
|
|
|
==== Flushing the caches
|
|
|
|
. Use the [command]`create` operation and one of the following endpoints: [filename]`clear-realm-cache`, [filename]`clear-user-cache`, or [filename]`clear-keys-cache`.
|
|
. Set `realm` to the same value as the target realm.
|
|
+
|
|
For example:
|
|
+
|
|
[options="nowrap"]
|
|
----
|
|
$ kcadm.sh create clear-realm-cache -r demorealm -s realm=demorealm
|
|
$ kcadm.sh create clear-user-cache -r demorealm -s realm=demorealm
|
|
$ kcadm.sh create clear-keys-cache -r demorealm -s realm=demorealm
|
|
----
|
|
|
|
|
|
=== Role operations
|
|
|
|
==== Creating a realm role
|
|
|
|
To create a realm role use `roles` endpoint:
|
|
|
|
$ kcadm.sh create roles -r demorealm -s name=user -s 'description=Regular user with limited set of permissions'
|
|
|
|
|
|
Creating a client role::
|
|
|
|
To create a client role identify the client first - use `get` to list available clients:
|
|
|
|
$ kcadm.sh get clients -r demorealm --fields id,clientId
|
|
|
|
Then, create a new role by using client's `id` attribute to construct an endpoint uri - `clients/ID/roles`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh create clients/a95b6af3-0bdc-4878-ae2e-6d61a4eca9a0/roles -r demorealm -s name=editor -s 'description=Editor can edit, and publish any article'
|
|
|
|
|
|
Listing realm roles::
|
|
|
|
To list existing realm roles use `get` command on `roles` endpoint:
|
|
|
|
$ kcadm.sh get roles -r demorealm
|
|
|
|
You can also use `get-roles` command:
|
|
|
|
$ kcadm.sh get-roles -r demorealm
|
|
|
|
|
|
Listing client roles::
|
|
|
|
There is a dedicated `get-roles` command to simplify listing of both realm and client roles. It is an extension of `get` command and so it behaves
|
|
the same with additional semantics for listing roles.
|
|
|
|
To list client roles use `get-roles` command, passing it either `clientId` (via `--cclientid` option) or `id` (via `--cid` option) to identify the client.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --cclientid realm-management
|
|
|
|
|
|
|
|
Getting a specific realm role::
|
|
|
|
Use `get` command, and role `name` to construct an endpoint uri for a specific realm role - `roles/ROLE_NAME`
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get roles/user -r demorealm
|
|
|
|
Where `user` is the name of existing role.
|
|
|
|
Alternatively, use special `get-roles` command, passing it role `name` (via `--rolename` option) or `id` (via `--roleid` option).
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --rolename user
|
|
|
|
|
|
|
|
Getting a specific client role::
|
|
|
|
Use a dedicated `get-roles` command, passing it either `clientId` (via `--cclientid` option) or `id` (via `--cid` option) to identify the client,
|
|
and passing it either role `name` (via `--rolename` option) or 'id' (via `--roleid`) to identify a specific client role:
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --cclientid realm-management --rolename manage-clients
|
|
|
|
|
|
Updating a realm role::
|
|
|
|
Use `update` operation with the same endpoint uri as for getting a specific realm role. For example:
|
|
|
|
$ kcadm.sh update roles/user -r demorealm -s 'description=Role representing a regular user'
|
|
|
|
|
|
Updating a client role::
|
|
|
|
Use `update` operation with the same endpoint uri as for getting a specific client role. For example:
|
|
|
|
$ kcadm.sh update clients/a95b6af3-0bdc-4878-ae2e-6d61a4eca9a0/roles/editor -r demorealm -s 'description=User that can edit, and publish articles'
|
|
|
|
|
|
Deleting a realm role::
|
|
|
|
Use `delete` operation with the same endpoint uri as for getting a specific realm role. For example:
|
|
|
|
$ kcadm.sh delete roles/user -r demorealm
|
|
|
|
|
|
Deleting a client role::
|
|
|
|
Use `delete` operation with the same endpoint uri as for getting a specific client role. For example:
|
|
|
|
$ kcadm.sh delete clients/a95b6af3-0bdc-4878-ae2e-6d61a4eca9a0/roles/editor -r demorealm
|
|
|
|
|
|
Listing assigned, available and effective realm roles for a composite role::
|
|
|
|
Use a dedicated `get-roles` command.
|
|
|
|
To list *assigned* realm roles for the composite role you can specify the target composite role by either `name` (via --rname option) or `id` (via --rid option).
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --rname testrole
|
|
|
|
|
|
To list *effective* realm roles, use additional `--effective` option.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --rname testrole --effective
|
|
|
|
|
|
To list realm roles that can still be added to the composite role, use `--available` option instead.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --rname testrole --available
|
|
|
|
|
|
Listing assigned, available, and effective client roles for a composite role::
|
|
|
|
Use a dedicated `get-roles` command.
|
|
|
|
To list *assigned* client roles for the composite role you can specify the target composite role by either `name` (via --rname option)
|
|
or `id` (via --rid option), and client by either `clientId` (via --cclientid option) or `id` (via --cid option).
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --rname testrole --cclientid realm-management
|
|
|
|
|
|
To list *effective* realm roles, use additional `--effective` option.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --rname testrole --cclientid realm-management --effective
|
|
|
|
|
|
To list realm roles that can still be added to the target composite role, use `--available` option instead.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --rname testrole --cclientid realm-management --available
|
|
|
|
|
|
Adding realm roles to a composite role::
|
|
|
|
There is a dedicated `add-roles` command that can be used for adding both realm roles and client roles.
|
|
|
|
For example, to add 'user' role to composite role 'testrole' :
|
|
|
|
$ kcadm.sh add-roles --rname testrole --rolename user -r demorealm
|
|
|
|
|
|
Removing realm roles from a composite role::
|
|
|
|
There is a dedicated `remove-roles` command that can be used to remove both realm roles and client roles.
|
|
|
|
For example, to remove 'user' role from target composite role 'testrole':
|
|
|
|
$ kcadm.sh remove-roles --rname testrole --rolename user -r demorealm
|
|
|
|
|
|
Adding client roles to a realm role::
|
|
|
|
This is how you create or modify a composite realm role.
|
|
|
|
Use a dedicated `add-roles` command that can be used for adding both realm roles and client roles.
|
|
|
|
For example, to add to `testrole` composite role two roles defined on client `realm-management` - `create-client` role and `view-users` role:
|
|
|
|
$ kcadm.sh add-roles -r demorealm --rname testrole --cclientid realm-management --rolename create-client --rolename view-users
|
|
|
|
|
|
Adding client roles to a client role::
|
|
|
|
This is how you create or modify a composite client role.
|
|
|
|
First, find out an `id` of the composite client role - by using `get-roles` command for example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --cclientid test-client --rolename operations
|
|
|
|
Let's assume that there exists a client with "clientId": 'test-client', a client role called 'support', and another client role - that will become composite role - that has an "id": "fc400897-ef6a-4e8c-872b-1581b7fa8a71", "name":"operations".
|
|
|
|
In this example 'operations' is our target composite role, and we just got its `id`.
|
|
|
|
We can now add another role to it:
|
|
|
|
$ kcadm.sh add-roles -r demorealm --cclientid test-client --rid fc400897-ef6a-4e8c-872b-1581b7fa8a71 --rolename support
|
|
|
|
|
|
Afterwards all the roles of a composite role can be listed by using `get-roles --all`. For example:
|
|
|
|
$ kcadm.sh get-roles --rid fc400897-ef6a-4e8c-872b-1581b7fa8a71 --all
|
|
|
|
|
|
Removing client roles from a composite role::
|
|
|
|
Use a dedicated `remove-roles` command.
|
|
|
|
For example, to remove from `testrole` composite role two roles defined on client `realm management` - `create-client` role and `view-users` role:
|
|
|
|
$ kcadm.sh remove-roles -r demorealm --rname testrole --cclientid realm-management --rolename create-client --rolename view-users
|
|
|
|
|
|
=== Client operations
|
|
|
|
Creating a client::
|
|
|
|
To create a new client perform `create` command on `clients` endpoint. For example:
|
|
|
|
$ kcadm.sh create clients -r demorealm -s clientId=myapp -s enabled=true
|
|
|
|
If you want to set a secret for adapters to authenticate specify a `secret`. For example:
|
|
|
|
$ kcadm.sh create clients -r demorealm -s clientId=myapp -s enabled=true -s clientAuthenticatorType=client-secret -s secret=d0b8122f-8dfb-46b7-b68a-f5cc4e25d000
|
|
|
|
|
|
Listing clients::
|
|
|
|
Use `get` operation on `clients` endpoint. For example:
|
|
|
|
$ kcadm.sh get clients -r demorealm --fields id,clientId
|
|
|
|
Here we filter the output to only list `id`, and `clientId` attributes.
|
|
|
|
|
|
Getting a specific client::
|
|
|
|
Use client's `id` to construct an endpoint uri targeting specific client - `clients/ID`. For example:
|
|
|
|
$ kcadm.sh get clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm
|
|
|
|
|
|
Getting current secret for specific client::
|
|
|
|
Use client's `id` to construct an endpoint uri - `clients/ID/client-secret`. For example
|
|
|
|
$ kcadm.sh get clients/$CID/client-secret
|
|
|
|
|
|
Getting adapter configuration file (keycloak.json) for specific client::
|
|
|
|
Use client's `id` to construct an endpoint uri targeting specific client - `clients/ID/installation/providers/keycloak-oidc-keycloak-json`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get clients/c7b8547f-e748-4333-95d0-410b76b3f4a3/installation/providers/keycloak-oidc-keycloak-json -r demorealm
|
|
|
|
|
|
Getting Wildfly subsystem adapter configuration for specific client::
|
|
|
|
Use client's `id` to construct an endpoint uri targeting specific client - `clients/ID/installation/providers/keycloak-oidc-jboss-subsystem`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get clients/c7b8547f-e748-4333-95d0-410b76b3f4a3/installation/providers/keycloak-oidc-jboss-subsystem -r demorealm
|
|
|
|
|
|
Updating a client::
|
|
|
|
Use `update` operation with the same endpoint uri as for getting a specific client. For example on Linux:
|
|
|
|
$ 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
|
|
|
|
Or on Windows:
|
|
|
|
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
|
|
|
|
Deleting a client::
|
|
|
|
Use `delete` operation with the same endpoint uri as for getting a specific client. For example:
|
|
|
|
$ kcadm.sh delete clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm
|
|
|
|
|
|
=== User operations
|
|
|
|
Creating a user::
|
|
|
|
To create a new user perform `create` operation on `users` endpoint. For example:
|
|
|
|
$ kcadm.sh create users -r demorealm -s username=testuser -s enabled=true
|
|
|
|
|
|
Listing users::
|
|
|
|
Use `users` endpoint to list users. Number of users may be large, and you may want to limit how many are returned:
|
|
|
|
$ kcadm.sh get users -r demorealm --offset 0 --limit 1000
|
|
|
|
It's also possible to filter users by `username`, `firstName`, `lastName`, or `email`. For example:
|
|
|
|
$ kcadm.sh get users -r demorealm -q email=google.com
|
|
$ kcadm.sh get users -r demorealm -q username=testuser
|
|
|
|
Note that filtering doesn't use exact matching. For example, the above would match the value of `username` attribute against '\*testuser*' pattern.
|
|
|
|
You can also filter across multiple attributes by specifying multiple `-q` options, which would return only users
|
|
that match condition for all the attributes.
|
|
|
|
|
|
Getting a specific user::
|
|
|
|
Use user's `id` to compose an endpoint uri - `users/USER_ID`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm
|
|
|
|
|
|
Updating a user::
|
|
|
|
Use `update` operation with the same endpoint uri as for getting a specific user. For example on Linux:
|
|
|
|
$ kcadm.sh update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm -s 'requiredActions=["VERIFY_EMAIL","UPDATE_PROFILE","CONFIGURE_TOTP","UPDATE_PASSWORD"]'
|
|
|
|
Or on Windows:
|
|
|
|
c:\> kcadm update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm -s "requiredActions=[\"VERIFY_EMAIL\",\"UPDATE_PROFILE\",\"CONFIGURE_TOTP\",\"UPDATE_PASSWORD\"]"
|
|
|
|
Deleting a user::
|
|
|
|
Use `delete` operation with the same endpoint uri as for getting a specific user. For example:
|
|
|
|
$ kcadm.sh delete users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm
|
|
|
|
|
|
Resetting user's password::
|
|
|
|
There is a dedicated `set-password` command specifically to reset user's password. For example:
|
|
|
|
$ kcadm.sh set-password -r demorealm --username testuser --new-password NEWPASSWORD --temporary
|
|
|
|
That will set a temporary password for the user, which they will have to change the next time they login.
|
|
|
|
You can use `--userid` if you want to specify the user by using `id` attribute.
|
|
|
|
|
|
The same can be achieved using `update` operation on an endpoint constructed from one for getting a specific user - `users/USER_ID/reset-password`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2/reset-password -r demorealm -s type=password -s value=NEWPASSWORD -s temporary=true -n
|
|
|
|
The last parameter (`-n`) ensures that only PUT is performed without a prior GET. In this case it is necessary since `reset-password` endpoint doesn't support GET.
|
|
|
|
|
|
|
|
Listing assigned, available, and effective realm roles for a user::
|
|
|
|
Use a dedicated `get-roles` command.
|
|
|
|
To list *assigned* realm roles for the user you can specify the target user by either `username` or `id`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --uusername testuser
|
|
|
|
|
|
To list *effective* realm roles, use additional `--effective` option.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --uusername testuser --effective
|
|
|
|
|
|
To list realm roles that can still be added to the user, use `--available` option instead.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --uusername testuser --available
|
|
|
|
|
|
Listing assigned, available, and effective client roles for a user::
|
|
|
|
Use a dedicated `get-roles` command.
|
|
|
|
To list *assigned* client roles for the user you can specify the target user by either `username` (via --uusername option) or `id` (via --uid option),
|
|
and client by either `clientId` (via --cclientid option) or `id` (via --cid option).
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --uusername testuser --cclientid realm-management
|
|
|
|
|
|
To list *effective* realm roles, use additional `--effective` option.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --uusername testuser --cclientid realm-management --effective
|
|
|
|
|
|
To list realm roles that can still be added to the user, use `--available` option instead.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --uusername testuser --cclientid realm-management --available
|
|
|
|
|
|
Adding realm roles to a user::
|
|
|
|
Use a dedicated `add-roles` command.
|
|
|
|
For example, to add 'user' role to user 'testuser' :
|
|
|
|
$ kcadm.sh add-roles --username testuser --rolename user -r demorealm
|
|
|
|
|
|
Removing realm roles from a user::
|
|
|
|
Use a dedicated `remove-roles` command.
|
|
|
|
For example, to remove 'user' role from user 'testuser':
|
|
|
|
$ kcadm.sh remove-roles --username testuser --rolename user -r demorealm
|
|
|
|
|
|
Adding client roles to a user::
|
|
|
|
Use a dedicated `add-roles` command.
|
|
|
|
For example, to add to user `testuser` two roles defined on client `realm management` - `create-client` role and `view-users` role:
|
|
|
|
$ kcadm.sh add-roles -r demorealm --uusername testuser --cclientid realm-management --rolename create-client --rolename view-users
|
|
|
|
|
|
Removing client roles from a user::
|
|
|
|
Use a dedicated `remove-roles` command.
|
|
|
|
For example, to remove from user `testuser` two roles defined on client `realm management` - `create-client` role and `view-users` role:
|
|
|
|
$ kcadm.sh remove-roles -r demorealm --uusername testuser --cclientid realm-management --rolename create-client --rolename view-users
|
|
|
|
|
|
Listing user's sessions::
|
|
|
|
First identify user's `id` then use it to compose an endpoint uri - `users/ID/sessions`.
|
|
|
|
Now use `get` to retrieve a list of user's sessions.
|
|
|
|
For example:
|
|
|
|
$kcadm get users/6da5ab89-3397-4205-afaa-e201ff638f9e/sessions
|
|
|
|
|
|
Logging out user from specific session::
|
|
|
|
To logout the user's session first get session's `id` as described above.
|
|
|
|
Use session's `id` to compose an endpoint uri - `sessions/ID`.
|
|
|
|
Then use `delete` to invalidate it. For example:
|
|
|
|
$ kcadm.sh delete sessions/d0eaa7cc-8c5d-489d-811a-69d3c4ec84d1
|
|
|
|
|
|
|
|
Logging out user from all sessions::
|
|
|
|
You need user's `id` to construct an endpoint uri - `users/ID/logout`.
|
|
|
|
Use 'create' to perform POST on that endpoint uri:
|
|
|
|
$ kcadm.sh create users/6da5ab89-3397-4205-afaa-e201ff638f9e/logout -r demorealm -s realm=demorealm -s user=6da5ab89-3397-4205-afaa-e201ff638f9e
|
|
|
|
|
|
|
|
=== Group operations
|
|
|
|
Creating a group::
|
|
|
|
Use `create` operation on `groups` endpoint to create a new group:
|
|
|
|
$ kcadm.sh create groups -r demorealm -s name=Group
|
|
|
|
|
|
Listing groups::
|
|
|
|
Use `get` operation on `groups` endpoint to list groups:
|
|
|
|
$ kcadm.sh get groups -r demorealm
|
|
|
|
|
|
Getting a specific group::
|
|
|
|
Use group's `id` to construct an endpoint uri - groups/GROUP_ID:
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get groups/51204821-0580-46db-8f2d-27106c6b5ded -r demorealm
|
|
|
|
|
|
Updating a group::
|
|
|
|
Use `update` operation with the same endpoint uri as for getting a specific group. For example:
|
|
|
|
$ kcadm.sh update groups/51204821-0580-46db-8f2d-27106c6b5ded -s 'attributes.email=["group@example.com"]' -r demorealm
|
|
|
|
|
|
Deleting a group::
|
|
|
|
Use `delete` operation with the same endpoint uri as for getting a specific group. For example:
|
|
|
|
$ kcadm.sh delete groups/51204821-0580-46db-8f2d-27106c6b5ded -r demorealm
|
|
|
|
|
|
Creating a sub-group::
|
|
|
|
Find 'id' of the parent group - by listing groups for example. Use that `id` to construct an endpoint uri - groups/GROUP_ID/children:
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh create groups/51204821-0580-46db-8f2d-27106c6b5ded/children -r demorealm -s name=SubGroup
|
|
|
|
|
|
Moving a group under another group::
|
|
|
|
Find 'id' of existing parent group, and of existing child group. Use parent group's `id` to construct and endpoint uri - groups/PARENT_GROUP_ID/children.
|
|
|
|
Perform 'create' operation on this endpoint, and pass child group `id` as JSON body. For example:
|
|
|
|
$ kcadm.sh create groups/51204821-0580-46db-8f2d-27106c6b5ded/children -r demorealm -s id=08d410c6-d585-4059-bb07-54dcb92c5094
|
|
|
|
|
|
Get groups for specific user::
|
|
|
|
To get user's membership in groups, use user's `id` to compose an endpoint URI - `users/USER_ID/groups`
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get users/b544f379-5fc4-49e5-8a8d-5cfb71f46f53/groups -r demorealm
|
|
|
|
|
|
Adding user to a group::
|
|
|
|
To join user to a group use `update` operation with an endpoint uri composed from user's `id`, and group's `id` - users/USER_ID/groups/GROUP_ID.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh update users/b544f379-5fc4-49e5-8a8d-5cfb71f46f53/groups/ce01117a-7426-4670-a29a-5c118056fe20 -r demorealm -s realm=demorealm -s userId=b544f379-5fc4-49e5-8a8d-5cfb71f46f53 -s groupId=ce01117a-7426-4670-a29a-5c118056fe20 -n
|
|
|
|
|
|
Removing user from a group::
|
|
|
|
To remove user from a group use `delete` operation on the same endpoint uri as used for adding user to a group - users/USER_ID/groups/GROUP_ID.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh delete users/b544f379-5fc4-49e5-8a8d-5cfb71f46f53/groups/ce01117a-7426-4670-a29a-5c118056fe20 -r demorealm
|
|
|
|
|
|
|
|
Listing assigned, available, and effective realm roles for a group::
|
|
|
|
Use a dedicated 'get-roles' command.
|
|
|
|
To list *assigned* realm roles for the group you can specify the target group by `name` (via `--gname` option),
|
|
`path` (via `--gpath` option), or `id` (via `--gid` option).
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --gname Group
|
|
|
|
|
|
To list *effective* realm roles, use additional `--effective` option.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --gname Group --effective
|
|
|
|
|
|
To list realm roles that can still be added to the group, use `--available` option instead.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --gname Group --available
|
|
|
|
|
|
Listing assigned, available, and effective client roles for a group::
|
|
|
|
Use a dedicated 'get-roles' command.
|
|
|
|
To list *assigned* client roles for the user you can specify the target group by either `name` (via --gname option) or `id` (via `--gid` option),
|
|
and client by either `clientId` (via `--cclientid` option) or `id` (via `--id` option).
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management
|
|
|
|
|
|
To list *effective* realm roles, use additional `--effective` option.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management --effective
|
|
|
|
|
|
To list realm roles that can still be added to the group, use `--available` option instead.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management --available
|
|
|
|
|
|
=== Identity Providers operations
|
|
|
|
|
|
Listing available identity providers::
|
|
|
|
Use `serverinfo` endpoint to list available identity providers. For example:
|
|
|
|
$ kcadm.sh get serverinfo -r demorealm --fields 'identityProviders(*)'
|
|
|
|
Note that `serverinfo` endpoint is handled similarly to `realms` endpoint in that it is not resolved
|
|
relative to target realm, because it exists outside any specific realm.
|
|
|
|
|
|
Listing configured identity providers::
|
|
|
|
Use `identity-provider/instances` endpoint. For example:
|
|
|
|
$ kcadm.sh get identity-provider/instances -r demorealm --fields alias,providerId,enabled
|
|
|
|
|
|
Getting a specific configured identity provider::
|
|
|
|
To get a specific identity provider use `alias` attribute of identity provider to construct an endpoint uri - `identity-provider/instances/ALIAS`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get identity-provider/instances/facebook -r demorealm
|
|
|
|
|
|
Removing a specific configured identity provider::
|
|
|
|
Use `delete` operation with the same endpoint uri as for getting a specific configured identity provider. For example:
|
|
|
|
$ kcadm.sh delete identity-provider/instances/facebook -r demorealm
|
|
|
|
|
|
Configuring a Keycloak OpenID Connect identity provider::
|
|
|
|
Use `keycloak-oidc` as `providerId` when creating a new identity provider instance.
|
|
|
|
Provide config attributes `authorizationUrl`, `tokenUrl`, `clientId`, and `clientSecret`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh create identity-provider/instances -r demorealm -s alias=keycloak-oidc -s providerId=keycloak-oidc -s enabled=true -s 'config.useJwksUrl="true"' -s config.authorizationUrl=http://localhost:8180/auth/realms/demorealm/protocol/openid-connect/auth -s config.tokenUrl=http://localhost:8180/auth/realms/demorealm/protocol/openid-connect/token -s config.clientId=demo-oidc-provider -s config.clientSecret=secret
|
|
|
|
|
|
Configuring an OpenID Connect identity provider::
|
|
|
|
You configure the generic OpenID Connect provider the same way as Keycloak OpenID Connect provider, except that you set
|
|
`providerId` attribute value to `oidc`.
|
|
|
|
|
|
Configuring a SAML 2 identity provider::
|
|
|
|
Use `saml` as `providerId`. Provide `config` attributes - `singleSignOnServiceUrl`, `nameIDPolicyFormat`, and `signatureAlgorithm`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh create identity-provider/instances -r demorealm -s alias=saml -s providerId=saml -s enabled=true -s 'config.useJwksUrl="true"' -s config.singleSignOnServiceUrl=http://localhost:8180/auth/realms/saml-broker-realm/protocol/saml -s config.nameIDPolicyFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent -s config.signatureAlgorithm=RSA_SHA256
|
|
|
|
|
|
Configuring a Facebook identity provider::
|
|
|
|
Use `facebook` as `providerId`. Provide `config` attributes - `clientId` and `clientSecret`
|
|
as obtained from Facebook Developers application configuration page for your application.
|
|
|
|
$ kcadm.sh create identity-provider/instances -r demorealm -s alias=facebook -s providerId=facebook -s enabled=true -s 'config.useJwksUrl="true"' -s config.clientId=FACEBOOK_CLIENT_ID -s config.clientSecret=FACEBOOK_CLIENT_SECRET
|
|
|
|
|
|
Configuring a Google identity provider::
|
|
|
|
Use `google` as `providerId`. Provide `config` attributes - `clientId` and `clientSecret`
|
|
as obtained from Google Developers application configuration page for your application.
|
|
|
|
$ kcadm.sh create identity-provider/instances -r demorealm -s alias=google -s providerId=google -s enabled=true -s 'config.useJwksUrl="true"' -s config.clientId=GOOGLE_CLIENT_ID -s config.clientSecret=GOOGLE_CLIENT_SECRET
|
|
|
|
|
|
Configuring a Twitter identity provider::
|
|
|
|
Use `twitter` as `providerId`. Provide `config` attributes - `clientId` and `clientSecret`
|
|
as obtained from Twitter Application Management application configuration page for your application.
|
|
|
|
$ kcadm.sh create identity-provider/instances -r demorealm -s alias=google -s providerId=google -s enabled=true -s 'config.useJwksUrl="true"' -s config.clientId=TWITTER_API_KEY -s config.clientSecret=TWITTER_API_SECRET
|
|
|
|
|
|
Configuring a GitHub identity provider::
|
|
|
|
Use `github` as `providerId`. Provide `config` attributes - `clientId` and `clientSecret`
|
|
as obtained from GitHub Developer Application Settings page for your application.
|
|
|
|
$ kcadm.sh create identity-provider/instances -r demorealm -s alias=github -s providerId=github -s enabled=true -s 'config.useJwksUrl="true"' -s config.clientId=GITHUB_CLIENT_ID -s config.clientSecret=GITHUB_CLIENT_SECRET
|
|
|
|
|
|
Configuring a LinkedIn identity provider::
|
|
|
|
Use `linkedin` as `providerId`. Provide `config` attributes - `clientId` and `clientSecret`
|
|
as obtained from LinkedIn Developer Console application page for your application.
|
|
|
|
$ kcadm.sh create identity-provider/instances -r demorealm -s alias=linkedin -s providerId=linkedin -s enabled=true -s 'config.useJwksUrl="true"' -s config.clientId=LINKEDIN_CLIENT_ID -s config.clientSecret=LINKEDIN_CLIENT_SECRET
|
|
|
|
|
|
Configuring a Microsoft Live identity provider::
|
|
|
|
Use `microsoft` as `providerId`. Provide `config` attributes - `clientId` and `clientSecret`
|
|
as obtained from Microsoft Application Registration Portal page for your application.
|
|
|
|
$ kcadm.sh create identity-provider/instances -r demorealm -s alias=microsoft -s providerId=microsoft -s enabled=true -s 'config.useJwksUrl="true"' -s config.clientId=MICROSOFT_APP_ID -s config.clientSecret=MICROSOFT_PASSWORD
|
|
|
|
|
|
Configuring a StackOverflow identity provider::
|
|
|
|
Use `stackoverflow` as `providerId`. Provide `config` attributes - `clientId`, `clientSecret` and `key`
|
|
as obtained from Stack Apps OAuth page for your application.
|
|
|
|
$ kcadm.sh create identity-provider/instances -r demorealm -s alias=stackoverflow -s providerId=stackoverflow -s enabled=true -s 'config.useJwksUrl="true"' -s config.clientId=STACKAPPS_CLIENT_ID -s config.clientSecret=STACKAPPS_CLIENT_SECRET -s config.key=STACKAPPS_KEY
|
|
|
|
|
|
=== Storage Providers operations
|
|
|
|
Configuring a Kerberos storage provider::
|
|
|
|
Use `create` against `user-federation/instances` endpoint. Specify `kerberos` as a value of `providerName` attribute.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh create user-federation/instances -r demorealm -s providerName=kerberos -s priority=0 -s config.debug=false -s config.allowPasswordAuthentication=true -s 'config.editMode="UNSYNCED"' -s config.updateProfileFirstLogin=true -s config.allowKerberosAuthentication=true -s 'config.kerberosRealm="KEYCLOAK.ORG"' -s 'config.keyTab="http.keytab"' -s 'config.serverPrincipal="HTTP/localhost@KEYCLOAK.ORG"'
|
|
|
|
|
|
Configuring an LDAP user storage provider::
|
|
|
|
Use `create` against `components` endpoint. Specify `ldap` as a value of `providerId` attribute, and `org.keycloak.storage.UserStorageProvider` as value of `providerType` attribute. Provide realm `id` as value of `parentId` attribute.
|
|
|
|
For example, to create a Kerberos integrated LDAP provider:
|
|
|
|
$ kcadm.sh create components -r demorealm -s name=kerberos-ldap-provider -s providerId=ldap -s providerType=org.keycloak.storage.UserStorageProvider -s parentId=3d9c572b-8f33-483f-98a6-8bb421667867 -s 'config.priority=["1"]' -s 'config.fullSyncPeriod=["-1"]' -s 'config.changedSyncPeriod=["-1"]' -s 'config.cachePolicy=["DEFAULT"]' -s config.evictionDay=[] -s config.evictionHour=[] -s config.evictionMinute=[] -s config.maxLifespan=[] -s 'config.batchSizeForSync=["1000"]' -s 'config.editMode=["WRITABLE"]' -s 'config.syncRegistrations=["false"]' -s 'config.vendor=["other"]' -s 'config.usernameLDAPAttribute=["uid"]' -s 'config.rdnLDAPAttribute=["uid"]' -s 'config.uuidLDAPAttribute=["entryUUID"]' -s 'config.userObjectClasses=["inetOrgPerson, organizationalPerson"]' -s 'config.connectionUrl=["ldap://localhost:10389"]' -s 'config.usersDn=["ou=People,dc=keycloak,dc=org"]' -s 'config.authType=["simple"]' -s 'config.bindDn=["uid=admin,ou=system"]' -s 'config.bindCredential=["secret"]' -s 'config.searchScope=["1"]' -s 'config.useTruststoreSpi=["ldapsOnly"]' -s 'config.connectionPooling=["true"]' -s 'config.pagination=["true"]' -s 'config.allowKerberosAuthentication=["true"]' -s 'config.serverPrincipal=["HTTP/localhost@KEYCLOAK.ORG"]' -s 'config.keyTab=["http.keytab"]' -s 'config.kerberosRealm=["KEYCLOAK.ORG"]' -s 'config.debug=["true"]' -s 'config.useKerberosForPasswordAuthentication=["true"]'
|
|
|
|
|
|
Removing a user storage provider instance::
|
|
|
|
Use storage provider instance's `id` attribute to compose an endpoint uri - `components/ID`.
|
|
|
|
Perform `delete` operation against this endpoint. For example:
|
|
|
|
$ kcadm.sh delete components/3d9c572b-8f33-483f-98a6-8bb421667867 -r demorealm
|
|
|
|
|
|
Triggering synchronization of all users for specific user storage provider::
|
|
|
|
Use storage provider's `id` attribute to compose an endpoint uri - user-storage/ID_OF_USER_STORAGE_INSTANCE/sync
|
|
Add `action=triggerFullSync` query parameter and perform `create` command.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh create user-storage/b7c63d02-b62a-4fc1-977c-947d6a09e1ea/sync?action=triggerFullSync
|
|
|
|
|
|
Triggering synchronization of changed users for specific user storage provider::
|
|
|
|
Use storage provider's `id` attribute to compose an endpoint uri - user-storage/ID_OF_USER_STORAGE_INSTANCE/sync
|
|
Add `action=triggerChangedUsersSync` query parameter and use `create`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh create user-storage/b7c63d02-b62a-4fc1-977c-947d6a09e1ea/sync?action=triggerChangedUsersSync
|
|
|
|
|
|
Test LDAP user storage connectivity::
|
|
|
|
Perform `get` operation on `testLDAPConnection` endpoint. Provide query parameters `bindCredential`, `bindDn`, `connectionUrl`, and `useTruststoreSpi`, and set `action` query parameter to `testConnection`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get testLDAPConnection -q action=testConnection -q bindCredential=secret -q bindDn=uid=admin,ou=system -q connectionUrl=ldap://localhost:10389 -q useTruststoreSpi=ldapsOnly
|
|
|
|
|
|
Test LDAP user storage authentication::
|
|
|
|
Perform `get` operation on `testLDAPConnection` endpoint. Provide query parameters `bindCredential`, `bindDn`, `connectionUrl`, and `useTruststoreSpi`, and set `action` query parameter to `testAuthentication`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh get testLDAPConnection -q action=testAuthentication -q bindCredential=secret -q bindDn=uid=admin,ou=system -q connectionUrl=ldap://localhost:10389 -q useTruststoreSpi=ldapsOnly
|
|
|
|
|
|
|
|
=== Adding mappers
|
|
|
|
Adding a hardcoded role LDAP mapper::
|
|
|
|
Use `create` on `components` endpoint. Set `providerType` attribute to `org.keycloak.storage.ldap.mappers.LDAPStorageMapper`. Set `parentId` attribute to `id` of LDAP provider instance.
|
|
Set `providerId` attribute to `hardcoded-ldap-role-mapper`. Make sure to provide a value of `role` config parameter.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh create components -r demorealm -s name=hardcoded-ldap-role-mapper -s providerId=hardcoded-ldap-role-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config.role=["realm-management.create-client"]'
|
|
|
|
|
|
Adding a MS Active Directory mapper::
|
|
|
|
Use `create` on `components` endpoint. Set `providerType` attribute to `org.keycloak.storage.ldap.mappers.LDAPStorageMapper`. Set `parentId` attribute to `id` of LDAP provider instance.
|
|
Set `providerId` attribute to `msad-user-account-control-mapper`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh create components -r demorealm -s name=msad-user-account-control-mapper -s providerId=msad-user-account-control-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea
|
|
|
|
|
|
Adding an user attribute LDAP mapper::
|
|
|
|
Use `create` on `components` endpoint. Set `providerType` attribute to `org.keycloak.storage.ldap.mappers.LDAPStorageMapper`. Set `parentId` attribute to `id` of LDAP provider instance.
|
|
Set `providerId` attribute to `user-attribute-ldap-mapper`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh create components -r demorealm -s name=user-attribute-ldap-mapper -s providerId=user-attribute-ldap-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config."user.model.attribute"=["email"]' -s 'config."ldap.attribute"=["mail"]' -s 'config."read.only"=["false"]' -s 'config."always.read.value.from.ldap"=["false"]' -s 'config."is.mandatory.in.ldap"=["false"]'
|
|
|
|
|
|
Adding a group LDAP mapper::
|
|
|
|
Use `create` on `components` endpoint. Set `providerType` attribute to `org.keycloak.storage.ldap.mappers.LDAPStorageMapper`. Set `parentId` attribute to `id` of LDAP provider instance.
|
|
Set `providerId` attribute to `group-ldap-mapper`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh create components -r demorealm -s name=group-ldap-mapper -s providerId=group-ldap-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config."groups.dn"=[]' -s 'config."group.name.ldap.attribute"=["cn"]' -s 'config."group.object.classes"=["groupOfNames"]' -s 'config."preserve.group.inheritance"=["true"]' -s 'config."membership.ldap.attribute"=["member"]' -s 'config."membership.attribute.type"=["DN"]' -s 'config."groups.ldap.filter"=[]' -s 'config.mode=["LDAP_ONLY"]' -s 'config."user.roles.retrieve.strategy"=["LOAD_GROUPS_BY_MEMBER_ATTRIBUTE"]' -s 'config."mapped.group.attributes"=["admins-group"]' -s 'config."drop.non.existing.groups.during.sync"=["false"]' -s 'config.roles=["admins"]' -s 'config.groups=["admins-group"]' -s 'config.group=[]' -s 'config.preserve=["true"]' -s 'config.membership=["member"]'
|
|
|
|
|
|
Adding a full name LDAP mapper::
|
|
|
|
Use `create` on `components` endpoint. Set `providerType` attribute to `org.keycloak.storage.ldap.mappers.LDAPStorageMapper`. Set `parentId` attribute to `id` of LDAP provider instance.
|
|
Set `providerId` attribute to `full-name-ldap-mapper`.
|
|
|
|
For example:
|
|
|
|
$ kcadm.sh create components -r demorealm -s name=full-name-ldap-mapper -s providerId=full-name-ldap-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config."ldap.full.name.attribute"=["cn"]' -s 'config."read.only"=["false"]' -s 'config."write.only"=["true"]'
|
|
|
|
|
|
|
|
=== Authentication operations
|
|
|
|
|
|
Setting a password policy::
|
|
|
|
Set realm's `passwordPolicy` attribute to enumeration expression that includes the specific policy provider id, and optional configuration.
|
|
|
|
For example, to set password policy to default values - i.e.: 27500 hashing iterations, requiring at least one special character, at least one uppercase character,
|
|
at least one digit character, not be equal to user's `username`, and be at least 8 characters long you would use the following:
|
|
|
|
$ kcadm.sh update realms/demorealm -s 'passwordPolicy="hashIterations and specialChars and upperCase and digits and notUsername and length"'
|
|
|
|
If you want want to use values different from defaults, pass configuration in brackets.
|
|
|
|
For example, to set password policy to 25000 hash iterations, requiring at least two special characters, at least two uppercase characters, at least two lowercase characters, at least two digits, be at least nine characters long, not be equal to user's username, and not repeat for at least four changes back:
|
|
|
|
$ kcadm.sh update realms/demorealm -s 'passwordPolicy="hashIterations(25000) and specialChars(2) and upperCase(2) and lowerCase(2) and digits(2) and length(9) and notUsername and passwordHistory(4)"'
|
|
|
|
|
|
Getting the current password policy::
|
|
|
|
Get current realm configuration and filter out everything but `passwordPolicy` attribute.
|
|
|
|
For example, to display `passwordPolicy` for demorealm:
|
|
|
|
$ kcadm.sh get realms/demorealm --fields passwordPolicy
|
|
|
|
|
|
Listing authentication flows::
|
|
|
|
Use `get` operation on `authentication/flows` endpoint. For example:
|
|
|
|
$ kcadm.sh get authentication/flows -r demorealm
|
|
|