Scenario ListSessions

Login as an admin user with a username and password and list user and client sessions within a Realm.

See Scenario overview for a list of all scenarios.

Steps of this scenario

  1. Login with admin username and password via the API.

  2. Lookup the Client and list all the User Sessions under that client.

  3. Lookup the User and list all the User Sessions under that user with the client sessions connected to them.

See the source code at ListSessions.scala for details.

Specifics about this scenario

These scenarios are using the master admin account to perform realm operations with the built-in admin-cli client.

This information is specified to the scenarios with options --admin-username and --admin-password.

Usage of a service account token is irrelevant with these scenarios, because:

  • real-world list session operations are performed using the master realm’s admin credentials

  • as the token includes all realm permissions, it would grow very fast and would quickly exceed the maximum length for header (leading to 431 Request Header Fields Too Large responses).

To see how the lookup works, see the methods getClientUUID and getUserUUID in KeycloakScenarioBuilder.scala.

Base Scenario: Single user and single client

Prerequisites

  • Keycloak is running.

  • Realm, user and client exist with the values listed on the CLI.

  • This scenario doesn’t need any service account roles set for the client.

Running the scenario

The following scenario runs with the default settings for 30 seconds.

See Configuring benchmarks for additional CLI options.

bin/kcb.sh \
--scenario=keycloak.scenario.admin.ListSessions \
--server-url=http://localhost:8080/ \
--measurement=30 \
--username=user-0 \
--client-id=client-0 \
--realm-name=test-realm \
--admin-username=admin \
--admin-password=admin \
--log-http-on-failure

Variant: Range of users and range of clients

Prerequisites

To List sessions from varying number of users and clients, additional pre-requisite is a set of users and clients.

This can be created using the Generating datasets section of the guide.

This can be executed using its REST API or the dataset-import.sh shell script.

Alternative 1: Setup of users and clients using the REST API
curl 'https://keycloak-server/realms/master/dataset/create-realms?realm-name=realm-0&count=1&clients-per-realm=30&users-per-realm=200'
Alternative 2: Setup of users and clients using the dataset-import.sh shell script
./dataset-import.sh -a create-realms -r 1 -c 5 -u 30

Running the scenario

Use the below example command to scale the users and clients from a given range.

bin/kcb.sh \
--scenario=keycloak.scenario.admin.ListSessions \
--server-url=http://localhost:8080/ \
--measurement=30 \
--users-per-realm=30 \
--clients-per-realm=5 \
--admin-username=admin \
--admin-password=admin \
--log-http-on-failure

Error messages

Invalid username or password

This could be tested manually by trying to log in as the user on the account console at https://{keyloak-server}/realms/{realm}/account/. This could have the following reasons:

  • The user with the given username doesn’t exist.

    Remedy: Check that the user given on the command line or as the default exists in the given realm.

  • The user has a different password.

    Remedy: Check that the user has the correct password set up.

  • The range provided by --users-per-realm and --clients-per-realm is larger than the seeded users and clients from the Generating datasets module.

    Remedy: Check that the range is smaller for --users-per-realm and --clients-per-realm than the available users and clients.

Realm not found

The realm used for the scenarios doesn’t exist. This could have the following realms:

  • The realm specified on the command line doesn’t match the Keycloak setup, or one of the realms doesn’t exist if a realm range was specified on the CLI.

    Remedy: Check if CLI matches the Keycloak configuration by logging in to the Keycloak instance.

  • No CLI option was used to specify realm, so the scenario uses realm-0 which doesn’t exist.

    Remedy: Create a realm realm-0 in the Keycloak instance, or use the CLI options to specify a realm that exists.

Further Reading