Generating datasets

This describes how to use the dataset provider and its API to generate datasets for load testing.

Never install this provider in a production environment as its endpoints are not secured.

Prerequisites

Installing the dataset provider

When using Quarkus or the minikube installation, all URLs start with /realms/master. For the Wildfly distribution, the URL starts with /auth/realms/master.

Using the dataset provider

Scripted usage

This script contains a subset of the operations described in the next sections around realms, users and clients.

The script assumes that the dataset provider is installed as described in Installing on Minikube setup and that it is available at
https://keycloak-keycloak.$(minikube ip).nip.io/realms/master/dataset/.

Run the following command to receive a help description:

./dataset-import.sh -a help

You will see these options:

Dataset import to the local minikube Keycloak application - usage:
1) create realm/s with clients, users and password hash algorithm & iterations - run -a (action) with or without other arguments: -a create-realms -r 10 -g argon2 -i 5 -c 100 -u 100 -l 'https://keycloak.url.com'
2) create clients in specific realm: -a create-clients -c 100 -n realm-0 -l 'https://keycloak.url.com'
3) create users in specific realm: -a create-users -u 100 -n realm-0 -l 'https://keycloak.url.com'
4) create events in specific realm: -a create-events -e 100 -n realm-0 -l 'https://keycloak.url.com'
5) create offline sessions in specific realm: -a create-offline-sessions -o 100 -n realm-0 -l 'https://keycloak.url.com'
6) delete specific realm/s with prefix -a delete-realms -p realm -l 'https://keycloak.url.com'
7) dataset provider status -a status 'https://keycloak.url.com'
8) dataset provider status check of last completed job -a status-completed -t 10 -l 'https://keycloak.url.com'
9) dataset provider clear status of last completed job -a clear-status-completed -l 'https://keycloak.url.com'
10) dataset import script usage -a help

Example of creating 10 new realms:

./dataset-import.sh -a create-realms -r 10

Alternatively, the user could also run the Taskfile from within the provision/minikube module to execute the dataset-import task, to seamlessly execute the automation for Kubernetes style deployments.

The dataset-import task re-uses the command line arguments defined above to make it convenient for the user. Note the two dashes (--) that separate the task name from the command line options passed to the script.

task dataset-import -- -a create-realms -r 10

To learn more about the tool, see Automation using the tool task for details.

Dataset Provider APIs

Create many realms

You need to call this HTTP REST requests. This request is useful for create 10 realms. Each realm will contain specified amount of roles, clients, groups and users:

.../realms/master/dataset/create-realms?count=10

Create many clients

This is request to create 100 new clients in the realm realm-5 . Each client will have service account enabled and secret like «client_id»-secret (For example client-156-secret in case of the client client-156):

.../realms/master/dataset/create-clients?count=200&realm-name=realm-5

You can also configure the access-type (bearer-only, confidential or public) and whether the client should be a service-account-client with these two parameters:

...&client-access-type=bearer-only&service-account-client=false

Create many users

This is request to create 500 new users in the realm-5. Each user will have specified amount of roles, client roles and groups, which were already created by create-realms endpoint. Each user will have password like «Username»-password . For example user-156 will have password like user-156-password :

.../realms/master/dataset/create-users?count=1000&realm-name=realm-5

Create many groups

Groups are created as part of the realm creation. The number of groups and the structure of the created groups can be managed by using the following parameters:

groups-per-realm: Total number of groups per realm. The default value is 20.
groups-with-hierarchy: true or false, the default value is false. With the default value, only top-level groups are created. With groups-with-hierarchy set to true a tree structure of groups is created; the depth of the tree is defined by the parameter groups-hierarchy-depth and groups-count-each-level defines how many subgroups each created group will have.
groups-hierarchy-depth: The depth of the groups tree structure. The default value is 3. With the default value, top level groups will have groups-count-each-level subgroups and each subgroup will have groups-count-each-level themselves. This parameter is active only when groups-with-hierarchy is true.
groups-count-each-level: Number of subgroups each created group will have. This parameter is active only when groups-with-hierarchy is true.

With the default values, only top-level groups are created. With groups-with-hierarchy set to true, the groups-per-realm parameter is ignored and the group tree structure is created as defined by the other parameters. groups-count-each-level^{groups-hierarchy-depth} will be the total number of groups created. The hierarchical groups implementation honors groups-per-transaction. The adopted subgroup naming convention uses a dot (.) in the group names which allows finding the parent group even if it was created in a previous transaction.

Example parameters

.../realms/master/dataset/create-realms?count=1&groups-with-hierarchy=true&groups-hierarchy-depth=3&groups-count-each-level=50

You can also create groups in an existing realm by invoking the create-groups endpoint and setting the realm-name parameter:

Example parameters

.../realms/master/dataset/create-groups?realm-name=realm-0&count=10&groups-with-hierarchy=true&groups-hierarchy-depth=3&groups-count-each-level=5

Create many events

This is request to create 10M new events in the available realms with prefix realm-. For example if we have 100 realms like realm-0, realm-1, … realm-99, it will create 10M events randomly in them

.../realms/master/dataset/create-events?count=10000000

Create many offline sessions

This is request to create 10M new offline sessions in the available realms with prefix realm-. For example if we have 100 realms like realm-0, realm-1, … realm-99, it will create 10M events randomly in them

.../realms/master/dataset/create-offline-sessions?count=10000000

Remove many realms

To remove all realms with the default realm prefix realm

.../realms/master/dataset/remove-realms?remove-all=true

You can use realm-prefix to change the default realm prefix. You can use parameters to remove all realms for example just from foorealm5 to foorealm15

.../realms/master/dataset/remove-realms?realm-prefix=foorealm&first-to-remove=5&last-to-remove=15

Change default parameters

For change the parameters, take a look at DataSetConfig class to see available parameters and default values and which endpoint the particular parameter is applicable. For example to create realms with prefix foo and with just 1000 hash iterations (with the default hashing algorithm) used for the password policy you can use these parameters:

.../realms/master/dataset/create-realms?count=10&realm-prefix=foo&password-hash-iterations=1000

Another example would be, to specify a particular hashing algorithm in combination with the hashing iterations with the below parameters:

.../realms/master/dataset/create-realms?count=10&realm-prefix=foo&password-hash-algorithm=argon2&password-hash-iterations=1000

The configuration is written to the server log when HTTP endpoint is triggered, so you can monitor the progress and what parameters were effectively applied.

Note that creation of new objects will automatically start from the next available index. For example when you trigger endpoint above for creation many clients and you already had 230 clients in your DB (client-0, client-1, .. client-229), then your HTTP request will start creating clients from client-230 .

Check if the task is still running

Call the following URL using the GET method:

.../realms/master/dataset/status

If there is a task still running, it returns information like the following:

{"status":"Task in progress","task-id":{"startTimeMs":"1662115169043","message":"Creation of 1 realms from realm-6 to realm-6"}}

If there is no task running, it returns information like the following:

{"status":"No task in progress. New task can be started"}

Check the result of the last completed task

Call the following URL using the GET method:

.../realms/master/dataset/status-completed

If there is a task still running, it returns information like the following:

{"status":"previous task completed","task":{"success":"true","startTimeMs":"1662115169043","message":"Creation of 1 realms from realm-1 to realm-1","endTimeMs":"1662115173323"}}

If there is no completed task, it returns this information with status code 404:

{"status":"No completed task"}

Clear the result of the last completed task

Call the following URL using the DELETE method:

.../realms/master/dataset/status-completed

Check the last items of a particular object

To see the last created realm index

.../realms/master/dataset/last-realm

To see the last created client in given realm

.../realms/master/dataset/last-client?realm-name=realm5

To see the last created user in a given realm

.../realms/master/dataset/last-user?realm-name=realm5

Provisioning organizations

Before provisioning organizations, make sure to manually create or provision a realm. For example, provision a realm-0 realm as follows:

.../realms/master/dataset/create-realms?count=1&users-per-realm=5000

As a result, you have a realm realm-0 with 5k users in it.

This is the request to create 1000 organizations in a realm with prefix org-:

.../realms/realm-0/dataset/orgs/create?count=1000

Alternatively, you can create a single organization with a given name:

realms/realm-0/dataset/orgs/create?name=myorg.com&domains=myorg.com,myorg.org,myorg.net&count=1

You can also specify how many members (managed and unmanaged) and how many identity providers should be linked to each organization created:

.../realms/realm-0/dataset/orgs/create?count=1000&unmanaged-members-count=500&identity-providers-count=10

As a result, 1k organizations with the following configuration:

500 unmanaged members
10 identity providers

It is also possible te specify a number of identity provider mappers per each identity provider:

.../realms/realm-0/dataset/orgs/create?count=1000&unmanaged-members-count=500&identity-providers-count=10&identity-provider-mappers-count=3

In this case 1k organizations with each having 500 unmanaged members, 10 identity providers and each identity provider having 3 identity provider mnappers

You can also provision data to a specific organization. For instance, to provision more identity providers to a specific organization:

.../realms/realm-0/dataset/orgs/org-0/identity-providers/create?count=1000

Optionally it’s possible to specify a number of identity provider mappers per each identity provider

.../realms/realm-0/dataset/orgs/org-0/identity-providers/create?count=1000&identity-provider-mappers-count=5

Or to provision more unmanaged members to a specific organization:

.../realms/realm-0/dataset/orgs/org-0/members/create-unmanaged?count=100

Or to provision more managed members to a specific organization:

.../realms/realm-0/dataset/orgs/org-0/members/create-managed?count=100

When provisioning members make sure you have created enough users in the realm. For managed members, you also need at least a single identity provider linked to an organization.

If you want to remove an organization:

.../realms/realm-0/dataset/orgs/org-0/remove